Parse Markdown content into HTML.

Parse Markdown content and extract table of contents.

Two-stage process:

1. Parse markdown to HTML
2. Inject heading anchors (IDs and headerlinks)
3. Extract TOC from anchored headings

Parse Markdown with variable substitution support.

Variable Substitution:

Enables {{ page.title }}, {{ site.baseurl }}, etc. in markdown content.
Uses a separate mistune instance (_md_with_vars) with preprocessing.

Lazy Initialization:

_md_with_vars is created on first use and cached thereafter.
This happens once per parser instance (i.e., once per thread).

Important: In parallel builds with max_workers=N:

• N parser instances created (main: self.md)
• N variable parser instances created (vars: self._md_with_vars)
• Total: 2N mistune instances, but only 1 of each per thread
• This is optimal - each thread uses its cached instances

Parser Reuse:

The parser with VariableSubstitutionPlugin is cached and reused.
Only the context is updated per page (fast operation).
This avoids expensive parser re-initialization (~10ms) for every page.

Parse Markdown with variable substitution and extract TOC.

Single-pass parsing with VariableSubstitutionPlugin for {{ vars }}.

ARCHITECTURE DECISION: Separation of Concerns

SUPPORTED in markdown content:

• {{ page.metadata.xxx }} - Variable substitution
• {{ site.config.xxx }} - Site configuration access
• Code blocks naturally stay literal (AST-level protection)

NOT SUPPORTED in markdown content:

• {% if %} - Conditional blocks
• {% for %} - Loop constructs
• Complex Jinja2 logic

WHY: These belong in TEMPLATES, not markdown content.

Use conditionals and loops in your page templates:

<!-- templates/page.html -->
<article>
  {% if page.metadata.enterprise %}
  <div class="enterprise-badge">Enterprise</div>
  {% endif %}

  {{ content }}  <!-- Markdown renders here -->
</article>

This design:

• Keeps parsing simple and fast (single pass)
• Separates content parsing from template logic
• Maintains performance (no preprocessing overhead)
• Makes code blocks work naturally

Enable cross-reference support with [[link]] syntax.

Should be called after content discovery when xref_index is built. Creates CrossReferencePlugin for post-processing HTML output.

Also stores xref_index on the renderer for directive access (e.g., cards :pull:).

Performance: O(1) - just stores reference to index Thread-safe: Each thread-local parser instance needs this called once

Parse Markdown content to AST tokens.

Uses Mistune's built-in AST support by parsing with renderer=None. The AST is a list of token dictionaries representing the document structure.

Performance:

• Parsing cost is similar to parse() (same tokenization)
• AST is more memory-efficient than HTML for caching
• Multiple outputs can be generated from single AST

Render AST tokens to HTML.

Uses Mistune's renderer to convert AST tokens back to HTML. This enables parse-once, render-many patterns.

Parse content and return AST, HTML, and TOC together.

Single-pass parsing that returns all outputs efficiently. Use this when you need both AST (for caching) and HTML (for display).