Migrate Hugo docs to the Nebari Starlight baseline - #53
Merged
Conversation
Replace the Hugo + hugo-book site in docs/site/ with an Astro + Starlight project at docs/ using the shared @nebari/starlight theme plugin: - migrate all 27 content pages to docs/src/content/docs/, converting Hugo front matter and relref shortcodes to plain paths, with the section nav expressed as an explicit Starlight sidebar - update tools/docs-gen to emit Starlight-compatible cross-links - rewrite .github/workflows/docs.yml to the baseline shape (Node 22, npm ci, unit tests, build, internal link check) while keeping the GitHub Pages deploy that serves skillsctl.dev - add the baseline remark-base-links plugin (+ vitest tests) and scripts/check-links.sh internal link checker - carry CNAME and images into docs/public/ and remove the Hugo toolchain Closes #52 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Now that the dashboard Worker routes packs.nebari.dev/skillsctl/ to skillsctl.pages.dev: - pack-metadata.yaml: set docs_site: true and point links.docs at https://packs.nebari.dev/skillsctl/ - docs.yml: adopt the baseline Cloudflare Pages deploy with per-branch preview deploys and a PR preview comment, replacing GitHub Pages - astro.config.mjs: default SITE to https://packs.nebari.dev and send the header logo back to the pack catalog - drop the GitHub Pages CNAME and update the README docs link Co-Authored-By: Claude Fable 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.
Closes #52.
Replaces the Hugo + hugo-book site in
docs/site/with an Astro + Starlight project atdocs/, using the shared@nebari/starlighttheme plugin, matching the docs baseline in the pack repos (mlflow-pack,nebi-pack, …).What changed
docs/src/content/docs/with the same URLs (_index.md→index.md, front matter reduced totitle, duplicated leading H1s stripped since Starlight renders the title,{{< relref >}}shortcodes converted to plain paths). Sidebar nav is now explicit inastro.config.mjs, mirroring the old weight-based order.plugins: [nebari()]provides the shared Nebari identity;docs/public/favicon.svgis the skillsctl icon.CNAMEand images carried intodocs/public/.tools/docs-gennow emits plain-path cross-links instead of Hugo relrefs; output goes todocs/src/content/docs/cli/reference/(still generated in CI, gitignored, surfaced via a Starlightautogeneratesidebar group).make docs-cliupdated.remark-base-linksplugin + vitest tests, andscripts/check-links.shinternal link checker.docs.ymlrewritten to the baseline shape — Node 22,npm ci, unit tests, CLI-reference generation,SITE/BASE-driven build, link check — now also running on PRs.hugo.toml,docs/site/go.mod/go.sum,layouts/, custom CSS.Deploy note
Now deploys to Cloudflare Pages (project
skillsctl) behind the packs.nebari.dev portal Worker, with per-branch PR preview deploys and a preview-URL comment — the full pack baseline.pack-metadata.yamlsetsdocs_site: trueand pointslinks.docsat https://packs.nebari.dev/skillsctl/.CLOUDFLARE_API_TOKENis not currently shared with this repo (onlyCLOUDFLARE_ACCOUNT_IDis) — an org admin needs to addskillsctlto that secret's repository access list or the deploy step will fail.Verified locally
go test ./tools/docs-gen/✅npm test(10 tests) ✅go run ./tools/docs-gen -o docs/src/content/docs/cli/reference && npm run build— 42 pages, Pagefind index, sitemap ✅scripts/check-links.sh→LINKS_OKfor bothBASE=/and aBASE=/skillsctl/subpath build ✅🤖 Generated with Claude Code