doc-writer

name

doc-writer

description

Write, review, and organize the human-authored prose around a generated API reference on an rspress-plugin-api-extractor site. Use when authoring or editing a guide, concept, example, or package-overview page; deciding a site's information architecture and sidebar mount (guides spine + overview + generated api tree); setting page frontmatter (title, one-sentence description); deciding whether a code snippet earns a with-api fence versus a plain fence; writing a migration note for a breaking API change; cross-linking prose into the generated reference; or running an editorial review of a docs site. Do NOT use for the mechanics inside a with-api fence — notation, @errors, ---cut---, why a block will not compile (see twoslash); for ApiExtractorPlugin configuration, routes, theming or model plumbing (see plugin-config); or for generic RSPress routing, _nav.json, components, or frontmatter fields beyond title/description (see rspress-core).

doc-writer

Load this skill when you are writing or editing the human-authored documentation on a site built with rspress-plugin-api-extractor — the guides, overviews, concept and example pages a person writes by hand — or reviewing a site's prose for quality. It owns the editorial craft: what to write, how to structure it, and when a code snippet earns a live with-api fence.

It does not touch the generated reference tree (that is build output — see below) and it does not own code-fence mechanics.

Route these adjacent decisions elsewhere:

• The mechanics inside a with-api fence — notation (^?, @errors, ---cut---), why a block fails to compile, what strips on copy — see twoslash. This skill decides whether a snippet gets with-api; twoslash handles it once you have.
• ApiExtractorPlugin configuration — options, routes, --api-* theming, model plumbing — see plugin-config.
• Generic RSPress mechanics — _nav.json, sidebar field semantics, built-in components, frontmatter fields beyond title/description — see rspress-core.

Boundary: looks similar, is not

This skill and twoslash both concern code examples, so they read as one job. They are not.

• doc-writer owns the editorial when: does this snippet deserve to be a live, type-checked with-api block at all? That is a judgment about honesty and audience, made before any fence exists.
• twoslash owns the how: given that a block is with-api, what notation goes in it, why it compiles or fails, what the reader copies.

Decide with this skill; author with twoslash. A snippet that should stay a plain illustrative fence never reaches twoslash at all.

Site information architecture

A site built with this plugin has three tiers. Keep them distinct; readers navigate down through them.

1. A guide spine — hand-written pages that teach the package by task (getting started, then one page per real workflow). This is where a reader lands and learns.
2. A per-package overview — one page that frames the package: what it is, why it exists, install, a quick start, and the topic sections that link into the guides and reference. On a portal, one overview per package.
3. The generated reference — the plugin-owned api/ tree, one page per API item. You link into it; you never author inside it.

Mount the three tiers in the site's root _meta.json (array form — see rspress-core) with one entry each:

[
  { "type": "file", "name": "index", "label": "Home" },
  { "type": "dir", "name": "guides", "label": "Guides", "collapsible": true, "collapsed": false },
  { "type": "dir", "name": "api", "label": "API Reference", "collapsible": true, "collapsed": true }
]

The api dir entry is the only place you touch the generated tree — it mounts the plugin's output into the sidebar. Everything under it is build output.

The generated tree is read-only

The plugin rewrites changed pages under api/ and deletes stale ones on every build, so any hand-edit there is silently reverted. The API prose comes from the documented package's TSDoc. When the reference is wrong, the fix is upstream — the source comment and a model rebuild — reported as a finding, never patched in the generated MDX. Your editorial work lives entirely in tiers 1 and 2.

Frontmatter convention

Every hand-written page carries two frontmatter fields and, usually, no more:

• title — the page's short title (also the sidebar/tab label).
• description — one sentence, written to stand alone as an Open Graph / search snippet. Say what the page gives the reader, in a full sentence, not a keyword list.

---
title: Getting started
description: Create a pipeline, run it, and inspect its status — the core kitchensink workflow end to end.
---

Fields beyond these two (layout, hero, pageType) are generic RSPress frontmatter — see rspress-core.

The with-api discipline rule

This is the editorial call this skill exists to make.

• Real, importable code gets with-api. If a snippet imports from the documented package and a reader could run it, mark the fence with-api so it is type-checked against the real API model and stays honest as the package changes. This is the default for any example built from the package's public surface.
• Shape sketches stay plain fences. Pseudo-code, a JSON/config fragment, a partial signature written to illustrate a shape, or a snippet that references symbols the package does not export — none of these should compile, so none should be with-api. A plain ```ts fence is correct; forcing with-api onto them produces noise errors that erode trust in the ones that matter.

The test is one question: should this compile against the real package? Yes → with-api (then hand off to twoslash). No → plain fence. Never reach for with-api to make a non-program "look rigorous"; a red squiggle on a snippet that was never meant to run is worse than a plain fence.

Trap: ```typescript twoslash vfs is dead pre-1.0 syntax. If you find it while editing or reviewing an existing page, it is a broken block silently no longer type-checking — replace the meta with with-api. The mechanics belong to twoslash; flagging it is editorial.

The API-reference handoff

A guide or overview teaches a slice; the generated reference is the authority for everything. Close hand-written pages by handing the reader off to it, so prose and reference stay in their lanes:

• End a guide with a "Next steps" / "Learn more" list that includes an absolute link into the reference ([API reference](/my-library/api)).
• When prose names a type it does not fully document, link that mention to its generated page rather than re-documenting it inline.

This keeps guides short and lets the reference carry exhaustive detail — the two never compete to be the source of truth. Link construction and the hub-table pattern are in references/cross-linking.md.

Common mistakes

• Hand-editing a generated api/ page. It is reverted on the next build; the fix is the source TSDoc plus a model rebuild, raised as a finding.
• Forcing with-api onto a shape sketch. A snippet that was never meant to compile earns a red squiggle that trains readers to distrust the examples that are real. Plain fence.
• Leaving a twoslash vfs block in an edited page. Dead syntax — it silently stopped type-checking. Convert to with-api.
• Re-documenting a type inline instead of linking to its reference page. Prose drifts from the model; link the mention and let the generated page be authoritative.
• A guide with no handoff. A reader who finishes the prose should be pointed at the reference, not left at a dead end.
• A description that is a keyword list, not a sentence. It ships as the OG/search snippet; write it to read as one standalone sentence.
• Orphaned pages. A page not reachable from _meta.json or a hub link is invisible; every hand-written page needs a route in.

Reference map

Load on demand; none is required to write a first page. Each answers a narrower question than this file.

• references/page-skeletons.md — the Concept / Guide / Example page structures with content-source mapping, and the package-overview template.
• references/review-rubric.md — the editorial-review severity ladder (Critical → Low) and the pass checklist.
• references/sync-workflow.md — the "the API changed, update the prose" flow grounded on the plugin's snapshot statuses, with the migration-note pattern.
• references/cross-linking.md — absolute route links, hub tables, guide↔reference bridges, and the known-issues genre (status-stamped error signatures).