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 duplicate-ID validation to the existing prerendered HTML route checker, covering complete pages and redirects.

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

Public docs routes now reject duplicate IDs during the existing post-build route validation without adding a separate source checker or dedicated test suite.

Validation

• docs/app/.venv/bin/pytest -q docs/app/tests — 103 passed, 1 xfailed
• docs/app/.venv/bin/ruff check .
• docs/app/.venv/bin/ruff format --check .
• docs/app/.venv/bin/codespell .
• docs/app/.venv/bin/python scripts/gen_capability_matrix.py --check

Fixes #396

[coderabbitai]

📝 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
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%.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: rejecting duplicate IDs in public documentation pages.

✨ 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 (3b24b0f) with main (99eda6d)}

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>

[greptile-apps]

Greptile Summary

The PR disambiguates documentation headings and chart-factory groupings, then adds duplicate static-ID validation across prerendered public and redirect routes.

• Renames repeated capability-matrix headings in the generator and generated documents.
• Groups chart() and facet_chart() under distinct API-reference headings.
• Rejects duplicate non-empty element IDs found in complete prerendered HTML documents.

Confidence Score: 4/5

The PR appears safe to merge, with the non-blocking concern that its new documentation build gate lacks focused regression coverage.

The heading and grouping updates remain internally consistent, while the duplicate-ID validator is applied broadly and would benefit from tests pinning accepted and rejected HTML behavior.

Files Needing Attention: docs/app/scripts/check_html_routes.py

Important Files Changed

Filename	Overview
docs/app/scripts/check_html_routes.py	Adds whole-document duplicate-ID parsing and applies it to documentation and redirect routes; the behavior lacks focused regression tests.
docs/app/xy_docs/api_reference.py	Separates chart() and facet_chart() into uniquely named groups while preserving both in the documented factory set.
scripts/gen_capability_matrix.py	Generates distinct note headings consistently for both specification and public capability documents.
docs/api-reference/chart-factories.md	Updates authored prose and the chart-container heading to match the regrouped generated API reference.
docs/styling/capabilities.md	Updates public capability headings to avoid repeated static IDs.
spec/api/capability-matrix.md	Keeps the generated specification synchronized with the generator’s distinct headings.

_{Reviews (1): Last reviewed commit: "Trim duplicate-ID validation" | Re-trigger Greptile}

[greptile-apps]

Duplicate-ID gate lacks focused tests

The new parser and build-failing validation path have no focused positive and negative tests, so changes to empty-ID handling, inline SVG parsing, or duplicate reporting can either reject valid documentation output or allow ambiguous anchors without a targeted failure identifying the regression.

Knowledge Base Used: Testing and Benchmarks

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

[cubic-dev-ai]

1 issue found across 3 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="docs/app/tests/test_docs_site.py">

<violation number="1">
P2: This delta removes the only two tests covering the duplicate element-ID validation in check_html_routes.main(): test_prerendered_route_validator_rejects_ids_from_layout_and_raw_svg and test_redirect_route_validator_rejects_duplicate_ids. The production validator is still fully active — main() calls validate_unique_html_ids for both content routes and DOCS_REDIRECTS — so the core feature of this PR (rejecting duplicate docs IDs, including the redirect branch previously added for the fallback route) is left completely untested. Consider keeping at least the redirect integration test, or relocating both tests into a dedicated validator test module rather than dropping coverage.</violation>
</file>

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

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