• 设为首页
  • 点击收藏
  • 手机版
    手机扫一扫访问
    迪恩网络手机版
  • 关注官方公众号
    微信扫一扫关注
    公众号

dillonkearns/elm-markdown: Extensible markdown parser with custom rendering, in ...

原作者: [db:作者] 来自: 网络 收藏 邀请

开源软件名称(OpenSource Name):

dillonkearns/elm-markdown

开源软件地址(OpenSource Url):

https://github.com/dillonkearns/elm-markdown

开源编程语言(OpenSource Language):

Elm 82.8%

开源软件介绍(OpenSource Introduction):

elm-markdown

All Contributors Build Status Elm package

Extensible markdown parsing in pure elm.

This library extends the basic markdown blocks without actually adding features to the syntax. It simply provides a declarative way to map certain HTML tags to your Elm view functions to render them. For example,

<bio
  name="Dillon Kearns"
  photo="https://avatars2.githubusercontent.com/u/1384166"
  twitter="dillontkearns"
  github="dillonkearns"
>
  Dillon really likes building things with Elm! Here are some links -
  [Articles](https://incrementalelm.com/articles)
</bio>

And you wire up your Elm rendering function like this

Markdown.Html.oneOf
  [ Markdown.Html.tag "bio"
    (\name photoUrl twitter github dribbble renderedChildren ->
      bioView renderedChildren name photoUrl twitter github dribbble
    )
    |> Markdown.Html.withAttribute "name"
    |> Markdown.Html.withAttribute "photo"
    |> Markdown.Html.withOptionalAttribute "twitter"
    |> Markdown.Html.withOptionalAttribute "github"
    |> Markdown.Html.withOptionalAttribute "dribbble"
  ]

Note that it gets the rendered children as an argument. This is rendering the inner contents of the HTML tag using your HTML renderer, so you get all of your rendered lists, code blocks, links, etc. within your tag. You can try a live Ellie demo of this code snippet.

Live Code Demos

Core features

Custom Renderers

You define your own custom renderer, turning your markdown content into any data type with totally customizable logic. You can even pass back an Err to get custom failures (for example, broken links or validations like headings that are too long)!

Here's a snippet from the default HTML renderer that comes built in to give you a sense of how you define a Renderer:

import Html exposing (Html)
import Html.Attributes as Attr
import Markdown.Block as Block exposing (Block)
import Markdown.Html

defaultHtmlRenderer : Renderer (Html msg)
defaultHtmlRenderer =
    { heading =
        \{ level, children } ->
            case level of
                Block.H1 ->
                    Html.h1 [] children

                Block.H2 ->
                    Html.h2 [] children

                Block.H3 ->
                    Html.h3 [] children

                Block.H4 ->
                    Html.h4 [] children

                Block.H5 ->
                    Html.h5 [] children

                Block.H6 ->
                    Html.h6 [] children
    , paragraph = Html.p []
    , hardLineBreak = Html.br [] []
    , blockQuote = Html.blockquote []
    , strong =
        \children -> Html.strong [] children
    , emphasis =
        \children -> Html.em [] children
    , codeSpan =
        \content -> Html.code [] [ Html.text content ]
    , link =
        \link content ->
            case link.title of
                Just title ->
                    Html.a
                        [ Attr.href link.destination
                        , Attr.title title
                        ]
                        content

                Nothing ->
                    Html.a [ Attr.href link.destination ] content
    , image =
        \imageInfo ->
            case imageInfo.title of
                Just title ->
                    Html.img
                        [ Attr.src imageInfo.src
                        , Attr.alt imageInfo.alt
                        , Attr.title title
                        ]
                        []

                Nothing ->
                    Html.img
                        [ Attr.src imageInfo.src
                        , Attr.alt imageInfo.alt
                        ]
                        []
    , text =
        Html.text
    , unorderedList =
        \items ->
            Html.ul []
                (items
                    |> List.map
                        (\item ->
                            case item of
                                Block.ListItem task children ->
                                    let
                                        checkbox =
                                            case task of
                                                Block.NoTask ->
                                                    Html.text ""

                                                Block.IncompleteTask ->
                                                    Html.input
                                                        [ Attr.disabled True
                                                        , Attr.checked False
                                                        , Attr.type_ "checkbox"
                                                        ]
                                                        []

                                                Block.CompletedTask ->
                                                    Html.input
                                                        [ Attr.disabled True
                                                        , Attr.checked True
                                                        , Attr.type_ "checkbox"
                                                        ]
                                                        []
                                    in
                                    Html.li [] (checkbox :: children)
                        )
                )
    , orderedList =
        \startingIndex items ->
            Html.ol
                (case startingIndex of
                    1 ->
                        [ Attr.start startingIndex ]

                    _ ->
                        []
                )
                (items
                    |> List.map
                        (\itemBlocks ->
                            Html.li []
                                itemBlocks
                        )
                )
    , html = Markdown.Html.oneOf []
    , codeBlock =
        \block ->
            Html.pre []
                [ Html.code []
                    [ Html.text block.body
                    ]
                ]
    , thematicBreak = Html.hr [] []
    , table = Html.table []
    , tableHeader = Html.thead []
    , tableBody = Html.tbody []
    , tableRow = Html.tr []
    , tableHeaderCell =
        \maybeAlignment ->
            let
                attrs =
                    maybeAlignment
                        |> Maybe.map
                            (\alignment ->
                                case alignment of
                                    Block.AlignLeft ->
                                        "left"

                                    Block.AlignCenter ->
                                        "center"

                                    Block.AlignRight ->
                                        "right"
                            )
                        |> Maybe.map Attr.align
                        |> Maybe.map List.singleton
                        |> Maybe.withDefault []
            in
            Html.th attrs
    , tableCell = \_ children -> Html.td [] children
    , strikethrough = Html.span [ Attr.style "text-decoration-line" "line-through" ]
    }

Markdown Block Transformation

You get full access to the parsed markdown blocks before passing it to a renderer. That means that you can inspect it, do custom logic on it, perform validations, or even go in and transform it! It's totally customizable, and of course it's all just nice Elm custom types!

Here's a live Ellie example that transforms the AST into a table of contents and renders a TOC data type along with the rendered markdown.

Philosophy & Goals

  • Render markdown to any type (Html, elm-ui Elements, Strings representing ANSI color codes for terminal output... or even a function, allowing you to inject dynamic values into your markdown view)
  • Extend markdown without adding to the syntax using custom HTML renderers, and fail explicitly for unexpected HTML tags, or missing attributes within those tags
  • Allow users to give custom parsing failures with nice error messages (for example, broken links, or custom validation like titles that are too long)

Parsing Goals

This is evolving and I would like input on the direction of parsing. My current thinking is that this library should:

  • Do not add any new syntax, this library has a subset of the features of Github flavored markdown.
  • Only parse the Github-flavored markdown style (not CommonMark or other variants)
  • (This breaks GFM compliance in favor of explicit errors) All markdown is valid in github-flavored markdown and other variants. This library aims to give explicit errors instead of falling back and silently continuing, see example below
  • Only deviate from Github-flavored markdown rules when it helps give better error feedback for "things you probably didn't mean to do." In all other cases, follow the Github-flavored markdown spec.

Current Github-flavored markdown compliance

The test suite for this library runs through all the expected outputs outlined in the GFM spec. It uses the same test suite to test these cases as highlight.js (the library that elm-explorations/elm-markdown uses under the hood).

You can see the latest passing and failing tests from this test suite in the test-results folder (in particular, take a look at the Github-Flavored Markdown failures in in failing/GFM.

Examples of fallback behavior

Github flavored markdown behavior: Links with missing closing parens are are rendered as raw text instead of links

[My link](/home/ wait I forgot to close the link

Renders the raw string instead of a link, like so:

<p>
  [My link](/home/ wait I forgot to close the link
</p>

This library gives an error message here, and aims to do so in similar situations.

Contributors

A huge thanks to Pablo Hirafuji, who was kind enough to allow me to use his InlineParser in this project. It turns out that Markdown inline parsing is a very specialized algorithm, and the elm/parser library isn't suited to solve that particular problem.


Stephen Reddekopp

⚠️

鲜花

握手

雷人

路过

鸡蛋
该文章已有0人参与评论

请发表评论

全部评论

专题导读
上一篇:
zenn-dev/zenn-editor: Convert markdown to html in Zenn format发布时间:2022-08-18
下一篇:
JasKang/vite-plugin-md-preview: markdown vue code preview发布时间:2022-08-18
热门推荐
阅读排行榜

扫描微信二维码

查看手机版网站

随时了解更新最新资讯

139-2527-9053

在线客服(服务时间 9:00~18:00)

在线QQ客服
地址:深圳市南山区西丽大学城创智工业园
电邮:jeky_zhao#qq.com
移动电话:139-2527-9053

Powered by 互联科技 X3.4© 2001-2213 极客世界.|Sitemap