Documentation Site Architecture

Phase 10 publishes blipcoard documentation as a browsable static docs site. This document records the stack choice, information architecture, and local commands that later migration and publishing work should follow.

Stack Choice

Use Docusaurus with the classic preset for the public docs site.

Reasons:

• Docusaurus is optimized for versioned documentation, sidebars, MDX, static HTML generation, and searchable docs.
• The current repository docs are Markdown-first and can move into Docusaurus with low rewrite cost.
• Docusaurus supports filesystem-generated sidebars and explicit sidebar config, which fits the current phase-based docs and future reference pages.
• GitHub Pages deployment is a supported Docusaurus path, which keeps initial hosting simple.

Do not add a marketing-first landing page in Phase 10. The first screen should be documentation entry points for users and contributors.

Site Location

Create the Docusaurus app in a dedicated site/ folder:

npx create-docusaurus@latest site classic

Keep source-of-truth product docs in the site once migrated. Keep raw repository Markdown only when it is better as repo-local operational context, such as:

• AGENTS.md
• generated or local-only task state
• low-level ADRs that are still actively edited with code
• short notes that are not useful to public users or contributors

The migration issue should decide each existing Markdown file explicitly:

• move into site/docs/
• copy into site/docs/ and leave a repo-local pointer
• keep raw only

Local Commands

Recommended package scripts at the repo root after the site is created:

{
  "scripts": {
    "docs:start": "npm --prefix site start",
    "docs:build": "npm --prefix site run build",
    "docs:serve": "npm --prefix site run serve"
  }
}

Local preview:

npm run docs:start

Production build:

npm run docs:build

Local production preview:

npm run docs:serve

Top-Level Navigation

Use a documentation-first navbar:

Label	Target	Purpose
Docs	docs sidebar first page	Main docs entry point.
Product	product overview	User-facing concepts and workflows.
Architecture	architecture overview	Runtime model and storage/API design.
Reference	CLI/daemon/config reference	Operational and API-style docs.
Contribute	contributor guide	Local setup, docs workflow, release checks.
GitHub	repository URL	Source and issue tracker.

Avoid a blog or changelog navbar item in Phase 10 unless release notes become a dedicated maintained artifact.

Sidebar Structure

Use explicit sidebars rather than fully autogenerated navigation. Autogenerated sections can be used inside a category after the migration stabilizes, but the top-level IA should be deterministic.

Recommended primary sidebar:

Start
  Overview
  Install
  Quickstart
Product
  Workspaces
  Clipboard capture
  Rich payloads
  Agent access
Architecture
  Runtime model
  Daemon API
  Storage and blobs
  Security and privacy
Operations
  CLI install and operations
  Desktop bundles
  Upgrade and migrations
  Troubleshooting
Reference
  CLI commands
  Daemon API
  Config
  Environment variables
Contributor
  Development setup
  Docs maintenance
  Release checklist
Roadmap
  MVP phases
  Project breakdown

This structure covers product, architecture, reference, and contributor docs as required by Phase 10.

Content Boundaries

Move or adapt these existing docs into the site:

Existing file	Site destination
README.md	Start / Overview, with README left as a short repo entry.
docs/architecture.md	Architecture / Runtime model.
docs/daemon-api.md	Reference / Daemon API.
docs/runtime-distribution.md	Operations / Runtime distribution.
docs/desktop-bundles.md	Operations / Desktop bundles.
docs/cli-operations.md	Operations / CLI install and operations.
docs/upgrade-migrations.md	Operations / Upgrade and migrations.
docs/rich-payload-reliability.md	Architecture / Storage and blobs or Operations / Reliability.
docs/adr/*	Architecture / ADRs, unless still too low-level.
docs/mvp-phases.md	Roadmap / MVP phases.
docs/project-breakdown.md	Roadmap / Project breakdown.
docs/repo-layout.md	Contributor / Repository layout.

Keep AGENTS.md raw in the repository. It is agent/operator process guidance, not public product documentation.

Search

Phase 10 should enable local site search before public launch. If no hosted search provider is configured yet, use Docusaurus' local search plugin in the site implementation issue and keep hosted search as a publishing follow-up.

Versioning

Do not enable Docusaurus docs versioning in the initial site scaffold. Add it when blipcoard has its first public release series that needs preserved docs.

Before enabling versioning, make sure release notes define:

• the current stable docs version
• supported previous version count
• migration checklist for docs changes that follow code changes

Publishing

The site build is validated by GitHub Actions on pull requests. After docs changes merge to develop, .github/workflows/docs.yml publishes the generated site/build output to the gh-pages branch. The generated build directory is not committed to develop.

Implementation Phasing

Phase 10.1 chose the stack and IA. Follow-up issues own the implementation:

• Phase 10.2: create site/, migrate existing docs into the chosen IA, and validate/publish the site with GitHub Actions.
• Phase 10.3 and 10.4: fill product, architecture, CLI, daemon, and troubleshooting reference gaps.
• Phase 10.5: contributor workflow and maintenance docs.
• Phase 10.6: expand the build, publish, and versioning pipeline as release versioning needs mature.

Source Notes

This decision follows current Docusaurus docs for:

• scaffold command: npx create-docusaurus@latest my-website classic
• sidebars: filesystem-generated sidebars and explicit sidebar items
• navbar: doc, docSidebar, and external link navbar items
• deployment: GitHub Pages as a supported static publishing target