smalldocs.llms

Write the Markdown copy of each page, page.llms.md, and the index llms.txt, for website.llms-txt.

kept

source

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

Decide conditional content for the copy: a condition on llms-txt decides alone, as in Quarto; any other, as on the HTML page.

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 page’s render environment
returns bool | None Whether the copy keeps its content; None when it is not conditional

tag

source

tag(name: str, params: str) -> str

Write Pandoc attributes as an HTML opening tag.

Parameter Type Default Description
name str required div or span
params str required Pandoc attributes, such as .callout-note title="A"
returns str The HTML opening tag

inline

source

inline(text: str, link: Callable[[str], str], env: dict) -> str

Rewrite the links and spans of a line, but not those inside code spans.

Parameter Type Default Description
text str required A line of Markdown, outside code blocks
link Callable[[str], str] required Rewrites one link
env dict required The page’s render environment
returns str The line with its links rewritten and its spans as HTML, and its code spans as they were

hidden_cell

source

hidden_cell(info: str, code: str, env: dict) -> bool

Say whether an executable cell is hidden on the page by echo: false or include: false, as markdown.fence decides.

Parameter Type Default Description
info str required The text after a code fence’s backticks
code str required The code in the fence
env dict required The page’s render environment, with its cell_defaults
returns bool Whether the page hides the cell

class Prose

source

Prose(link: Callable[[str], str], env: dict)

Turn a page’s Markdown into the copy’s: Pandoc’s divs become HTML divs, conditional content is kept or dropped, and links are rewritten.

Parameter Type Default Description
link Callable[[str], str] required Rewrites one link, to another page’s copy
env dict required The page’s render environment

Prose.feed

source

Prose.feed(body: str) -> str

Turn some Markdown into the copy’s; code blocks and HTML blocks stay as they are.

Parameter Type Default Description
body str required Markdown; a div may open in one call and close in a later one, as across a notebook’s cells
returns str The Markdown for the copy

Prose.close

source

Prose.close(out: list[str], quote: str) -> None

End the innermost open div: write its closing tag, unless it was dropped or unwrapped.

Parameter Type Default Description
out list[str] required The copy’s lines so far; this adds to it
quote str required The quote marks before the div’s lines

Prose.finish

source

Prose.finish() -> str

Close the divs left open at the end of the page.

Parameter Type Default Description
returns str The closing tags of the divs still open

prose

source

prose(body: str, p: Prose) -> str

Turn a page’s Markdown into its copy’s, with every div closed.

Parameter Type Default Description
body str required Markdown, after includes and shortcodes
p Prose required The converter, with the page’s links and environment
returns str The Markdown for the copy

indent

source

indent(text: str) -> str

Indent text by four spaces, as nbconvert’s indent filter does.

Parameter Type Default Description
text str required Text to show as code
returns str The text indented by four spaces, Markdown’s indented code block

joined

source

joined(value: str | list) -> str

Join a notebook string that is stored as a list of lines.

Parameter Type Default Description
value str | list required A notebook string, which may be stored as a list of lines
returns str It as one string

output

source

output(out: dict, name: str, files: dict[str, bytes], folder: str, opts: dict, n: int, caption: Callable[[str], str]) -> str

Write one stored output as nbconvert’s Markdown exporter does.

Parameter Type Default Description
out dict required One stored output of a code cell
name str required The file name for a picture, without its extension
files dict[str, bytes] required The pictures to save beside the copy; this adds to it
folder str required The folder of the pictures, relative to the copy
opts dict required The cell’s options, for fig-cap and fig-alt
n int required Which picture of the cell this is, from 0, for a list of captions
caption Callable[[str], str] required Rewrites a caption’s links
returns str The output as Markdown

notebook

source

notebook(text: str, defaults: dict, stem: str, prose: Prose, expand: Callable[[str], str]) -> tuple[str, dict[str, bytes]]

Write a notebook as nbconvert’s Markdown exporter does, showing the cells and outputs that the page shows.

Parameter Type Default Description
text str required The notebook’s JSON
defaults dict required The page’s echo, output and include, which a cell’s #| options override
stem str required The notebook’s name without .ipynb, which names its pictures
prose Prose required Turns the Markdown cells into the copy’s; a div may span cells
expand Callable[[str], str] required Expands the shortcodes of a Markdown cell
returns tuple[str, dict[str, bytes]] The copy’s body, and the pictures to save beside it, by path

page_markdown

source

page_markdown(title: str, description: str, body: str) -> str

Put a page’s title and description on top of its copy’s body.

Parameter Type Default Description
title str required The page’s title, or empty when the body starts with it
description str required Its description, or empty
body str required The copy’s body
returns str The Markdown copy

index

source

index(title: str, description: str, pages: list[tuple[str, str]]) -> str

Write llms.txt, as Quarto does: the site’s title, its description, and a list of the pages.

Parameter Type Default Description
title str required The site’s title
description str required The site’s description, or empty
pages list[tuple[str, str]] required Each page’s title and the address of its Markdown copy
returns str The text of llms.txt