Fix: Disable edit links for unreleased versions#1066
Conversation
- Add section on testing and verifying changes locally - Add spellchecking guidance with dictionary setup - Add documentation versioning guidelines - Reference human-centric guidelines (DCO, PR etiquette) to CONTRIBUTING.md - Add troubleshooting sections Signed-off-by: Jonah Kowall <jkowall@kowall.net>
This change disables the 'Edit this page', 'View page source', and 'Create child page' links for pages within the '_dev' directory (unreleased versions). This prevents broken links (404) in CI checks for new documentation files that do not yet exist on the main branch. It also updates .htmltest.yml to enable checking of edit links for released versions, ensuring no regressions. Fixes #1065 Signed-off-by: Jonah Kowall <jkowall@kowall.net>
There was a problem hiding this comment.
Pull request overview
Updates Docsy meta link rendering and link-check configuration to avoid CI failures caused by “Edit/View this page” GitHub links that point at content not present on the main branch yet (intended for unreleased docs content).
Changes:
- Adds a Docsy partial override to suppress GitHub view/edit/create-child links for
_devcontent. - Removes the htmltest ignore rule that skipped Docsy-generated GitHub
new|editURLs. - Expands AGENTS.md with local verification/testing guidance and doc versioning notes.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
themes/docsy-overrides/layouts/_partials/page-meta-links.html |
Conditionally hides GitHub meta links for _dev pages. |
AGENTS.md |
Adds contributor workflow tips (build/test/link checks/spellcheck/versioning). |
.htmltest.yml |
Changes link-check ignore patterns to start checking Docsy GitHub edit links. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| - ^/docs/latest(/?|/architecture/)$ | ||
| - /livereload.js # cSpell:disable-line | ||
| - ^https://www.jaegertracing.io/js/lunr | ||
| # Ignore Docsy-generated GitHub links for now | ||
| - ^https?://github\.com/.*?/.*?/(new|edit)/ # view-page, edit-source etc | ||
|
|
There was a problem hiding this comment.
Removing the ignore rule for Docsy GitHub new|edit links will make htmltest fail on pull requests that add new documentation files outside _dev (notably the automated release PR, which adds a new content/docs/v2/<version>/ tree). Those pages will still emit GitHub URLs targeting main, which 404 until after merge. Either keep ignoring these GitHub URLs in PR builds, or change the generated URLs to point at the current PR branch/commit for CI link-check runs.
the linter was failing for the latest release links which are valid in the PR branch but not valid against main. The |
Addressing feedback from @yurishkuro: - Reverted the logic that disabled links for _dev versions. - Updated page-meta-links.html to use GITHUB_SHA (Actions) or HEAD (Netlify) environment variables when running in CI. This ensures edit links point to the commit/branch being tested, making them valid for new files introduced in PRs. - Updated hugo.yaml to whitelist GITHUB_SHA and HEAD in the security.funcs.getenv policy. Signed-off-by: Jonah Kowall <jkowall@kowall.net>
Thanks, I reverted the _dev exclusion logic as you pointed out. |
There was a problem hiding this comment.
is this overridig docsy's existing template?
There was a problem hiding this comment.
Yes, this overrides Docsy's existing page-meta-links.html template. Hugo's theme override mechanism allows placing a file at the same relative path in themes/docsy-overrides/ to replace the original. The only modification from the original Docsy template is lines 8-11, which dynamically sets $gh_branch to GITHUB_SHA (GitHub Actions) or HEAD (Netlify) when running in CI environments. This ensures edit links point to the correct commit/branch for new files introduced in PRs, preventing 404 errors during link checking
There was a problem hiding this comment.
@chalin tried very hard to avoid unnecessary theme overrides, especially for relatively complex templates.
I would rather just keep the ignore instruction, except that the regex seems wrong and we could make it more precise
# Ignore Docsy-generated GitHub links for now
2 participants
This PR fixes #1065 by disabling the 'Edit this page' link for unreleased versions (files in
_dev).Changes
page-meta-links.htmlto conditionally hide edit links for_devcontent..htmltest.ymlto enable checking of edit links for released versions.Verification
_devpages but present for released pages.