Module header_id_utils

Source

Expand description

Utilities for extracting custom header IDs from various Markdown flavors

This module supports multiple syntax formats for custom header IDs:

§Kramdown Format

{#custom-id} - Simple ID without colon
Example: # Header {#my-id}

§Python-markdown attr-list Format

{:#custom-id} - ID with colon, no spaces
{: #custom-id} - ID with colon and spaces
{: #custom-id .class} - ID with classes
{: #custom-id .class data="value"} - ID with full attributes
Example: # Header {: #my-id .highlight}

§Position Support

Inline: # Header {#id} (all formats)
Next-line: Jekyll/kramdown style where attr-list appears on the line after the header
```
# Header
{#next-line-id}
```

§HTML anchors

<a id="custom-id"></a> or <a name="custom-id"></a> beside the heading text
Example: ## <a name="my-id"></a>Header

An empty anchor element is stripped from the heading text but, unlike an attr-list ID, it does not replace the slug generated from the text: the rendered heading answers to both. Tags are read in source order as a browser tokenizes them, so an <a> written inside another tag’s attribute value is part of that value. Anchor markup inside a code span or an HTML comment, or whose < is backslash-escaped, is heading text and defines nothing.

The module provides functions to detect and extract IDs from both inline and standalone (next-line) attr-list syntax.

Constants§

HTML_BLOCK_TAG_NAME_PATTERN: The name of a tag as a browser reads it inside raw HTML: a letter, then anything up to whitespace, / or >.
HTML_TAG_ATTRIBUTES_PATTERN: Attribute list of an inline HTML open tag as CommonMark defines it.
HTML_TAG_NAME_PATTERN: The name of an HTML tag: a letter, then letters, digits and hyphens.

Statics§

HTML_BLOCK_OPEN_TAG: An open tag inside an HTML block, where the browser’s tokenizer rather than CommonMark’s inline grammar decides what a tag is. Only the tag name is read the browser’s way; attributes still follow the CommonMark grammar.
HTML_OPEN_TAG: An inline HTML open tag, self-closing or not, with its name captured.

Functions§

extract_header_id: Extract custom header ID from a line if present, returning clean text and ID
extract_html_anchor_ids: The targets of the empty <a> elements in text, in source order.
extract_standalone_attr_list_id: Extract ID from a standalone attr-list line
html_tag_attribute: The value of attribute name in the HTML open tag tag.
is_backslash_escaped: Whether the character at byte pos of text is backslash-escaped.
is_standalone_attr_list: Check if a line is a standalone attr-list (Jekyll/kramdown style)