Skip to content

feat(toc): Incremental Markdown AST Table of Contents & Anchor Slug Generator - #36

Merged
ATLURI0001 merged 1 commit into
mainfrom
feat/toc-generator
Nov 21, 2026
Merged

ATLURI0001 merged 1 commit into
mainfrom
feat/toc-generator

Conversation

@ATLURI0001

Copy link
Copy Markdown
Owner

Bullet-Driven Engineering: Incremental Markdown AST Table of Contents & Anchor Slug Generator

Key Architectural Highlights

  • Markdown AST ATX Heading Extractor:

    • Parses header levels $H1$ through $H6$ with arbitrary heading depth.
    • Immune to false positive heading lines inside fenced code blocks (``` and ~~~) and HTML comments (<!-- ... -->).
    • Strips inline Markdown links ([text](url)), formatting characters (*, _, `), and trailing ATX hashes (##).
  • Deterministic Slug Disambiguation:

    • Implements Unicode NFKD normalization with ASCII conversion.
    • Disambiguates duplicate anchor slugs deterministically via counter suffixes (slug, slug-1, slug-2).
    • Provides a safe fallback (section) when headings contain empty or non-ASCII tokens.
  • Hierarchical Node Tree & Stack Builder:

    • Converts flat $(level, title, slug)$ tuples into a nested HeadingNode tree.
    • Manages sibling branches and depth transitions ($H1 \to H2 \to H3$) using an iterative stack.
  • Dual-Mode Rendering Engine:

    • render_markdown_toc: Emits nested indented Markdown lists with configurable depth bounds (min_level, max_level) and optional numbered bullets.
    • render_html_toc: Generates semantic <nav class="toc"> tags enclosing <ul> or <ol> elements with valid anchor tags (<a href="#slug">...</a>).

Verification Matrix

  • test_slugify_heading_basics_and_unicode: Confirmed ASCII transformation, accent stripping, inline link stripping, and fallback handling.
  • test_slugify_heading_collision_disambiguation: Verified sequential collision resolution (overview -> overview-1 -> overview-2).
  • test_parse_markdown_headings_atx_and_fences: Verified code fence immunity and HTML comment exclusion.
  • test_build_heading_tree_hierarchy: Verified recursive tree structure and sibling grouping.
  • test_render_markdown_toc_formatting: Verified level filtering ($H2 \to H3$) and ordered/unordered formatting.
  • test_render_html_toc_semantic_nav: Verified semantic HTML tags and proper nesting.
  • test_extract_table_of_contents_end_to_end: Verified end-to-end extraction from full document markdown.
  • 87/87 tests passing in 6.27s.

@ATLURI0001
ATLURI0001 merged commit 08d1f39 into main Nov 21, 2026
@ATLURI0001
ATLURI0001 deleted the feat/toc-generator branch November 21, 2026 05:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant