Skip to content
Nexus Docs

docs (this site)

apps/docs is a static documentation site built with Astro Starlight. It is deployed to Railway and served by Caddy.

Overview

Section titled “Overview”
Attribute Value
Framework Astro 7.0.3 + Starlight 0.41.1
Port 4330
Build Static (astro build)
Server Caddy (clean URLs, SPA fallback)
Search Pagefind (indexes dist/ at build time)
Diagrams astro-mermaid 2.1.0 (client-side rendering)
API docs starlight-openapi 0.25.3 (reads public/openapi.json)

Adding content

Section titled “Adding content”

Content lives in apps/docs/src/content/docs/. Create a .md or .mdx file in the appropriate directory — Starlight auto-generates the sidebar entry from the filename and title frontmatter.

src/content/docs/
├── users/        → "Users" sidebar group
├── flows/        → "Flows" sidebar group
├── services/     → "Services" sidebar group
├── graphs/       → "Graphs" sidebar group
├── concepts/     → "Concepts" sidebar group
├── development/  → "Development" sidebar group
├── runbooks/     → "Runbooks" sidebar group
└── reference/    → "Reference" sidebar group

Each directory maps to a sidebar group defined in astro.config.mjs.

Mermaid diagrams

Section titled “Mermaid diagrams”

Fenced ```mermaid ``` blocks are rendered client-side by astro-mermaid. The plugin intercepts the blocks before Expressive Code can style them as plain code — mermaid() must be listed before starlight() in astro.config.mjs.

Supported diagram types: flowchart, sequenceDiagram, stateDiagram-v2, graph, classDiagram, gantt, and all other standard Mermaid types.

OpenAPI reference

Section titled “OpenAPI reference”

The Scheduler API reference is auto-generated from public/openapi.json, which is committed to the repo and regenerated by:

Terminal window
pnpm --filter @nexus/scheduler-api openapi:dump

Run this and commit the updated file whenever the scheduler API contracts change. The starlight-openapi plugin renders the spec as a full sidebar subtree under “Reference → Scheduler API”.

Running locally

Section titled “Running locally”
Terminal window
pnpm --filter docs dev      # Start at http://localhost:4330
pnpm --filter docs build    # Production build
pnpm --filter docs preview  # Preview production build

Deployment

Section titled “Deployment”

The docs site is deployed on Railway via Pulumi IaC (infra/src/railway-docs.ts).

The Pulumi stack creates:

  • A Railway service (repo-sourced, Docker build)
  • A custom domain (docs.stage.innerlight.dev / docs.innerlight.dev)
  • Cloudflare CNAME + ownership TXT record

The service uses an account-scoped Railway token (not project-scoped). It is gated on docsManage: true in the Pulumi stack config and requires pulumi config set railwayDocsServiceId <id> to be set once the service is created.

OpenAPI is committed, not live

Section titled “OpenAPI is committed, not live”

There is no runtime connection to scheduler-api. The OpenAPI spec is a committed snapshot. Keep it fresh by regenerating after contract changes.