To get live-reloading via elm-hot, it's necessary not to store the content in the model, since the way hot reloading works is by reloading the code, but keeping the model the same.

This can be done by storing the chapters in a closure, so instead of:

application :
    List ( String, List (ChapterCustom state html) )
    -> BookBuilder state html
    -> BookApplication state html
application chapterGroups (BookBuilder config) =
    Browser.application
        { init =
            init
                { config = config
                , chapterGroups = chapterGroups
                }
        , view = view
        , update =
            \msg model ->
                update msg model
                    |> withActionLogReset model
        , onUrlChange = OnUrlChange
        , onUrlRequest = OnUrlRequest
        , subscriptions =
            \_ ->
                Sub.batch
                    [ onKeyDown keyDownDecoder
                    , onKeyUp keyUpDecoder
                    , Sub.batch config.statefulOptions.subscriptions
                    ]
        }

...

view model =
  let 
     chapterGroups = model.chapterGroups
  in
  ...

you can do

application :
    List ( String, List (ChapterCustom state html) )
    -> BookBuilder state html
    -> BookApplication state html
application chapterGroups (BookBuilder config) =
    Browser.application
        { init =
            init chapterGroups
                { config = config
                }
        , view = view chapterGroups
        , update =
            \msg model ->
                update chapterGroups msg model
                    |> withActionLogReset model
        , onUrlChange = OnUrlChange
        , onUrlRequest = OnUrlRequest
        , subscriptions =
            \_ ->
                Sub.batch
                    [ onKeyDown keyDownDecoder
                    , onKeyUp keyUpDecoder
                    , Sub.batch config.statefulOptions.subscriptions
                    ]
        }

possibly the same should be done with the config.

Screenshots illustrating the issue:

Scrolled to left:

Scrolled to right:

As you can see above, there is no gap between the right end of the content and the code block container. I'd expect a padding similar to the left padding.

"Model" should be "SharedState" in the example below:

https://elm-book-in-elm-book.netlify.app/guides/stateful-chapters

Some UI components depend on JS. I can not render. them in elm-book unless I can include javascript.

The code blocks currently use Fire Code as Font.
This looks pretty, but the ligatures might confuse people that have never seen Fire Code before.

This feature has been suggested on discourse as a feature request for leaf-lang.

Our design system has concepts of dark and light and it would be neat if we could also switch the style of the rendered components based on what the book does.

First of all, thanks so much for a great library! I tried out elm-book after the presentation at the last meetup and I think it'll see regular use.

I found the following issue when using elm-ui - it looks like elm-book's css is overriding elm-ui's colors in component lists. It's only with colours, and strangely it renders the last item in the component list correctly.

Description

1. Elm-UI Setup is as described in the docs for ElmBook.Custom
2. A Chapter contains a list of variations on a simple component using Elm-UI, with different colours for each component.
3. The Elm-UI colours are ignored for all items in the list except for the last. Note that font style and borders are rendered correctly, just the colours are incorrect.

Example

main =
    book
        "My Book"
        |> withChapters
            [ bugs
            ]

bugs : Chapter x
bugs =
    chapter ""
        |> renderComponentList
            [ ( "Blue, blue box", viewtest <| [Font.color blue
                                              , Border.width 1
                                              , Border.color blue
                                              , Element.padding 5] )
            , ( "Green italic, green box", viewtest <| [Font.color green
                                                       , Font.italic
                                                       , Border.width 1
                                                       , Border.color green
                                                       , Element.padding 5])
            , ( "Orange bold, orange box", viewtest <| [Font.color orange
                                                       , Font.bold
                                                       , Border.width 1
                                                       , Border.color orange
                                                       , Element.padding 5] )
            , ( "Red, red box", viewtest <| [Font.color red
                                            , Border.width 1
                                            , Border.color red
                                            , Element.padding 5] )
            ]
        
green : Element.Color
green =
    Element.rgb255 0x7F 0xC4 0x36

red =
    Element.rgb255 255 0 0

orange =
    Element.rgb255 0xFF 0x80 0x00

blue =
    Element.rgb255 0x44 0x84 0xCE

viewtest style =
    Element.el style <| Element.text "This is a test"

This example renders as follows:

Expected Behaviour

All examples are coloured as their labels suggest.

See the following screenshot, created by disabling "color: inherit;" for each item in the list in the inspector.

Tested With

Elm 19.1
elm-book 1.4.2
elm-ui 1.1.8

Tested in both Firefox and Chrome.

I have also confirmed that this happens with Element.Input.text

I think it would be great if we could also change the theme colors + custom header when going to dark mode.
Dark and light modes are really different so it's pretty hard for a wrapper theme to fit both.

Problem

