Skip to content
CatalystCatalyst Docs

Docs Contributor Guide

Prerequisites

Section titled “Prerequisites”
  • A clone of the docs repository (this site’s source).
  • Node.js ≥ 20 and pnpm. The repository pins pnpm@9.15.9 in packageManager.

Edit

Section titled “Edit”

Docs are Markdown/MDX under src/content/docs/, organized by audience: getting-started/, users/, admin/, api/, troubleshooting/, contributing/. Every page except the splash index.mdx needs all six frontmatter fields:

---
title: Creating Backups
description: One line saying what the page teaches.
audience:              # user, admin, developer — first entry is the primary audience
  - user
features:              # one or more tags from the canonical vocabulary
  - backups
sources:               # repo paths whose changes should trigger review
  - catalyst-backend/src/routes/backups.ts
last_verified: YYYY-MM-DD   # bump only when you verify against source
---

Rules: task-oriented prose, one primary audience per page (the first frontmatter entry — add more only when the task genuinely spans them), Catalyst terminology (panel, node, server, template, allocation, task — never reuse the Pterodactyl product name for a Catalyst server, and never call a server a container or an instance; container only means the Docker/OCI runtime object), and no invented flags, ports, or defaults.

AGENTS.md is the authoritative contract — it holds the per-field requirements, the canonical 30-tag features vocabulary that scripts/validate-docs.mjs enforces, and the aside syntax (:::note[Title], no space after :::; kinds note, tip, caution, danger). A new page also needs a sidebar entry in astro.config.mjs; the sidebar is nested (Starlight items: groups) and nesting does not change URLs.

Validate

Section titled “Validate”
Terminal window
pnpm install
pnpm dev          # preview at http://localhost:4321
pnpm validate     # links, slugs, frontmatter, features, assets, OpenAPI, terminology
pnpm test         # docs-agent unit tests
pnpm run build    # the same command Cloudflare Pages runs

The checks are plain Node scripts, runnable without the pnpm aliases:

Terminal window
node scripts/validate-docs.mjs      # pnpm validate
node scripts/check-terminology.mjs  # pnpm check-terminology
node scripts/sync-openapi.mjs --check

Fix every failure — CI runs pnpm validate --strict on every pull request, which also turns an orphan page (one no sidebar entry reaches) into a failure.

API reference

Section titled “API reference”

Never hand-edit api/openapi.json or public/openapi.json. Regenerate from a Catalyst checkout (--from-checkout runs that repo’s openapi:export script and refreshes the served copy):

Terminal window
node scripts/sync-openapi.mjs --from-checkout ../catalyst

Commit the result. The Scalar viewer (api/reference) renders whatever is committed, and --check fails when public/openapi.json drifts from api/openapi.json.

The docs agent

Section titled “The docs agent”

For larger sync work, run the docs agent (tools/docs-agent/) in audit, diff, feature, validate, or api mode. It maps Catalyst changes to affected pages:

Terminal window
pnpm docs-agent audit --source-repo ../catalyst --docs-repo .
pnpm docs-agent diff --source-repo ../catalyst --docs-repo . \
  --base origin/main --head HEAD --dry-run

diff and feature write proposed changes into the working tree without committing; --dry-run writes nothing. Details in its README.

Publish

Section titled “Publish”

Merge to main → Cloudflare Pages builds and deploys to docs.catalystctl.com. Pull requests get preview deployments. Deployment details: DEPLOYMENT.md.

Section titled “Related”