Contribute to the docs

This site is the apiome-suite-docs/ workspace in the private-suite repository. Documentation is part of the definition of done: a change to a Suite surface updates its page here in the same pull request, and yarn docs:check must pass before it merges.

Run the site

From the private-suite root:

Command	What it does
yarn docs:dev	Live-reloading site at http://localhost:3201/
yarn docs:build	Production build into apiome-suite-docs/build/
yarn docs:check	Page and link rules, then the production build — what CI runs
yarn workspace apiome-suite-docs test	Unit tests for the rules and components
yarn workspace apiome-suite-docs typecheck	Type-check the config and components

Write a page

The site is three guides, each with its own sidebar: the User guide (getting-started, design, authoring, scribe, slate, hosted — one folder per Suite surface, in the order of the suite dropdown), the Administration guide (admin) and the Reference (reference). Pick the guide its reader is in, then the group:

1. Add docs/<group>/<page>.md — or .mdx when the page uses a component.
2. Give it front matter: title, a description of 14 words or fewer, sidebar_position and tags. Do not repeat the title as a heading; the site renders it.
3. Write steps with bold UI nouns ("click Generate README") and quote buttons, menu items and empty states as they read in the product.
4. Link other pages with relative paths (./settings.mdx) or site routes (/scribe/settings), and the open-source product's pages with full URLs on https://docs.apiome.dev.

Every group folder has a _category_.json (label, position) and an index.mdx landing page that lists its pages with <DocCardList />.

Components

Available in every .mdx page without an import:

Component	Use	Example
<Route path/>	A badge naming the studio route a page describes	<Route path="/authoring/scribe"/>
<Plan name/>	A badge naming the entitlement a surface needs; scribe, slate and hosted read as previews	<Plan name="scribe"/>
<Flag name on?/>	A badge marking a surface behind a build-time flag	<Flag name="NEXT_PUBLIC_STUDIO_UNIFIED_WORKSPACE" on/>
<Kbd keys/>	A key or chord; Mod reads "Ctrl / ⌘"	<Kbd keys="Mod+K"/>
<Surfaces/>	The grid of Suite surfaces with the product's own icons	<Surfaces/>

Release notes

Add a post to release-notes/ named YYYY-MM-DD-<slug>.mdx with title, description and authors: [apiome], and put {/* truncate */} after the summary paragraph.

What the gate checks

yarn docs:check runs scripts/check-docs.mjs, then the production build. It fails when:

• a page has no title or description, or the description is over 14 words;
• a folder under docs/ has no _category_.json (with a label) or no index.mdx;
• a page is an orphan — in no sidebar: directly in docs/ outside every group folder, or hidden by unlisted: true, draft: true or displayed_sidebar: null;
• an internal link is broken: a relative link to a .md / .mdx file that does not exist, or a site path that no page, category landing page, release-notes post or static/ file serves. The build then checks anchors too.

Each rule has a fixture site under test/fixtures/gate/ that the tests run the gate over, so a rule that stops firing fails yarn workspace apiome-suite-docs test.

Screenshots

This site has no screenshot pipeline yet. The open-source site captures its screens from a manifest with Playwright (see its contribute page); when the studio gets the same treatment, the <Screenshot/> component and the screens.json manifest come over with it.

Pull request checklist

### Documentation
- [ ] Pages: <paths under apiome-suite-docs/docs/ added or changed>
- [ ] Release notes: <apiome-suite-docs/release-notes post>
- [ ] `yarn docs:check` passes