docs: Astro/Starlight documentation site (supersedes #108)#120
Merged
Conversation
…ap-fill) + Pages workflow
…fill pin) Align scaffold with brief spec: proper title casing on all stub pages, TODO comments in go.mod and hugo.toml for re-pinning after PR #5 merges, concurrency group set to "pages", and _index.md content per spec.
Full sections 1-13 of docs/install-production.md migrated verbatim into docs/site/content/installation.md. Updated stale chart targetRevision from v0.1.0-alpha.8 to v0.1.0-alpha.9. Rewrote links to getting-started.md and troubleshooting into root-relative /local-development/ and /troubleshooting/. Added Beta documentation gate callouts for Keycloak prereqs (sec 7) and dual-endpoint auth explanation (sec 10.9).
Covers HuggingFace PVC-backed model caching, OCI/modelcar emptyDir loading, the concurrent-download lock mechanism, PVC sizing guidance, and per-model storage class override. All technical claims confirmed against operator/internal/controller/reconcilers/storage.go and docs/design.md.
…-serving-operator)
Add full configuration.md replacing the stub. Covers Helm values reference (27 user-customizable keys with exact defaults from values.yaml), LLMModel CRD field reference (spec.model, spec.model.storage, spec.resources, spec.access, spec.serving, spec.endpoints, spec.advanced, status fields), and NebariApp fields used by the key-manager template. All tables reconciled against the real source files; no README/design discrepancies found that affected content.
Replaces the stub with the full architecture narrative migrated from docs/design.md: components, reconciliation flow, dual endpoint auth (external apiKeyAuth + internal JWT), key manager design and data model, Envoy AI Gateway, cluster-singleton TLS reconciler, single- namespace deployment model, and security model. Values reference and CRD spec table are deliberately left in /configuration/; cross-links added throughout.
Documents all five GitHub Actions workflows (test, lint, build-images, docs, add-to-project), the three GHCR images they produce, chart versioning (version/appVersion kept in sync), and the current manual release process with explicit note of gaps (no automated Helm publish, draft alpha.9 release).
…grated flat docs - Add ## Known Limitations section to README.md drawn from design.md non-goals, key manager limitations, and single-namespace constraint - Add Documentation link near the top of README.md pointing to the published docs site - Update README.md links: docs/install-production.md -> installation/, docs/getting-started.md -> local-development/ - Update pack-metadata.yaml links.docs to published docs site /installation/ - git rm docs/design.md, docs/getting-started.md, docs/install-production.md
Adds scripts/check-links.sh which builds the Hugo site and verifies: - every internal href/src in public/**/*.html resolves to an existing file under public/ (handles the /nebari-llm-serving-pack subpath prefix) - every .edit-link href maps to an existing source file under content/ Pure bash + grep/sed; no Node or external tools beyond Hugo + coreutils.
- repoint stale docs/design.md + docs/getting-started.md refs in operator source comments to the published site (architecture / local-development) - wire scripts/check-links.sh into the docs CI build job - check-links.sh: hard-error on missing editBase; strip #fragment before resolving - fix Quickstart key-manager URL to the configured nebariApp hostname - scope Pages write/id-token permissions to the deploy job (least privilege) - pack-metadata docs link -> site root; hugo mod tidy cleans stale go.sum hash
…building in check-links
Address review feedback on the docs site: - shared-storage: remove the described .locked/noclobber/stale-lock mechanism, which the operator does not implement; describe the actual per-replica idempotent download behavior. - local-development: fix key-manager API paths (/api/models, /api/keys; the /api/v1/* routes do not exist). - architecture + README + configuration: state that key stripping (sanitize/forwardClientIDHeader) is planned, not yet enabled (needs Envoy Gateway v1.7+), and that the group-change audit is off by default (requires keyManager.oidcUserinfoURL, which ships empty). - check-links.sh: portable sed -E; robust edit-link extraction with a hard-fail when zero edit-links are found; note that fragments are not validated. - docs.yml: pin Go via go-version-file so it can't drift from go.mod; document the link-check step in cicd-and-releasing.
|
📄 Docs preview for |
andrewfulton9
left a comment
andrewfulton9
left a comment
There was a problem hiding this comment.
I think it could be helpful to add a docs readme. It could include how to run the server locally, build, what steps need to be taken to add/remove a component, how to add a page, ect. Anything in general someone who needs to update the docs would need/want to know to be effective
jbouder
reviewed
Jun 30, 2026
jbouder
left a comment
jbouder
left a comment
Contributor
There was a problem hiding this comment.
In general this looks good, but a few thoughts:
- why not put the astro files directly in the docs folder? The additional folder feels unneeded and adds an extra click to navigate
- Can we move the markdown and screenshots currently into the docs content?
- Suggest moving image assets from
publictosrc/assets
Flatten the Astro/Starlight project from docs/astro/ up to docs/ so the site is no longer nested a level deeper than it needs to be. Update every path reference in docs.yml, check-links.sh, check-content-parity.mjs, and the cicd-and-releasing page. Remove the stale root docs (design.md, getting-started.md, install-production.md) whose content was already migrated into the Starlight pages, along with the orphaned docs/screenshots/. Repoint the two remaining references (the passthrough example and the modelservice.go maintenance-contract comment) at the architecture/installation pages. Move the install-production screenshots from public/ to src/assets/ and switch their references to relative imports, so Astro optimizes and hashes them at build time instead of serving them unprocessed. installation.md is excluded from the content-parity check since its image refs now diverge from the frozen Hugo source by design. Expand the root Makefile into a self-documenting set of docs targets (help, docs, docs-install, docs-build, docs-preview, docs-test, docs-check-links) and add a Documentation site section to the README covering how to run and build the site, add a page, work with components, and handle images.
Contributor
Author
|
Thanks @andrewfulton9, good suggestion. I handled this in two places rather than a standalone README:
Pushed in ded3452. |
Contributor
Author
|
Thanks @jbouder, all three were good calls and they're in ded3452:
|
…ace checks The LLMModel and PassthroughModel validating webhooks read existing resources through the manager's cache-backed client. When a name-collision check runs immediately after the colliding resource is created, the informer cache may not have caught up yet, so the webhook misses the collision and admits a resource that shares another kind's api-keys Secret. The same race made the "reject a PassthroughModel whose name collides with an existing LLMModel" envtest spec fail intermittently in CI. Switch both webhooks to an uncached reader (mgr.GetAPIReader()) for their validation reads (the namespace-label check and the cross-kind name collision check), so admission decisions always see current API-server state. After a create returns, the object is durable in the API server, so a direct read is guaranteed to observe it. Verified by repeating the webhook suite 13 times with no failures, plus the full operator suite and golangci-lint.
Contributor
Author
|
Heads-up: 4ca3d92 is an operator fix, not docs. The Test workflow flaked on the previous push - the PassthroughModel name-collision webhook spec. Root cause: both the LLMModel and PassthroughModel validating webhooks ran their collision and namespace-label reads through the manager's cache-backed client, so a check firing right after the colliding resource was created could miss it while the informer cache caught up. That is a real admission gap and not just a test flake, since both kinds share the |
This was referenced Jul 1, 2026
This was referenced Jul 3, 2026
dcmcand
added a commit
that referenced
this pull request
Jul 7, 2026
Resolve docs conflict from the Astro/Starlight restructure (PR #120): - local-development.md: keep the PR's AI Gateway v0.5 dev-path content and additive sections; adopt main's slug-style internal links and renumber. - ui-development.md: relocate into docs/src/content/docs, add Starlight frontmatter, fix cross-links, add sidebar entry. - check-content-parity.mjs: exclude local-development.md (diverges by design).
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
3 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.
Replaces the Hugo docs site (#108) with an Astro + Starlight site, keeping the same content and the same Cloudflare Pages deploy setup.
Content is migrated 1:1 from #108 into Starlight's native content collection (bodies byte-identical, enforced by
scripts/check-content-parity.mjs). The one exception is the CI/CD page, which is rewritten to describe the new Astro workflow.Design uses the nebari-design tokens and components (light and dark verified).
Deploy is unchanged in shape:
docs.ymlnow builds Astro and deploys to the samellm-serving-packCloudflare Pages project. Per-PR previews,docs-preview-cleanup.yml, and production atpacks.nebari.dev/llm-serving-pack/are all preserved. Internal links are base-path-aware via a small remark plugin, and a portedcheck-links.shgates the build.The Hugo tree (
docs/site/) is removed.Known follow-up (non-blocking): harden
check-links.sh([ -f ]plus a checked-count line on success).