Module

docs.frontmatter

YAML frontmatter parser for markdown documentation files.

Parses the---delimited YAML header from markdown files. Missing frontmatter is handled gracefully: title is derived from the first #heading, and all other fields use defaults.

9Functions

Functions

parse_frontmatter 1 tuple[dict[str, object],… ▼
Split frontmatter from markdown body.
def parse_frontmatter(text: str) -> tuple[dict[str, object], str]
Parameters
Name Type Description
text str
Returns
tuple[dict[str, object], str]
_parse_simple 1 dict[str, object] ▼
Minimal key: value parser when PyYAML is unavailable.
def _parse_simple(raw: str) -> dict[str, object]
Parameters
Name Type Description
raw str
Returns
dict[str, object]
_meta_from_dict 1 DocMetadata ▼
Build a ``DocMetadata`` from a parsed frontmatter dict.
def _meta_from_dict(d: dict[str, object]) -> DocMetadata
Parameters
Name Type Description
d dict[str, object]
Returns
DocMetadata
_title_from_body 1 str ▼
Extract title from first markdown heading, or return empty string.
def _title_from_body(body: str) -> str
Parameters
Name Type Description
body str
Returns
str
_extract_toc 1 tuple[TocEntry, ...] ▼
Extract table-of-contents entries from rendered HTML headings.
def _extract_toc(html: str) -> tuple[TocEntry, ...]
Parameters
Name Type Description
html str
Returns
tuple[TocEntry, ...]
_slug_to_identifier 1 str ▼
Convert kebab-case (or arbitrary text) to a snake_case Python identifier. Kida…
def _slug_to_identifier(s: str) -> str

Convert kebab-case (or arbitrary text) to a snake_case Python identifier.

Kida block names must be valid Python identifiers, while heading ids emitted by patitas are kebab-case (section-overview).

Parameters
Name Type Description
s str
Returns
str
_split_blocks 1 tuple[DocBlock, ...] ▼
Split rendered HTML into sections at H2 (or H3 fallback) boundaries. Content b…
def _split_blocks(html: str) -> tuple[DocBlock, ...]

Split rendered HTML into sections at H2 (or H3 fallback) boundaries.

Content before the first heading becomes a synthesizedintroblock (depth=0, empty heading/anchor). Duplicate ids are disambiguated with a numeric suffix.

Parameters
Name Type Description
html str
Returns
tuple[DocBlock, ...]
_slug_from_path 2 str ▼
Derive a URL slug from a file path relative to content_dir. Index-like files b…
def _slug_from_path(md_path: Path, content_dir: Path) -> str

Derive a URL slug from a file path relative to content_dir.

Index-like files become the parent directory slug:

content_dir/guides/getting-started.md → guides/getting-started content_dir/guides/index.md → guides content_dir/guides/_index.md → guides content_dir/guides/README.md → guides content_dir/index.md → index content_dir/_index.md → index

Parameters
Name Type Description
md_path Path
content_dir Path
Returns
str
parse_file 2 DocPage ▼
Parse a single markdown file into a ``DocPage``. Reads the file, splits frontm…
def parse_file(md_path: Path, content_dir: Path) -> DocPage

Parse a single markdown file into aDocPage.

Reads the file, splits frontmatter, renders markdown via MarkdownRenderer, and extracts TOC entries.

Parameters
Name Type Description
md_path Path
content_dir Path
Returns
DocPage