Editing These Docs

These docs are a Starlight site, kept self-contained under docs/ (separate from the Drupal module code).

Run the docs locally

From the docs/ directory, install dependencies once:

npm install

Then pick the script that fits what you want to do. Every URL includes a base path — the site serves at http://localhost:4321/groupsdrupalorg/, not the bare root (visiting / just redirects there).

Build & launch

npm run docs:local:launch

The one-command “just show me the site”: production build, waits for the preview server, and opens your browser at the site. Use when you just want to look at the built site.

npm run docs:local:run

Same production build and preview server, but does not open a browser — open the URL yourself, or use it on a headless machine.

npm run dev

A hot-reloading dev server for writing and editing pages. Prints the URL and port (default 4321, or the next free one).

npm run build
npm run preview

The production build followed by a preview of it — what CI runs, so the definitive pre-push check.

npm run build runs astro check (type- and frontmatter-schema validation) and a link checker that fails the build on any dead internal link or heading anchor — so a broken link is caught here, not after it ships. astro check may print informational notices; what matters is that it reports 0 errors and the build completes.

Edit in a GUI (Keystatic, local)

Prefer a visual editor over hand-editing Markdown? Run the local Keystatic admin:

npm run keystatic

Then open http://localhost:4321/keystatic — it lists the docs pages with a rich editor (formatting, links, images, tables, Markdoc components). Saving writes the .md/.mdoc file back to disk; commit it through the normal git workflow.

4321 is the default; if it’s already in use, Astro starts on the next free port and prints the actual URL — use the one it shows, with /keystatic appended.

• Local only. npm run keystatic runs the site at base / (Keystatic’s admin can’t run under a base path yet — upstream Thinkmill/keystatic#1170) and is a dev-only server. The deployed site is unaffected — it stays a plain static build at /groupsdrupalorg with no Keystatic (the whole integration is gated behind KEYSTATIC_LOCAL).
• Two collections — Docs — prose (.md) and Docs — components (.mdoc) — split because a Keystatic collection has one on-disk format. Files are edited in place: prose stays .md, component pages stay .mdoc.
• This page (editing-docs.mdx) is the one .mdx file and is not Keystatic-editable (Keystatic forbids imports) — edit it by hand.

Add or edit a page

Pages live in docs/src/content/docs/ as .md, .mdoc, or .mdx files. Each file becomes a route from its filename — e.g. team.md → /team/. Every page needs a title (and optionally a description) in its frontmatter:

---
title: Page Title
---

Task	How
Edit an existing page	Open the file and edit the Markdown.
Add a new page	Create a file in docs/src/content/docs/, then add it to the sidebar in docs/src/config/sidebar.ts (under the relevant group’s items). New files aren’t auto-listed unless they’re in a directory that uses autogenerate (see meeting-notes/).
Add a meeting note	Drop a file in docs/src/content/docs/meeting-notes/ (e.g. 2026-07-15.md); that directory is autogenerated, so no sidebar change is needed.
Link to another page	Use a relative link with the file extension, e.g. [Events](./events.md). Astro rewrites it to the correct base-aware URL. Don’t hand-write /events/ — root-absolute links skip the base path and 404 in production.
Images	Put them in docs/src/assets/ and reference with a relative path so Astro optimizes them.

Which format to use

Pages can be .md, .mdoc, or .mdx — see Choosing a Page (File) Format for when to use each, and Adding Components to Your Pages for the Markdoc tags available on .mdoc pages.

Content must stay Keystatic-editable: plain Markdown by default, components only via registered Markdoc tags (aside, showcode) on .mdoc pages, no .mdx except this page, and frontmatter limited to title/description. A build gate (npm run check:keystatic, also run on commit, push, and in CI) enforces this — an unregistered {% tag %} or a stray .mdx fails the build with a file:line message. The full rules for authors (and bots) are in docs/AGENTS.md → Keystatic-editable content.

Reuse shared values with content tokens

Some values appear in more than one place (for example, the project tagline shows in both the homepage hero and the site footer). Rather than re-typing them and letting them drift, define each once as a content token in docs/src/content/tokens/tokens.yaml and read it in code. The Content Tokens page (in the sidebar under Docs) lists every token and explains how to add one.

Once your change is merged, the pages CI job rebuilds and redeploys the site automatically.

Where things live

docs/
├── astro.config.mjs        # site config (imports the sidebar), base path
└── src/
    ├── config/sidebar.ts   # nav sidebar + homepage cards (single source of truth)
    ├── content/docs/       # all page content (.md / .mdoc / .mdx)  ← you edit here
    └── assets/             # images referenced from pages