Docs: Move Hugo engine out of this repo - #433
Open
tr0njavolta wants to merge 3 commits into
Open
tr0njavolta wants to merge 3 commits into
tr0njavolta wants to merge 3 commits into
Conversation
tr0njavolta
changed the title
tr0njavolta
force-pushed
the
docs-in-code-repo
branch
from
September 8, 2026 17:42
144235f to
6c6135a
Compare
negz
reviewed
Sep 8, 2026
Comment on lines
+336
to
+340
| # Preview the docs from this repo, with live reload. The Hugo project that | ||
| # renders them - config, layouts, theme, asset pipelines - is the docs-site | ||
| # repo; the prose is here, under docs/content. This clones it into docs/site | ||
| # (gitignored, and the same path vercel.json builds from) and points it at | ||
| # this working tree, so what you see is the file under your cursor. |
Collaborator
There was a problem hiding this comment.
Is there some way we can keep all docs interactions one-way, from this repo -> docs-site? iidc We currently have a situation where docs-site clones this repo and this repo also clones docs-site.
I'm imagining something like:
- Only docs-site has a Vercel project (not this repo)
- Any utils for previewing or otherwise working with docs are defined in docs-site
- A PR workflow from this repo triggers a preview workflow/build in docs-site
For the utils, if you define them as a Nix flake in docs-site, this repo would be able to import and reference them as a convenience.
The Hugo project - config, layouts, the geekboot theme, and the CSS and JavaScript pipelines - now lives in modelplaneai/docs-site, along with the build, the Vercel project, and the preview tooling. This repo keeps the prose and knows nothing about Hugo. Everything crosses the boundary in one direction. That repo fetches content when it builds; this repo asks it to build, and .github/workflows/docs.yml is the whole interface: a pull request touching docs/ or apis/ a preview of that revision a merge to main or a release-* branch every version, into production The preview link is posted here the moment the pull request opens, because the hostname derives from the pull request number rather than from the deployment, so the site repo needs no write access to this one. A merge is what publishes: nothing there pins a content revision, so publishing is a rebuild that reads the tip of every branch. Previewing locally is one command from the root of this repo, and needs no checkout of the site: nix run github:modelplaneai/docs-site#preview Versions are this repo's release-X.Y branches - whatever is on release-0.2 is what the 0.2 docs say. Cutting that branch is this repo's whole part in publishing a version. What stays here is the content and the checks that belong with it: Vale on the prose and the Pydantic validation of the example manifests. The site build and htmltest move with the site, as does the DocSearch crawl, whose config lives with the theme it indexes. docs/data stays as well. apigroups.yaml and recipes.yaml are content, not theme: they group the generated API reference and fill the recipe tables, and docs/content/reference/_content.gotmpl reads the first of them as much as the theme does. Only versions.yaml goes, superseded by the site's own version list. Dropping them would not fail a build - it would silently empty the reference landing page's grouped cards, the sidebar's reference tree, and every recipe table row. Vale's style sync is also taught to find its styles on macOS, where it installs them under Application Support rather than the XDG data directory, so 'nix flake check' works on a maintainer's machine and not only in CI. Signed-off-by: Rae Sharp <resharp20@gmail.com>
tr0njavolta
force-pushed
the
docs-in-code-repo
branch
from
September 9, 2026 20:04
6c6135a to
b41c65f
Compare
Signed-off-by: Rae Sharp <resharp20@gmail.com>
Signed-off-by: Rae Sharp <resharp20@gmail.com>
Collaborator
Author
|
docs-site clones read-only, nothing here clones docs-site. A PR touching .The docs-site has a Vercel project now, vercel.json is deleted here. The preview utils are a flake there, so nix run github:modelplaneai/docs-site#preview from a checkout here serves main with live reload. A PR here triggers the build there through repository_dispatch. Still need approval on the PAT DOCS_SITE_DISPATCH_TOKEN secret here, with Contents write to docs-site. After merge we can point the modelplane-docs Vercel project from this repo to docs-site. |
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
2 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.
Description of your changes
This PR closes the loop on moving the hugo theme to modelplaneai/docs-site.. The docs-site build clones one branch of this repo per docs version and mounts docs/content, docs/data, docs/manifests, and apis/ into the site. The site build, htmltest, DocSearch crawl move to the docs-site repo.
Vale, example manifest validation, apigroups.yaml, recipes.yaml stay in this repo.
versions.yaml removed because modelplaneai/docs-site/blob/main/themes/geekboot/data/docversions.json controls the available/latest versions.
vercel.json keeps a Vercel preview on pull requests here: it clones the site repo and runs its build.sh with CONTENT_DIR set to this checkout, which builds this branch alone at the deployment root rather than cloning the version list.
Fixes #
I have:
nix flake check(or./nix.sh flake check) and made sure it passes.git commit -s.