Sections and placement

Give your package its own docs section and place guides in it.

Add a docs section

Give your package its own section in the docs tree with integration add doc <name> --parent <section>. The first run also writes the section's namespace doc.

bash
npx astryx integration add doc deploying --parent acme
# Open your section
npx astryx docs acme

docs/acme.doc.mjs

javascript
/** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */
export default {
  type: 'namespace',
  name: 'acme',
  title: 'Acme',
  summary: 'Guides for Acme.',
  slots: {
    guides: {title: 'Guides', accepts: {kinds: ['generic']}},
  },
};

Edit its title and summary: readers see them in the docs list and at the top of your section.
The guide, docs/deploying.doc.mjs, gets placement: {parent: 'namespace:acme', slot: 'guides'}. Later runs with --parent acme reuse the namespace doc.
package.json gets the optional peer "@astryxdesign/cli": ">=0.7.0", because an older CLI does not read sections; see astryx docs cli/integrations/ship/versioning.

Place a doc

A guide names its one home with placement: a namespace of your package, a slot in it, and an order. Its route is the section name, then the guide name.

javascript
placement: {parent: 'namespace:acme', slot: 'guides', order: 10}, // route: acme/deploying

parent is namespace:<name>, a namespace that your own package ships. You cannot place a doc in the CLI's sections or in another package's.
slot is a slot that the namespace declares for the doc's kind. You can leave it out when the namespace has only one slot.
order is an integer that sorts the guides in the slot and sets their Previous and Next moves. Guides without one come last, by name.
A placed guide opens only by its route, acme/deploying. Its bare name no longer opens it.

bash
npx astryx docs acme/deploying

Fix a failed placement

A failed placement hides the doc: it gets no route and does not show in the docs list. doctor integration docs fails with invalid_doc_graph and names what to fix.

bash
npx astryx doctor integration docs

text
severity: [fail]
code:     invalid_doc_graph
message:  @acme/astryx-widgets/deploying.doc.mjs: placement.parent "namespace:cli" names no namespace; @acme/astryx-widgets declares "acme".

A parent that your package does not ship, such as namespace:cli, "names no namespace".
A slot that the namespace does not declare "is not a slot of namespace"; the message lists the slots it does declare.
The check exits 1; see astryx docs cli/integrations/building-blocks/docs/check-your-docs.