Extend or replace a topic

Take over a topic, or merge sections into it.

Replace a topic

Set replaces to take over an existing topic, such as Core's getting-started. Readers who open the old name get your topic.

bash
npx astryx integration add doc acme-getting-started --replaces getting-started
# The old name now opens your topic
npx astryx docs getting-started

docs/acme-getting-started.doc.mjs

javascript
export default {
  type: 'generic',
  name: 'acme-getting-started',
  replaces: 'getting-started',
  title: 'Acme getting started',
  description: 'Install Acme widgets and render your first carousel.',
  sections: [/* ... */],
};

The docs list shows your topic in place of the old one. Because your topic has its own name, the old name keeps resolving to it, so links and agents that learned the old name still land on your topic.

Extend a topic

Set extends to merge sections into an existing topic instead of owning it. A section with the same key replaces the base section, and a new section is added at the end.

bash
npx astryx integration add doc acme-theming --extends theme
npx astryx docs theme --index

docs/acme-theming.doc.mjs

javascript
export default {
  type: 'generic',
  name: 'acme-theming',
  extends: 'theme',
  title: 'Acme theming',
  description: 'Theme an app that uses Acme widgets.',
  sections: [
    {id: 'quick-start', title: 'Quick Start', content: [/* replaces the base section */]},
    {id: 'use-the-ocean-theme', title: 'Use the ocean theme', content: [/* added at the end */]},
  ],
};

A section's key is its id, or a key made from its title. Read the base topic's keys with --index.
The topic keeps the base's title and description, and readers open it by the base's name.
Replace the Overview placeholder that integration add writes, or it is added to the base topic.
Extend a topic to correct or add to it. A copy made with replaces stops getting the owner's fixes.

Check overlaps with Core topics

A topic sets replaces or extends, never both, and a placed guide sets neither. A topic that uses a Core topic's name with neither is an accidental conflict: apps keep reading the Core topic.

bash
npx astryx doctor integration docs

text
severity:     [info]
topic:        acme-getting-started
relationship: replaces
coreTopic:    getting-started
message:      Intentional override: "acme-getting-started" replaces the Core topic "getting-started".
severity:     [fail]
topic:        tokens
relationship: accidental
coreTopic:    tokens
message:      Accidental conflict: "tokens" is already a Core topic. Rename it, declare replaces: 'tokens' to take it over, or declare extends: 'tokens' to merge sections.

An intentional overlap prints as [info]. An accidental one fails with exit code 1.
A topic that sets both fails as invalid_doc, and so does a placed guide that sets either one.