refactor ToC - improve DRYness

Author: hesreallyhim

.pre-commit-config.yaml

@@ -14,7 +14,7 @@ repos:
       - id: mixed-line-ending
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.8.5
+    rev: v0.12.2
     hooks:
       # Run the linter
       - id: ruff

README_ALTERNATIVES/README_EXTRA.md

@@ -97,7 +97,7 @@
 </a>
 </td>
 <td align="center">
-<a href="#workflows-knowledge-guides-">
+<a href="#workflows--knowledge-guides-">
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="../assets/card-workflows.svg">
   <source media="(prefers-color-scheme: light)" srcset="../assets/card-workflows-light-anim-lineprint.svg">

docs/development/toc-anchor-generation.md

@@ -82,14 +82,15 @@ make test  # Includes TOC anchor validation tests
 
 ## HTML Fixture Storage
 
-GitHub-rendered HTML fixtures are stored in `tests/fixtures/github-html/` (version controlled):
+GitHub-rendered HTML fixtures are stored in `tests/fixtures/github-html/` (version controlled).
+Fixture filenames indicate root vs non-root placement to detect potential rendering differences:
 
-| Style | README Path | HTML Fixture Path |
-|-------|-------------|-------------------|
-| AWESOME | `README.md` | `tests/fixtures/github-html/awesome.html` |
-| CLASSIC | `README_ALTERNATIVES/README_CLASSIC.md` | `tests/fixtures/github-html/classic.html` |
-| EXTRA | `README_ALTERNATIVES/README_EXTRA.md` | `tests/fixtures/github-html/extra.html` |
-| FLAT | `README_ALTERNATIVES/README_FLAT_ALL_AZ.md` | `tests/fixtures/github-html/flat.html` |
+| Style | README Path | HTML Fixture | Placement |
+|-------|-------------|--------------|-----------|
+| AWESOME | `README.md` | `awesome-root.html` | Root |
+| CLASSIC | `README_ALTERNATIVES/README_CLASSIC.md` | `classic-non-root.html` | Non-root |
+| EXTRA | `README_ALTERNATIVES/README_EXTRA.md` | `extra-non-root.html` | Non-root |
+| FLAT | `README_ALTERNATIVES/README_FLAT_ALL_AZ.md` | `flat-non-root.html` | Non-root |
 
 Validation commands:
 ```bash
@@ -102,17 +103,55 @@ python3 -m scripts.testing.validate_toc_anchors --style extra
 python3 -m scripts.testing.validate_toc_anchors --style flat
 ```
 
-## Remaining Work
+## Validation Status
 
-| Style | Validated | Notes |
-|-------|-----------|-------|
-| AWESOME | ✅ | Root README, tested and fixed |
-| CLASSIC | ✅ | Tested and fixed (different anchor format due to 🔝 in headings) |
-| EXTRA | ❌ | Uses explicit `id` attributes; needs validation |
-| FLAT | ❌ | Simpler format (no subcategories); needs validation |
+| Style | Status | Notes |
+|-------|--------|-------|
+| AWESOME | ✅ | Root README, 30 TOC anchors verified |
+| CLASSIC | ✅ | Different anchor format due to 🔝 in headings |
+| EXTRA | ✅ | Uses explicit `id` attributes; template anchor fixed |
+| FLAT | ✅ | No TOC anchors (flat list format) |
 
