tur/markdown

(markdown/default-opts :MdOpts)

the GFM extensions on, math off.

(.tables (markdown/default-opts))  ; => true

Since: markdown-library-plan M1

(markdown/commonmark-opts :MdOpts)

plain CommonMark: every extension off.

(.tables (markdown/commonmark-opts))  ; => false

Since: markdown-library-plan M1

(markdown/default-html-opts :MdHtmlOpts)

the renderer's defaults: raw HTML through GitHub's tag filter, and no heading ids.

The output is the CommonMark spec's and cmark-gfm's. For heading ids, build an MdHtmlOpts with (MdSlugPython) or (MdSlugGitHub) instead.

(markdown/render-html d (markdown/default-html-opts))

Since: markdown-library-plan M1

(markdown/parse [src :String opts :MdOpts] :MdDoc)

parse Markdown source into a document.

Any String parses: Markdown has no syntax errors. Lines may end in LF, CR or CR LF, and a NUL byte reads as U+FFFD. The document keeps its own copy of what it needs, so src can be released straight away.

(markdown/parse (string/from-cstr "# Hi") (markdown/default-opts))

Since: markdown-library-plan M1

(markdown/render-html [d :MdDoc opts :MdHtmlOpts] :String)

the HTML for a document.

Block structure as the CommonMark spec writes it: one line per block tag, a tight list's paragraphs without <p>, a code block's info string's first word as a language- class.

(markdown/render-html d (markdown/default-html-opts))  ; => "<h1>Hi</h1>\n"

Since: markdown-library-plan M1

(markdown/doc-free [d :MdDoc] :void)

release a document and everything it holds.

(markdown/doc-free d)

Since: markdown-library-plan M1

(markdown/escape-html [s :String] :String)

s with & < > and " replaced by their HTML entities.

(string/to-cstr (markdown/escape-html (string/from-cstr "a<b")))  ; => "a&lt;b"

Since: markdown-library-plan M1

(defstruct MdBlockId :copy [ix :int])

a block of a parsed document. Valid only with the MdDoc it came from.

(defdata MdAlign :copy (MdAlignNone) (MdAlignLeft) (MdAlignCenter) (MdAlignRight))

a table column's alignment, from the colons of its delimiter cell.

(defdata MdTask :copy (MdNotTask) (MdUnchecked) (MdChecked))

a list item's GFM task box: none, [ ], or [x].

(defdata MdBlock :copy (MdDocument) (MdBlockQuote) (MdList bool int bool) (MdItem MdTask) (MdParagraph) (MdHeading int) (MdThematicBreak) (MdCodeBlock bool) (MdHtmlBlock) (MdTable int) (MdTableRow bool) (MdTableCell MdAlign) (MdMathBlock))

what a block is, with the facts that go with its kind.

(MdList ordered start tight): start is the first item's number (1 for a bullet list). (MdItem task): whether the item opens with a GFM task box. (MdHeading level): 1 to 6. (MdCodeBlock fenced). (MdTable columns), (MdTableRow header?) and (MdTableCell alignment) are a GFM table: its rows are its children, and a row's cells are its children. (MdMathBlock) is a $$ display formula, with math on; markdown/block-text has its TeX.

(md/-node-of [d :MdDoc id :MdBlockId] :MdNode)

internal: the arena node behind id.

(md/-new-ids :(Vec MdBlockId))

internal: an empty MdBlockId Vec.

(md/-pool-copy [d :MdDoc i :int] :(Option String))

internal: a fresh copy of pool String i, or (none) when i is -1.

(md/-align [a :int] :MdAlign)

internal: the MdAlign for alignment code a (1 left, 2 center, 3 right).

(markdown/root [d :MdDoc] :MdBlockId)

the document block, the root of the tree.

(markdown/block d (markdown/root d))  ; => (MdDocument)

Since: markdown-library-plan M1

(markdown/children [d :MdDoc id :MdBlockId] :(Vec MdBlockId))

the blocks directly inside a block, in order.

A Vec rather than first-child / next-sibling Options: an Option of a struct is a heap box that a recursive walk would leak (see docs/reported/carrier-sum-option-boxes-have-no-owner.md).

(vec-len (markdown/children d (markdown/root d)))  ; => the number of top-level blocks

Since: markdown-library-plan M1

(markdown/block [d :MdDoc id :MdBlockId] :MdBlock)

what a block is.

(markdown/block d id)  ; => (MdHeading 2) for "## Title"

Since: markdown-library-plan M1

(markdown/block-text [d :MdDoc id :MdBlockId] :(Option String))

a leaf block's text.

A paragraph's or heading's source text, trimmed, with its inner line endings and its inline syntax kept (markdown/inlines has it parsed); a table cell's, the same, with each \| written as |; a code block's contents, ending in a line feed; an HTML block's HTML; or a display formula's TeX, ending in a line feed.

(markdown/block-text d id)  ; => (some "code\n") for "    code"

Since: markdown-library-plan M1

(markdown/code-info [d :MdDoc id :MdBlockId] :(Option String))

a fenced code block's info string.

(markdown/code-info d id)  ; => (some "python") for a fence whose info string is python

Since: markdown-library-plan M1

(markdown/list-marker [d :MdDoc id :MdBlockId] :(Option Char))

a list's marker: a bullet list's bullet, or the delimiter after an ordered list's numbers.

