Skip to content

MkDocs Material docs site + GitHub Pages publish#341

Merged
clkao merged 5 commits into
mainfrom
spacedock-ensign/mkdocs-material-docs-site
Jun 10, 2026
Merged

MkDocs Material docs site + GitHub Pages publish#341
clkao merged 5 commits into
mainfrom
spacedock-ensign/mkdocs-material-docs-site

Conversation

@clkao

@clkao clkao commented Jun 9, 2026

Copy link
Copy Markdown
Collaborator

Stand up a public MkDocs Material documentation site so users and contributors can navigate Spacedock from install through advanced workflows in one place.

What changed

  • Add a MkDocs Material docs site (docs/site/) — 7-section tabbed nav, light/dark, search.
  • Move install-journey into the site; symlink functional contributor docs (dev README, releasing, runtime-support, specs) in.
  • Generate /llms.txt (mkdocs-llmstxt) as the product-using-agent index; re-home AGENTS.md under Contributing.
  • Add a GitHub Pages workflow: mkdocs build --strict as a PR gate + deploy-on-main.
  • Stub synthesized pages as honest [TODO]s; ship real content where it exists (install, the symlinked docs, Voice & tone).

Evidence

  • mkdocs build --strict: exit 0, zero warnings (clean rebuild).
  • go test ./...: 1247/1247 passed (install-journey move ripples fixed).

Review guidance

The install-journey move touched install.sh + install_doc_test.go + the README link — covered by go test.

wv

clkao and others added 5 commits June 8, 2026 21:57
@clkao @claude
docs site: stand up MkDocs Material site + GitHub Pages publish
cb1e040 
Build the public docs site to the approved 7-section IA (Home · Get started ·
Concepts · Running workflows · Advanced topics · Reference · Contributing),
green under `mkdocs build --strict`.

- docs/site/ single content root: install-journey MOVED to
  get-started/install.md; functional files (docs/dev/README.md, AGENTS.md,
  docs/releasing.md, docs/specs/state-behavior-extension, docs/runtime-support.md)
  SYMLINKED in, canonical path unchanged.
- mkdocs.yml: Material theme, light/dark palette toggle, content.code.copy +
  search.suggest/highlight + navigation.sections/instant + content.tabs.link;
  explicit nav mirroring the IA; mkdocs-llmstxt -> site/llms.txt.
- "For agents" banner link (theme override) to llms.txt + the AGENTS.md page.
- docs/requirements.txt pins mkdocs + mkdocs-material + mkdocs-llmstxt.
- .github/workflows/docs.yml: strict build as a PR check; deploy to Pages on
  push to main (the stable branch per docs/releasing.md).
- Net-new pages authored to a first-version bar (Concepts/Running/Advanced
  syntheses, Voice & tone lifted from the ideation draft, e6 example stub,
  Reference -> Frontmatter contract surfacing the dev README schema table).

Move-induced fixes: README install link, install.sh source-build hint, and
internal/release/install_doc_test.go path now point at the relocated install.md.
go test ./... green (1247 passed).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@clkao @claude
docs site: swap For-agents banner for machine-discoverable head <link…
a36c52b 
… rel> tags

Captain refinement at the validation gate: a banner is human chrome for a
machine resource, so agents should discover the for-agents surface from the
document head, not a visible banner.

- docs/overrides/main.html: drop the visible "For agents" announce banner; add
  two <link rel="alternate" type="text/markdown"> tags (llms.txt, AGENTS.md) to
  the extrahead block. rel="alternate" type="text/markdown" is the standards-safe
  form (no registered rel for llms.txt yet).
- /llms.txt stays at the build-output root (the convention a14y scores) and the
  AGENTS.md page stays reachable; only the human-facing surface changed.
- Removed the now-unused extra.agents_url / agents_md_url keys; updated the Home
  page prose to point at the head links instead of the banner.

mkdocs build --strict green; the two <link rel> tags render in every page's
<head> (verified in site/index.html and nested pages).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@clkao @claude
docs site: tab nav, example→Concepts, [TODO]-stub synthesized pages
096e2b2 
Captain refinements for a releasable shell now, prose filled incrementally.

