Fix docs breadcrumb overview routes

[Alek99]

Summary

• Resolve generated docs breadcrumb hrefs against registered docs routes.
• Fall back parent breadcrumb links to /overview/ when the synthesized parent path is not a route.
• Add a regression test for the Enterprise breadcrumb case from the breadcrumb base links aren't working on [reflex.dev](http://reflex.dev/docs) #6437.

Root Cause

The docs breadcrumb builder created parent links by concatenating path segments. For Enterprise docs, that produced /docs/enterprise/, but the real route is /docs/enterprise/overview/.

Validation

• uv run pytest tests/test_breadcrumbs.py tests/test_routes.py -q
• uv run ruff check reflex_docs/templates/docpage/docpage.py tests/test_breadcrumbs.py
• Verified locally in Browser that clicking the Enterprise breadcrumb lands on /docs/enterprise/overview/.

Fixes #6437

[codspeed-hq]

Merging this PR will not alter performance

✅ 17 untouched benchmarks
⏩ 2 skipped benchmarks¹

---

_{Comparing codex/fix-docs-breadcrumb-overview-routes (37d385e) with main (b438de1)}

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. ↩

[greptile-apps]

Greptile Summary

This PR fixes broken parent breadcrumb links in the docs site — specifically for routes like /docs/enterprise/ where the real landing page is /docs/enterprise/overview/ — by tracking all registered doc routes at decoration time and resolving each breadcrumb segment against that registry.

• Route registry: A module-level _REGISTERED_DOC_ROUTES set is populated via _register_doc_route when each @docpage-decorated page function is imported, giving the breadcrumb builder a live list of valid paths.
• _resolve_breadcrumb_href: For each intermediate breadcrumb segment, the function first checks the direct path, then falls back to <path>overview/, and otherwise returns the raw path; the fallback of returning the un-normalized href when no match is found is inconsistent with the two success branches that always return normalized (trailing-slash) paths.
• Test: A new regression test monkeypatches the route registry and checks the rendered component string for the correct to: props.

Confidence Score: 4/5

Safe to merge for the primary Enterprise breadcrumb fix; the fallback branch returns a non-trailing-slash URL which could cause navigation inconsistencies for routes not in the registry.

The breadcrumb resolver correctly handles the registered-route and overview-fallback cases. The last return hands back the raw, un-normalized path rather than the already-computed route, so any breadcrumb segment that doesn't match either branch will produce a URL without a trailing slash — inconsistent with every other branch and potentially causing redirects or wrong-page navigation.

The fallback return in _resolve_breadcrumb_href in docs/app/reflex_docs/templates/docpage/docpage.py is worth correcting before merge.

Important Files Changed

Filename	Overview
docs/app/reflex_docs/templates/docpage/docpage.py	Introduces module-level route registry and _resolve_breadcrumb_href to fix broken parent breadcrumb links. Fallback branch returns raw href instead of the normalized route, causing a trailing-slash inconsistency.
docs/app/tests/test_breadcrumbs.py	New regression test for the Enterprise breadcrumb case; assertions depend on Reflex's internal component serialization format, making them brittle to upstream rendering changes.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A["@docpage decorator applied\n(import time)"] --> B["_register_doc_route(path)"]
    B --> C["_REGISTERED_DOC_ROUTES.add(\n_normalize_doc_route(path)\n)"]

    D["breadcrumb(path, …) called\n(request time)"] --> E["Split path into segments\n(strip 'docs')"]
    E --> F["Build current_path\nfor each segment"]
    F --> G["_resolve_breadcrumb_href(current_path)"]
    G --> H{"_normalize_doc_route(href)\nin routes?"}
    H -- Yes --> I["Return normalized route"]
    H -- No --> J{"_normalize_doc_route(\nhref + 'overview')\nin routes?"}
    J -- Yes --> K["Return overview route\ne.g. /enterprise/overview/"]
    J -- No --> L["Return raw href ⚠️\n(not normalized)"]
    I & K & L --> M["rx.el.a href=…"]

Loading

_{Reviews (1): Last reviewed commit: "Fix docs breadcrumb overview routes" | Re-trigger Greptile}

[greptile-apps]

The fallback branch returns the raw, un-normalized href (e.g. /enterprise with no trailing slash) while every other return in this function returns the fully-normalized route (e.g. /enterprise/). When a path segment has no matching route and no …/overview/ variant, the resulting breadcrumb link will be missing a trailing slash, producing an inconsistent URL relative to all other crumbs. Returning route keeps the output uniform.

Suggested change

	overview_route = _normalize_doc_route(f"{route}overview")
	if overview_route in routes:
	return overview_route
	return href
	overview_route = _normalize_doc_route(f"{route}overview")
	if overview_route in routes:
	return overview_route
	return route

[greptile-apps]

Fragile serialization-based assertions

The assertions match against Reflex's internal component serialization string (e.g. 'to:"/enterprise/overview/"'). If Reflex ever changes how it stringifies component props — which is an implementation detail, not a public contract — these assertions will silently break even when the breadcrumb logic is perfectly correct. A less brittle alternative would be to call _resolve_breadcrumb_href directly for the intermediate path segments, or to inspect the rendered component tree's props rather than the raw str() output.