Right now, it's not possible to have a Cmd that returns another kind of Msg other than the one in ElmBook.Internal.Msg. This is important because sometimes we might have children components which execute Cmds and return their own Msg type. With the current API, it's not possible to have these kinds of components.

Solution

We already have initialState and subscriptions on StatefulOptions. We could embrace The Elm Architecture even more and have an update : (subMsg -> state -> ( state, Cmd subMsg )) -> Attribute state subMsg function. This would then be used at the top level by the user, and the user could use a Chapter.map : (subMsg -> mappedSubMsg) -> Chapter state subMsg -> Chapter state mappedSubMsg function to have chapters with their own update function that returns their custom Cmds.

Context

Sometimes chapters will produce their own subscriptions or consume libraries which produce subscriptions. Elm-book currently handles subscriptions at the Book level but does not make available chapter state that may be required for a subscription.

-- SomeChapter.elm

subscriptions : SomeChapterModel -> Sub SomeChapterMsg
subscriptions model =
    if model.run then
        -- some Sub
    else
        Sub.none

It seems the ElmBook.StatefulOptions.subscriptions allows you to modify state after a subscription but not give you access to chapter models when creating one.

Would be great if the chapter state could be passed to the subscription handler in order to achieve the above.

e.g.

bookSubscriptions : SharedState -> Sub msg
bookSubscriptions state =
        SomeChapter.subscriptions state.someChapterState |> mapWithElmBookMsgSomehow

book : Book SharedState
book "My Book"
        |> withStatefulOptions
            [ ElmBook.StatefulOptions.initialState sharedState
            , ElmBook.StatefulOptions.subscriptions bookSubscriptions
            ]

I have a chapter in my styleguide that's a large markdown document, and I'd like to be able to make links within the document that link to other headings within that same document. If the Markdown renderer automatically added <a name="...generated-from-heading...">...</a> tags around the headings, then I could easily add those links.

