Running & deploying the docs

This site is a plain Astro Starlight project — no backend, no database. You edit .mdx under src/content/docs/, run it locally, and every push to main builds and publishes to Azure Static Web Apps with Cloudflare Access gating the front door. This page is the whole loop: install, run, verify, ship.

The site is live at lemon-ground-07bcf2c0f.7.azurestaticapps.net (SWA core-docs in rg-core), with docs.soundverse.ai to be bound in front via Cloudflare.

The docs repo at a glance

• Directorycore-docs/

  • astro.config.mjs site URL + sidebar / IA + mermaid wiring
  • package.json scripts + pinned deps (Node >=22.12)
  • src/styles/theme.css the Soundverse brand theme
  • Directoryscripts/

    • pages.manifest.mjs the page backbone (one entry per page)
    • gen-stubs.mjs creates a draft stub for any manifest page that doesn’t exist yet
    • check-secrets.mjs the secret-safety gate
    • check-links.mjs post-build internal-link checker
  • Directorysrc/content/docs/ the pages — one directory per sidebar group

    • …
  • public/staticwebapp.config.json SWA routing (trailing slash + 404)
  • Directory.github/workflows/

    • azure-static-web-apps.yml the deploy workflow
  • Directorydist/ build output (gitignored)

    • …

Run it locally

1. Install (Node >=22.12 — see engines in package.json):

   npm install

2. Start the dev server — hot-reload at http://localhost:4321:

   npm run dev

3. Add or edit a page. Pages live at src/content/docs/<group>/<slug>.mdx. The authoring contract covers the MDX rules; new pages are declared once in scripts/pages.manifest.mjs and stubbed by scripts/gen-stubs.mjs so the sidebar and build stay green.

The scripts

Everything runs through npm run … (defined in package.json):

Command	What it does
npm install	Install dependencies (Node >=22.12).
npm run dev	Astro dev server at localhost:4321, hot-reload.
npm run build	Production build into dist/ (gitignored).
npm run preview	Serve the built dist/ locally, exactly as it will ship.
npm run check:secrets	Secret-safety gate — scans src/content for anything credential-shaped.
npm run check:links	Post-build internal-link check — needs a build first (it reads dist/).
npm run verify	The full gauntlet: check:secrets → build → check:links in one shot.

Before you push: verify

npm run verify

The secret gate is a hard gate — names only, never values

scripts/check-secrets.mjs scans src/content for private-key blocks, JWTs, provider keys, Azure SAS signatures, the prod DB host, and any secret-looking env-var assignment (a name ending in _SECRET, _TOKEN, _PASSWORD, or _API_KEY set to a non-placeholder value). It runs in CI before the build and fails the deploy on a hit. Reference env-var names only — never real values.

CI does not check links — you must

The deploy workflow runs check:secrets, then builds. It does not run check:links. A broken internal link (a /slug/ that no page generates) will sail through CI. Always run npm run verify locally first.

How it deploys Deployed

Push-to-main, driven by .github/workflows/azure-static-web-apps.yml:

1. Push to main (or open a PR against it). The build_and_deploy_job runs on ubuntu-latest with Node 22.

2. Secret gate → build. It runs npm ci, then npm run check:secrets (a hit fails the run and nothing publishes), then npm run build → dist/ (including the Pagefind index).

3. Deploy via the Azure/static-web-apps-deploy@v1 action with skip_app_build: true and app_location: dist — the already-built output is uploaded to the SWA. Auth is the repo secret AZURE_STATIC_WEB_APPS_API_TOKEN (the SWA deployment token).

4. PRs get a preview environment. Opening/updating a PR publishes an ephemeral SWA preview URL; close_pull_request_job tears it down when the PR closes.

5. Cloudflare Access gates the front door. Access sits in front of the SWA hostname, so the site is reachable only to authorized staff. Search is Pagefind — fully static, so Cmd/Ctrl+K works behind the gate with no external service.

Routing

public/staticwebapp.config.json sets trailingSlash: "always" (matches Starlight’s URLs) and a /404.html fallback. No SWA route auth — gating is Cloudflare Access in front. To unpublish, revert the commit on main.

Where the sidebar & IA live

The information architecture is defined in one place: astro.config.mjs. The sidebar array declares the seven groups, each autogenerated from its directory under src/content/docs/. Ordering within a group comes from each page’s sidebar.order frontmatter. The same file wires astro-mermaid (before starlight()) and the brand theme.

To add a page: add its entry to scripts/pages.manifest.mjs, run node scripts/gen-stubs.mjs to create the draft stub, then write it.

Related

• Authoring conventions — the MDX rules and the secret-safety rule
• How these docs are structured — the Diátaxis groups and the manifest backbone
• Adding a Mermaid diagram — the astro-mermaid fences configured in astro.config.mjs