1. Declutter nav: swap navigation.sections for navigation.tabs +
   navigation.tabs.sticky (top-level sections become top tabs; the sidebar
   shows only the active section's pages, sub-sections collapsed by default).
2. Move the worked-example (e6 slot) from Running workflows → Concepts
   (Concepts → A worked example); nav + file relocated, stays the e6 stub.
3. [TODO]-stub every synthesized/thin page (Home synthesis, Get-started
   first-launch/first-workflow, all Concepts intros, all Running-workflows
   pages, the synthesized Advanced pages, the worked-example, the synthesized
   Reference + Contributing pages) with an honest one-line "[TODO] — <what this
   page covers>". KEPT REAL and unchanged: the moved install page, the 5
   symlinked docs (dev/README, releasing, AGENTS, runtime-support, specs), the
   drafted Voice & tone page, and /llms.txt.

Bar met: nav complete, every page resolves, mkdocs build --strict green — a
releasable shell with honest [TODO]s, not fake depth.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@clkao @claude
docs site: make for-agents head links subpath-safe (base-aware, no le…
b1213bc 
…ading slash)

Change the head <link rel> hrefs from root-absolute `{{ '/llms.txt' | url }}`
to base-aware `{{ 'llms.txt' | url }}` (no leading slash) for both llms.txt and
agents/, so they resolve to the site-root files whether the site deploys at the
domain root OR under a /spacedock/ project-Pages subpath.

Rendered: href="llms.txt" / "agents/" on the root page; href="../../llms.txt" /
"../../agents/" on nested pages — each resolving to the real site-root file.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@clkao @claude
docs site: cut the for-agents head-link surface; re-home AGENTS.md to…
b62597a 
… Contributing

Captain correction: the "For agents" surface conflated two different agents.
AGENTS.md is repo-DEVELOPMENT guidance (an agent working ON Spacedock), not
product-using-agent guidance — that's what /llms.txt already covers.

- Remove the head <link rel> block; remove docs/overrides/main.html entirely
  (it had no other purpose) and the theme.custom_dir reference.
- Keep /llms.txt at the build root as the product-using-agent surface
  (mkdocs-llmstxt output, a14y-scored), discoverable via the canonical path —
  no head link needed. Drop the "For agents" llmstxt section.
- Re-home AGENTS.md as contributor content: move the symlink
  docs/site/agents/index.md -> docs/site/contributing/agent-development.md and
  give it a Contributing nav entry "Agent development" (replacing the top-level
  "For agents" nav entry), so the page stays in-nav and --strict stays green.
- Reframe the Home agent note: /llms.txt for product-using agents; repo-dev
  guidance points to Contributing -> Agent development.

mkdocs build --strict green; 0 head-link tags; /llms.txt at root; AGENTS.md
renders at contributing/agent-development/.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
clkao added a commit that referenced this pull request Jun 9, 2026
@clkao
pr: mkdocs-material-docs-site #341 pending
c5161f9
@gcko

gcko commented Jun 9, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Code Review: PR #341

SHA b62597ae · Verdict GO

Updated: my earlier NO-GO was wrong. I flagged docs.yml triggering only on main, but that is the intended setup — next is the integration branch PRs merge into, and main is the stable branch that deploys the site. The deploy is gated either way: deploy has needs: build, so a failing mkdocs build --strict on push to main blocks the deploy, and a release PR (next→main) hits the pull_request: branches: [main] check before merge. No ungated deploy path exists.

Notes

  • Strict build verified locally: mkdocs build --strict exits 0, zero warnings; site/llms.txt generated. Symlinked contributor docs (git mode 120000) resolve and build cleanly. install.sh / install_doc_test.go / README link all correctly re-pointed to the moved docs/site/get-started/install.md.
  • The synthesized [TODO] stub pages ship as live nav entries — honest and acknowledged in the PR body, not a defect.

Limits

  • GitHub Pages source (must be set to "GitHub Actions") and the github-pages environment are repo-settings, not verifiable from the diff.

gcko
gcko requested changes Jun 9, 2026
View reviewed changes

@gcko gcko left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

NO-GO — 1 ISSUE: the strict-build PR gate triggers on PRs to main but PRs target next, so it never runs. Full review in the issue comment above.

gcko
gcko approved these changes Jun 9, 2026
View reviewed changes

@gcko gcko left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

GO — withdrawing my earlier change request. The main-only docs trigger is correct: next is the integration branch, main is stable/deploys, and the strict build gates the deploy via needs: build (and the release PR to main). Full updated review in the comment above.

clkao added a commit that referenced this pull request Jun 9, 2026
@clkao
debrief: session 2026-06-09 #1 — 0.19.9 cut+released, 0200 pre-flip s…
70dd96c 
…hipped, flip in progress, docs site PR #341, 4 filed
@gcko gcko self-requested a review June 9, 2026 06:05
@gcko gcko mentioned this pull request Jun 9, 2026
Merged
gcko
gcko approved these changes Jun 10, 2026
View reviewed changes

@gcko gcko left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@clkao clkao changed the base branch from next to main June 10, 2026 19:04
@clkao clkao merged commit 4efb18e into main Jun 10, 2026
4 of 7 checks passed
clkao added a commit that referenced this pull request Jun 10, 2026
@clkao
advance: mkdocs-material-docs-site -> done (pr #341 merged)
f02288f
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@gcko gcko gcko approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@clkao @gcko