The complete reference for every script-facing builtin, the converter object it
returns, and the configuration accessor exposed by the markdown module. For an
overview, installation, and a quickstart, see the README.
The module exposes two top-level builtins via load("markdown", …) — convert
and create_converter — plus a read-only configuration accessor (get_<key>)
generated from the module's one option. That option (max_input_bytes) is
host-only, so no set_<key> setter is generated. create_converter hands back a
callable named custom_converter with its rendering options frozen in.
convert(text, unsafe?, heading_id?, linkify?, table?, task_list?, strikethrough?, footnote?, definition?, typograph?, emoji?, hard_wraps?)
Converts Markdown text to an HTML string in one call.
Parameters:
text(string / bytes / None): Markdown source to convert. The argument is required — omitting it entirely is an error — butNonerenders as an empty document, andbytesare decoded as UTF-8.unsafe(bool): Pass raw inline/block HTML through instead of filtering it (default:False; see Safety).heading_id(bool): Auto-generateidattributes for headings (default:True).linkify(bool): Auto-link bare URLs (default:True).table(bool): Enable GFM tables (default:True).task_list(bool): Enable task-list checkboxes (- [ ]/- [x]) (default:True).strikethrough(bool): Enable~~strikethrough~~(default:True).footnote(bool): Enable footnotes ([^1]) (default:False).definition(bool): Enable definition lists (default:False).typograph(bool): Enable the typographer — smart quotes, dashes, ellipses (default:False).emoji(bool): Enable GitHub-style emoji shortcodes (:smile:) (default:False).hard_wraps(bool): Convert source newlines to<br>(default:False).
See Rendering options for the shared option reference.
Returns: The rendered HTML (string).
Errors: Fails if text is omitted, if the input exceeds the configured
max_input_bytes cap (see Configuration), or if the underlying
renderer fails. A panic in the renderer is recovered and surfaced as a normal
script error, so malformed input never crashes the host.
Example:
load("markdown", "convert")
# Basic conversion.
html = convert(text="# Hello World\n\nThis is **bold** text.")
print(html)
# <h1 id="hello-world">Hello World</h1>
# <p>This is <strong>bold</strong> text.</p>
# Enable extra extensions per call.
html = convert(
text="""
- [x] Done
- [ ] Todo
| Name | Value |
|------|-------|
| Key | Val |
Visit https://example.com
I :heart: Markdown!
""",
footnote=True,
emoji=True,
)create_converter(unsafe?, heading_id?, linkify?, table?, task_list?, strikethrough?, footnote?, definition?, typograph?, emoji?, hard_wraps?)
Builds a reusable converter with rendering options preset, and returns a
callable named custom_converter that renders Markdown with those frozen-in
options. Useful when many strings share the same rendering configuration.
Parameters: the same option set as convert,
minus text — the source string is supplied later, on each call to the
returned converter. See Rendering options for the shared
option reference.
Returns: A custom_converter callable.
Example:
load("markdown", "create_converter")
# Build a reusable converter with preset options.
to_html = create_converter(table=False, linkify=False, hard_wraps=True)
print(to_html("# Title\n\nFirst line\nSecond line"))The callable returned by
create_converter.
It renders Markdown using the options captured at create_converter time and
accepts no further option keywords.
Parameters:
text(string): Markdown source to render — a single positional argument. Unlikeconvert, this entry point accepts a string only (notbytesorNone).
Returns: The rendered HTML (string).
Errors: The same max_input_bytes cap is enforced on every call; oversized
input and renderer failures surface as script errors (renderer panics are
recovered), exactly as with convert.
Example:
load("markdown", "create_converter")
render = create_converter(emoji=True, footnote=True)
print(render("# Notes\n\nReady :tada:"))
print(render("Another **document**."))Both convert
and create_converter
accept the same rendering options (only convert takes the text argument).
The defaults reproduce the historical behavior: heading IDs, linkify, tables,
task lists, and strikethrough on; everything else off.
| Option | Type | Default | Description |
|---|---|---|---|
text |
string / bytes / None | (required) | Markdown text to convert (convert only); the argument is required, but None renders as empty |
unsafe |
bool | False |
Pass raw inline/block HTML through instead of filtering it (see Safety) |
heading_id |
bool | True |
Auto-generate id attributes for headings |
linkify |
bool | True |
Auto-link bare URLs |
table |
bool | True |
Enable GFM tables |
task_list |
bool | True |
Enable task-list checkboxes (- [ ] / - [x]) |
strikethrough |
bool | True |
Enable ~~strikethrough~~ |
footnote |
bool | False |
Enable footnotes ([^1]) |
definition |
bool | False |
Enable definition lists |
typograph |
bool | False |
Enable the typographer (smart quotes, dashes, ellipses) |
emoji |
bool | False |
Enable GitHub-style emoji shortcodes (:smile:) |
hard_wraps |
bool | False |
Convert source newlines to <br> |
Raw HTML embedded in the Markdown source is filtered out by default
(unsafe=False) — goldmark replaces it with an HTML comment placeholder. This
secure-by-default posture matches the rest of the ecosystem and prevents
script-supplied Markdown from injecting arbitrary HTML/JS.
load("markdown", "convert")
src = "Hello <script>alert('x')</script> world"
convert(text=src) # raw <script> is stripped (default)
convert(text=src, unsafe=True) # opt in: raw HTML passes throughOnly set unsafe=True when you fully trust the Markdown source. Conversion
panics from the underlying renderer are also recovered into normal errors, so
malformed input never crashes the host.
The module's one configuration option is exposed to scripts through generated
accessor builtins (loaded from the markdown module alongside the functions
above):
get_<key>()— returns the current value of the option.set_<key>(value)— sets the option (returnsNone) — generated only for options that are not host-only.
An option's value resolves in priority order: an explicit host value, the environment variable, then the default.
Both options are host-only DoS levers, so the host stays in control: only the
getters (get_max_input_bytes, get_max_convert_time) are generated —
set_max_input_bytes and set_max_convert_time are intentionally NOT exposed,
so a script cannot disable or widen a limit (e.g. set_max_input_bytes(0)). The
host sets them in Go (the option default) or via the MARKDOWN_* environment
variables. Their values are snapshotted when the module is constructed, so a
script cannot re-widen them at runtime by mutating the environment either (e.g.
via a runtime.setenv builtin loaded alongside this module).
max_input_bytes bounds input size, but goldmark's nested block-quote / list
parsing is roughly O(n²) — an input well under the byte cap can still spin the
CPU — so max_convert_time bounds a single conversion's wall-clock time
(0 = no module limit; the conversion is still bounded by the thread context
deadline if the host set one). A conversion exceeding it returns a time-limit
error.
| Option | Getter | Setter | Type | Env var | Default | Description |
|---|---|---|---|---|---|---|
max_input_bytes |
get_max_input_bytes |
set_max_input_bytes — host-only, not generated |
int | MARKDOWN_MAX_INPUT_BYTES |
5242880 |
Maximum input size in bytes when converting (5 MiB); 0 disables the cap (host-set only) |
max_convert_time |
get_max_convert_time |
set_max_convert_time — host-only, not generated |
float | MARKDOWN_MAX_CONVERT_TIME |
0 |
Maximum wall-clock seconds for a single conversion; 0 = no module limit (still bounded by the thread context deadline) |
Untrusted Markdown is bounded by this input-size cap before it reaches the
renderer — input longer than max_input_bytes is rejected with a clean error
(matching the yaml / toml modules). The cap is enforced on every conversion
path: both convert and the custom_converter returned by create_converter.
Example:
load("markdown", "convert", "get_max_input_bytes")
print(get_max_input_bytes()) # 5242880 (host-controlled; scripts can only read it)
html = convert(text="# Within the cap")