dillonkearns / elm-markdown / Markdown.Html


type alias Renderer a =
Markdown.HtmlRenderer.HtmlRenderer a

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

Creating an HTML renderer

tag : String -> view -> Renderer view

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
    )

withAttribute : String -> Renderer (String -> view) -> Renderer view

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"

withOptionalAttribute : String -> Renderer (Maybe String -> view) -> Renderer view

Same as withAttribute, but the Renderer won't fail if the attribute is missing. Instead, it just returns Nothing for missing attributes.

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

Markdown.Html.tag "bio"
    (\name twitter github children ->
        bioView name twitter github children
    )

map : (a -> b) -> Renderer a -> Renderer b

Map the value of a Markdown.Html.Renderer.

oneOf : List (Renderer view) -> Renderer view

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)
        ]