docs: add versioned docs build with tag-based snapshots#980
Open
efiacor wants to merge 2 commits into
Open
Conversation
✅ Deploy Preview for porch ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
efiacor
requested review from
Catalin-Stratulat-Ericsson,
CsatariGergely,
liamfallon,
lovesprung,
mozesl-nokia and
rendre-greyling
- Add versions.json manifest to define which versions to build - Add build-versioned-docs.sh script that builds main (latest) and tagged versions into subdirectories (e.g. /v1.5/) - Update netlify.toml to use the versioned build script - Update config.toml: relative URLs, version dropdown entries, latestTag - Docsy's built-in version-banner and navbar-version-selector handle the archived banner and version switcher dropdown The script uses only standard tools (awk, git, hugo, npm) with no additional dependencies. Tagged versions are built with an archived overlay config so Docsy renders the 'no longer maintained' banner. Signed-off-by: Fiachra Corcoran <fiachra.corcoran@est.tech>
|
mozesl-nokia
approved these changes
May 13, 2026
aravindtga
approved these changes
May 13, 2026
Contributor
There was a problem hiding this comment.
Pull request overview
This PR introduces a tag-based, multi-version Hugo docs build so the site can serve “latest” plus archived snapshots under versioned prefixes (e.g. /v1.5/) for Netlify deployment.
Changes:
- Added
scripts/build-versioned-docs.shto build current docs plus archived versions from git tags described indocs/versions.json. - Switched Netlify docs build to use the new script instead of a single Hugo invocation.
- Updated docs config for the version selector and refreshed the latest release tag metadata.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| scripts/build-versioned-docs.sh | New multi-version docs build script: builds latest + per-tag archived sites into one publish directory. |
| docs/versions.json | Declares which versions/tags/paths should be built as archived snapshots. |
| docs/netlify.toml | Uses the new versioned build script for Netlify builds. |
| docs/config.toml | Updates latest tag metadata and version selector entries; makes latest-docs link relative. |
Comments suppressed due to low confidence (4)
scripts/build-versioned-docs.sh:63
rm -rf "${OUTPUT_DIR}"can be destructive if the script is invoked with an unexpected/empty argument (e.g./). Add a safety check/guardrail (reject empty,/, and possibly paths outside the repo/docs tree) before deleting.
# Clean output directory
rm -rf "${OUTPUT_DIR}"
mkdir -p "${OUTPUT_DIR}"
scripts/build-versioned-docs.sh:73
npm install --quiet 2>/dev/null || truehides install failures and allows the build to proceed with missing PostCSS tooling, potentially producing incomplete/broken assets without surfacing the root cause. Consider failing the build on npm errors (and/or using a more deterministic install likenpm ciif a lockfile is available).
# Install npm dependencies (needed for PostCSS/autoprefixer)
if [[ -f "package.json" ]]; then
npm install --quiet 2>/dev/null || true
fi
scripts/build-versioned-docs.sh:107
- Temp dirs are only removed on the success path; if
git archive,sed, orhugofails, the script exits (due toset -e) and leaves${TEMP_DIR}behind. Use atrapto ensure cleanup on EXIT/ERR for each created temp dir.
# Create a temporary directory for the tagged docs
TEMP_DIR=$(mktemp -d)
# Extract the docs directory from the tag
git -C "${REPO_ROOT}" archive "${TAG}" -- docs/ | tar -x -C "${TEMP_DIR}"
scripts/build-versioned-docs.sh:144
- Same issue as the latest build:
npm install --quiet ... || truesuppresses errors in the tagged builds, which can yield silently broken CSS/JS for archived versions. Prefer surfacing npm failures and using a deterministic install approach.
# Install npm dependencies if package.json exists (needed for PostCSS/autoprefixer)
if [[ -f "package.json" ]]; then
npm install --quiet 2>/dev/null || true
fi
Comment on lines
+36
to
+42
| # Ensure required tools are available | ||
| for cmd in hugo git npm; do | ||
| if ! command -v "${cmd}" &> /dev/null; then | ||
| echo "ERROR: ${cmd} is required but not installed." >&2 | ||
| exit 1 | ||
| fi | ||
| done |
Comment on lines
+1
to
+11
| [ | ||
| { | ||
| "version": "latest", | ||
| "tag": null, | ||
| "path": "/" | ||
| }, | ||
| { | ||
| "version": "v1.5", | ||
| "tag": "v1.5.9", | ||
| "path": "/v1.5/" | ||
| } |
| # point people to the main doc site. | ||
|
|
||
| url_latest_version = "https://docs.porch.nephio.org/docs/" | ||
| url_latest_version = "/docs/" |
Contributor
Catalin-Stratulat-Ericsson
left a comment
Catalin-Stratulat-Ericsson
left a comment
There was a problem hiding this comment.
just a few comments
Comment on lines
+156
to
+157
| # Clean up temp dir | ||
| rm -rf "${TEMP_DIR}" |
Contributor
There was a problem hiding this comment.
This will only cleanup if its reached no? what if the script exists early for some reason? on github netlify build runners that's not an issue and these get wiped anyways but if people build locally and crash occurs their tmp dir's will leave a the temp_dir behind on every crash no?
Not a big deal but just a thought
Comment on lines
+109
to
+116
| # Remove existing [[params.versions]] entries from the tagged config | ||
| # to prevent duplication when our override config is merged | ||
| sed -i '/^\[\[params\.versions\]\]/,/^$/d' "${TEMP_DIR}/docs/config.toml" | ||
|
|
||
| # Fix hardcoded absolute paths in content files so they respect the versioned baseURL. | ||
| # Raw HTML links in Hugo shortcodes bypass baseURL processing. | ||
| find "${TEMP_DIR}/docs/content" -name "*.md" -exec \ | ||
| sed -i "s|href=\"/docs|href=\"${URL_PATH}docs|g" {} \; |
Contributor
There was a problem hiding this comment.
This is an AI discovered potential issue as i would not have found this but apparently on MacOS sed parses slightly differently e.g. On macOS, sed -i requires an empty string argument (sed -i '') and If contributors build docs locally on macOS, this will fail. Since it runs on Netlify (Linux), it's fine for CI.
We would need someone using MacOS to confirm it.
Did a bit of digging and found the following which explains it here
Suggested change
| # Remove existing [[params.versions]] entries from the tagged config | |
| # to prevent duplication when our override config is merged | |
| sed -i '/^\[\[params\.versions\]\]/,/^$/d' "${TEMP_DIR}/docs/config.toml" | |
| # Fix hardcoded absolute paths in content files so they respect the versioned baseURL. | |
| # Raw HTML links in Hugo shortcodes bypass baseURL processing. | |
| find "${TEMP_DIR}/docs/content" -name "*.md" -exec \ | |
| sed -i "s|href=\"/docs|href=\"${URL_PATH}docs|g" {} \; | |
| # Remove existing [[params.versions]] entries from the tagged config | |
| # to prevent duplication when our override config is merged | |
| sed -i'' -e '/^\[\[params\.versions\]\]/,/^$/d' "${TEMP_DIR}/docs/config.toml" | |
| # Fix hardcoded absolute paths in content files so they respect the versioned baseURL. | |
| # Raw HTML links in Hugo shortcodes bypass baseURL processing. | |
| find "${TEMP_DIR}/docs/content" -name "*.md" -exec \ | |
| sed -i'' -e "s|href=\"/docs|href=\"${URL_PATH}docs|g" {} \; |
Collaborator
There was a problem hiding this comment.
This is well known by MacOS users, especially the different behavoiour of the -i parameter. We usually just do some hackery to override the MacOS stock sed with gsed, the Linux-compatible one. I have done this
% which sed
/usr/local/bin/sed
% ls -l /usr/local/bin/sed
lrwxr-xr-x 1 root admin 22 15 May 14:10 /usr/local/bin/sed -> /opt/homebrew/bin/gsed
% sed --version
sed (GNU sed) 4.10
So in short it is fine to ignore this comment.
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
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.
Description
scripts/build-versioned-docs.shreadsdocs/versions.json, builds main to/and each tagged version to its subdirectory (e.g./v1.5/). Docsy's built-in version-banner and navbar-version-selector handle the UI.Type of Change
Checklist
Testing Instructions
/v1.5/in the preview — should show archived docs with banner./scripts/build-versioned-docs.shand checkdocs/public/anddocs/public/v1.5/Additional Notes
AI Disclosure
[x] I have used AI in the creation of this PR.