(markdown/list-marker d id)  ; => (some #\)) for "1) one\n2) two"

Since: markdown-library-plan M5

(markdown/block-lines [d :MdDoc id :MdBlockId] :(Pair int int))

the source lines a block spans.

(markdown/block-lines d id)  ; => (pair 3 4) for a paragraph on lines 3-4

Since: markdown-library-plan M1

(markdown/render-block-html [d :MdDoc id :MdBlockId opts :MdHtmlOpts] :String)

the HTML for one block and everything in it, as markdown/render-html writes it in place.

A heading keeps the id it has in the whole document's HTML, and a paragraph of a tight list is still written without <p>, so rendering each of the root's children in turn gives the document's HTML.

(markdown/render-block-html d id (markdown/default-html-opts))  ; => "<p>Hi</p>\n"

Since: markdown-library-plan M5

(md/-blocks-of [d :MdDoc keep? :(fn [MdKind] bool)] :(Vec MdBlockId))

internal: the blocks for which keep? holds, in document order, as MdBlockIds.

(markdown/headings [d :MdDoc] :(Vec MdBlockId))

every heading of a document, in order.

Headings inside block quotes and list items are in it too, where they come in the text. markdown/heading-ids lists their ids in the same order.

(vec-len (markdown/headings d))  ; => 2 for "# A\n\n> ## B\n"

Since: markdown-library-plan M3

(markdown/heading-text [d :MdDoc id :MdBlockId] :(Option String))

a heading's content as plain text, for a table of contents.

The text of its inlines: code spans' contents included, raw HTML and images' alt text left out, character references decoded, and each run of whitespace one space. It is the text the heading-id rules start from.

(markdown/heading-text d id)  ; => (some "Use make here") for "## Use `make` *here*"

Since: markdown-library-plan M3

(markdown/heading-html [d :MdDoc id :MdBlockId opts :MdHtmlOpts] :(Option String))

a heading's content as markdown/render-html writes it, for a table of contents.

The HTML between the heading's tags: its inlines rendered with opts, so the raw-HTML rule is the page's. No id is in it; markdown/heading-ids has those.

(markdown/heading-html d id (markdown/default-html-opts))
; => (some "Use <code>make</code>") for "## Use `make`"

Since: markdown-library-plan M4

(markdown/heading-ids [d :MdDoc opts :MdHtmlOpts] :(Vec String))

the id markdown/render-html gives each heading.

One per heading, in the order markdown/headings lists them, by the rule opts's heading-ids names, made unique in the document as that rule does. Under (MdNoIds) the renderer writes none, and the Vec is empty.

(markdown/heading-ids d (MdHtmlOpts (MdRawTagFilter) (MdSlugPython)))
; => ["intro" "intro_1"] for "# Intro\n# Intro\n"

Since: markdown-library-plan M3

(markdown/code-blocks [d :MdDoc] :(Vec MdBlockId))

every code block of a document, fenced or indented, in order.

markdown/code-info, markdown/block-text and markdown/block-lines read each one's info string, contents and source lines.

(vec-len (markdown/code-blocks d))  ; => 1 for "```c\nx;\n```\n"

Since: markdown-library-plan M3

(defstruct MdInlineId :copy [ix :int])

an inline of a parsed document. Valid only with the MdDoc it came from.

(defdata MdInline :copy (MdText) (MdCode) (MdEmph) (MdStrong) (MdLink) (MdImage) (MdHtmlInline) (MdSoftBreak) (MdHardBreak) (MdStrikethrough) (MdMath bool))

what an inline is.

MdText, MdCode, MdHtmlInline and MdMath carry text (markdown/inline-text). MdEmph, MdStrong, MdStrikethrough, MdLink and MdImage hold inlines (markdown/inline-children). A link's or image's destination and title come from markdown/link-dest and markdown/link-title, and an image's children are its alt text. An autolink, extended ones included (www., scheme:// or an email address), is an MdLink. (MdMath display) is a formula, with math on: $...$, or $$...$$ when display is true.

(md/-inl-of [d :MdDoc id :MdInlineId] :MdInl)

internal: the arena inline behind id.

(md/-inl-ids [d :MdDoc i :int] :(Vec MdInlineId))

internal: inline i's children as MdInlineIds.

(markdown/inlines [d :MdDoc id :MdBlockId] :(Vec MdInlineId))

a paragraph's, heading's or table cell's inlines, in order.

(vec-len (markdown/inlines d id))  ; => 2 for the paragraph "a *b*": text, then emphasis

Since: markdown-library-plan M2

(markdown/inline-children [d :MdDoc id :MdInlineId] :(Vec MdInlineId))

the inlines inside emphasis, strong emphasis, strikethrough, a link or an image.

(vec-len (markdown/inline-children d id))  ; => 1 for *b*: the text b

Since: markdown-library-plan M2

(markdown/inline [d :MdDoc id :MdInlineId] :MdInline)

what an inline is.

(markdown/inline d id)  ; => (MdStrong) for **b**

Since: markdown-library-plan M2

(markdown/inline-text [d :MdDoc id :MdInlineId] :(Option String))

the text of a text, code, raw-HTML or math inline.

A text inline's escapes and character references are resolved; a code span's contents have their line endings as spaces; raw HTML is as written, and so is a formula's TeX, without its $ delimiters.

(markdown/inline-text d id)  ; => (some "x") for `x`

Since: markdown-library-plan M2

(markdown/link-dest [d :MdDoc id :MdInlineId] :(Option String))

a link's or image's destination.

With escapes and references resolved and the URL percent-encoded, as the HTML renderer writes it; mailto: comes first for an email autolink.

(markdown/link-dest d id)  ; => (some "/a%20b") for [x](</a b>)

Since: markdown-library-plan M2

(markdown/link-title [d :MdDoc id :MdInlineId] :(Option String))

a link's or image's title.

(markdown/link-title d id)  ; => (some "t") for [x](/u "t")

Since: markdown-library-plan M2