Surface package changelogs on docs site

[masenf]

Type of change

• New feature (non-breaking change which adds functionality)
• This change requires a documentation update

Description

This PR adds changelog discovery and rendering to the docs site, making package changelogs accessible at /docs/changelog/ instead of requiring users to visit GitHub releases.

What changed:

1. New reflex_docs/changelogs.py module — Discovers and normalizes changelogs:

   • discover_repo_changelogs() finds towncrier-managed changelogs in the monorepo (repo root + packages/*/CHANGELOG.md)
   • find_distribution_changelog() locates changelogs shipped with installed distributions (e.g., reflex-enterprise)
   • discover_changelogs() combines both sources, ordering reflex first then alphabetically
   • normalize_changelog() ensures consistent H1 headings across different changelog formats (towncrier vs. Keep-a-Changelog)

2. Changelog rendering in docs — Integrated into the docs pipeline:

   • New handle_changelog_doc() handler normalizes changelog markdown and limits TOC to version headings (H2 and above)
   • Changelogs are registered as virtual docs under docs/changelog/ with the main reflex changelog at the section index
   • Updated footer link to point to /changelog/ instead of GitHub releases

3. Sidebar navigation — Added changelog section to the docs sidebar:

   • New get_sidebar_items_changelog() dynamically generates sidebar items from discovered packages
   • Changelog routes are treated as API reference content for sidebar styling

4. Helper function — Added render_markdown_with_toc() to extract heading structure while rendering markdown

5. Documentation — Updated CONTRIBUTING.md to explain where changelogs are published

Tests

• Added comprehensive test suite in docs/app/tests/test_changelogs.py covering:
  • Repo changelog discovery (monorepo structure)
  • Distribution changelog discovery (installed packages)
  • Changelog normalization (towncrier and Keep-a-Changelog formats)
  • Page title generation
  • Edge cases (missing distributions, stale file records, no file metadata)
• Added route validation test in test_routes.py to ensure all discovered changelogs are served
• Added section naming test in test_agent_files.py for root-level markdown docs

All tests pass with the changes.

Related issues

Closes the need for users to navigate to GitHub releases for changelog information.

https://claude.ai/code/session_01ToXo8Yg1VTuuT2jgBqK6T7

[codspeed-hq]

Merging this PR will not alter performance

✅ 26 untouched benchmarks
⏩ 8 skipped benchmarks¹

---

_{Comparing claude/lucid-hypatia-xq0xzi (82823ee) with main (559e79b)}

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 surfaces package changelogs on the docs site at /docs/changelog/ by discovering towncrier-managed changelogs in the monorepo (CHANGELOG.md and packages/*/CHANGELOG.md) and reading the reflex-enterprise changelog from its installed distribution, then registering them as virtual docs with normalized headings and a filtered TOC.

• New changelogs.py module handles discovery, ordering (reflex first, rest alphabetical), distribution-file depth-sorting to avoid vendored changelogs, and H1 normalization for both towncrier (no H1) and Keep-a-Changelog (generic H1) formats.
• Docs pipeline integration adds a handle_changelog_doc handler, a render_markdown_with_toc helper, and module-level registration of changelog paths into all_docs/manual_titles before the main processing pass.
• Sidebar and footer are updated to link to the on-site changelog; changelog pages are displayed under the API-reference sidebar tab using the existing styling.

Confidence Score: 5/5

Safe to merge — changes are additive (new virtual docs, updated sidebar/footer links, CI env var) with no modifications to existing rendering logic or data paths.

The changelog discovery and normalization logic is straightforward and well-exercised by a thorough test suite covering edge cases (missing distributions, stale file records, vendored changelogs, ordering invariants). The module-level registration correctly populates all_docs and manual_titles before the main pipeline loop runs. The one non-trivial runtime concern — reading changelog files at page-render time — is consistent with the existing doc handler pattern and benign for a build-time docs site.

No files require special attention.

Important Files Changed

Filename	Overview
docs/app/reflex_docs/changelogs.py	New module for discovering and normalizing package changelogs; clean implementation with good guards for missing distributions and vendored files
docs/app/reflex_docs/pages/docs/init.py	Integrates changelog discovery into the docs pipeline; module-level loop correctly populates all_docs and manual_titles before the main processing pass runs
docs/app/reflex_docs/templates/docpage/sidebar/sidebar.py	Adds changelog_index parameter to sidebar_comp and registers changelog pages under the API-reference sidebar tab via url.startsWith("/changelog/")
docs/app/reflex_docs/templates/docpage/sidebar/sidebar_items/reference.py	Adds get_sidebar_items_changelog() that creates one SideBarItem per discovered package; items use raw PyPI names as display labels (intentional per PR rationale)
docs/app/tests/test_changelogs.py	Comprehensive test suite covering discovery, normalization, edge cases (stale records, None files, vendored changelogs), and ordering invariants
docs/app/tests/test_routes.py	New test_changelog_routes validates that every discovered package changelog resolves to a real route in the app
docs/app/agent_files/_plugin.py	One-line bug fix: strips .md suffix from root-level docs before formatting the section name so "changelog.md" → "Changelog" not "Changelog.Md"
docs/app/reflex_docs/docgen_pipeline.py	Adds render_markdown_with_toc() helper that parses markdown once and returns both the TOC heading list and the rendered component

_{Reviews (5): Last reviewed commit: "Merge branch 'main' into claude/lucid-hy..." | Re-trigger Greptile}