Skip to content
Dashecorp Rig Docs

Docs tooling decision: Starlight + Cloudflare Pages (2026-04-18)

Decision

Section titled “Decision”

Astro Starlight, sources in dashecorp/rig-docs, deployed to Cloudflare Pages at https://rig-research.pages.dev.

Context

Section titled “Context”

The research report (research/2026-04-18-docs-tools-evaluation.md) surveyed 25 tools against 12 criteria and recommended Notion, primarily on mobile-editing quality. Three facts that arrived after the report changed the calculus:

  1. Plane was set up mid-session without confirming team conventions. The Plane workspace, Terraform module, and DASHE-* items are being retired.
  2. The Tablez enterprise uses Linear on its own side — it is not a sunk cost for the rig side, and Tablez integration is webhook-based, not tool-coupling.
  3. The rig operator prefers code-first markdown with YAML frontmatter, on an owned git repo, deployed statically. This aligns with the rig’s pre-existing rig-docs.pages.dev convention (Material for MkDocs, aggregated from rig-gitops/docs-site/) and the “all docs must use YAML frontmatter markdown” rule. This site is a sibling Starlight surface, not a replacement — see the retired-decisions note below.

With those in place, Notion’s mobile-editing advantage (the main reason it beat Outline/GitBook) is no longer load-bearing. Phone-based authoring is acceptable via the GitHub mobile app for occasional edits; the primary authoring surface is desktop.

Why Starlight specifically

Section titled “Why Starlight specifically”

Starlight was picked over Material for MkDocs and Docusaurus on four dimensions:

  • Active development. Material for MkDocs entered maintenance mode in November 2025. Starlight is actively developed by the Astro team.
  • Cloudflare Pages fit. Astro has first-class Cloudflare support (it is Cloudflare’s own docs stack for Agents SDK docs and several customer-facing sites).
  • Native Mermaid. Via a small custom remark plugin (src/plugins/remark-mermaid.mjs), fenced mermaid code fences render client-side with mermaid.js. No build-time rendering, no committed SVG artifacts.
  • Mobile-first responsive defaults. Starlight’s reading experience on phones is strong out of the box — matters for anyone reviewing the site on mobile even if authoring is desktop.

What moves

Section titled “What moves”
  • dashecorp/rig-docs: converted from flat markdown to Starlight scaffold. Existing research and proposals moved to src/content/docs/research/ and src/content/docs/proposals/ with their frontmatter intact.
  • Diagrams: PNG/SVG artifacts deleted. Mermaid .mmd sources preserved under public/diagrams/ for direct linking; inline Mermaid fences are now the preferred form.
  • Cloudflare Pages: a GitHub Action deploys dist/ on merge to main and previews on PRs. Secrets CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID must exist on the repo.

What retires

Section titled “What retires”
  • The Plane workspace (dashecorp / project DASHE) — to be archived after research content is migrated.
  • The infra/plane/dashecorp/ Terraform module and TF_VAR_plane_token plumbing.
  • BOOTSTRAP.md steps 17-18 (GitHub Project v2 and Plane intake) are superseded by a simpler step: enable GitHub Pages / Cloudflare Pages on the rig-docs repo.
  • The makeplane GitHub App install on the org (not critical — can be left installed or removed).

What this proposal does not decide

Section titled “What this proposal does not decide”
  • User-story intake format. Phone-first intake is deferred. If commute authoring becomes painful, a Telegram-to-PR bridge can be built later. User stories are, for now, GitHub issues in dashecorp/rig-docs.
  • Linear integration for Tablez handoff. Out of scope for this proposal. When Tablez onboarding starts, a Linear webhook receiver in the rig runtime will translate Linear issues to internal work items.

Rollback

Section titled “Rollback”

If Starlight proves wrong, the markdown files survive as-is — the src/content/docs/ tree is standard markdown with frontmatter and can be served by MkDocs, Docusaurus, or any other SSG with minor config changes. Content portability was a first-class concern.