rokstones.io

markdown 0.1.0

CommonMark + GFM (tables, callouts, footnotes, heading anchors) to HTML

markdown

A rok library that converts Markdown to HTML. It covers the main parts of CommonMark plus GitHub extensions, and renders the pages of docs.rok-lang.org and the READMEs on rokstones.io.

  • Blocks: ATX headings (GitHub-compatible id and # anchor), paragraphs, fenced code (``` / ~~~), block quotes, nested lists (tight / loose, start number), thematic breaks, <div> / <section> HTML blocks
  • GFM: tables (alignment, \|), strikethrough (~~), callouts (> [!NOTE] ..), footnotes ([^1] and [^1]: ..)
  • Inline: code, emphasis (CommonMark flanking rules), links, images, autolinks (<https://..>), entities, backslash escapes, hard line breaks

Usage

Package {
    deps: { "markdown": "0.1" },
}

use markdown::{Options, render, render_untrusted};

let doc = render("# Title\n\nBody *emphasis*\n");
println(doc.html);       // <h1 id="title"><a class="anchor" tabindex="-1" href="#title" aria-hidden="true">#</a>Title</h1> ..
println(doc.title);      // Title

// `.md` links to `.html`, ```rok blocks highlighted with rok-syntax
let opts = Options {
    link: |h| h.replace(".md", ".html"),
    code: |lang, code| if lang == "rok" { rok_syntax::highlight_rok(code) } else { none },
};
let page = render(src, opts);

// a README of unknown origin
let readme = render_untrusted(text);

API

ItemDescription
render(src: str, opts: Options | none = none) -> DocTrusted Markdown. Emits <div> / <section> blocks as is
render_untrusted(src: str, opts: Options | none = none) -> DocMarkdown from anywhere. HTML blocks become text; link / image URLs whose scheme is not http / https / mailto become #
Options.link: fn(str) -> str(Every field has a default.) Maps a link / image destination as written to the emitted href / src. Default: unchanged
Options.code: fn(str, str) -> (str | none)HTML inside <pre><code> from the info string's first word and the code. none only escapes. Default: always none
Options.callout: fn(str) -> strTitle of a callout from its kind (lowercase). Default: Note / Tip / Important / Warning / Caution
Doc { html, title, headings }The result. title is the text of the first level-1 heading
Heading { level, id, text }A heading of the document (for tables of contents)
esc(s: str) -> strEscapes & < > "
strip_tags(html: str) -> strText with tags removed and basic entities decoded
slug(text: str) -> strGitHub's heading anchor

Inline HTML is escaped as text in both modes. Callout titles and all attribute values are escaped. There is no highlighter dependency; pass one through Options.code (pairs well with rok-syntax).

Development

rok test        # tests
rok bench       # benchmarks
rok fmt --check
rok doc         # API docs in target/doc/

License

Licensed under either of MIT or Apache-2.0, at your option.