Docs versioning #422
Description
Summary:
- As a user, I want to quickly review the docs for the particular version that I have.
- As a contributor, I want to be able to document the way that a feature works without overwriting the steps that were accurate for a past release.
Initial approach:
- Try out the MkDocs Material theme's versioning capability
- Figure out how to integrate versioned docs into the doc build process
More resources:
- Issue where doc versioning first came up: Quickstart Started Guide Does Not Work #407
- Feb 27, 2025 meeting minutes where doc versioning was discussed
Metadata
Metadata
Assignees
Type
Projects
Relationships
Participants
Activity
danehans commentedon Feb 27, 2025
@artberger I have assigned this issue to you. It would be great if this issue can be resolved in time for the v0.2.0 release. Track the milestones for upcoming details on the release date. cc: @ahg-g in case this issue should be added to #362.
liu-cong commentedon Jun 5, 2025
@artberger
This issue is currently in the v0.4 release tracker and v0.4 release is planned for Mid-June. Can you provide an estimate if this can be finished in the week of June 9?
Based on the estimate, we can decide whether to include this or postpone it to the v0.5 release. Thanks!
artberger commentedon Jun 6, 2025
@liu-cong thanks for following up. While it is possible that it might be finished next week (working PR), I am waiting on help from k8s GitHub/Netlify admins (ref Slack thread), so I am not sure on their availability. If we could postpone to the v0.5 release or a fast-follow post v0.4, that might be more realistic.
liu-cong commentedon Jun 6, 2025
Thanks for the update! We can check back next week again and postpone if not done.
danehans commentedon Jun 12, 2025
Bumped to v0.5 since @artberger is blocked due to #422 (comment).
@artberger I played around with docs versioning here earlier this week. This fork uses a GH action to trigger the versioned docs build and does not require a separate branch. This PR failed CI, but it's because GitHub Actions are not supported for this repository. I believe this process needs to be followed to have CI trigger the docs versioning (
latestversion for main branch andvX.Xfor tagged releases. You can also ref kubernetes/test-infra#34974 which adds an e2e CI job. LMKWYT.@robscott thoughts on ^?
artberger commentedon Jun 26, 2025
@danehans I updated my fork and Netlify preview site to use a GitHub workflow approach, based on your PR. For now, it just does the version dropdown and
v0.3.1 manual testquote that changes per version, not any of the content changes per version.Perhaps we can review to confirm that this approach would be better than #869 and the next steps?