A Markdown.Html.Renderer is how you register the list of valid HTML tags that can be used in your markdown. A Renderer also defines how to render those tags that it accepts.

Using an HTML renderer feels similar to building a JSON decoder. You're describing what kind of data you expect to have. You also provide functions that tell what to do with those bits of data.

For example, if you expect to have an attribute called button-text for the <signup-form ...> tags in your Markdown, you could use the value of the button-text attribute to render your <signup-form like so

Start a Renderer by expecting a tag of a particular type.

Markdown.Html.tag "contact-button"
    (\children ->
        -- we don't want to use any inner markdown
        -- within <contact-button> tags, so we'll
        -- ignore this argument
        Html.button
     -- ... fancy SVG and mailto links here
    )

Expects an attribute. The Renderer will fail if that attribute doesn't exist on the tag. You can use the values of all the expected tags in the function you define for the tag's renderer.

import Html
import Html.Attributes as Attr
import Markdown.Html


Markdown.Html.tag "contact-button"
    (\children buttonText color ->
        Html.button
            [ Attr.style "background-color" color ]
            [ Html.text buttonText ]
    )
    |> Markdown.Html.withAttribute "button-text"
    |> Markdown.Html.withAttribute "color"

Map the value of a Markdown.Html.Renderer.

Usually you want to handle a list of possible HTML tags, not just a single one. So 99% of the time you'll be using this function when you use this module.

htmlRenderer =
    Markdown.Html.oneOf
        [ Markdown.Html.tag "contact-button"
            (\children -> contactButtonView)
        , Markdown.Html.tag "signup-form"
            (\children -> signupFormView children)
        ]