jxxcarlson/elm-markdown

The aim of this Markdown library is to provide a pure Elm implementation of Markdown which offers a small set of extensions, along with options:

• Standard: the usual thing
• Extended: strike-though text, tables, and Poetry and Verbatim blocks
• ExtendedMath: like Extended, but math formulas written in TeX/LaTeX, eg.,

This **is** a test: $a^2 + b^2 = c^2$.

are properly rendered.

See markdown.minilatex.app for a demo of the latest implementation. There are two versions of the demo, one in ./app-demo/, the other in app-demo-optimized. The former works well for Markdown documents with no math text or not too much math text. The latter has some optimizations for math-heavy documents, but is slightly more complex to implement. This is explained in the comments to the code.

Example

To convert text to Html, do something like this:

Markdown.Elm.toHtml ExtendedMath "This **is** a test: $a^2 + b^2 = c^2$."

According to your needs, you can also use the Standard or Extended options. Use this line to make options available:

import Markdown.Option exposing(Option(..))

where

type Option
    = Standard
    | Extended
    | ExtendedMath

Demo app

The demo app resides in ./app-test of the Github repository. To run it, go into that folder and say sh make.sh. Then double-click on index.html.

Style

The style used by the library is entirely determined by the definitions of the CSS classes that you refer to in your index.html. The ones used for the demo app are found in./app-test/assets/style.css. You can easily reconfigure the CSS to satsify your own esthetics.

Images

The usual ![My favorite image](imageUrl) does the usual thing, with the image scaled to 100% width. You can also say ![My favorite image::left](imageUrl) or ![My favorite image::right](imageUrl) to float the image left or right at 40% width. The widths are defined in style.css.

MathJax

TeX/LaTeX math text is rendered using \href{https://mathjax.org}{MathJax}. For this you must use the ExtendedMath option. In addition, you must have the files

assets/math-text.js
assets/custom-element.config.js

in the same directory as index.html, and index.html must contain the three lines below at the top of the <head> section, just under <meta charset="utf-8" />, for example.`

<!-- Load MathJax code -->
<script src="assets/custom-element-config.js"></script>
<script src="assets/math-text.js"></script>
<script src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-chtml.js"></script>

The demo app is now using MathJax 3.0.

Markdown extensions

I am trying to be conservative about extensions to Markdown. However, there are two that I thought important enough to add: tables, poetry blocks and verbatim text. Poetry blocks are are like quotation blocks, except that they begin with ">>" instead of ">". Line endings are respected in poetry blocks. Verbatim blocks are like code blocks, except that they are set off by four backticks instead of three. No syntax coloring is applied to verbatim blocks.

AST

The simplest way to render Markdown is to use a one of the built-in rendering functions, e.g., make the call

Markdown.Elm.toHtml Extended document

However, if you wish to write your own renderer, you can produce the abstract syntax tree of a document by running

Parse.toMDBlockTree : Option -> Document -> Tree MDBlock

where Document is a type alias for String. This is also useful if you wish to transform the abstact syntax tree before rendering it.

Bugs and whatnot

Please write me at [email protected] or post an issue on the Github repository regarding bugs or anything else. I will steer this library towards the Commonmark spec to the greatest extent possible by the method of successive approximations

Thanks

Thanks to Folkert deVries for a number of significant optimizations to the parser.