Documentation

This site lives in docs/: a Docusaurus project whose pages are the Markdown files of docs/content/.

Running it

cd docs
npm ci          # once
npm start       # http://localhost:3000/, reloads as you edit
npm run build   # what the CI runs: fails on a broken link

Node 20 or newer.

The search (docusaurus-lunr-search) needs no external service: its index is built with the site and searched in the browser. It only works on a built site, so try it with npm run build then npm run serve, not with npm start.

Where things go

Part	Folder	For
Features	content/features/	Server owners and admins: what GrayCore does, how to use and configure it.
Developers	content/developers/	Contributors and plugin authors: the code, the API, the workflow.
Reference	content/reference/	The lists: commands, permissions, settings, environment variables, tables.

A new page is added to sidebars.js, in the part a reader would look in.

Keeping it up to date

A change comes with its documentation, in the same pull request. Update the pages when a change touches:

• a command, an alias, an argument or a permission: the feature page and Commands and permissions;
• a setting, a default value or an environment variable: the feature page and the Configuration or Environment variables reference;
• the database schema: Database;
• a module (new, removed, renamed, its settings or commands): its page under Modules;
• the @StableApi classes, the module system, player data or events: the developer pages;
• the build, the dev stack or the workflow: the developer pages.

A pure refactoring, or a fix that changes nothing a reader can see, needs no update.

Writing

• In English, plain and short: what it does, what to type, what to expect.
• Say what is true now. A plan or a limit is written as such ("not saved", "not yet").
• Tables for lists of commands and settings; one example rather than a long explanation.
• Link to the page that explains a thing rather than explaining it twice.

Publishing

.github/workflows/docs.yml builds the site on every pull request that touches docs/, so a broken link fails the check.

The site is published by Cloudflare Pages, which builds every branch of the repository on its own:

Branch	Address	What it is
master	https://graycore-docs.pages.dev	The released documentation.
dev	https://dev.graycore-docs.pages.dev	What comes next, with a banner saying it is not released yet.
Any other, and pull requests	an address per branch, linked from the pull request	A preview, with a banner naming the branch.

The released version links to the dev one in the navigation bar, and the others to the released one. Cloudflare gives the build the branch in CF_PAGES_BRANCH: that is how a version knows which one it is.

The Cloudflare project

Created once, in the Cloudflare dashboard: Workers & Pages > Create > Pages > Connect to Git, then this repository.

Setting	Value
Project name	graycore-docs (the addresses above, and docusaurus.config.js, depend on it)
Production branch	master
Framework preset	Docusaurus
Build command	npm run build
Build output directory	build
Root directory	docs

The Node version comes from docs/.nvmrc. Under Settings > Builds > Branch control, keep preview deployments for all branches, or at least dev. A build that does not touch docs/ still runs: Cloudflare builds every push.