main =
    book "Example book"
        |> Book.withChapterGroups
            [ ( "Non-empty name"
              , [ Chapter.chapterLink { title = "title", url = "https://example.com/" }
                ]
            ]

The link in the rendered navbar will be invalid, as it will be concatenated with the group's URL http://localhost/non-empty-namehttps://example.com/ instead of being recognized as an absolute URL.

(Note that things work fine if the group's name is the empty string "".)

<component with=label="Empty actions list" />

Note the with=label instead of with-label.

This silently breaks a chapter: nothing gets shown, but there's no error on the page nor in the console.

I suppose any indication that the Markdown parser has failed would improve this.

Happens in:

• MacOS, Firefox 95.0.2
• Linux, Firefox 96.0

Steps to reproduce:

• In the docs/demo https://elm-book-in-elm-book.netlify.app :
• Click in the search field
• Type "Mark"
• Click the "Markdown" chapter in the filtered chapter list

Expected result:

• I'm taken to the Markdown chapter page

Actual result:

• The search is cleared, and I'm still on the same page I was on.

In order to provide examples I want to create full-page chapters that are not narrowed by the sidebar.

ElmBook hijacks links when they start with /logAction so they are only logged but the user does not leave the page or scroll unexpectedly – however, this should check if /logAction is present in the String at all otherwise this won't work with chapters inside chapterGroups as their url can start with the chapter group name /buttons/logAction/....

Thanks for this nice project.

We would like to use this for our internal styleguide and documentation, but the way we deploy our monorepo, we use urls like:

http://somedomain.co/styleguide.html

(there are other apps at the same level)

our apps that need client side routing solve this by using the older pattern:

http://somedomain/styleguide.html#/foo/bar

I am wondering if this could be implemented (perhaps as an option; although it does make it easier to deploy on static hosts so you might consider making it the default and having the current behavior be opt-in).

If you'd be willing to add it, I am happy to implement it (I'd appreciate some pointers on where in the API it should be exposed, as its not entirely clear where this would fit in the various option categories).

The docs for ElmBook.Chapter.withComponentOptions say:

[component options] can also be overriden on the component level. Take a look at the ElmBook.Component module for more details.

But there is no such ElmBook.Component module.

Is there a way to set component options for a single component? If not, I humbly request that feature (my real end-goal is to make a horizontal layout option for a list of components, which I'm trying to do by building a custom html and adding it as a single component, but then I want that one component to use ComponentOptions.displayBlock and leave other components to render normally as cards).

In general within my styleguide, I'd like to make links to external sites automatically open in new tabs. If target=_blank were automatically added to any markdown links with an absolute URL href, or if there were a Theme/Book/Chapter/etc option to enable that, then I could easily do so. (I'd still want styleguide-internal links (which are all going to be relative URLs) to behave as they currently do.)

"withStatefulComponent" should be "renderStatefulComponent" in the example below:

https://elm-book-in-elm-book.netlify.app/guides/stateful-chapters

Should the links in these examples be safe for work?

Currently when rendering code blocks there is no out-of-the-box syntax highlighting but also no easy way to add a custom implementation since the <code /> element doesn't get information from the markdown language name tag. In the images attached as an example, the markdown code block has the javascript tag but the generated <code /> element only gets a class name of elmsh and the generated code is simply unstyled white on black.

Markdown:

Generated HTML:

Unstyled content:

It would be nice to get either out-of-the-box syntax highlighting OR some form of data-* attribute to implement some custom logic if otherwise preferred.

The ChapterBuilder type is used by public functions (like ElmBook.Chapter.withComponent), but it's not exposed.

I have a helper function I use for some company-specific component example layouts, but I'm unable to add a type signature to those helper functions because I can't refer to ChapterBuilder. Ideally the type (though not its internals) would be exposed.

A tiny issue but I don't know which is the right way to communicate so I go here. Please let me know if you think there is the better way to do 😅

Here in ElmBook.Chapter.withComponentList documentation, it says withComponents on the place that should be withComponentList -- I guess?

I would love to use elm-book for a documentation site I am currently planning out but I see no way to deeply nest chapters currently. For example, imagine a sidebar like so for example:

| Getting Started (Group)
| -> Introduction (Chapter)
| -> Key Concepts (Chapter)
| Guides (Group)
| -> Javascript (Group)
| -> -> Installation (Chapter)
| -> -> Basic Usage (Chapter)
| -> -> Reference Guide (Chapter)
| -> Typescript (Group)
| -> -> Installation (Chapter)
| -> -> Basic Usage (Chapter)
| -> -> Reference Guide (Chapter)
| -> PHP (Group)
| -> -> Installation (Chapter)
| -> -> Basic Usage (Chapter)
| -> -> Reference Guide (Chapter)

As things stand, it seems not possible to implement such nested groupings, is this understanding correct and if so, is it addressable or is there a reason why it isn't or shouldn't? For me it would definitely be a helpful thing to have the possibility of as the rest of the implementation works like a charm AFAICS so far for the use case.

In the below screenshot, the action log shows 9 actions, but the panel at the very bottom shows (10). In general the number it shows is one more than the number of actions emitted.

Expected: show (9) there if 9 actions have been emitted, not (10).

PS: the modal itself might somehow tell the user which actions are most recent (at the top? or at the bottom?)

For the book I'm planning to write I'd like to have "stateful markdown". I implemented a proof of concept and added the following function to ElmBook.Chapter:

renderStateful : (state -> String) -> ChapterBuilder state html -> ChapterCustom state html

It works as expected, and I could create a pull request, if you like.

Alternatively, I could also imagine the following interface analogous to withStatefulComponentList:

withStatefulMarkdownList :
    List ( String, state -> String )
    -> ChapterBuilder state html
    -> ChapterBuilder state html

I could create a pull request for this, too.

What do you think? Would it be a useful addition? Which interface would you prefer?

Never mind, I've found ComponentOptions and the with-display="inline" attribute.
This is exactly what I need. Unfortunately I'm not allowed to delete this issue.

In order to ensure that typography is consistent with my design system I want to adjust the theme options to a different font.

In The Roadmap you write

Generating ElmBooks based on doc comments – the same that are used to generate docs on elm-packages. This could allow published elm packages to automatically have their own ElmBook with example codes turning into live components and no code duplication.

Is this still up for grabs? I'm currently interested in anything related to generating content and am currently investigating different ways of doing so. This task might be a good way to explore various possibilities.

Some technologies I want to explore using this task:

• Elm-codegen - generates code using Elm
• Elm-pen - generates code using Moustache Files & Json
• elm-posix - lets you read & write files using node.js

Hello,

I'm trying to create a stateful chapter with a model holding some Html.
The problem is with Elm we have to specify the message of Html but can't find how to align types well and I don't see anything on your doc about this use case: https://elm-book-in-elm-book.netlify.app/guides/stateful-chapters

Is it possible? If yes, what types should be used? Do you have an example?

My chapter if you want to have a look: https://github.com/azimuttapp/azimutt/pull/57/files#diff-c9ee7b79dd1b6e81e3ab9c660f623a0892c6df7c66e77be47b41cff3c93967d6R130
BTW I'm using ElmCSS ;)

We would prefer not to set up a separate dev server for elm-book. Instead we would like to setup elm book such that it is available at the /elm-book route on the same localhost port as the app we're currently developing.

Right now, however elm-book assumes it always "lives" at /. So clicking on a chapter in the sidebar always navigates to /chapter_group/chapter.

We would like to have an option that would allow us to add a prefix to this route, so that elm-book navigates to /${prefix}/chapter_group/chapter. In other words, we would like to be able to specify on which route elm-book will "live".