On this page

Guidedog / Documentation 0.2.0

readers/commonmark

Package commonmark reads Markdown into a Guidedoc document without calling an allocator, as two readers with distinct ids: “commonmark” (reader, read, read_inline) is pure CommonMark 0.31.2 and takes no settings; “myst” (myst_reader, read_myst, read_myst_inline) is the MyST Markdown that Sphinx projects write (myst-parser 0.16.1): directives, roles, targets, comments, front matter, footnotes, GFM tables, and the optional syntax that Settings.enable_extensions turns on.

Block structure is parsed line by line into a skeleton in scratch; link reference definitions are collected over the whole document; then the skeleton is emitted in preorder, with inline content parsed per paragraph and heading. Directive content is parsed the same way when the directive asks for it (see extension.odin), so a parse works on line views of any source.

Types

commonmark.Directive :: struct

Directive is a directive the reader has split into its parts. Lines are views of source.

name: string

name_span: gd.Source_Span

span: gd.Source_Span

source: gd.Source_Id

arg: []Line

the argument; empty when there is none.

options: []Option

content: []Line

sections: bool

the directive stands where sections are allowed.

classes: gd.Text

classes a handler leaves for the next element (Docutils’ class directive without content); the reader gives them to the next block it emits.

commonmark.Directive_Handler :: struct

name: string

compared case-insensitively.

run: Directive_Proc

commonmark.Directive_Proc :: #type proc(h: ^Host, d: ^Directive, user: rawptr) -> Directive_Result

Directive_Proc runs a parsed directive; user is Extension.user. The directive and its lines are borrowed for the call.

commonmark.Directive_Result :: enum u8

Ran

Unknown

the handler does not know the name; the reader reports it.

Failed

the handler refused the directive and reported why.

commonmark.Directive_Shape :: struct

Directive_Shape tells the reader how a directive takes its first line: as an argument, or, for a directive without arguments, as the first line of content; and whether it takes options at all.

argument: bool

options: bool

it has options; without, an option block stays content.

commonmark.Extension :: struct

directives: []Directive_Handler

directive: Directive_Proc

directive is offered every directive the table does not list.

shape: proc(h: ^Host, name: string, user: rawptr) -> (Directive_Shape, bool)

shape describes a directive by name; found is false for an unknown directive.

roles: []Role_Handler

role: Role_Proc

role is offered every role the table does not list.

table: proc(h: ^Host, id: gd.Node_Id, span: gd.Source_Span, columns: int, user: rawptr) -> bool

table runs after the reader opens a Table node, before its rows, so a table directive around it can add its title and attributes; it returns true when it did, and the reader then adds no attributes of its own.

begin: proc(h: ^Host, user: rawptr)

before the document’s blocks.

end: proc(h: ^Host, user: rawptr)

after them.

resolve: proc(h: ^Host, user: rawptr) -> gd.Status

resolve, when set, links references, targets, and footnotes instead of the reader’s own resolution (resolve.odin); the Sphinx layer resolves as for reStructuredText.

user: rawptr

commonmark.Host :: struct

Host is the reader’s document-wide state, shared by the parse of the document and the parses of nested content. Directive and role handlers receive it and treat it as opaque: they reach the read through context_of and the procedures below.

ctx: ^gd.Read_Context

b: ^gd.Builder

settings: Settings

ext: ^Extension

myst: bool

the MyST syntax is on: the “myst” reader, not “commonmark”.

disabled: Rules

myst_disable_syntax.

syntax: Syntax_Extensions

myst_enable_extensions in force.

refs: []Ref

Link reference definitions, collected over the whole document.

nrefs: int

names: gd.Symbol_Table

labels: gd.Buffer

label_tmp: []u8

html_format: gd.Text

rel_images: bool

MyST include options in force: rewrite image paths, and link paths starting with rel_docs, of included sources to be relative to the main source.

rel_docs: string

using state: Myst_State

commonmark.Line :: gd.Line_View

Line is a view of one input line: its text without the line break, and the source offset of text[0]. Directive handlers pass nested content as lines.

commonmark.Meta :: struct

Meta is one HTML meta tag: key as MyST writes it (“description lang=en”, “http-equiv=Content-Type”, “keywords”) and its content.

