frontmatter - Chirp

docs.frontmatter

module

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…

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.

docs.frontmatter

Name	Type	Default	Description
`type`		—
`qualified_name`		—
`element_type`		—
`description`		—
`source_file`		—
`line_number`		—
`is_autodoc`		—
`autodoc_element`		—
`_autodoc_template`		—
`_autodoc_url_path`		—
`_autodoc_page_type`		—
`title`		—
`doc_content_hash`		—

Symbols on this page

function parse_frontmatter

Split frontmatter from markdown body.

function _meta_from_dict

Build aDocMetadatafrom a parsed frontmatter dict.

function _title_from_body

Extract title from first markdown heading, or return empty string.

function _extract_toc

Extract table-of-contents entries from rendered HTML headings.

function _slug_to_identifier

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…

function _split_blocks

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

Content before the first heading becomes a synthesizedintroblock (depth=0,…

function _slug_from_path

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…

function parse_file

Parse a single markdown file into aDocPage.

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

parse_frontmatter

function

def parse_frontmatter(text: str) -> tuple[dict[str, object], str]

Split frontmatter from markdown body.

Parameters

Name	Type	Default	Description
`text`	`str`	—

_meta_from_dict

function

def _meta_from_dict(d: dict[str, object]) -> DocMetadata

Build aDocMetadatafrom a parsed frontmatter dict.

Parameters

Name	Type	Default	Description
`d`	`dict[str, object]`	—

_title_from_body

function

def _title_from_body(body: str) -> str

Extract title from first markdown heading, or return empty string.

Parameters

Name	Type	Default	Description
`body`	`str`	—

_extract_toc

function

def _extract_toc(html: str) -> tuple[TocEntry, ...]

Extract table-of-contents entries from rendered HTML headings.

Parameters

Name	Type	Default	Description
`html`	`str`	—

_slug_to_identifier

function

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	Default	Description
`s`	`str`	—

_split_blocks

function

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	Default	Description
`html`	`str`	—

_slug_from_path

function

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	Default	Description
`md_path`	`Path`	—
`content_dir`	`Path`	—

parse_file

function

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	Default	Description
`md_path`	`Path`	—
`content_dir`	`Path`	—

View source · /home/runner/work/chirp/chirp/site/../src/chirp/docs/frontmatter.py:1