Reject duplicate docs IDs

[Alek99]

What changed

• Disambiguated the authored Chart Factories headings and grouped chart() only once.
• Renamed repeated capability-matrix Notes sections in both the generator and generated docs/spec output.
• Added an all-public-route static-ID validator plus a negative regression test.

Why

Authored and generated headings collided on Chart Factories, while repeated Notes headings collided on the Capability Matrix. Duplicate IDs make anchor links and generated navigation ambiguous.

Impact

Each public docs route now has unique static element IDs, and the docs suite will reject future duplicate anchors.

Validation

• docs/app/.venv/bin/pytest -q docs/app/tests/test_unique_ids.py — 2 passed
• docs/app/.venv/bin/python docs/app/scripts/check_duplicate_ids.py
• .venv/bin/python scripts/gen_capability_matrix.py --check
• Ruff lint and format checks on changed Python files

Fixes #396

Summary by CodeRabbit

• Documentation

  • Clarified chart factory groupings and renamed shared chart container properties.
  • Improved styling capability documentation with descriptive note headings.
  • Updated generated capability references with clearer section names.

• Bug Fixes

  • Added validation to detect duplicate element IDs across documentation pages, including redirects and SVG content.

• Tests

  • Added regression coverage for duplicate IDs in rendered documentation and HTML routes.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 163f54aa-5abb-40af-9bac-ddb47e6006ff

📥 Commits

Reviewing files that changed from the base of the PR and between d505ef5 and 8509941.

📒 Files selected for processing (9)

• docs/api-reference/chart-factories.md
• docs/app/scripts/check_duplicate_ids.py
• docs/app/scripts/check_html_routes.py
• docs/app/tests/test_docs_site.py
• docs/app/tests/test_unique_ids.py
• docs/app/xy_docs/api_reference.py
• docs/styling/capabilities.md
• scripts/gen_capability_matrix.py
• spec/api/capability-matrix.md

---

📝 Walkthrough

Walkthrough

The PR separates chart-factory and capability headings, adds duplicate-ID validation for rendered documentation components and prerendered HTML routes, and adds regression tests for content and redirect pages.

Changes

Documentation validation

Layer / File(s)	Summary
Documentation heading corrections docs/api-reference/chart-factories.md, docs/app/xy_docs/api_reference.py, docs/styling/capabilities.md, scripts/gen_capability_matrix.py, spec/api/capability-matrix.md	Chart factories use separate Annotations and Layers and Facets groups. Capability-matrix note headings now identify their section type.
Rendered component ID validation docs/app/scripts/check_duplicate_ids.py, docs/app/tests/test_unique_ids.py	The validator renders public pages, traverses component trees, detects repeated literal IDs, and reports duplicate IDs by route.
Prerendered HTML route validation docs/app/scripts/check_html_routes.py, docs/app/tests/test_docs_site.py	Route validation parses page and redirect HTML, rejects repeated element IDs, and tests layout, SVG, and redirect duplicates.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant PublicPage
  participant DocumentationRenderer
  participant IDValidator
  participant HTMLRouteValidator
  PublicPage->>DocumentationRenderer: render documentation components
  DocumentationRenderer->>IDValidator: provide component tree
  IDValidator-->>PublicPage: report duplicate literal IDs
  PublicPage->>HTMLRouteValidator: provide prerendered HTML
  HTMLRouteValidator-->>PublicPage: report duplicate element IDs

Loading

Possibly related PRs

• reflex-dev/xy#282: Extends the same HTML route validation and llms.txt checks.
• reflex-dev/xy#371: Modifies the same route validator and documentation-site tests.
• reflex-dev/xy#388: Modifies the same chart-factory documentation grouping logic.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the primary change: rejecting duplicate IDs in documentation.
Linked Issues check	✅ Passed	The PR disambiguates affected headings, validates unique IDs across public routes, and adds regression tests for issue #396.
Out of Scope Changes check	✅ Passed	The changes support issue #396 by updating affected headings, generated documentation, validators, and regression tests.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch agent/fix-396-unique-docs-ids

---

_{Comment @coderabbitai help to get the list of available commands.}

[codspeed-hq]

Merging this PR will not alter performance

✅ 109 untouched benchmarks
⏩ 2 skipped benchmarks¹

---

_{Comparing agent/fix-396-unique-docs-ids (8509941) with main (d505ef5)}

Footnotes

1. 2 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

[cubic-dev-ai]

All reported issues were addressed across 7 files

<sub>Reply with feedback, questions, or to request a fix.

Fix all with cubic | Re-trigger cubic</sub>