On this page

doc-kit reads GitHub Flavored Markdown, so everything you already know applies. On top of it, a handful of conventions get special treatment.

# hello

A one-line description of the module.
markdown

The level-one heading is the page's identity: it becomes the sidebar label and the output filename. Every file needs exactly one, at the top.

  • {curly braces} in prose and lists are type annotations, not literal text.
  • Blockquotes beginning with Stability: are stability indicators.
  • HTML comments beginning with YAML (and key=value comments) are metadata, not ignored text.

Everything else is standard GFM.

Each heading below the title starts an entry. Write the heading the way API docs are conventionally written, and doc-kit classifies it — no annotation needed:

## Class: `http.Server`

### `new Agent([options])`

### `server.listen(port[, callback])`

### `server.maxHeadersCount`

### Static method: `Buffer.from(string[, encoding])`

### Event: `'close'`
markdown

Parentheses make a method; their absence makes a property; Class:, Static method:, and Event: prefixes mark those kinds; new X() marks a constructor. Optional parameters go in square brackets — [, callback] — nesting where needed: buf.write(string[, offset[, length]]).

Headings that match none of these patterns (like ## Synopsis) are ordinary sections, which is exactly right for prose. Wrap identifiers in backticks; leave prose headings unwrapped.

Directly under an entry's heading, an unordered list describes its parameters. Each item is a name, a type in braces, and prose:

### `fs.readFile(path[, options], callback)`

- `path` {string|URL} The file to read.
- `options` {Object}
  - `encoding` {string} **Default:** `'utf8'`.
  - `signal` {AbortSignal} Allows aborting the read.
- `callback` {Function}
- Returns: {Promise} Fulfills with the file contents.
markdown
  • Nested lists document the properties of an object parameter, to any depth.
  • **Default:** `value` marks a parameter optional and records its default.
  • Returns: describes the return value; Extends: names a class's superclass; Type: gives a property's type.

The list is lifted out of the prose and becomes structured data — rendered as parameter tables in HTML, fields in JSON, and so on.

Anything in {braces} — in a list or mid-prose — is a TypeScript type expression, rendered as code with each type name resolved to a link:

- `data` {string|Buffer} The payload.

On success, returns a {Promise} that fulfills with a {stream.Readable}.
markdown

Names resolve in tiers: your configured type map first, then JavaScript built-ins, then Web APIs on MDN, and finally module.Name patterns link to the matching page in your own docs. A name nothing recognizes stays plain text — that's fine, not an error.

An HTML comment holding YAML, placed right after a heading, records an entry's life story:

### `hello.greet(name)`

<!-- YAML
added: v1.2.0
changes:
  - version: v2.0.0
    pr-url: https://github.com/me/hello/pull/42
    description: Invalid names now throw instead of returning `null`.
-->
markdown

added, deprecated, and removed take a version (or an array of versions, for backports); changes is a chronological list of notable changes with their pull requests. The HTML generator renders this as a version-history widget; JSON consumers get it as data.

A blockquote in the exact form below marks an entry's lifecycle stage — 0 (deprecated), 1 (experimental, with optional 1.0/1.1/1.2 sub-levels), 2 (stable), or 3 (legacy):

### `hello.shout(name)`

> [Stability: 1](documentation.html#stability-index) - Experimental. May change without notice.
markdown

Place it after the YAML comment (if any) and before the parameter list. On the title heading, it applies to the whole page.

Use fenced code blocks with a language identifier. An optional displayName labels the block in rendered output:

```js displayName="Reading a file"
const data = await fs.readFile('/path/to/file');
```
markdown

Link to other documents by their source filename — the .md extension is rewritten to the right output extension at build time:

See [`hello.greet()`][] for the simple form.

[`hello.greet()`]: hello.md#hellogreetname
markdown

Reference-style links with the definitions collected at the bottom of the file keep prose readable. References to system calls like open(2) link to their man pages automatically.

Guides and tutorials need nothing special, most of the time. Headings that match none of the patterns above stay ordinary sections.

The exception is a page whose headings do look like signatures but aren't module exports. A type directive under the title reclassifies the whole document, so those entries render as conceptual sections instead:

# C++ addons

<!--type=misc-->
markdown

Frontmatter (----delimited YAML) at the top of a file is also accepted and treated as metadata. And if a page needs real components — heroes, tabs, live examples — name it .mdx and use JSX directly; see Customizing the site.

This page covers what most documents use, but a full specification is also available.

PreviousGetting startedNextCustomizing the site