docs: turn release notes into a chronological blog timeline - #2721
Draft
claudiacodacy wants to merge 3 commits into
Draft
docs: turn release notes into a chronological blog timeline#2721claudiacodacy wants to merge 3 commits into
claudiacodacy wants to merge 3 commits into
Conversation
Replace the hand-maintained release notes index (a manually curated
bullet list, with every post also individually listed in mkdocs.yml's
nav) with mkdocs-material's built-in blog plugin, giving Cloud and
Self-hosted release notes a unified, card-based timeline with date/
category metadata, category filter pages, year archives, and a TOC --
closer to the changelog experience the team wanted to match.
- Move 135 release notes (95 Cloud + 40 Self-hosted) into
docs/release-notes/updates/, each with added date/categories front
matter. Cloud dates parsed from filenames, Self-hosted dates parsed
from each post's "released on <date>" sentence.
- Configure material/blog with post_url_format: "{categories}/{file}"
so every existing release-notes/cloud/... and
release-notes/self-hosted/... URL is preserved exactly -- no broken
links, no redirect churn for public URLs.
- Update ~40 redirects: targets that pointed at the old file paths
(mkdocs-redirects validates targets against source path, not final
URL, so this was required once files moved).
- Fix links that the reorg would have broken: 3 internal
cross-references, 15 self-hosted upgrade guides linking to the
removed #self-hosted anchor, and 5 links from other doc pages.
Tighten the rss plugin's match_path so its auto-generated archive/
category/pagination pages don't crowd real posts out of the feed.
- Trim nav from ~300 manually-listed file entries down to one.
- Move special-thanks.md to the end of the Documentation tab's nav
(it had been silently dropped from any nav entirely by an earlier
tab-reduction commit).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Contributor
Up to standards ✅🟢 Issues
|
Contributor
|
Overall readability score: 53.81 (🔴 -0.11) View detailed metrics🟢 - Shows an increase in readability
Averages:
View metric targets
|
Writing the Release notes nav entry as a bare single-page shorthand
("- Release notes: release-notes/index.md") collapsed it from a nav
section into a leaf page: the tab label fell back to the page's own
title ("Codacy release notes") instead of the configured "Release
notes" label, and the secondary sidebar (Archive/Categories, normally
auto-injected by the blog plugin into the section) disappeared
entirely. Restoring the section form (a list, even with a single
child) fixes both -- verified locally, tab label and sidebar are back.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
- Disable Microsoft.RangeFormat and Microsoft.Ranges in .vale.ini. Vale checks front matter values as prose, so the new date: front matter (e.g. 2026-01-16) got flagged as "a range of numbers needing an en dash". These rules already fire 271 times across the existing docs corpus (just never surfaced, since CI only lints added lines), so disabling them fits the repo's existing pattern of trimming down noisy Microsoft rules. - Raise categories_pagination_per_page to 50. htmltest was failing on CI with "target does not exist" for release-notes/category/self-hosted/, even though the page builds fine locally (tried both Python 3.13 and CI's exact 3.14.6, matching package versions) -- couldn't reproduce or root-cause the Linux-vs-macOS difference. Since Self-hosted has 40 posts, raising the per-page limit puts them all on one page, avoiding pagination for that category entirely rather than depending on whatever page-1-of-N edge case caused the missing file on CI. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
mkdocs.yml's nav) with mkdocs-material's built-inblogplugin: a unified, card-based timeline for Cloud + Self-hosted release notes with date/category metadata, category filter pages, year archives, and a TOC.release-notes/cloud/...,release-notes/self-hosted/...) are preserved exactly viapost_url_format: "{categories}/{file}"— no broken links, no churn on existing redirects' final destinations.redirects:targets that pointed at the old file paths (required sincemkdocs-redirectsvalidates targets against source path, not final URL).rssplugin'smatch_pathso the blog plugin's auto-generated archive/category/pagination pages don't crowd real posts out of the feed.special-thanks.mdto the end of the Documentation tab's nav (it had been silently dropped from any nav entirely by an earlier tab-reduction commit).Test plan
mkdocs build(strict mode) — clean, no warningsmkdocs serve+ browser: release notes timeline, category filter pages, Special thanks page, TOC, light/dark modehc/...and old release-notes paths) still resolve to the migrated posts🤖 Generated with Claude Code