The Zuri Standard Library Zuri

Text and Markup

markdown

import markdown
Zuri

Converts Markdown to HTML. It follows CommonMark and GitHub Flavored Markdown, and supports the extensions that Pandoc made popular, such as tables of contents, abbreviations, definition lists, attributes, footnotes and math.

import markdown

echo markdown.render('# Hello\n\nSome *emphasis* and a [link](https://example.com).')
Zuri
<h1>Hello</h1>
<p>Some <em>emphasis</em> and a <a href="https://example.com">link</a>.</p>
HTML

Every string is a valid document, so parsing and rendering never fail because of the Markdown itself. Text that doesn't match any Markdown syntax is rendered as plain text.


Flavors

markdown() takes a dictionary of options, and returns a Markdown object that parses and renders with them. If you render more than one document, create one and reuse it. The module's own render() and parse() functions take the same options, for a single document.

import markdown

var md = markdown({ preset: 'extended', html: true })

echo md.render(file('README.md').read())
Zuri

preset sets the starting value of every other option:

Preset What it turns on
'commonmark' Nothing beyond the CommonMark specification.
'gfm' The default. GitHub's tables, strikethrough, autolinks, task lists, footnotes, tag filter, alerts and emoji.
'extended' GFM, plus every extension below except metadata, along with heading identifiers and smart punctuation.

An option given alongside the preset overrides it, so { preset: 'commonmark', tables: true } is CommonMark with tables.


Markdown is often written by someone other than the person running the site, so by default it's treated as untrusted:

  • Raw HTML is shown as text instead of being passed through. Set html for Markdown that you wrote yourself.
  • A link or image whose destination uses javascript:, vbscript: or file:, or a data: URL that isn't an image, gets an empty destination. Set unsafe_links to keep them.
  • An attribute written as {key=value} whose name isn't on a short list of safe names is renamed to data-key, so {onclick=...} can't run a script. Setting html turns this off too.

With html on and the gfm preset, GFM's tag filter still escapes <script>, <style>, <iframe>, <textarea>, <title>, <xmp>, <noembed>, <noframes> and <plaintext>. Turn tag_filter off to allow them.


Options

