{"$schema":"https://doc-kit.nodejs.org/schemas/api-doc/1.0.1.json","id":"writing-docs","path":"/writing-docs","type":"module","module":"writing-docs","title":"Writing documentation","introducedIn":null,"sourceLink":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"doc-kit reads GitHub Flavored Markdown, plus a handful of conventions that\nturn a page into an API reference: headings written as signatures, typed\nparameter lists, version history and stability. This page covers what most\ndocuments use. The [Markdown specification](./specification.html) is the full\ncontract.\n\n> \\[!TIP]\n> Documenting a TypeScript or JavaScript project?\n> [`@doc-kit/typedoc`](./packages/typedoc.html) writes this Markdown for you,\n> from your source code and its JSDoc comments. See\n> [Documenting TypeScript](./typescript.html).","summary":"doc-kit reads GitHub Flavored Markdown, plus a handful of conventions that turn a page into an API reference: headings written as signatures, typed parameter lists, version history and stability. This page covers what most documents use. The Markdown specification is the full contract.","examples":[],"children":[{"kind":"section","id":"the-smallest-document","name":"The smallest document","title":"The smallest document","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"```markdown displayName=\"docs/kittens.md\"\n# Kittens\n\nThe `kittens` module adopts, feeds and pets kittens.\n```\n\nStart every file with one level-one heading. Its text is the page's title: it\nnames the browser tab and, unless you configure the sidebar yourself, the\npage's link in the sidebar. The website skips a file that has headings but no\nlevel-one heading. The first paragraph is the page's description, which\n[`llms.txt`](./generators/llms-txt.html) lists next to the link.\n\nThe output file follows the source path, not the title: with `docs/**/*.md` as\ninput, `docs/kittens.md` becomes `kittens.html`.","summary":"Start every file with one level-one heading. Its text is the page's title: it names the browser tab and, unless you configure the sidebar yourself, the page's link in the sidebar. The website skips a file that has headings but no level-one heading. The first paragraph is the page's description, which `llms.txt` lists next to the link.","examples":[{"language":"markdown","displayName":"docs/kittens.md","code":"# Kittens\n\nThe `kittens` module adopts, feeds and pets kittens."}],"children":[]},{"kind":"section","id":"what-differs-from-github-markdown","name":"What differs from GitHub Markdown","title":"What differs from GitHub Markdown","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"Everything GitHub Markdown does still works. On top of it:\n\n* Text in curly braces is a [type annotation](#types-that-link-themselves):\n `{string}` renders as code that links to the type's documentation. Put\n literal braces in a code span.\n* Headings written like signatures, such as `` `kittens.adopt(name)` ``, are\n [API entries](#how-headings-are-classified).\n* A list under an entry whose items start with a name and a type is a\n [typed list](#parameters-return-values-and-defaults).\n* HTML comments carry metadata: `` comments set\n [page metadata](#page-metadata).\n* A blockquote that starts with `Stability:` is a\n [stability indicator](#stability).\n* Two or more code blocks in a row become [tabs](#code-samples).\n* Links to `.md` files [point to the generated pages](#linking-between-pages).","summary":"Everything GitHub Markdown does still works. On top of it:","examples":[],"children":[]},{"kind":"section","id":"documenting-an-api","name":"Documenting an API","title":"Documenting an API","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"Each heading below the title, down to `#####`, starts an *entry*, and deeper\nheadings start entries nested inside it. An entry has up to six parts, in this\norder: a heading, its history, its stability, its typed list, prose, and code\nsamples. All but the heading come before the next heading, whatever its level.\n\n![The parts of an API entry in doc-kit Markdown, and what each becomes](./diagrams/entry-anatomy.svg)\n\nEvery part after the heading is optional, and most entries use only a few:\n\n````markdown displayName=\"docs/kittens.md\"\n## `kittens.adopt(name[, options])`\n\n\n\n- `name` {string} The kitten's name.\n- `options` {Object}\n - `color` {string} Coat color. **Default:** `'tabby'`.\n- Returns: {Promise} Fulfills with the adopted kitten.\n\nAdopts a kitten, once the paperwork is done.\n\n```js\nconst kitten = await kittens.adopt('Mittens');\n```\n````\n\nThe heading makes this a method and gives its signature, the comment records\nwhen it was added, and the list becomes its parameters and return value. The\nwebsite renders a signature, a parameter table and a version history; the\n[JSON output](./generators/json.html) keeps each part as data.","summary":"Each heading below the title, down to `#####`, starts an _entry_, and deeper headings start entries nested inside it. An entry has up to six parts, in this order: a heading, its history, its stability, its typed list, prose, and code samples. All but the heading come before the next heading, whatever its level.","examples":[{"language":"markdown","displayName":"docs/kittens.md","code":"## `kittens.adopt(name[, options])`\n\n\n\n- `name` {string} The kitten's name.\n- `options` {Object}\n - `color` {string} Coat color. **Default:** `'tabby'`.\n- Returns: {Promise} Fulfills with the adopted kitten.\n\nAdopts a kitten, once the paperwork is done.\n\n```js\nconst kitten = await kittens.adopt('Mittens');\n```"}],"children":[]},{"kind":"section","id":"how-headings-are-classified","name":"How headings are classified","title":"How headings are classified","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"doc-kit reads an entry's kind from its heading, with no annotation needed:\n\n| Heading | Kind |\n| -------------------------------------------- | ------------- |\n| `` ## Class: `kittens.Kitten` `` | Class |\n| `` ### `new kittens.Kitten(name)` `` | Constructor |\n| `` ### Static method: `Kitten.from(json)` `` | Static method |\n| `` ### `kitten.pet([times])` `` | Method |\n| `` ### `kitten.name` `` | Property |\n| `` ### Event: `'purr'` `` | Event |\n\n* Parentheses make a method, and their absence a property. A method needs only\n a name, as in `` `adopt(name)` ``, but a property needs an owner:\n `` `kitten.name` `` or `` `kitten[key]` ``.\n* The `Class:`, `Static method:` and `Event:` prefixes mark those kinds, and\n `new` marks a constructor.\n* The code span must be the whole heading, after any prefix:\n ``### `kitten.pet()` again`` is a plain section.\n* Optional parameters go in square brackets, nested when one only makes sense\n after another: `` `kitten.groom(brush[, side[, strokes]])` ``. A rest\n parameter is written `[...names]`. Leave types and defaults out of the\n heading; they belong in the typed list.\n* Anything else, like `## Synopsis`, is a plain section. Write those headings\n in plain words, without backticks.\n\nEntries nest by heading level, so put a class's constructor, methods,\nproperties and events one level below the class.","summary":"doc-kit reads an entry's kind from its heading, with no annotation needed:","examples":[],"children":[]},{"kind":"section","id":"parameters-return-values-and-defaults","name":"Parameters, return values and defaults","title":"Parameters, return values and defaults","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"Under the heading, and after any history or stability, a typed list describes\nwhat the entry takes and returns. Each item is a name in a code span, a type\nin curly braces, and a description:\n\n```markdown\n### `kitten.feed(food[, options])`\n\n- `food` {string|string[]} What to serve.\n- `options` {Object}\n - `portion` {number} Grams per serving. **Default:** `50`.\n - `signal` {AbortSignal} Cancels the meal.\n- Returns: {Promise} Fulfills with `true` once the bowl is empty.\n```\n\n* Nested lists describe the properties of an object, to any depth.\n* `**Default:**` followed by the value in a code span records a default and\n makes the parameter optional. Square brackets in the heading make it\n optional too.\n* Three prefixes stand in for the name: `Returns:` for a return value, `Type:`\n for a property's type, and `Extends:` for a class's parent class.\n\nThe same list works for the other kinds. An event's list describes the\narguments its listeners receive:\n\n```markdown\n## Class: `kittens.Kitten`\n\n- Extends: {EventTarget}\n\n### `kitten.name`\n\n- Type: {string}\n\n### Event: `'purr'`\n\n- `volume` {number} How loud, from 1 to 10.\n```\n\ndoc-kit recognizes a typed list by its first item, which must start with a\nname and a type, a bare type, or one of the prefixes. A list whose first item\nhas a name but no type stays a plain list, and plain bullets after the typed\nitems stay prose.\n\nOn the website, a typed list becomes a table, under the signature for methods\nand constructors. In JSON, each item's name, type, description, default and\nwhether it's optional become fields.","summary":"Under the heading, and after any history or stability, a typed list describes what the entry takes and returns. Each item is a name in a code span, a type in curly braces, and a description:","examples":[{"language":"markdown","displayName":null,"code":"### `kitten.feed(food[, options])`\n\n- `food` {string|string[]} What to serve.\n- `options` {Object}\n - `portion` {number} Grams per serving. **Default:** `50`.\n - `signal` {AbortSignal} Cancels the meal.\n- Returns: {Promise} Fulfills with `true` once the bowl is empty."},{"language":"markdown","displayName":null,"code":"## Class: `kittens.Kitten`\n\n- Extends: {EventTarget}\n\n### `kitten.name`\n\n- Type: {string}\n\n### Event: `'purr'`\n\n- `volume` {number} How loud, from 1 to 10."}],"children":[]},{"kind":"section","id":"types-that-link-themselves","name":"Types that link themselves","title":"Types that link themselves","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"Curly braces hold a TypeScript type, in a typed list or anywhere in prose.\ndoc-kit renders it as code and links each type name in it to its\ndocumentation:\n\n```markdown\n- `food` {string|string[]} What to serve.\n\n`kittens.adopt()` returns a {Promise} that fulfills with a {kittens.Kitten}.\n```\n\nAnything valid on the right of a TypeScript `type X =` works, including\nunions, arrays and generics such as `{Promise}`. doc-kit looks each\nname up in order, and the first match wins:\n\n1. Your [type map](#the-type-map). Its names are case-sensitive and may\n contain spaces.\n2. JavaScript primitives and keywords, such as `string`, `number`, `null` and\n `any`, linked to MDN.\n3. JavaScript's built-in objects and the Web APIs documented on MDN, such as\n `Promise`, `Map`, `AbortSignal` and `URL`.\n4. Dotted names, which link into your own docs: the part before the first dot\n names the page. `{kittens.Kitten}` links to the `Class:` heading on the\n `kittens` page (a capitalized last part means a class), and\n `{kittens.breeds}` to the `kittens.breeds` property.\n\nSteps 2 and 3 ignore case. A name that nothing matches stays plain text inside\nthe code, which is fine. If the braces don't hold a valid type, doc-kit logs a\nwarning and renders the text as plain code.","summary":"Curly braces hold a TypeScript type, in a typed list or anywhere in prose. doc-kit renders it as code and links each type name in it to its documentation:","examples":[{"language":"markdown","displayName":null,"code":"- `food` {string|string[]} What to serve.\n\n`kittens.adopt()` returns a {Promise} that fulfills with a {kittens.Kitten}."}],"children":[{"kind":"section","id":"the-type-map","name":"The type map","title":"The type map","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"For your own types, and other projects' types, write a JSON file that maps\nnames to URLs:\n\n```json displayName=\"type-map.json\"\n{\n \"Litter\": \"https://example.com/docs/litter\",\n \"Adoption options\": \"kittens.html#kittensadoptname-options\"\n}\n```\n\nThen point `metadata.typeMap` at it, or pass it to the CLI's\n[`--type-map`](./cli.html) option:\n\n```js displayName=\"doc-kit.config.mjs\"\nexport default {\n metadata: {\n typeMap: './type-map.json',\n },\n};\n```\n\n`typeMap` takes a URL, or a path read from the directory you run doc-kit in.\nA relative URL in the map is relative to the output root, and doc-kit adjusts\nit for each page.","summary":"For your own types, and other projects' types, write a JSON file that maps names to URLs:","examples":[{"language":"json","displayName":"type-map.json","code":"{\n \"Litter\": \"https://example.com/docs/litter\",\n \"Adoption options\": \"kittens.html#kittensadoptname-options\"\n}"},{"language":"js","displayName":"doc-kit.config.mjs","code":"export default {\n metadata: {\n typeMap: './type-map.json',\n },\n};"}],"children":[]}]},{"kind":"section","id":"recording-history","name":"Recording history","title":"Recording history","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"An HTML comment that starts with `YAML`, right after an entry's heading,\nrecords the entry's history:\n\n```markdown\n### `kittens.adopt(name[, options])`\n\n\n```\n\n| Field | What it records |\n| ------------ | ---------------------------------------------------------------------------------- |\n| `added` | The version the entry first shipped in. |\n| `deprecated` | The version that deprecated it. |\n| `removed` | The version that removed it. |\n| `changes` | Notable changes, each with a `version`, a `pr-url` and a `description` (Markdown). |\n\nA version is a string such as `v1.0.0`. Use a list of versions for a change\nthat was backported to older release lines. The website shows the history next\nto the heading, and JSON keeps it as data.","summary":"An HTML comment that starts with `YAML`, right after an entry's heading, records the entry's history:","examples":[{"language":"markdown","displayName":null,"code":"### `kittens.adopt(name[, options])`\n\n"}],"children":[]},{"kind":"section","id":"stability","name":"Stability","title":"Stability","scope":"module","overloadOf":null,"stability":{"index":"2","description":"Stable. This box is a live stability indicator."},"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"A blockquote that starts with `Stability:`, a level and a label marks an\nentry's stage in its lifecycle. The website renders it as a colored box, like\nthis one:\n\nPlace it after the history comment, if there is one, and before the typed\nlist. The text after the level is yours: explain, link to an alternative, or\ncontinue on more lines.\n\n```markdown\n### `kittens.adopt(name[, options])`\n\n\n\n> Stability: 1 - Experimental. The adoption fee may change.\n\n- `name` {string} The kitten's name.\n```\n\n| Level | Meaning |\n| ----- | ------------------------------------------------------------------------- |\n| 0 | Deprecated: may emit warnings, and compatibility isn't guaranteed. |\n| 1 | Experimental: outside semantic versioning, and may change in any release. |\n| 2 | Stable: compatibility is a priority. |\n| 3 | Legacy: still covered by semantic versioning, but no longer maintained. |\n\nLevel 1 takes sub-levels that say how close an API is to stable: `1.0` (early\ndevelopment), `1.1` (active development) and `1.2` (release candidate). On the\ntitle, a stability indicator applies to the whole page.","summary":"A blockquote that starts with `Stability:`, a level and a label marks an entry's stage in its lifecycle. The website renders it as a colored box, like this one:","examples":[{"language":"markdown","displayName":null,"code":"### `kittens.adopt(name[, options])`\n\n\n\n> Stability: 1 - Experimental. The adoption fee may change.\n\n- `name` {string} The kitten's name."}],"children":[]},{"kind":"section","id":"code-samples","name":"Code samples","title":"Code samples","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"Fence code samples with a language, so the website can highlight them. Two or\nmore code blocks in a row become one block with a tab each. A tab is labelled\nby its block's `displayName`, or by its language when it has none (`cjs` and\n`mjs` read as CJS and ESM):\n\n````markdown\n```bash displayName=\"npm\"\nnpm install kittens\n```\n\n```bash displayName=\"pnpm\"\npnpm add kittens\n```\n````\n\nThat renders as:\n\n```bash displayName=\"npm\"\nnpm install kittens\n```\n\n```bash displayName=\"pnpm\"\npnpm add kittens\n```\n\nTo keep blocks apart, put a sentence between them. The JSON output lists each\nentry's code samples, with their language and `displayName`.","summary":"Fence code samples with a language, so the website can highlight them. Two or more code blocks in a row become one block with a tab each. A tab is labelled by its block's `displayName`, or by its language when it has none (`cjs` and `mjs` read as CJS and ESM):","examples":[{"language":"markdown","displayName":null,"code":"```bash displayName=\"npm\"\nnpm install kittens\n```\n\n```bash displayName=\"pnpm\"\npnpm add kittens\n```"},{"language":"bash","displayName":"npm","code":"npm install kittens"},{"language":"bash","displayName":"pnpm","code":"pnpm add kittens"}],"children":[]},{"kind":"section","id":"alerts","name":"Alerts","title":"Alerts","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"GitHub's alert syntax renders as a callout, like the tip at the top of this\npage:\n\n```markdown\n> [!WARNING]\n> Kittens adopted before eight weeks of age need extra care.\n```\n\nThe five kinds are `NOTE`, `TIP`, `IMPORTANT`, `WARNING` and `CAUTION`.","summary":"GitHub's alert syntax renders as a callout, like the tip at the top of this page:","examples":[{"language":"markdown","displayName":null,"code":"> [!WARNING]\n> Kittens adopted before eight weeks of age need extra care."}],"children":[]},{"kind":"section","id":"linking-between-pages","name":"Linking between pages","title":"Linking between pages","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"Link to other pages by their source file, with a relative path. doc-kit\nrewrites the `.md` extension to the output's `.html`:\n\n```markdown\nSee [`kittens.adopt()`][] for the details, or the [care guide](care.md).\n\n[`kittens.adopt()`]: kittens.md#kittensadoptname-options\n```\n\nAnchors are heading slugs, made much as GitHub makes them:\n`` ## `kittens.adopt(name[, options])` `` becomes `#kittensadoptname-options`,\nand `` ## Class: `kittens.Kitten` `` becomes `#class-kittenskitten`. When in\ndoubt, copy the link from the heading on the rendered page.\n\nReference-style links, with their definitions at the end of the file, keep\nlong pages readable. A system call written like `open(2)` in plain text (not\nin a code span) links to its Linux manual page.","summary":"Link to other pages by their source file, with a relative path. doc-kit rewrites the `.md` extension to the output's `.html`:","examples":[{"language":"markdown","displayName":null,"code":"See [`kittens.adopt()`][] for the details, or the [care guide](care.md).\n\n[`kittens.adopt()`]: kittens.md#kittensadoptname-options"}],"children":[]},{"kind":"section","id":"page-metadata","name":"Page metadata","title":"Page metadata","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"One-line comments right after the title set metadata for the whole page:\n\n```markdown\n# Kittens\n\n\n\n\n```\n\n| Directive | What it does |\n| ----------------- | ---------------------------------------------------------------------------- |\n| `introduced_in` | The version the module first shipped in, shown with the page's history. |\n| `source_link` | Links the page to the file that implements it, in your repository on GitHub. |\n| `llm_description` | Describes the page in `llms.txt`, in place of its first paragraph. |\n| `type` | What the page documents: `module` (the default), `misc` or `global`. |\n| `name` | The module's name in JSON output, when it isn't the file name. |\n\nA frontmatter block at the top of the file does the same job with YAML keys:\nany of the directives above or the history fields, plus `title`, which\nreplaces the heading's text in the browser tab, and `mdx`, described in\n[MDX pages](#mdx-pages).\n\n```markdown\n---\ntitle: Adopting kittens\nintroduced_in: v1.0.0\n---\n\n# Kittens\n```","summary":"One-line comments right after the title set metadata for the whole page:","examples":[{"language":"markdown","displayName":null,"code":"# Kittens\n\n\n\n"},{"language":"markdown","displayName":null,"code":"---\ntitle: Adopting kittens\nintroduced_in: v1.0.0\n---\n\n# Kittens"}],"children":[]},{"kind":"section","id":"guides-and-api-pages","name":"Guides and API pages","title":"Guides and API pages","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"Guides need nothing special: headings that don't look like an API stay plain\nsections. Still, doc-kit treats every page as documenting a module unless its\n`type` directive says otherwise:\n\n```markdown\n# Caring for your kitten\n\n\n```\n\n`misc` marks a guide or another conceptual page: JSON output records the\npage's `type` as `misc`, with no module name. `global` marks a page of\nglobals, which need no import, and JSON gives its entries a global scope.\n\nThe directive doesn't change how headings are classified: on a `misc` page,\n`` ## `kitten.pet()` `` is still a method. When a heading looks like an API\nbut isn't an entry, write it in plain words, or override its kind in its YAML\ncomment so that it becomes a plain section:\n\n```markdown\n### `kitten.whiskers`\n\n\n```","summary":"Guides need nothing special: headings that don't look like an API stay plain sections. Still, doc-kit treats every page as documenting a module unless its `type` directive says otherwise:","examples":[{"language":"markdown","displayName":null,"code":"# Caring for your kitten\n\n"},{"language":"markdown","displayName":null,"code":"### `kitten.whiskers`\n\n"}],"children":[]},{"kind":"section","id":"mdx-pages","name":"MDX pages","title":"MDX pages","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"When a page needs components, such as a landing page or a live demo, write it\nin MDX: name the file `.mdx`, or set `mdx: true` in a Markdown file's\nfrontmatter (`mdx: false` turns an `.mdx` file back into Markdown).\n\n```mdx displayName=\"docs/index.mdx\"\n---\ntitle: Kittens\n---\n\n# Kittens\n\nEverything about adopting, feeding and petting kittens.\n\n\n```\n\n`` is built in: it lists every page with its stability\nand description. Components you register yourself work too; see\n[Customizing the site](./customization.html#custom-components-and-mdx).\n\nIn MDX, curly braces are JavaScript expressions, not types, so typed lists\nstay plain lists and type names don't link. HTML comments aren't valid MDX\neither, so set page metadata in frontmatter, write comments as `{/* ... */}`,\nand keep entries that need history in Markdown pages. Headings and stability\nindicators work as they do in Markdown.","summary":"When a page needs components, such as a landing page or a live demo, write it in MDX: name the file `.mdx`, or set `mdx: true` in a Markdown file's frontmatter (`mdx: false` turns an `.mdx` file back into Markdown).","examples":[{"language":"mdx","displayName":"docs/index.mdx","code":"---\ntitle: Kittens\n---\n\n# Kittens\n\nEverything about adopting, feeding and petting kittens.\n\n"}],"children":[]},{"kind":"section","id":"learn-more","name":"Learn more","title":"Learn more","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"* The [Markdown specification](./specification.html) is the full contract for\n the format, edge cases included.\n* [Documenting TypeScript](./typescript.html) generates these pages from your\n source code.\n* [Customizing the site](./customization.html) covers navigation, the theme and\n components.","summary":"","examples":[],"children":[]}]}