Contribute to these docs

developer.audiencekit.com is built with Astro Starlight from the docs/ folder of the AudienceKit repository.

Preview locally

You need Node 22 (mise install at the repository root sets it up).

cd docs
npm install
npm run dev     # http://localhost:4321
npm run build   # writes the static site to docs/dist

Where things live

Path	What it is
docs/src/content/docs/	The pages, as Markdown or MDX. A file’s path is its URL.
docs/astro.config.mjs	Site settings and the sidebar. Add new pages to the sidebar here.
docs/src/styles/audiencekit.css	Maps the AudienceKit design system onto Starlight.
docs/scripts/graphql-reference.mjs	Generates the GraphQL reference from api/schema.graphql.

Publishing

Every push to master that touches the docs builds the site in the Docs workflow and publishes it to the gh-pages branch of the public audience-kit/developer.audiencekit.com repository, which serves https://developer.audiencekit.com with GitHub Pages. Publishing uses the DOCS_DEPLOY_KEY secret, an SSH deploy key with write access to that repository.

Look and feel

The docs use the AudienceKit design system’s default theme. Starlight loads admin/src/design/tokens.css, the stylesheet generated from the design system’s tokens, so the docs pick up token changes when the admin console’s tokens are regenerated. Starlight’s light and dark modes map to the design system’s light and dark themes.

Writing style

• Write in second person and sentence case, and lead with what the reader can do.
• Take facts from the code, and link to the file when it helps.
• Keep examples runnable: real endpoints, real field names, and placeholders in <angle brackets> or $VARIABLES.
• Don’t edit api/graphql-reference.md by hand. Change the schema, run bin/rails graphql:schema:dump in api/, and the reference is rebuilt with the site.