-### TODO
-- [ ] Download GitHub HTML for EXTRA style and validate
-- [ ] Download GitHub HTML for FLAT style and validate
-- [ ] Fix any anchor mismatches found in EXTRA/FLAT
-- [ ] Consider unifying anchor generation logic into shared helpers
+## Future Work
+
+- [ ] Unify anchor generation logic into shared helper with parameterized flags
+- [ ] Add CI job to validate TOC anchors on README changes
+
+---
+
+## Architectural Decision: Anchor Generation Unification
+
+**Date**: 2026-01-09
+
+**Context**: TOC anchor generation logic is duplicated across three files (`awesome.py`, `minimal.py`, `visual.py`) with subtle differences due to each style's heading format.
+
+**Options Considered**:
+
+1. **Parameterized flags** - Create shared helper with semantic flags like `has_back_to_top_in_heading`
+2. **Unify to ID-based** - Migrate all styles to use explicit `<h2 id="...">` like EXTRA
+
+**Decision**: Option 1 (parameterized flags)
+
+**Rationale**:
+- Lower risk: heading markup remains unchanged
+- AWESOME style intentionally uses clean markdown (`## Title`) for aesthetic reasons
+- ID-based approach would require CLASSIC to restructure its `[🔝](#...)` links
+- Parameterized flags are self-documenting and decouple anchor logic from style names
+
+**Proposed API**:
+```python
+def generate_toc_anchor(
+    title: str,
+    icon: str | None = None,
+    has_back_to_top_in_heading: bool = False,
+) -> str:
+    """Generate TOC anchor for a heading.
+
+    Args:
+        title: The heading text (e.g., "Agent Skills")
+        icon: Optional trailing emoji icon (e.g., "🤖")
+        has_back_to_top_in_heading: True if heading contains 🔝 back-to-top link
+    """
+```
+
+**Trade-off**: If a style changes its heading format (e.g., CLASSIC removes 🔝), only the flag value changes—not the shared logic.

scripts/readme/helpers/readme_utils.py

@@ -60,6 +60,63 @@ def get_anchor_suffix_for_icon(icon: str | None) -> str:
     return "-"
 
 
+def generate_toc_anchor(
+    title: str,
+    icon: str | None = None,
+    has_back_to_top_in_heading: bool = False,
+) -> str:
+    """Generate a TOC anchor for a heading.
+
+    Centralizes anchor generation logic across all README styles.
+
+    Args:
+        title: The heading text (e.g., "Agent Skills")
+        icon: Optional trailing emoji icon (e.g., "🤖"). Each emoji adds a dash.
+        has_back_to_top_in_heading: True if heading contains 🔝 back-to-top link,
+            which adds an additional trailing dash to the anchor.
+
+    Returns:
+        The anchor string without the leading '#' (e.g., "agent-skills-")
+    """
+    base = title.lower().replace(" ", "-").replace("&", "").replace("/", "").replace(".", "")
+    suffix = get_anchor_suffix_for_icon(icon)
+    back_to_top_suffix = "-" if has_back_to_top_in_heading else ""
+    return f"{base}{suffix}{back_to_top_suffix}"
+
+
+def generate_subcategory_anchor(
+    title: str,
+    general_counter: int = 0,
+    has_back_to_top_in_heading: bool = False,
+) -> tuple[str, int]:
+    """Generate a TOC anchor for a subcategory heading.
+
+    Handles the special case of multiple "General" subcategories which need
+    unique anchors (general, general-1, general-2, etc.).
+
+    Args:
+        title: The subcategory name (e.g., "General", "IDE Integrations")
+        general_counter: Current count of "General" subcategories seen so far
+        has_back_to_top_in_heading: True if heading contains 🔝 back-to-top link
+
+    Returns:
+        Tuple of (anchor_string, updated_general_counter)
+    """
+    base = title.lower().replace(" ", "-").replace("&", "").replace("/", "")
+    back_to_top_suffix = "-" if has_back_to_top_in_heading else ""
+
+    if title == "General":
+        if general_counter == 0:
+            anchor = f"general{back_to_top_suffix}"
+        else:
+            # GitHub uses double-dash before counter when back-to-top present
+            separator = "-" if has_back_to_top_in_heading else ""
+            anchor = f"general-{separator}{general_counter}"
+        return anchor, general_counter + 1
+
+    return f"{base}{back_to_top_suffix}", general_counter
+
+
 def sanitize_filename_from_anchor(anchor: str) -> str:
     """Convert an anchor string to a tidy filename fragment."""
     name = anchor.rstrip("-")

scripts/readme/markup/awesome.py

@@ -6,7 +6,8 @@
 
 from scripts.readme.helpers.readme_paths import asset_path_token
 from scripts.readme.helpers.readme_utils import (
-    get_anchor_suffix_for_icon,
+    generate_subcategory_anchor,
+    generate_toc_anchor,
     parse_resource_date,
 )
 
@@ -60,24 +61,16 @@ def generate_toc(categories: list[dict], csv_data: list[dict]) -> str:
         section_title = category.get("name", "")
         icon = category.get("icon", "")
         subcategories = category.get("subcategories", [])
