smalldocs.markdown

Pandoc-flavoured Markdown to the HTML that Quarto makes, with markdown-it-py and a few rules of our own.

class Attrs

source

Attrs(id: str = '', classes: list[str] = <factory>, kv: dict[str, str] = <factory>)

Pandoc attributes: {#id .class key=value}.

Parameter Type Default Description
id str '' The identifier, without the #
classes list[str] <factory> The classes, without the dots
kv dict[str, str] <factory> The other key and value pairs

Attrs.html

source

Attrs.html() -> str

Write the attributes as HTML.

Parameter Type Default Description
returns str The attributes as they go in an HTML tag, with a leading space, or empty

parse_attrs

source

parse_attrs(text: str) -> Attrs

Parse Pandoc attributes; a bare word with no # or . is a class, as in ::: warning.

Parameter Type Default Description
text str required What is between the braces, or a bare word such as callout-note
returns Attrs The identifier, classes and pairs

split_front_matter

source

split_front_matter(text: str) -> tuple[dict, str]

Take the YAML front matter off the top of a page.

Parameter Type Default Description
text str required The whole source of a page
returns tuple[dict, str] The YAML front matter as a dict (empty when there is none), and the rest

pandoc_id

source

pandoc_id(text: str) -> str

Make a heading’s identifier by Pandoc’s rules: lower case, punctuation gone, spaces to hyphens, from the first letter.

Parameter Type Default Description
text str required The plain text of a heading
returns str Its identifier, as Pandoc makes it

plain

source

plain(tokens: list[Token] | None) -> str

The plain text of an inline run: text and code, without links’ targets or footnotes.

Parameter Type Default Description
tokens list[Token] | None required The children of an inline token
returns str The text without its formatting

is_fence_line

source

is_fence_line(line: str) -> str | None

Say whether a line opens or closes a fenced div, and give what follows the colons.

Parameter Type Default Description
line str required One line of source
returns str | None The text after the colons, or None when the line is no div fence

fenced_div

source

fenced_div(state: StateBlock, start: int, end: int, silent: bool) -> bool

Parse ::: {.class} … ::: into div tokens; a fence with no attributes closes the innermost div.

Parameter Type Default Description
state StateBlock required The block parser’s state
start int required The line to try
end int required The line after the last one
silent bool required Only say whether a div starts here
returns bool Whether a div starts here

heading_attrs

source

heading_attrs(state: StateCore) -> None

Take {#id .class} off the end of each heading, before inline parsing, and keep it on the heading.

Parameter Type Default Description
state StateCore required The core parser’s state

quote_attr_values

source

quote_attr_values(state: StateCore) -> None

Quote bare attribute values such as width=50%, which Pandoc reads and the attrs plugin does not.

Parameter Type Default Description
state StateCore required The core parser’s state

matching_close

source

matching_close(toks: list[Token], i: int) -> int

Find the closing token of the block that opens at i.

Parameter Type Default Description
toks list[Token] required The token list
i int required The index of an opening token
returns int The index of the token that closes it

raw

source

raw(content: str) -> Token

Make a token of raw HTML.

Parameter Type Default Description
content str required HTML
returns Token A token that renders the HTML as it is

class Rules

source

Rules(md: MarkdownIt)

The core rules that run after inline parsing; each reads and writes env.

Parameter Type Default Description
md MarkdownIt required The parser they belong to

Rules.ids

source

Rules.ids(state: StateCore) -> None

Give every heading an identifier, as Pandoc does, unique on the page; note its text for the table of contents.

Parameter Type Default Description
state StateCore required The core parser’s state

Rules.title

source

Rules.title(state: StateCore) -> None

When the page has no title, a level-one heading at the very top becomes it, as in Quarto.

Parameter Type Default Description
state StateCore required The core parser’s state

Rules.callouts

source

Rules.callouts(state: StateCore) -> None

Turn ::: {.callout-note} divs into Quarto’s callout markup, with a title from title= or a first heading.

Parameter Type Default Description
state StateCore required The core parser’s state

Rules.tabsets

source

Rules.tabsets(state: StateCore) -> None

Turn ::: {.panel-tabset} divs into Bootstrap tabs, one tab for each heading at the first level found.

Parameter Type Default Description
state StateCore required The core parser’s state

Rules.figures

source

Rules.figures(state: StateCore) -> None

An image alone in its paragraph, with alt text, becomes a figure with a caption, as Pandoc’s implicit figures.

Parameter Type Default Description
state StateCore required The core parser’s state

Rules.sections

source

Rules.sections(state: StateCore) -> None

Wrap each top-level heading and what follows in <section>, as Pandoc’s section divs.

Parameter Type Default Description
state StateCore required The core parser’s state

Rules.typography

source

Rules.typography(state: StateCore) -> None

Dashes and ellipses as Pandoc’s smart makes them: ---, -- and ....

Parameter Type Default Description
state StateCore required The core parser’s state

Rules.search_text

source

Rules.search_text(state: StateCore) -> None

Note the text under each heading, for the search index.

Parameter Type Default Description
state StateCore required The core parser’s state

heading_open

source

heading_open(tokens: Sequence[Token], idx: int, options: OptionsDict, env: dict) -> str

Render a heading as Quarto does: the id is on the section; the heading has anchored and data-anchor-id.

Parameter Type Default Description
tokens Sequence[Token] required The tokens of the page
idx int required The index of the token to render
options OptionsDict required The parser’s options
env dict required The render environment
returns str The opening tag of the heading

div_open

source

div_open(tokens: Sequence[Token], idx: int, options: OptionsDict, env: dict) -> str

Render a fenced div with its attributes; .cell and other Quarto classes pass through.

Parameter Type Default Description
tokens Sequence[Token] required The tokens of the page
idx int required The index of the token to render
options OptionsDict required The parser’s options
env dict required The render environment
returns str The opening tag of the div

div_close

source

div_close(tokens: Sequence[Token], idx: int, options: OptionsDict, env: dict) -> str

Close a fenced div.

Parameter Type Default Description
tokens Sequence[Token] required The tokens of the page
idx int required The index of the token to render
options OptionsDict required The parser’s options
env dict required The render environment
returns str The closing tag

paragraph_open

source

paragraph_open(tokens: Sequence[Token], idx: int, options: OptionsDict, env: dict) -> str

Open a paragraph, or the figure that wraps a lone image.

Parameter Type Default Description
tokens Sequence[Token] required The tokens of the page
idx int required The index of the token to render
options OptionsDict required The parser’s options
env dict required The render environment
returns str The opening tag of the paragraph, or of the figure

paragraph_close

source

paragraph_close(tokens: Sequence[Token], idx: int, options: OptionsDict, env: dict) -> str

Close a paragraph, or the figure with its caption.

Parameter Type Default Description
tokens Sequence[Token] required The tokens of the page
idx int required The index of the token to render
options OptionsDict required The parser’s options
env dict required The render environment
returns str The closing tag of the paragraph, or the caption and the end of the figure

image

source

image(tokens: Sequence[Token], idx: int, options: OptionsDict, env: dict) -> str

Render an image with Bootstrap’s img-fluid, and its source rewritten for the page.

Parameter Type Default Description
tokens Sequence[Token] required The tokens of the page
idx int required The index of the token to render
options OptionsDict required The parser’s options
env dict required The render environment
returns str The <img> tag

code_inline

source

code_inline(tokens: Sequence[Token], idx: int, options: OptionsDict, env: dict) -> str

Render inline code; a documented name in backticks, outside a link, links to its reference entry.

Parameter Type Default Description
tokens Sequence[Token] required The tokens of the page
idx int required The index of the token to render
options OptionsDict required The parser’s options
env dict required The render environment
returns str The <code> element, linked when it names a documented symbol

table_open

source

table_open(tokens: Sequence[Token], idx: int, options: OptionsDict, env: dict) -> str

Render a table with Bootstrap’s classes, as Quarto does.

Parameter Type Default Description
tokens Sequence[Token] required The tokens of the page
idx int required The index of the token to render
options OptionsDict required The parser’s options
env dict required The render environment
returns str The opening tag of the table

fence

source

fence(tokens: Sequence[Token], idx: int, options: OptionsDict, env: dict) -> str

Render a fenced code block: raw {=html}, mermaid, or highlighted code with a copy button.

Parameter Type Default Description
tokens Sequence[Token] required The tokens of the page
idx int required The index of the token to render
options OptionsDict required The parser’s options
env dict required The render environment
returns str The HTML of the block, or nothing

code_block_html

source

code_block_html(body: str, lang: str, a: Attrs, env: dict, extra: str = '') -> str

Highlight a code block with Pygments, in Quarto’s markup with a copy button.

Parameter Type Default Description
body str required The code
lang str required Its language, or empty
a Attrs required Its attributes: filename=, classes, an id
env dict required The render environment, which counts the blocks
extra str '' More classes on the outer div, such as cell-code
returns str The HTML of the block

code_block

source

code_block(tokens: Sequence[Token], idx: int, options: OptionsDict, env: dict) -> str

Render an indented code block like a fence with no language.

Parameter Type Default Description
tokens Sequence[Token] required The tokens of the page
idx int required The index of the token to render
options OptionsDict required The parser’s options
env dict required The render environment
returns str The HTML of the block

math_renderer

source

math_renderer(content: str, opts: dict) -> str

Write maths as Pandoc does for KaTeX or MathJax: \(...\) inline and \[...\] for display.

Parameter Type Default Description
content str required The TeX
opts dict required display_mode: whether it is display maths
returns str The TeX between the delimiters that KaTeX’s auto-render finds

math_inline

source

math_inline(tokens: Sequence[Token], idx: int, options: OptionsDict, env: dict) -> str

Render inline maths.

Parameter Type Default Description
tokens Sequence[Token] required The tokens of the page
idx int required The index of the token to render
options OptionsDict required The parser’s options
env dict required The render environment
returns str The maths, in a span

math_block

source

math_block(tokens: Sequence[Token], idx: int, options: OptionsDict, env: dict) -> str

Render display maths.

Parameter Type Default Description
tokens Sequence[Token] required The tokens of the page
idx int required The index of the token to render
options OptionsDict required The parser’s options
env dict required The render environment
returns str The maths, in a paragraph

make_parser

source

make_parser(extensions: str = '') -> MarkdownIt

Make a markdown-it parser that reads Pandoc’s Markdown as far as Quarto sites use it.

Parameter Type Default Description
extensions str '' Pandoc’s reader with extensions, such as markdown-tex_math_dollars-smart
returns MarkdownIt The parser, with every rule in place

render

source

render(text: str, env: dict, extensions: str = '') -> str

Render a page’s Markdown to HTML, filling env with what the layout needs.

Parameter Type Default Description
text str required Markdown, without its front matter
env dict required In: title, link, symbols, code_copy, number_sections. Out: headings, search, math, …
extensions str '' Pandoc’s reader with extensions, from from: in the config
returns str The HTML of the body