key: string

content: string

commonmark.Option :: struct

Option is one directive option: its name and value lines. A value written as a YAML scalar has its quoting and folding processed; its lines may then be copies in scratch, whose offset is where the value starts in the source.

name: string

value: []Line

span: gd.Source_Span

commonmark.Role :: struct

Role is one role, {name}`content`. lines hold the whole construct, split at line breaks; content is the range of the content in the lines joined by “\n”.

name: string

lines: []Line

content: [2]int

span: gd.Source_Span

source: gd.Source_Id

commonmark.Role_Handler :: struct

name: string

compared case-insensitively.

run: Role_Proc

commonmark.Role_Proc :: #type proc(h: ^Host, r: ^Role, user: rawptr) -> bool

Role_Proc handles a role; it returns false for a role it does not know.

commonmark.Rule :: enum u8

Rule names a syntax element that myst_disable_syntax can turn off, by markdown-it’s rule name.

Table

Code

Fence

Blockquote

Hr

List

Reference

Html_Block

Heading

Lheading

Emphasis

Backticks

Link

Image

Autolink

Html_Inline

Entity

Escape

Newline

Front_Matter

Myst_Target

Myst_Line_Comment

Myst_Block_Break

Myst_Role

Math_Block

Math_Inline

Footnote_Def

Footnote_Ref

Myst_Directive

not a markdown-it rule: {name} fences (off with commonmark_only).

commonmark.Settings :: struct

Settings are the “myst” reader’s settings: myst-parser 0.16.1’s myst_* configuration values, named without the prefix. They reach the reader through gd.Read_Options.extension, made with gd.read_extension(&settings); an empty extension means default_settings(). The “commonmark” reader (pure CommonMark) takes none. A caller that supplies Settings starts from default_settings(), because several defaults are not zero.

extension: ^Extension

Directive and role handlers (the Sphinx layer provides them); nil means none, and directives and roles are then reported as unknown.

commonmark_only: bool

myst_commonmark_only: CommonMark syntax only (no directives, roles, or other MyST syntax), but a document’s tree as for MyST: headings make sections.

enable_extensions: Syntax_Extensions

myst_enable_extensions: the optional syntax. Default {.Dollarmath}.

disable_syntax: []string

myst_disable_syntax: markdown-it rule names whose syntax is not parsed, e.g. “emphasis”, “table”, “html_block” (see syntax_rule).

url_schemes: []string

myst_url_schemes: schemes of [text](scheme:...) links that are external; other destinations are cross-references. nil recognizes every scheme. Default http, https, mailto, and ftp.

linkify_fuzzy_links: bool

myst_linkify_fuzzy_links: linkify recognizes URLs without a scheme. Default true.

heading_anchors: int

