docs: SEO optimization for graphing / charts documentation

[Alek99]

Summary

On-page SEO pass across the graphing docs, grounded in Ahrefs keyword/SERP data. These pages wrap Recharts (not Plotly, as sometimes assumed), and the winnable, high-volume terms are Recharts + general chart-type terms (mostly KD 0–15) where Reflex already ranked page 1 but with weak on-page signals. Two structural gaps affected every chart page — no meta descriptions and malformed titles ("Barchart") — plus near-zero internal linking and several thin/undocumented pages.

Type of change

• This change requires a documentation update (it is a documentation update, plus small supporting code changes)

What changed

Framework/code (small, supporting):

• Library docs now emit a page-specific meta description (derived from frontmatter/body) and honor an explicit frontmatter title: — previously every component doc inherited the generic site-wide description and a title-cased filename.
• Sidebar labels now use the frontmatter title (e.g. "Area Chart" instead of "Areachart") while still deriving the URL from the filename.
• reflex-docgen frontmatter parser: meta_description/description added to the known-keys set so they aren't misparsed as component-preview lambdas (with regression test).
• Library index.md files render as normal docs (not components), enabling section overview pages.

Content:

• Titles + keyword-rich meta descriptions on all chart pages; intros mention Reflex / Recharts / pure Python and high-value synonyms (scatter plot, donut, spider, gauge, combo, stacked/grouped/horizontal bar, bubble, multi-line).
• New Stacked Bar Chart and Bubble Chart examples; expanded the thin composed / error-bar / radial-bar pages.
• New Treemap page (the rx.recharts.treemap component shipped but was undocumented).
• Plotly page built out with Plotly Express examples (bar, scatter, pie, heatmap, histogram, box plot) targeting the low-difficulty Plotly long-tail.
• "Related Charts" cross-links added across all chart pages (internal linking was near-zero).
• New graphing overview page at /library/graphing/general/ targeting category terms (python data visualization, python dashboard) and acting as an internal-linking hub.

Testing

• ruff check and ruff format --check pass on all changed Python files.
• Added regression tests: tests/units/docgen/test_markdown.py and docs/app/tests/test_doc_description.py.
• Every added demo/demo exec code block AST-parses; all new component APIs (z_axis, Treemap, ErrorBar on Line, dual y_axis_id) verified against the component source; all internal links verified to resolve; all frontmatter validated as YAML.
• ⚠️ I could not run the full pytest suite or a reflex compile in the sandbox (the pinned Python toolchain wasn't installable there). Please run the docs build + unit tests in CI before merging.

Notes

Two remaining levers are outside on-page docs: the /library/graphing/charts/ index is still a thin shell (could get the same overview treatment), and backlinks (every subpage has URL Rating 0). Rankings will move only after deploy + re-crawl (~1–4 weeks); the target keywords aren't yet in the Ahrefs Rank Tracker, so adding them would make the impact measurable.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Ez43BK9AhhMPMdRcFmMEPR

---

Generated by Claude Code

[codspeed-hq]

Merging this PR will not alter performance

✅ 26 untouched benchmarks
⏩ 8 skipped benchmarks¹

---

_{Comparing claude/plotly-charts-seo-o8sxyy (397887a) with main (a73404a)}

Footnotes

1. 8 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 performs an SEO pass across the Recharts-based graphing documentation: adding keyword-rich title and meta_description frontmatter to every chart page, new examples (stacked bar, bubble/scatter, treemap, Plotly Express chart types), "Related Charts" cross-links, and a new Treemap page for the previously undocumented rx.recharts.Treemap component.

• Framework changes: handle_library_doc now reads frontmatter to emit page-specific meta descriptions and human-friendly titles (e.g. "Bar Chart" instead of "Barchart"); a new library_display_titles module-level dict is populated during doc processing and used by the sidebar builder via the same deferred-import pattern already in place. meta_description/description were added to _KNOWN_KEYS in the reflex_docgen frontmatter parser so they are not misparsed as component-preview lambdas.
• Content: Frontmatter titles and meta descriptions added to all chart pages; new stacked bar, bubble chart, dual-axis composed chart, error-bar-on-line, and Plotly Express examples; "Related Charts" sections across all pages; new treemap.md page. All APIs verified against component source.

Confidence Score: 5/5

Safe to merge — all Python changes are additive and narrowly scoped to doc metadata extraction and sidebar label rendering.

The Python changes are small: a new module-level dict populated during startup, a deferred import following the existing pattern in the sidebar, and a one-line addition to _KNOWN_KEYS in the docgen parser. All component API usages in the new examples were verified against the component source. Tests cover both the parser fix and the description extraction fallback. No existing paths are altered.

No files require special attention.

Important Files Changed

Filename	Overview
docs/app/reflex_docs/pages/docs/init.py	Adds library_display_titles dict and populates it from frontmatter title: in handle_library_doc; correctly threaded into multi_docs call. Logic and ordering look correct.
docs/app/reflex_docs/templates/docpage/sidebar/sidebar_items/component_lib.py	Uses a deferred from reflex_docs.pages.docs import library_display_titles inside get_category_children, consistent with the existing pattern for component_list and graphing_components. Lookup with fallback to get_display_name is correct.
docs/library/graphing/charts/treemap.md	New page documenting rx.recharts.Treemap. Props (data_key, name_key, aspect_ratio) verified against component source. rx.color() inside data dicts matches the established pattern used in piechart.md and radialbarchart.md.
docs/library/graphing/other-charts/plotly.md	Added six Plotly Express examples (bar, scatter, pie, heatmap, histogram, box plot) using px.data built-in datasets; all use demo exec code blocks and rx.plotly(data=fig) correctly.
docs/library/graphing/charts/composedchart.md	New dual-axis composed chart example; y_axis_id on bar/line and orientation=right on the second y_axis are valid props verified against component source.
docs/library/graphing/charts/scatterchart.md	New bubble chart section using rx.recharts.z_axis(); data_key, range, and name props verified against ZAxis component source.
tests/units/docgen/test_markdown.py	Added test_meta_description_not_treated_as_preview confirming meta_description/description stay in frontmatter.metadata and don't become component-preview lambdas; correct and covers the newly added _KNOWN_KEYS entries.
docs/app/tests/test_doc_description.py	New test validates the regex fallback path of extract_doc_description handles the components: list + meta_description: pattern without treating component names as description content.
docs/app/reflex_docs/pages/library_previews.py	Updated three graphing section descriptions to be more keyword-rich and accurate; purely cosmetic/copy change.

_{Reviews (5): Last reviewed commit: "Merge remote-tracking branch 'origin/mai..." | Re-trigger Greptile}