Text and Markup
markdown
import markdown
ZuriConverts 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>
HTMLEvery 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())
Zuripreset 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.
Raw HTML and links
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
htmlfor Markdown that you wrote yourself. - A link or image whose destination uses
javascript:,vbscript:orfile:, or adata:URL that isn't an image, gets an empty destination. Setunsafe_linksto keep them. - An attribute written as
{key=value}whose name isn't on a short list of safe names is renamed todata-key, so{onclick=...}can't run a script. Settinghtmlturns 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$
markdownMath 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
}
Zuriuse() 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')
ZuriSee 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
ZuriCreates 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>
ZuriParameters
options(?dict)
Returns Markdown
Raises ValueError When an option is unknown or has the wrong type
render()
markdown.render(source: string, options: ?dict) -> string
ZuriConverts 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
ZuriParses 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
ZuriConverts 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
ZuriReturns 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
ZuriParameters
text(string)style(?string)
Returns string
Raises ValueError When style is neither 'github' nor
'pandoc'
escape()
markdown.escape(text: string) -> string
ZuriReturns 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>
ZuriParameters
text(string)
Returns string
Classes
Markdown
class markdown.Markdown
ZuriParses 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(), soechoandprint()show something useful
Fields
| Field | Type | Description |
|---|---|---|
options |
dict |
Every option, resolved from the options given and their preset. |
Constructor
markdown.Markdown(options: ?dict)
ZuriParameters
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
ZuriAdds 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')
}
})
ZuriParameters
transform(function)
Returns Markdown
Markdown.parse()
markdown.Markdown.parse(source: string)
ZuriParses 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
ZuriConverts 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
ZuriConverts 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
ZuriParameters
source(string)
Returns string
Markdown.to_html()
markdown.Markdown.to_html(node: instance) -> string
ZuriConverts 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]
ZuriReturns 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}'
}
ZuriParameters
doc(Node)
Returns list[dict]
2026, Richard Ore and Zuri contributors