doc-kit reads GitHub Flavored Markdown, so everything you already know\napplies. On top of it, a handful of conventions get special treatment.
# hello\n\nA one-line description of the module.\nThe level-one heading is the page's identity: it becomes the sidebar label\nand the output filename. Every file needs exactly one, at the top.
", "displayName": "The smallest document" }, { "textRaw": "Where this departs from plain Markdown", "name": "where_this_departs_from_plain_markdown", "type": "module", "desc": "{curly braces} in prose and lists are type annotations,\nnot literal text.Stability: are stability indicators.YAML (and key=value comments) are\nmetadata, not ignored text.Everything else is standard GFM.
", "displayName": "Where this departs from plain Markdown" }, { "textRaw": "Documenting an API", "name": "documenting_an_api", "type": "module", "desc": "Each heading below the title starts an entry. Write the heading the way\nAPI docs are conventionally written, and doc-kit classifies it — no\nannotation needed:
## Class: `http.Server`\n\n### `new Agent([options])`\n\n### `server.listen(port[, callback])`\n\n### `server.maxHeadersCount`\n\n### Static method: `Buffer.from(string[, encoding])`\n\n### Event: `'close'`\nParentheses make a method; their absence makes a property; Class:,\nStatic method:, and Event: prefixes mark those kinds; new X() marks a\nconstructor. Optional parameters go in square brackets — [, callback] —\nnesting where needed: buf.write(string[, offset[, length]]).
Headings that match none of these patterns (like ## Synopsis) are ordinary\nsections, which is exactly right for prose. Wrap identifiers in backticks;\nleave prose headings unwrapped.
Directly under an entry's heading, an unordered list describes its\nparameters. Each item is a name, a type in braces, and prose:
\n### `fs.readFile(path[, options], callback)`\n\n- `path` {string|URL} The file to read.\n- `options` {Object}\n - `encoding` {string} **Default:** `'utf8'`.\n - `signal` {AbortSignal} Allows aborting the read.\n- `callback` {Function}\n- Returns: {Promise} Fulfills with the file contents.\n**Default:** `value` marks a parameter optional and records its\ndefault.Returns: describes the return value; Extends: names a class's\nsuperclass; Type: gives a property's type.The list is lifted out of the prose and becomes structured data — rendered\nas parameter tables in HTML, fields in JSON, and so on.
", "displayName": "Parameters and return values" }, { "textRaw": "Types that link themselves", "name": "types_that_link_themselves", "type": "module", "desc": "Anything in {braces} — in a list or mid-prose — is a TypeScript type\nexpression, rendered as code with each type name resolved to a link:
- `data` {string|Buffer} The payload.\n\nOn success, returns a {Promise} that fulfills with a {stream.Readable}.\nNames resolve in tiers: your configured type map first, then JavaScript\nbuilt-ins, then Web APIs on MDN, and finally module.Name patterns link to\nthe matching page in your own docs. A name nothing recognizes stays plain\ntext — that's fine, not an error.
An HTML comment holding YAML, placed right after a heading, records an\nentry's life story:
\n### `hello.greet(name)`\n\n<!-- YAML\nadded: v1.2.0\nchanges:\n - version: v2.0.0\n pr-url: https://github.com/me/hello/pull/42\n description: Invalid names now throw instead of returning `null`.\n-->\nadded, deprecated, and removed take a version (or an array of versions,\nfor backports); changes is a chronological list of notable changes with\ntheir pull requests. The HTML generator renders this as a version-history\nwidget; JSON consumers get it as data.
A blockquote in the exact form below marks an entry's lifecycle stage —\n0 (deprecated), 1 (experimental, with optional 1.0/1.1/1.2\nsub-levels), 2 (stable), or 3 (legacy):
### `hello.shout(name)`\n\n> [Stability: 1](documentation.html#stability-index) - Experimental. May change without notice.\nPlace it after the YAML comment (if any) and before the parameter list. On\nthe title heading, it applies to the whole page.
", "displayName": "Stability" }, { "textRaw": "Code samples", "name": "code_samples", "type": "module", "desc": "Use fenced code blocks with a language identifier. An optional displayName\nlabels the block in rendered output:
```js displayName=\"Reading a file\"\nconst data = await fs.readFile('/path/to/file');\n```\nLink to other documents by their source filename — the .md extension is\nrewritten to the right output extension at build time:
See [`hello.greet()`][] for the simple form.\n\n[`hello.greet()`]: hello.md#hellogreetname\nReference-style links with the definitions collected at the bottom of the\nfile keep prose readable. References to system calls like open(2) link to\ntheir man pages automatically.
Guides and tutorials need nothing special, most of the time. Headings that\nmatch none of the patterns above stay ordinary sections.
\nThe exception is a page whose headings do look like signatures but aren't\nmodule exports. A type directive under the title reclassifies the whole\ndocument, so those entries render as conceptual sections instead:
# C++ addons\n\n<!--type=misc-->\nFrontmatter (----delimited YAML) at the top of a file is also accepted and\ntreated as metadata. And if a page needs real components — heroes, tabs, live\nexamples — name it .mdx and use JSX directly; see\nCustomizing the site.
This page covers what most documents use, but a full\nspecification is also available.
", "displayName": "The full contract" } ], "displayName": "Writing documentation" } ] }