docs: publish a MkDocs site to GitHub Pages - #203
Merged
Conversation
The repo had ~1500 lines of Markdown split across README.md, docs/design/, and specs/ with no navigation between them and nothing published. Organize them into a MkDocs site matching the convention already used by lance-namespace and lance-spark (mkdocs-material, docs_dir: src, gh-pages branch). - docs/mkdocs.yml with nav over Guide / Specs / Design - Guide pages (quickstart, rollouts, storage, development) lifted from the README so the front page stays short - Move specs/ and docs/design/ under docs/src/; update the four Rust doc comments that referenced the old specs/ path - .github/workflows/docs.yml: build with --strict on every PR touching docs/, deploy to gh-pages only on push to main - Ignore docs/site/ (the existing /site rule only matched the repo root) Verified with a local `mkdocs build --strict` (MkDocs 1.6.1, same version the other org sites deploy with) and `cargo check`. Co-Authored-By: Claude <noreply@anthropic.com>
beinan
added a commit
that referenced
this pull request
Jul 27, 2026
## Summary Follow-up to #203. That PR deployed the docs site by pushing built HTML to a `gh-pages` branch (`mkdocs gh-deploy`), matching what lance-namespace / lance-spark / lance-python-doc do. This switches to GitHub's official Pages deployment path — `upload-pages-artifact` + `deploy-pages`. ## Why - **Drops `contents: write`.** The old deploy job needed write access to the repository to push a branch. The workflow is now read-only by default, and the deploy job opts into only `pages: write` + `id-token: write`. A compromised docs dependency can no longer push commits. - **No build output in the repo.** The site travels as an artifact, so `gh-pages` can be deleted and the repo keeps only source. - **Deployment history.** Runs are tracked under the `github-pages` environment, which is also where protection rules would go. - **Deploy is no longer cancel-in-progress.** Cancelling a live site deploy half-way is worse than letting it finish; PR builds stay cancellable. PRs still build with `--strict` and never deploy — unchanged. ##⚠️ Requires a one-time admin action Under **Settings → Pages → Source**, select **GitHub Actions**. Worth being explicit about something I got wrong in #203: I claimed no admin action would be required, based on testing on my fork where pushing `gh-pages` auto-created the site. That does not generalize — it worked because I'm an admin on my own fork. On this repo the `Docs` workflow ran green and created the `gh-pages` branch, but the Pages site was never created, so <https://lance-format.github.io/lance-context/> is still 404. **Both modes need that same one-time click**, so given a maintainer has to touch Settings either way, Actions mode gets the better long-term setup for the same cost. Until the switch is flipped, the `deploy` job fails with a Pages-not-configured error; `build` is unaffected, so PR checks stay green. ## Note on org convention This makes lance-context the first repo in the org on Actions mode — `lance`, `lance-spark`, `lance-namespace`, and `lance-python-doc` are all `build_type: legacy` on `gh-pages`. Flagging that deliberately in case you'd rather stay consistent; happy to revert to #203's approach if so, in which case the admin step is instead "Source → Deploy from a branch → `gh-pages` / root" and the branch is already sitting there ready. ## Verification - `mkdocs build --strict` passes; workflow YAML parses with the expected job graph, permissions, and environment. - The site content itself is unchanged by this PR — only how it's published. Content preview from #203: <https://beinan.github.io/lance-context/> - The deploy path can't be fully exercised until Pages is switched on, since that's the thing being enabled. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude <noreply@anthropic.com>
beinan
added a commit
that referenced
this pull request
Jul 27, 2026
## Summary Switches the docs from a standalone GitHub Pages site to lance.org, which is how the other subprojects publish. I'd previously set up Pages here (#203, #206) and asked for the repo's Pages setting to be enabled. @jackye1995 pointed out that the org doesn't enable per-subproject Pages by design — public docs should build into lance.org. He's right, and it turns out the docs are already in exactly the right shape for it: lance.org is built from the `lance` repo, whose `make-full-website.sh` copies each subproject's `docs/src` into the main site. So the content stays; only the publishing route changes. ## Changes - **Add `.pages` nav files.** The main site uses the `awesome-pages` plugin, so navigation must come from `.pages` files rather than a hardcoded `nav:` block — otherwise these pages render unordered under lance.org. Enabling the plugin here too keeps local preview and the published site on one source of truth. - **Drop the hardcoded `nav:` from `mkdocs.yml`**, now redundant. - **`site_url` → `https://lance.org/integrations/context/`**, the address the docs will actually be served from. - **Remove `.github/workflows/docs.yml`.** It deployed to a Pages site that doesn't exist and can't be created without an org-level policy change, so it only ever produced a red X on `main`. ## Verification Ran `lance/docs/make-full-website.sh` against this checkout and built the full site: all 12 pages land under `site/integrations/context/`, and the nav nests correctly (`Quickstart`, `Rollouts (RolloutDB)`, `Rollout schema`, ... all appear in the sidebar). ## Depends on lance-format/lance#8014 — until that merges, this repo's docs simply aren't picked up by the website build. Nothing here breaks in the meantime; `mkdocs build --strict` still passes locally for preview. ## Follow-ups from the same conversation Two other things Jack raised, not in this PR: - **Developer guide → `CONTRIBUTING.md`**, which also auto-builds into lance.org. The lance-side PR already wires up the copy rule; this repo has no `CONTRIBUTING.md` yet, so that's a separate change. - **Discussions** are moving to lance-format/lance/discussions org-wide. Also worth cleaning up once this lands: the now-unused `gh-pages` branch on this repo. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude <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.
Summary
The repo has ~1500 lines of Markdown split across
README.md,docs/design/, andspecs/, with no navigation between them and nothing published. This organizes them into a MkDocs site and publishes it to GitHub Pages.Live preview (deployed from this branch on my fork): https://beinan.github.io/lance-context/
Follows the convention already used by lance-namespace and lance-spark: mkdocs-material,
docs_dir: src, deployed to agh-pagesbranch.docs/mkdocs.ymlis deliberately near-identical to lance-namespace's (same theme/palette, markdown extensions, mermaid setup).Changes
docs/mkdocs.yml— nav over Guide / Specs / Design.docs/src/index.md+docs/src/guide/— quickstart, rollouts, storage, and development pages lifted out of the README so the front page stays short. Content is the README's, reorganized, not rewritten.specs/→docs/src/specs/anddocs/design/→docs/src/design/so all six existing documents get navigation and search. Git tracks these as pure renames (0 content changes).rollout_store.rs/config.rsthat referenced the oldspecs/rollout-deployment.mdpath..github/workflows/docs.yml— builds with--stricton every PR touchingdocs/(so a PR that moves a doc can't silently ship a dead link), deploys togh-pagesonly on push tomain..gitignore— the existing/siterule only matches the repo root; addeddocs/site/.Verification
Rather than guess whether this works, I ran the whole thing end-to-end on my fork:
mkdocs build --strictpasses locally (MkDocs 1.6.1 — the same version lance-namespace and lance-spark deploy with).mkdocs gh-deployproducedDeployed <sha> with MkDocs version: 1.6.1, matching the other org sites' commit format exactly./,/guide/quickstart/,/guide/rollouts/,/specs/rollout-schema-design/,/design/auto-dream/.cargo check -p lance-context-core -p lance-context-serverpasses (doc-comment edits).No admin action should be required. Pushing the
gh-pagesbranch auto-created the Pages site on my fork (build_type: legacy,source: gh-pages) with no Settings change. The first merge tomainshould do the same here.Two things worth a maintainer's call
site_urlis set tohttps://lance-format.github.io/lance-context/. If this should eventually live underlance.org/...like lance-spark does (lance.org/integrations/spark), that value and a CNAME need to change — happy to adjust.specs/is a path-breaking change. Any external link tospecs/*.mdwould 404. I judged it worth it for a single coherentdocs/src/tree, but if you'd rather keepspecs/in place I can leave it and pull it in some other way.🤖 Generated with Claude Code