StaticBlog.Markdown (StaticBlog v0.2.0)

Copy Markdown View Source

Converts post markdown to HTML.

Every markdown-to-HTML conversion in the blog engine goes through this module so that a post renders identically whether it is built by mix blog.build, served by the preview server, or summarised by the Micropub endpoint.

Conversion uses MDEx, a CommonMark parser built on Comrak. Code blocks are then syntax highlighted with Makeup.

Enabled syntax

Beyond CommonMark, the default option set enables tables, strikethrough, autolinks, task lists, smart punctuation, and footnotes in both the labelled [^name] and inline ^[note] forms. Raw HTML in a post is passed through rather than stripped, because posts are authored by the site owner rather than submitted by untrusted visitors.

See the footnotes guide for how footnotes render and how to style them.

Configuration

The option set can be replaced or extended per-site. Options are deep-merged over the defaults, so a site only names what it wants to change:

config :static_blog, :markdown,
  extension: [alerts: true],
  parse: [smart: false]

See MDEx.Document for the full list of accepted options.

Summary

Functions

default_options()

Return the built-in markdown options, before any site configuration.

options(options \\ [])

Return the markdown options in effect, with options merged over them.

to_html(markdown, options \\ [])

Convert a markdown string to HTML.

Functions

default_options()

@spec default_options() :: keyword()

Return the built-in markdown options, before any site configuration.

Returns

Examples

iex> StaticBlog.Markdown.default_options()[:render]
[unsafe: true]

options(options \\ [])

@spec options(keyword()) :: keyword()

Return the markdown options in effect, with options merged over them.

Arguments

  • options is a keyword list of overrides. Defaults to [].

Returns

Examples

iex> StaticBlog.Markdown.options()[:extension][:footnotes]
true

iex> options = StaticBlog.Markdown.options(extension: [footnotes: false])
iex> {options[:extension][:footnotes], options[:extension][:table]}
{false, true}

to_html(markdown, options \\ [])

@spec to_html(
  String.t(),
  keyword()
) :: String.t()

Convert a markdown string to HTML.

Arguments

  • markdown is the post body as a markdown string, without frontmatter.

Options

  • Any option accepted by MDEx.Document, such as :extension, :parse, or :render. Options given here are deep-merged over the configured defaults, which are themselves merged over default_options/0.

Returns

  • The rendered HTML as a string.

Examples

iex> StaticBlog.Markdown.to_html("A *simple* post.")
"<p>A <em>simple</em> post.</p>"

iex> StaticBlog.Markdown.to_html("Tildes ~~strike~~ through.")
"<p>Tildes <del>strike</del> through.</p>"