Write the docs

The rules every page of these docs follows, the example scenario, and the checks a change to the docs passes. The docs live in the sites_docs project.

Audiences and structure

Navigation	Directory	For	Holds
Get started	index.md, concepts.md, build/	Anyone new to Sites	The home page, the terms, the installation, a first platform, the example platforms
Guide > Working in a site	use/	Editors and site managers working inside one or a few sites	Tasks in the admin UI
Guide > Running the platform	build/	Site builders setting up the platform	Configuration, site types, access, operation
Develop	develop/	Developers extending Sites	APIs, code samples, design notes
Reference	reference/	Lookups	Tables, mostly generated from the code

• In the Guide and Get started only labels the UI shows: no class, service, route, hook, entity type or setting machine names; a permission by its UI label. Machine names live in Develop and Reference.
• One fact, one page. COVERAGE.md in the docs repository names the page that owns a feature; every other page links to it. A new feature gets a row there first.
• A feature of a module other than Sites opens with !!! info "Needs <module label>", linking to the module's page under Modules.

Page shapes

Shape	Parts	Length
How-to	A goal sentence, "Before you start" (permission, module), numbered steps with one action each, the result	Under about 400 words
Concept	The definition, a diagram where it helps, the consequences	Under about 700 words
Reference	Tables
Module	What it does (by hand), Install (generated), Configure (by hand, then the generated settings, permissions and admin pages), For developers (generated), the guides that link to it (added by the build)	Under about 300 words by hand

No "When to use it" or "Skip it if" sections unless the reader has a real decision to make. Design rationale goes to Develop, if anywhere.

Prose

• No em dashes and no en dashes. Use a comma, colon, semicolon, period or parentheses, or rewrite. Hyphens only inside compound words.
• Active voice, present tense, facts a reader can verify.
• No marketing tone and no value judgements (powerful, seamless, simply).
• No contrast framing (not X, but Y). Say what it is.
• No emojis in prose. Icons in card grids are fine.
• The first sentence carries information; no introduction before it.

Examples

Every example uses the Valtora scenario: the sites valtora, hydrion (with the sub-sites hydrion_uk and hydrion_us) and torqline, the people Mara, Jonas, Priya and Tom, and the content of the valtora_demo recipe. A site that does not exist yet is Velmora (velmora, www.velmora.example). Addresses use the reserved .example domain; DDEV hostnames appear only where a page explains the local environment.

MkDocs features

• Hub and site tabs: where a task's steps differ between the hub and a site's own address, give both as content tabs labeled exactly === "On the hub" and === "On the site". What both share goes below the tabs.

• Captions: a screenshot's caption goes in a caption block below it:

  ![The dashboard of Hydrion.](../screenshots/site-dashboard.png)
  
  /// caption
  The dashboard of a site.
  ///
  

• Diagrams: a flow, a resolution order or a relationship between entities that reads better drawn goes in a mermaid code fence.

Screenshots

A screenshot sits next to the step it shows and only where it saves a sentence. tools/screenshots/ in the docs repository regenerates all of them on a local install of the valtora_demo recipe: stage.php adds what the shots show beyond the recipe, shoot.mjs captures them in the default environment (the .example addresses) with Devel switched off.

Generated pages

Modules, permissions, settings, admin paths, Drush commands, the API, tokens and the agent tools come from the code (tools/reference/generate.php); a poor line there is fixed in the module. The agent tools are also published as JSON: tools.json.

The build adds to every page the date of its last change, lists under each reference entry the pages that link to it, and writes llms.txt (every page with its first sentence) and llms-full.txt (every page's text) for AI agents.

Checks

CI runs both on every change:

uvx --with-requirements requirements.txt mkdocs build --strict -d /tmp/sites-docs-site
docker run --rm -v "$PWD":/docs -w /docs jdkato/vale:v3.24.0 docs

The strict build fails on broken links and anchors and on pages missing from the navigation. Vale checks the prose rules a pattern can catch (dashes, marketing words, contrast framing); its rules are in .vale.ini and styles/Sites/.

Last updated 2026-10-16