Writing docs

Every doc is one node in one docs graph, with a stable identity and one home in a tree.

• Identity: the doc's provider, its kind, and its name. Moving a doc never changes it.
• Route: the names of the doc and its parents, such as cli/api/functions/search; astryx docs <route> reads it.
• Moves: every read ends with Up, Previous, Next, and Related, each as a command you can run.
• Search: a hit is the smallest part that answers, one section or one tree page. It gives the command that reads it and the command that opens the level above.

You never write moves or lists of children. The CLI derives them from each doc's home and its typed links.

To add a doc, write one .doc.mjs file named after the doc, and stamp the type that matches what it describes.

A topic or guide holds sections. Each section has a title and content blocks, and covers one idea. The description is one sentence that says what the doc covers.

javascript
export default {
  type: 'generic',
  name: 'deploying',
  title: 'Deploying',
  description: 'Ship an app built with Acme widgets.',
  sections: [
    {
      title: 'Build before you ship',
      content: [
        {type: 'prose', text: 'Build the app, then check it with {@link @astryxdesign/cli:command:doctor}.'},
        {type: 'code', lang: 'bash', code: 'npm run build'},
        {type: 'list', style: 'unordered', items: ['Check the output folder.']},
        {type: 'table', headers: ['Env', 'Value'], rows: [['NODE_ENV', 'production']]},
      ],
    },
  ],
};

• A name is a command argument, so use only letters, digits, _, and -. Use lowercase kebab-case, such as writing-docs, so the name and its route segment match.
• Keep the name stable. Links name a doc by its identity, and the name is part of it.
• A name that collides with an existing topic is an error unless the doc declares replaces or extends.
• Name the cases a doc does not cover, and link to where they are covered. A reader cannot tell a case you left out from a case that does not exist.

Every field of every doc type is in astryx docs authoring.

Each doc gets one home in one of three ways: a namespace adopts it, it places itself, or it stays a flat topic. Folders never decide a home.

Adopted: a CLI typed doc declares namespace, either 'cli/commands' or 'cli/api'. That namespace adopts it by kind, so its route is cli/commands/<name> or cli/api/functions/<name>.

javascript
{type: 'function', name: 'search', namespace: 'cli/api' /* ... */} // cli/api/functions/search

Placed: a guide declares placement. The parent names a namespace of your own package, the slot is one that namespace declares for the doc's kind, and order sorts the siblings in the slot. A placement that fails withdraws the doc with an error.

javascript
placement: {parent: 'namespace:cli', slot: 'guides', order: 20}, // cli/writing-docs

Flat: a doc with neither is a flat topic, read with astryx docs <name>.

javascript
{type: 'generic', name: 'tokens', title: 'All Tokens' /* ... */} // astryx docs tokens

Link a doc with {@link <target>} or a typed field, never by writing its astryx docs route in prose: a route you write goes stale when the doc moves. Other commands, such as astryx doctor, you write as they are.

Typed fields: a FunctionDoc's command names the CLI command that runs it, and its related names functions. A CommandDoc's fn names the function it runs, and its related names commands.

javascript
{type: 'function', name: 'search', command: 'search', related: ['docs']}
{type: 'command', name: 'search', fn: 'search', related: ['docs']}

Inside a section's text, write {@link <target>}, where the target is [<provider>:]<kind>:<name>; leave out the provider for a doc of your own provider. The CLI prints the command that opens the doc. It works in prose, list items, and table cells; link syntax inside code ticks is shown as written, and an older CLI prints the link as plain text. A namespace doc can also carry reference and workflow blocks in its blocks, though the CLI does not print them yet; a topic's sections cannot hold them.

javascript
{type: 'prose', text: 'Check it with {@link command:doctor}.'}
{type: 'list', style: 'unordered', items: ['Search with {@link @astryxdesign/cli:function:search}.']}
​
// In a namespace doc's blocks only:
{type: 'workflow', steps: [
  {title: 'Write the doc', references: ['generic:authoring']},
  {title: 'Check it', references: ['command:doctor']},
]}

The route in the printed command is derived when the doc is read, so a link follows its doc when the doc moves. A target that names no doc prints as written, and so does a typed-field name that matches more than one doc; astryx doctor warns on both.

Keep every read short so a reader gets one answer per command: one idea per section, a summary first, and a hard size limit.

• Give each section one idea. If it needs a second topic, split it into two sections.
• A section's summary, shown in the section list and in search, is its first prose block or first list item, cut at 240 characters. Lead with what the section answers.
• In text, a topic with more than one section reads as its section list. The reader opens one section, or prints everything with --full. With --json, a topic returns the whole doc and --index its section list.
• Every read should fit in 32 KB; astryx doctor warns on one that does not. Aim for sections under about 30 lines.

bash
astryx docs cli/writing-docs
astryx docs cli/writing-docs keep-reads-short
astryx docs cli/writing-docs --full

Search finds a doc only by the words it indexes, so put the words a reader types where search looks.

Search matches titles, section titles, headings, each section's summary, and identifiers written in code ticks, such as ERR_UNKNOWN_SECTION or token-ref. It also matches a doc's own name and the keywords of a namespace or typed doc.

Test it the way a new reader arrives: search for the question, not the title, and check that the first hit answers it.

bash
astryx search placement --type doc

An integration joins the same graph with a namespace doc in its docs directory and guides placed in it. The namespace shows in astryx docs beside cli, with the same moves, search, and links. You can place a doc only in a namespace of your own package.

Let the CLI write the files: inside the package, astryx integration add doc deploying --parent acme writes the guide with its placement, declares the docs root, and writes the acme namespace doc the first time. Run astryx docs in the package to see it.

A CLI release that does not read the docs tree can hide every doc topic your package ships when the package contains a namespace doc or a placed guide: none appear in astryx docs, in text or JSON, and astryx doctor may not say why. So --parent also declares the CLI release your docs need as an optional @astryxdesign/cli peer in package.json, which makes npm warn when an older CLI is installed, and astryx integration pack --check fails a package that ships either one without it.

javascript
// docs/acme.doc.mjs
/** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */
export default {
  type: 'namespace', name: 'acme', title: 'Acme widgets',
  summary: 'Guides for building apps with Acme widgets.',
  slots: {guides: {title: 'Guides', accepts: {kinds: ['generic']}}},
};
​
// docs/deploying.doc.mjs (route: acme/deploying)
/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
export default {
  type: 'generic', name: 'deploying', title: 'Deploying',
  description: 'Ship an app built with Acme widgets.',
  placement: {parent: 'namespace:acme', slot: 'guides', order: 10},
  sections: [{title: 'Check before you ship', content: [
    {type: 'prose', text: 'Run {@link @astryxdesign/cli:command:doctor} before every deploy.'},
  ]}],
};

The link names the @astryxdesign/cli provider because its target lives in another package. A link without a provider resolves against yours: your manifest's providerId, or else your package name. That holds in a topic that extends another package's topic too: your sections link your docs, and a link to the other package's docs names its provider.

Everything else an integration ships is in astryx docs cli/integrations.

Run the doctor commands to check every home, link, and read in your docs.

• astryx doctor, in a project, checks the whole graph: the tree, the links, and the size of each read.
• astryx doctor integration docs, inside an integration package, runs the same checks on that package's docs before it ships.
• astryx integration pack --check fails a package that ships a namespace doc or a placed guide without a CLI peer that reads them.

No check can tell whether a doc is still true. Describe what the CLI does now, and change the doc in the same change that changes the behavior.

A problem in the tree or a link is a warning: it names what to fix, but the exit code stays 0, so read the report (or its --json) before you ship.