templates/documentation-md.mdBrowse 8 files

504 tokens

2,135 bytes
Token encoding: o200k_base
Snapshot 646e806

documentation .md template

For the colocated doc of a migration entry. Read by humans on nx.dev and handed to agents as reference material; both consumers resolve it from the entry's documentation key. Exemplar: packages/nx/src/migrations/update-21-0-0/remove-legacy-cache.md.

Headings start at h4: the docs site nests the content under an h3 entry heading, so h1-h3 would break the page hierarchy.

#### <What the migration does, as a short title>

One or two paragraphs: what changes, why (the upstream or Nx change that forced
it), and any user-visible effect after migrating.

#### Sample code changes

Optional one-line setup for the example.

##### Before

```ts title="apps/app1/vite.config.ts"
<before>
```

##### After

```ts title="apps/app1/vite.config.ts"
<after>
```

Rules:

Use the title="<file path>" attribute on fenced blocks so readers see where the change lands.
Multiple distinct changes get multiple Before/After pairs, each under its own h5 or with a one-line lead-in.
The Sample code changes section is for changes with a code shape; omit it when there is none (a removed cache flag, a moved directory).
These files render on nx.dev, so the docs style rules apply: astro-docs/STYLE_GUIDE.md, sentence-case headings per the site's Nx.Headings vale rule. Vale's scope does not reach these files today (it lints only astro-docs/src/content), so self-check; many shipped migration docs predate this and use title case.
Optional trailing #### Reference section with links to the upstream changelog or guide.
Name the file after the implementation (<name>.md next to <name>.ts); the shared name is pairing convention, and the docs site and agentic runs both resolve the file from the entry's documentation key.
Prompt migrations use the what-the-upgrade-involves genre instead: prose on what the upgrade involves and what is automated, named upgrade-to-<framework>-<major>.md (exemplar: packages/react/src/migrations/update-23-1-0/upgrade-to-react-19.md). It renders on the docs page and reaches agents through the documentation key like any other entry.

Referenced from SKILL.md

SKILL.mdView in source ↗

196- `description` feeds the agentic prompt and the public docs page. State the concrete action ("Removes the deprecated X option from Y executor options"). For prompt migrations, also state why it is AI-driven ("...whose options do not map 1:1, so it is driven by an AI prompt rather than a deterministic generator").197- Every new entry gets a colocated `documentation` .md, set on the entry's `documentation` key, per [templates/documentation-md.md](templates/documentation-md.md): before/after samples for generator-based migrations, what-the-upgrade-involves for prompt migrations (`upgrade-to-<framework>-<major>.md`); h4/h5 headings only, sentence case, and prose per `astro-docs/STYLE_GUIDE.md` (the content renders on nx.dev; vale does not lint these files today, so self-check). The key feeds both consumers: the agentic flow hands the agent its path, and the docs site renders its content on the plugin's migrations page (nothing is inferred from the implementation's basename). A prompt .md never doubles as documentation: it is agent-voiced, wrong audience (see `packages/react/migrations.json` `update-23-1-0-create-ai-instructions-for-react-19`, which pairs both).198- Before finishing, re-read every claim in the .md files against the implementation as written: version selection, trigger conditions, file coverage, and option lists must describe what the code actually does, not an earlier draft's design. Doc text written before a design change is the easiest artifact to leave stale. Scope claims drift most: a "handles X" sentence written while the code handles one shape of X. Back every handles/covers claim with the spec case that exercises it; if none exists, narrow the claim or add the test.