Add a topic

Run integration add doc in your package to add a topic. It writes the topic file and declares the docs root in astryx.integration.mjs.

bash
npx astryx integration add doc deploying
# Read it the way an app will
npx astryx docs deploying

text
doc contribution added
​
[ok] deploying
​
Declare doc root ./docs in astryx.integration.mjs.
​
- docs/deploying.doc.mjs
- astryx.integration.mjs

• Name the topic in lowercase kebab-case, such as deploying. Readers type the name as a command argument, so it holds only letters, digits, _, and -.
• Keep the name stable: readers and links find the topic by it.
• Pick a name no Core topic uses. To take over or add to a Core topic, see astryx docs cli/integrations/building-blocks/docs/extend-or-replace.

A topic is a plain object with type: 'generic', a name, a title, a one-sentence description, and sections. Each section has a title and a list of content blocks.

javascript
/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
export default {
  type: 'generic',
  name: 'deploying',
  title: 'Deploying',
  description: 'Ship an app built with Acme widgets.',
  sections: [{
    id: 'build-before-you-ship',
    title: 'Build before you ship',
    content: [
      {type: 'prose', text: 'Build the app, then upload the `dist` folder.'},
      {type: 'code', lang: 'bash', code: 'npm run build'},
      {type: 'list', style: 'unordered', items: ['Keep `dist` out of git.']},
      {type: 'table', headers: ['Variable', 'Value'], rows: [['`NODE_ENV`', '`production`']]},
    ],
  }],
};

• Content blocks are prose, code, list, and table, as shown; heading, with a level from 3 to 6 and a text; and token-ref, which inlines a token table from another topic.
• id is optional: a stable key for the section. Without it, the key comes from the title. A stable CLI before 0.7.0 cannot read id; see astryx docs cli/integrations/ship/versioning.
• Replace the Overview placeholder that integration add writes. Every field is in astryx docs authoring.

Every doc is a .doc.mjs file whose type says what it describes. integration add writes the right type and file for each kind.

Only guides, topics, and your docs section go in the docs root. The others have their own guides: astryx docs cli/integrations/building-blocks/components, astryx docs cli/integrations/building-blocks/templates, and astryx docs cli/integrations/building-blocks/themes.

The docs field in astryx.integration.mjs names the folder that holds your topics. The CLI reads every .doc.mjs file under it, in subfolders too.

javascript
export default {
  docs: './docs'
};

• Readers open a topic by its name, not its file name. Name the file after the doc, <name>.doc.mjs, so each one is easy to find.
• A topic with no placement is a flat topic: the docs list shows it under Topics, and readers open it by its name.
• To give your package its own section in the docs tree instead, see astryx docs cli/integrations/building-blocks/docs/sections-and-placement.