docs: publish the library changelogs - #650
Draft
tonyandrewmeyer wants to merge 2 commits into
Draft
tonyandrewmeyer wants to merge 2 commits into
tonyandrewmeyer wants to merge 2 commits into
Conversation
Every library has a CHANGELOG.md at its package root, but you can only read it by finding the right folder in the repo. Copy each one into the reference tree during preprocessing, under a per-library heading, and give them a Change logs page in the Reference section. Three heading conventions are in use: a per-version H1, a prose "# Changelog" with H2 versions, and Keep a Changelog with bracketed versions. A leading prose heading is dropped rather than demoted, so those pages don't carry a redundant Changelog section under their own title, and any remaining H1 is demoted so each page has one top-level heading.
Contributor
Author
|
@james-garner-canonical maybe we could talk about this and #649 together? |
tonyandrewmeyer
commented
Aug 31, 2026
Collaborator
Sure. I think this one would actually be fine to land essentially as-is, since it only requires the changelogs to be valid markdown. We could standardise accepted formats later, and build fancy things on top of that later if we wanted to. |
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
2 participants
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.
Every library has a
CHANGELOG.mdat its package root, but the only way to read one is to find the right folder in the repo, so nothing on the docs site tells you what changed in a release. This copies each of them into the reference tree during preprocessing and adds a Change logs page to the Reference section, so there's a page per library with the versions as subsections.Three heading conventions turned out to be in use: most packages go straight to a per-version H1 (
# 1.3.0 - 2 June 2026), the interfaces packages open with a prose# Changelogand use H2 for versions, andotlpandslothuse Keep a Changelog with bracketed versions. A leading prose heading is dropped rather than demoted - otherwise those pages get a redundantChangelogsection directly under their own title - and any remaining H1 is demoted so each page has exactly one top-level heading.just docs htmlproduces 23 pages and they all come out with a single H1 and version H2s.Preview.
Fixes #389