Elm-book – books with markdown and embedded elm components

Hello folks – I just published v1.0.0 of elm-book!

I’ll copy-paste a little sneak of the overview page here to explain a little bit more about the goals behind the project:


This library takes a lot of inspiration from two libraries:

  • Storybook – a JS ecosystem tool that focus on showcasing components and their states, mostly aiming at internal design systems but also enabling the pattern of creating visual components in isolation.
  • HexDocs – an Erlang/Elixir ecosystem tool that enables structured library documentation with guides, function docs, links to code and external sources.

Both of these tools affected their whole ecosystems greatly. Creating good docs is a common place when you’re in Elixir world. Using Storybook to facilitate design-engineering iteration is a common place in the JS world.What if the Elm ecosystem can create its own thing with the best of both worlds?

ElmBook aims to be just that – making it easy to create attractive documentation websites that can also work as a playground for live components built with Elm.


Please take a look, use it, throw punches at it and let me know how can we make it better!

The theme builder is a particularly fun little tool I made available as part of the website if you like messing around with theme colors.

I’d like to especially thanks @dillonkearns for the work on dillonkearns/elm-markdown since I piggybacked a lot on it to achieve the end results. :grin:

25 Likes

Looks very cool. I’d say another great possible source of inspiration would be LiveBook and the live code execution and package install features of that in particular.

1 Like

This looks really neat, thank you for building and sharing! Do you have any thoughts on how it compares to GitHub - kalutheo/elm-ui-explorer?

1 Like

Hey @rjdellecese ! There is definitely an overlap between the two libraries but the outputs are different enough that I believe it will come down to taste (in terms of both ux design and developer experience preferences).

With elm-book I’m trying to focus on “rich documentations” – not necessarily component libraries (though those are definitely considered). This opens up a few interesting possibilities that drift away from the Storybook inspiration like long posts explaining a concept with markdown and interactive examples… the possibilities are quite numerous.

I believe I’ve heard that Kalutheo is also planning something for the next version of elm-ui-explorer– so maybe we might end up filling different community needs? I really don’t know :slight_smile:

1 Like

wondering what constraints made you choose to reach for needing <component with-label="???" /> in the markdown string

|> withComponents
    [ ( "Default", view props )
    , ( "Disabled", view { props | disabled = True } )
    ]
|> render """
Buttons are pretty amazing, right? You can click them and stuff.

Try clicking on this one:

<component with-label="Default" />

They can also be disabled! Unbelievable.

<component with-label="Disabled" />
"""

vs rendering them sequentially, e.g. perhaps like

|> render
    [ Markdown
        """
        Buttons are pretty amazing, right? You can click them and stuff.

        Try clicking on this one:
        """
    , Component (view props)
    , Markdown
        """
        They can also be disabled! Unbelievable.
        """
    , Component (view { props | disabled = True })
    ]

just the fact that I can click on the netlify link and see what the readme words is talking about, greatly lowered the barrier :stuck_out_tongue: for me

I thought about that! It was mainly two things (tho I know there is the downside of decreased type-safety when using some random custom element and random custom props):

  • since I’m not only focusing on storybook-like documents, it would be great to be able to use elm components wherever I want in the markdown. Including in the middle of other tags (using the “displayInline” option) - this is trivial when using dillonkearns/elm-markdown. when I first explored the idea you mentioned it seemed trickier but thinking about it now it is less tricky and it opens up a few possibilities (based on other recent feedbacks…) - I’ll keep exploring it :grin:

  • working with markdown and elm is a bit of a painful experience. there is no syntax highlighting. no autoformat or anything. so I thought that separating both steps would enable code generation more easily since you can split the writing of markdown somewhere else and then just replace the string on the elm file… even on the markdown-in-elm approach I found it simple to just move components around without thinking about the boundaries between text and components.

but its definitely an interesting idea! thanks for bringing it in. I’m putting a pile of feedback together for future work. thanks!

1 Like