-        anchor_suffix = get_anchor_suffix_for_icon(icon)
-
-        anchor = (
-            section_title.lower()
-            .replace(" ", "-")
-            .replace("&", "")
-            .replace("/", "")
-            .replace(".", "")
-        )
 
+        anchor = generate_toc_anchor(section_title, icon=icon)
         display_title = f"{section_title} {icon}" if icon else section_title
 
         if subcategories:
             category_name = category.get("name", "")
             has_resources = any(r["Category"] == category_name for r in csv_data)
 
             if has_resources:
-                toc_lines.append(f"- [{display_title}](#{anchor}{anchor_suffix})")
+                toc_lines.append(f"- [{display_title}](#{anchor})")
 
                 for subcat in subcategories:
                     sub_title = subcat["name"]
@@ -90,20 +83,12 @@ def generate_toc(categories: list[dict], csv_data: list[dict]) -> str:
                     ]
 
                     if resources:
-                        sub_anchor = (
-                            sub_title.lower().replace(" ", "-").replace("&", "").replace("/", "")
+                        sub_anchor, general_counter = generate_subcategory_anchor(
+                            sub_title, general_counter
                         )
-
-                        if sub_title == "General":
-                            if general_counter == 0:
-                                sub_anchor = "general"
-                            else:
-                                sub_anchor = f"general-{general_counter}"
-                            general_counter += 1
-
                         toc_lines.append(f"  - [{sub_title}](#{sub_anchor})")
         else:
-            toc_lines.append(f"- [{display_title}](#{anchor}{anchor_suffix})")
+            toc_lines.append(f"- [{display_title}](#{anchor})")
 
     return "\n".join(toc_lines).strip()
 

scripts/readme/markup/minimal.py

@@ -5,7 +5,8 @@
 from datetime import datetime, timedelta
 
 from scripts.readme.helpers.readme_utils import (
-    get_anchor_suffix_for_icon,
+    generate_subcategory_anchor,
+    generate_toc_anchor,
     parse_resource_date,
 )
 from scripts.utils.github_utils import parse_github_url
@@ -67,28 +68,21 @@ def generate_toc(categories: list[dict], csv_data: list[dict]) -> str:
     toc_lines.append("")
 
     general_counter = 0
+    # CLASSIC style headings include [🔝](#awesome-claude-code) which adds another dash
+    has_back_to_top = True
 
     for category in categories:
         section_title = category.get("name", "")
         icon = category.get("icon", "")
         subcategories = category.get("subcategories", [])
-        anchor_suffix = get_anchor_suffix_for_icon(icon)
-        # CLASSIC style headings include [🔝](#awesome-claude-code) which adds another dash
-        back_to_top_suffix = "-"
-
-        anchor = (
-            section_title.lower()
-            .replace(" ", "-")
-            .replace("&", "")
-            .replace("/", "")
-            .replace(".", "")
+
+        anchor = generate_toc_anchor(
+            section_title, icon=icon, has_back_to_top_in_heading=has_back_to_top
         )
 
         if subcategories:
             toc_lines.append("- <details open>")
-            toc_lines.append(
-                f'  <summary><a href="#{anchor}{anchor_suffix}{back_to_top_suffix}">{section_title}</a></summary>'
-            )
+            toc_lines.append(f'  <summary><a href="#{anchor}">{section_title}</a></summary>')
             toc_lines.append("")
 
             for subcat in subcategories:
@@ -103,27 +97,15 @@ def generate_toc(categories: list[dict], csv_data: list[dict]) -> str:
                 ]
 
                 if resources:
-                    sub_anchor = (
-                        sub_title.lower().replace(" ", "-").replace("&", "").replace("/", "")
+                    sub_anchor, general_counter = generate_subcategory_anchor(
+                        sub_title, general_counter, has_back_to_top_in_heading=has_back_to_top
                     )
-
-                    # CLASSIC subcategory headings include 🔝 which adds a trailing dash
-                    if sub_title == "General":
-                        if general_counter == 0:
-                            sub_anchor = "general-"
-                        else:
-                            # GitHub uses double-dash before counter: general--1, general--2
-                            sub_anchor = f"general--{general_counter}"
-                        general_counter += 1
-                    else:
-                        sub_anchor = f"{sub_anchor}-"
-
                     toc_lines.append(f"  - [{sub_title}](#{sub_anchor})")
 
             toc_lines.append("")
             toc_lines.append("  </details>")
         else:
-            toc_lines.append(f"- [{section_title}](#{anchor}{anchor_suffix}{back_to_top_suffix})")
+            toc_lines.append(f"- [{section_title}](#{anchor})")
 
         toc_lines.append("")
 

scripts/readme/markup/visual.py

@@ -16,6 +16,7 @@
 )
 from scripts.readme.helpers.readme_paths import asset_path_token
 from scripts.readme.helpers.readme_utils import (
+    generate_toc_anchor,
     parse_resource_date,
     sanitize_filename_from_anchor,
 )
@@ -163,22 +164,15 @@ def generate_toc_from_categories(
         section_title = category["name"]
         category_name = category.get("name", "")
         category_id = category.get("id", "")
-        anchor = (
-            section_title.lower()
-            .replace(" ", "-")
-            .replace("&", "")
-            .replace("/", "")
-            .replace(".", "")
-        )
-
-        anchor_suffix = "-"
+        # EXTRA style uses explicit IDs with trailing dash (no icon in anchor)
+        anchor = generate_toc_anchor(section_title, icon=None, has_back_to_top_in_heading=True)
 
         svg_filename = get_category_svg_filename(category_id)
 
         dark_svg = svg_filename
         light_svg = svg_filename.replace(".svg", "-light-anim-scanline.svg")
         toc_lines.append('<div style="height:40px;width:400px;overflow:hidden;display:block;">')
-        toc_lines.append(f'<a href="#{anchor}{anchor_suffix}">')
+        toc_lines.append(f'<a href="#{anchor}">')
         toc_lines.append("  <picture>")
         toc_lines.append(
             f'    <source media="(prefers-color-scheme: dark)" srcset="{asset_path_token(dark_svg)}">'
@@ -285,8 +279,8 @@ def generate_section_content(
     lines.append("</div>")
     lines.append("")
 
-    anchor = title.lower().replace(" ", "-").replace("&", "").replace("/", "").replace(".", "")
-    anchor_id = f"{anchor}-"
+    # EXTRA style uses explicit IDs with trailing dash (no icon in anchor)
+    anchor_id = generate_toc_anchor(title, icon=None, has_back_to_top_in_heading=True)
 
     section_number = str(section_index + 1).zfill(2)
     display_title = title

scripts/testing/validate_toc_anchors.py

@@ -42,18 +42,19 @@
 EXPECTED_ANCHORS_PATH = REPO_ROOT / "tests" / "fixtures" / "expected_toc_anchors.txt"
 
 # Style configurations: (html_fixture, readme_path)
+# HTML fixture names indicate root vs non-root placement on GitHub
 STYLE_CONFIGS = {
-    "awesome": (FIXTURES_DIR / "awesome.html", REPO_ROOT / "README.md"),
+    "awesome": (FIXTURES_DIR / "awesome-root.html", REPO_ROOT / "README.md"),
     "classic": (
-        FIXTURES_DIR / "classic.html",
+        FIXTURES_DIR / "classic-non-root.html",
         REPO_ROOT / "README_ALTERNATIVES" / "README_CLASSIC.md",
     ),
     "extra": (
-        FIXTURES_DIR / "extra.html",
+        FIXTURES_DIR / "extra-non-root.html",
         REPO_ROOT / "README_ALTERNATIVES" / "README_EXTRA.md",
     ),
     "flat": (
-        FIXTURES_DIR / "flat.html",
+        FIXTURES_DIR / "flat-non-root.html",
         REPO_ROOT / "README_ALTERNATIVES" / "README_FLAT_ALL_AZ.md",
     ),
 }

templates/README_EXTRA.template.md

@@ -80,7 +80,7 @@
 </a>
 </td>
 <td align="center">
-<a href="#workflows-knowledge-guides-">
+<a href="#workflows--knowledge-guides-">
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="{{ASSET_PATH('card-workflows.svg')}}">
   <source media="(prefers-color-scheme: light)" srcset="{{ASSET_PATH('card-workflows-light-anim-lineprint.svg')}}">