Docs Site

The docs site is an Astro Starlight static site that lives inside the level147.net repository at docs/. It deploys automatically to docs.level147.net via Cloudflare Pages on every push.

How it works

level147.net repo
  └── docs/                   ← Astro project root
      ├── astro.config.mjs
      ├── src/
      │   ├── content.config.ts
      │   └── content/docs/   ← all .md/.mdx files here auto-build
      └── plans/              ← excluded (internal planning docs)

Starlight’s docsLoader() recursively discovers every .md and .mdx file under src/content/docs/. No registration needed — drop a file in and push.

Adding a page

Create a .md file anywhere under docs/src/content/docs/

Add required frontmatter:

---
title: My Page
description: Optional description shown in search results.
---

Commit and push — Cloudflare Pages builds and deploys automatically

The sidebar is configured manually in docs/astro.config.mjs. New pages won’t appear in the sidebar until you add an entry there:

sidebar: [
  {
    label: 'My Section',
    items: [
      { label: 'My Page', link: '/my-section/my-page' },
    ],
  },
]

Excluded content

The docs/plans/ directory is not inside src/content/docs/ and is therefore excluded from the build. It holds internal sprint planning documents that don’t need to be published.

To exclude other directories, move them outside src/content/docs/ (e.g. to docs/internal/).

Deployment

Deploys via Wrangler direct upload from Woodpecker CI — not CF Pages Git integration (CF Pages can’t pull from self-hosted Gitea).

Setting	Value
CF Pages project	`level147-docs`
CF account	`e564ade2903ed6f18c70a38a5d411f15`
Custom domain	`docs.level147.net`
CI pipeline	`.woodpecker/docs.yml`
Trigger	Push to `main` where `docs/**` changed, or manual

The Woodpecker pipeline (docs.yml):

Clones the repo
Runs npm ci && npm run build inside docs/
Runs npx wrangler pages deploy dist --project-name=level147-docs

Requires the CLOUDFLARE_API_TOKEN secret in Woodpecker (permission: Account → Cloudflare Pages: Edit).

The pages.dev domain is disabled on the CF Pages project. Access is restricted via Cloudflare Zero Trust → Access — only authenticated staff can reach docs.level147.net.

Theme

The visual theme is a port of the AI Studio control-surface design language:

File	Purpose
`src/styles/tokens.css`	Design tokens — colours, shadows, geometry
`src/styles/starlight.css`	Maps `--sl-*` Starlight variables to tokens + component overrides

The dark/light scheme is driven by [data-theme="dark"] / [data-theme="light"] on <html>. Section accents (--accent) can be set per-page via data-section="ops|consulting|admin" on the body.

Local development

cd docs
npm install
npm run dev       # dev server at http://localhost:4321
npm run build     # production build into docs/dist/
npm run preview   # serve the built output locally