Option Default Effect
preset 'gfm' The starting values of the other options.
html false Pass raw HTML through.
unsafe_links false Keep javascript: and similar destinations.
breaks false Render every line ending in a paragraph as <br />, as GitHub does in comments.
smart false Curly quotes, -- and --- as dashes, and ... as an ellipsis.
tables GFM Pipe tables.
strikethrough GFM ~~struck~~.
autolinks GFM Bare www., http:// and email addresses become links.
task_lists GFM - [ ] and - [x] items.
footnotes GFM [^1] references, [^1]: ... footnotes, and Pandoc's ^[inline] notes.
tag_filter GFM Escape the tags listed above in raw HTML.
alerts GFM > [!NOTE] and the other GitHub alerts.
emoji GFM :tada: and the other GitHub shortcodes.
heading_ids false Give every heading an id. Use true or 'github' for GitHub's style, 'pandoc' for Pandoc's, or a function that takes the heading's text and returns an id.
id_prefix '' A prefix for every generated heading id.
toc false Replace a paragraph that's just [TOC] with a table of contents. Turns on heading_ids.
toc_levels [1, 6] The lowest and highest heading levels in the table of contents.
attributes false {#id .class key=value} after headings, code, links, images and fenced code, and [text]{.class} spans.
abbreviations false *[HTML]: HyperText Markup Language definitions.
definition_lists false Terms with : definition lines under them.
superscript false 2^10^.
subscript false H~2~O.
mark false ==highlighted==.
math false $inline$, $$display$$ and ```math blocks.
divs false ::: name fenced divs.
line_blocks false Lines starting with `
metadata false YAML front matter between --- lines, read into the document's metadata.
highlight nil A function that's given each code block's text and language, and returns its markup or nil.
renderer HtmlRenderer The class that turns the tree into HTML.

The extensions

---
title: Field notes
---

[TOC]

## Results {#results .highlight}

Water is H~2~O and 2^10^ is 1024. ==Remember this.==

The HTML spec is long.[^1]

*[HTML]: HyperText Markup Language
[^1]: Very long.

Term
: Its definition.

::: warning
A fenced div, with the class `warning`.
:::

| The limerick packs laughs anatomical
| In space that is quite economical.

Euler: $e^{i\pi} + 1 = 0$
markdown

Math is output for MathJax or KaTeX to typeset. Inline math becomes <span class="math inline">\(...\)</span>, and display math becomes <span class="math display">\[...\]</span>.


The tree

parse() returns the document as a tree of Node objects. Use it when you need something other than the HTML, such as collecting the headings, checking the links, or taking the first paragraph as a summary.

import markdown

var doc = markdown.parse('# Title\n\nSee [the docs](/docs) and [the spec](/spec).')

for link in doc.find_all('link') {
  echo link.destination
}
Zuri

use() adds a transform. A transform is a function that's given each document after it's parsed, and can change it before it's rendered:

import markdown

var md = markdown().use(@(doc) {
  for heading in doc.find_all('heading') {
    heading.level = (heading.level + 1).min(6)
  }
})

echo md.render('# Becomes an h2')
Zuri

See markdown.renderer for how to change the HTML that a node is rendered as.

The module is callable. markdown(...) is the same call as markdown.markdown(...), documented below.

The markdown API

Every public name in markdown, wherever it is declared. Each links to the page that documents it.

Name Kind Summary
markdown.HtmlRenderer class Renders a parsed document as HTML.
markdown.Markdown class Parses and renders Markdown with a fixed set of options.
markdown.MarkdownError class The base class of every error that this module raises.
markdown.MetadataError class Raised when front matter can't be read, because it isn't valid YAML or it isn't a mapping.
markdown.Node class A node in a parsed Markdown document.
markdown.escape function Returns text with a backslash before each character that Markdown could treat as syntax, so that it's...
markdown.markdown function Creates a Markdown object with options, which are described in the module documentation.
markdown.parse function Parses source into a tree, using options or the defaults.
markdown.render function Converts source to HTML, using options or the defaults.
markdown.render_inline function Converts source to HTML without wrapping it in a paragraph, using options or the defaults.
markdown.slug function Returns the identifier that a heading with the text text is given.

Submodules

Module Reached as Summary
markdown.errors markdown.errors.* The errors that the markdown module raises.
markdown.node markdown.node.* The tree that markdown.parse() builds.
markdown.renderer markdown.renderer.* Converts a parsed document to HTML.

Functions

markdown()

markdown.markdown(options: ?dict) -> Markdown
Zuri

Creates a Markdown object with options, which are described in the module documentation.

import markdown

var md = markdown({ html: true, heading_ids: true })
echo md.render('# Guide')
# <h1 id="guide">Guide</h1>
Zuri

Parameters

  • options (?dict)

Returns Markdown

Raises ValueError When an option is unknown or has the wrong type

render()

markdown.render(source: string, options: ?dict) -> string
Zuri

Converts source to HTML, using options or the defaults.

To render several documents with the same options, create a Markdown with markdown() and reuse it, so that the options are only resolved once.

Parameters

  • source (string)
  • options (?dict)

Returns string

Raises ValueError When an option is unknown or has the wrong type

parse()

markdown.parse(source: string, options: ?dict) -> Node
Zuri

Parses source into a tree, using options or the defaults.

Parameters

  • source (string)
  • options (?dict)

Returns Node

Raises ValueError When an option is unknown or has the wrong type

render_inline()

markdown.render_inline(source: string, options: ?dict) -> string
Zuri

Converts source to HTML without wrapping it in a paragraph, using options or the defaults. See Markdown.render_inline().

Parameters

  • source (string)
  • options (?dict)

Returns string

slug()

markdown.slug(text: string, style: ?string) -> string
Zuri

Returns the identifier that a heading with the text text is given. The number that's added to tell repeated headings apart isn't included. style is 'github', the default, or 'pandoc'.

import markdown

echo markdown.slug('Hello, World!')            # hello-world
echo markdown.slug('3. Results', 'pandoc')     # results
Zuri

Parameters

  • text (string)
  • style (?string)

Returns string

Raises ValueError When style is neither 'github' nor 'pandoc'

escape()

markdown.escape(text: string) -> string
Zuri

Returns text with a backslash before each character that Markdown could treat as syntax, so that it's rendered as plain text. Line breaks and indentation are kept.

import markdown

var name = '*not* a [link]'
echo markdown.render('Hello, ${markdown.escape(name)}')
# <p>Hello, *not* a [link]</p>
Zuri

Parameters

  • text (string)

Returns string

Classes

Markdown

class markdown.Markdown
Zuri

Parses and renders Markdown with a fixed set of options.

Create one with markdown(). A Markdown object keeps no state between documents, so a program can use one for all of its documents.

  • printable — has a @to_string(), so echo and print() show something useful

Fields

Field Type Description
options dict Every option, resolved from the options given and their preset.

Constructor

markdown.Markdown(options: ?dict)
Zuri

Parameters

  • options (?dict) — see the module documentation for the full list.

Raises ValueError When an option is unknown or has the wrong type

Markdown.use()

markdown.Markdown.use(transform: function) -> Markdown
Zuri

Adds transform, a function that's called with each document after it's parsed, and can change it. Transforms run in the order they were added. Returns this Markdown, so that calls can be chained.

import markdown

# Every link opens in a new tab.
var md = markdown().use(@(doc) {
  for link in doc.find_all('link') {
    link.attributes.set('target', '_blank')
  }
})
Zuri

Parameters

  • transform (function)

Returns Markdown

Markdown.parse()

markdown.Markdown.parse(source: string)
Zuri

Parses source into a tree of nodes, and applies the transforms.

Parameters

  • source (string)

Returns — Node: a node of type document.

Raises MetadataError When metadata is on and the front matter is not a YAML mapping

Markdown.render()

markdown.Markdown.render(source: string) -> string
Zuri

Converts source to HTML.

Parameters

  • source (string)

Returns string

Raises MetadataError When metadata is on and the front matter is not a YAML mapping

Markdown.render_inline()

markdown.Markdown.render_inline(source: string) -> string
Zuri

Converts source to HTML without wrapping it in a paragraph. Use it for a line of Markdown that goes where a block can't, such as a title or a table cell. Block syntax isn't recognized, so # x stays # x.

import markdown

echo markdown().render_inline('A *short* title')
# A <em>short</em> title
Zuri

Parameters

  • source (string)

Returns string

Markdown.to_html()

markdown.Markdown.to_html(node: instance) -> string
Zuri

Converts node and its descendants to HTML, using the class given by the renderer option.

Parameters

  • node (Node)

Returns string

Markdown.toc()

markdown.Markdown.toc(doc: instance) -> list[dict]
Zuri

Returns the headings of doc as a table of contents. The result is a list of dictionaries with level, text, id and children keys, where children holds the headings nested under each one. Only the levels in the toc_levels option are included. id is nil unless heading_ids or toc is on.

import markdown

var md = markdown({ heading_ids: true })
var doc = md.parse('# Guide\n\n## Install\n\n## Use')

for entry in md.toc(doc)[0].children {
  echo '${entry.text} -> #${entry.id}'
}
Zuri

Parameters

  • doc (Node)

Returns list[dict]


2026, Richard Ore and Zuri contributors