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

table_caption

source

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

Parse a table’s caption, : text or Table: text, in the paragraph just after a table or just before one.

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 caption starts here
returns bool Whether a caption starts here

sub_sup

source

sub_sup(mark: str, tag: str) -> Callable

Make an inline rule for Pandoc’s H~2~O and x^2^: no space inside, unless escaped as \ ; ~~ stays strikethrough.

Parameter Type Default Description
mark str required ~ for a subscript, ^ for a superscript
tag str required sub or sup
returns Callable The inline rule

roman

source

roman(s: str) -> int | None

Read a roman numeral, in lower or upper case.

Parameter Type Default Description
s str required Letters such as iv or XII
returns int | None Their value, or None when they are no roman numeral

marker_value

source

marker_value(tok: str, style: str | None) -> tuple[str, int] | None

Read a list marker by Pandoc’s rules: a lone i starts a roman list, another lone letter a lettered one.

Parameter Type Default Description
tok str required The letters of a list marker, such as b or iv
style str | None required The style of the list it continues: a, A, i or I; None for a new list
returns tuple[str, int] | None The style and the number, or None when the marker is not one

letter_lists

source

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

Rewrite list markers such as a., (b), iv) and A. to numbers, which markdown-it reads, and note each list’s type.

Parameter Type Default Description
text str required Markdown
returns tuple[str, dict[int, str]] The text with the markers as numbers, and the list type of each item’s line

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

holds

source

holds(kind: str, value: str, env: dict) -> bool

Test one condition of .content-visible or .content-hidden.

Parameter Type Default Description
kind str required format, meta or profile
value str required What the attribute names: a format, a dotted key of the page’s options, or profiles, with commas
env dict required The render environment, with the page’s options in meta
returns bool Whether the page is built in that format, has that option, or runs in that profile

shown

source

shown(classes: list[str], kv: dict[str, str], env: dict) -> bool | None

Decide whether conditional content stays: .content-visible when every condition holds, .content-hidden unless every one does.

Parameter Type Default Description
classes list[str] required The classes of a div or a span
kv dict[str, str] required Its other attributes
env dict required The render environment
returns bool | None Whether to keep it; None when it is not conditional

table_classes

source

table_classes(a: Attrs) -> list[str]

Turn Quarto’s table classes, such as .striped, into Bootstrap’s.

Parameter Type Default Description
a Attrs required The caption’s attributes
returns list[str] Bootstrap’s classes for the table, such as table-striped

layout_rows

source

layout_rows(kv: dict[str, str], n: int) -> list[list[float]] | None

Read a div’s layout into rows of widths, as Quarto does: layout-ncol=2, layout-nrow=2 or layout="[[1,1],[1]]".

Parameter Type Default Description
kv dict[str, str] required The div’s attributes: layout-ncol, layout-nrow or layout
n int required How many blocks the div holds
returns list[list[float]] | None The width of each cell of each row, as a share of the row; None when the layout cannot be read

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.conditions

source

Rules.conditions(state: StateCore) -> None

Keep or drop .content-visible and .content-hidden divs and spans; what is dropped is gone from the page and from search.

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

Rules.inline_conditions

source

Rules.inline_conditions(kids: list[Token], env: dict) -> list[Token]

Keep or drop the conditional spans of an inline run; a span that stays loses its condition, as in Quarto.

Parameter Type Default Description
kids list[Token] required The children of an inline token
env dict required The render environment
returns list[Token] The children, without the spans that are hidden

Rules.table_captions

source

Rules.table_captions(state: StateCore) -> None

Join each caption to its table: in the table as <caption>, or, with an id or in the margin, in a figure around it, as Quarto does.

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

Rules.escaped_spaces

source

Rules.escaped_spaces(state: StateCore) -> None

Turn \ in a subscript or a superscript into a space that does not break, as Pandoc does.

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

Rules.list_types

source

Rules.list_types(state: StateCore) -> None

Give a list numbered with letters or roman numerals its type, from the lines that letter_lists noted.

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

Rules.layouts

source

Rules.layouts(state: StateCore) -> None

Put the blocks of a div with layout-ncol, layout-nrow or layout side by side, in Quarto’s rows and cells.

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

Rules.video_sources

source

Rules.video_sources(state: StateCore) -> None

Rewrite the file of a video shortcode for the page, so the build copies it, as it does a picture.

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.margins

source

Rules.margins(state: StateCore) -> None

Note margin content; with reference-location: margin, put each footnote in the margin beside the block that cites it.

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

looks_like_code

source

looks_like_code(text: str) -> bool

Say whether a name in backticks looks like code: a call f(), a dotted name a.b, a name with _, or a class Name. A plain word such as main does not.

Parameter Type Default Description
text str required The text in backticks
returns bool Whether linkify may link it

code_inline

source

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

Render inline code; a documented name in backticks that looks like code, outside a link and without .nolink, links to its 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, in a box that scrolls when the table is too wide.

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

table_close

source

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

Close a table and the box that table_open opened.

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 tags of the table and its box

float_open

source

float_open(a: Attrs) -> str

Open the figure that holds a table with an id, as Quarto’s quarto-float, with the id where a link to #tbl-... lands.

Parameter Type Default Description
a Attrs required The caption’s attributes
returns str The opening tags of the figure around a table

described

source

described(a: Attrs) -> str

Point a table at its caption, for screen readers.

Parameter Type Default Description
a Attrs required The caption’s attributes
returns str The aria-describedby attribute, or nothing when the table has no id

table_caption_open

source

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

Open a table’s caption: <caption> in the table, or Quarto’s <figcaption> in a figure.

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 caption, after the figure’s when the caption comes first

table_caption_close

source

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

Close a table’s 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 caption, and of the figure when the caption comes last

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

numbered_lines

source

numbered_lines(code: str, cid: str) -> str

Put each line of highlighted code in its own span, cb1-1, as Pandoc does for numbered lines.

Parameter Type Default Description
code str required Highlighted code: escaped text and spans, which may run over several lines
cid str required The id of the block, such as cb1
returns str The code with each line in a span of its own, with an id and an anchor

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_display

source

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

Render $$...$$ inside a paragraph as display maths, on a line of its own, as Pandoc 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 maths, in a span of display maths

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

footnote_ref

source

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

Link to a footnote: markdown-it’s markup at the end of the page, Quarto’s with reference-location: margin.

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 link to the footnote

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

page_options

source

page_options(m: dict) -> dict

Read the page options that change the Markdown: code, figures, tables, callouts, headings, and the options for when-meta.

Parameter Type Default Description
m dict required A page’s merged options
returns dict What the Markdown rules read from them, as keys of env; only the options that the page sets

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, and page_options. Out: headings, search, math, …
extensions str '' Pandoc’s reader with extensions, from from: in the config
returns str The HTML of the body