myst_heading_anchors: headings up to this level get a GitHub-style slug anchor that [](#slug) and [](file.md#slug) reach. 0 means none.

heading_slug_func: string

myst_heading_slug_func is a Python callable and cannot be supported; a non-empty value is reported and the built-in slugs are used.

substitutions: []Substitution

myst_substitutions: global substitutions; front matter overrides them.

sub_delimiters: [2]u8

myst_sub_delimiters: the characters doubled around substitution references. Default {‘{‘, ‘}’}, giving {{ name }}.

html_meta: []Meta

myst_html_meta: HTML meta tags for every document; front matter html_meta overrides entries with the same key.

footnote_transition: bool

myst_footnote_transition: a transition of class “footnotes” precedes the footnotes at the end of the document. Default true.

dmath_allow_labels: bool

myst_dmath_allow_labels: $$...$$ (label). Default true.

dmath_allow_space: bool

myst_dmath_allow_space: inline math may start or end with a space. Default true.

dmath_allow_digits: bool

myst_dmath_allow_digits: inline math may follow or precede a digit. Default true.

dmath_double_inline: bool

myst_dmath_double_inline: $$...$$ inside a paragraph. Default false.

words_per_minute: int

myst_words_per_minute: for the wordcount-minutes substitution. Default 200.

docname: string

The document’s name (“usage/intro”) and configuration values, which substitutions reach as env.docname and env.config.<name>.

env_config: []Substitution

today: string

The {sub-ref} today: the project’s formatted date; empty is Read_Options.today.

commonmark.Substitution :: struct

A substitution’s value is Markdown, or a mapping written as nested YAML that dotted names reach (“key.sub”).

name: string

value: string

commonmark.Syntax_Extension :: enum u8

Syntax_Extension names an entry of myst_enable_extensions.

Amsmath

Colon_Fence

Deflist

Dollarmath

Fieldlist

Html_Admonition

Html_Image

Linkify

Replacements

Smartquotes

Substitution

Tasklist

commonmark.Syntax_Extensions :: bit_set[Syntax_Extension; u16]

Procedures

commonmark.context_of :: proc(h: ^Host) -> ^gd.Read_Context

context_of returns the read context, for handlers that build nodes.

commonmark.default_settings :: proc() -> Settings

default_settings returns myst-parser 0.16.1’s defaults. The value borrows only static data (the default URL schemes); fields a caller sets must outlive the read.

commonmark.include_paths :: proc(h: ^Host, images: bool, docs: string) -> (bool, string)

include_paths sets MyST’s include options :relative-images: and :relative-docs: for the content of the include directive being run; it returns the previous values.

commonmark.list_items :: proc(h: ^Host, lines: []Line, source: gd.Source_Id) -> (items: [][]Line, starts: []int, ok: bool)

list_items splits lines that hold one bullet list into the content lines of its items, and where each item starts in lines (for list-table). ok is false when the lines are anything but one bullet list. The results live in scratch.

commonmark.myst_reader :: proc() -> gd.Reader

myst_reader returns the “myst” reader by value: MyST Markdown with ^Settings.

commonmark.parse_body :: proc(h: ^Host, lines: []Line, source: gd.Source_Id, sections := false, classes := gd.Text{})

parse_body parses lines of a source as Markdown body content of the builder’s open node. sections lets headings open sections, as at the top of a document; classes, when set, go to every top-level element.

commonmark.parse_inline :: proc(h: ^Host, lines: []Line, source: gd.Source_Id)

parse_inline parses lines of a source as Markdown inline content of the builder’s open node.

commonmark.read :: proc(ctx: ^gd.Read_Context) -> gd.Status

read reads ctx.source as pure CommonMark 0.31.2 (gd.Read_Proc): headings, no sections. Any settings in the read options are refused with Invalid_Input. It borrows ctx for the call; its skeleton lives in scratch, released before it returns. Problems go to ctx.reports; the result is the builder’s status (.Capacity when a table is full).

commonmark.read_inline :: proc(ctx: ^gd.Read_Context, span: gd.Source_Span) -> gd.Status

read_inline parses a span of ctx.source as CommonMark inline content of the builder’s open node, for a translated message (gd.Read_Inline_Proc). Link reference definitions and footnote definitions of the surrounding document are not known to it.

commonmark.read_myst :: proc(ctx: ^gd.Read_Context) -> gd.Status

read_myst reads ctx.source as MyST Markdown (gd.Read_Proc), with the ^Settings the read options carry (gd.read_extension), or default_settings when they carry none. Settings of another type are refused with Invalid_Input. Ownership and failures are read’s; the settings are borrowed for the call.

commonmark.read_myst_inline :: proc(ctx: ^gd.Read_Context, span: gd.Source_Span) -> gd.Status

read_myst_inline is read_inline for MyST, with the settings of ctx.options.extension (roles included), as read_myst takes them.

commonmark.reader :: proc() -> gd.Reader

reader returns the “commonmark” reader by value: pure CommonMark 0.31.2, no settings.

commonmark.syntax_extension_named :: proc(name: string) -> (Syntax_Extension, bool)

syntax_extension_named finds a myst_enable_extensions entry by its name.

commonmark.syntax_rule :: proc(name: string) -> (Rule, bool)

syntax_rule finds a myst_disable_syntax entry by its markdown-it rule name.

Constants

commonmark.CONFORMANCE :: gd.Conformance.Conformant

commonmark.MYST_CONFORMANCE :: gd.Conformance.Partial

commonmark.MYST_VERSION :: "0.16.1"

MyST follows myst-parser 0.16.1, with the differences CONFORMANCE.md documents.

commonmark.VERSION :: "0.31.2"