JSON

The json generator writes each source file as a JSON document: a tree of its headings, each with its metadata, signature or type, Markdown and code examples, in a format a published JSON schema describes. Use it when a program needs your API as data, such as an editor integration, a linter or a site of your own.

To load every document from one file, add the JSON bundle (json-all). Debug JSON (json-simple) is a different format: a dump of the API entries behind every output, for debugging the pipeline.

npx @doc-kit/cli generate -t json -i "doc/api/*.md" -o out

The documents keep the input's directory layout, from where the glob starts: doc/api/fs.md becomes out/fs.json, and doc/api/guides/streams.md becomes out/guides/streams.json.

It also reads the global options output, minify, and repository and ref, which sourceLink.url points into. Without a repository, sourceLink.url is null.

{
  "$schema": "https://doc-kit.nodejs.org/schemas/api-doc/1.0.1.json",
  "id": "fs",
  "path": "/fs",
  "type": "module",
  "module": "fs",
  "title": "File system",
  "introducedIn": "v0.10.0",
  "sourceLink": {
    "path": "lib/fs.js",
    "url": "https://github.com/nodejs/node/blob/HEAD/lib/fs.js"
  },
  "stability": { "index": "2", "description": "Stable" },
  "added": [],
  "deprecated": [],
  "removed": [],
  "napiVersion": [],
  "changes": [],
  "description": "The `node:fs` module enables interacting with the file system in a\nway modeled on standard POSIX functions.\n\n…",
  "summary": "The `node:fs` module enables interacting with the file system in a way modeled on standard POSIX functions.",
  "examples": [],
  "children": []
}

A document stands for a source file and its title heading. Besides the fields every entry has, it carries these, most from the file's page metadata:

The document and every node carry:

Every field is always present: what a source doesn't declare is null, an empty string or an empty array.

A node is a heading below the title. Its kind says what the heading documents (how headings are classified) and decides which further fields the node has:

Every node also carries:

The further fields come from the heading and the typed list under it:

A parameter has a name, without ..., a type, a description, and:

• default: the value as authored, without its code span, or null.
• optional: true when the parameter is bracketed in the heading or has a default.
• rest: true when it's declared as ...args.
• properties: its nested items, such as the properties of an options object or the arguments of a callback, each a parameter too.

A type has text, the annotation as a TypeScript type on one line, with | between union members, and links, the names in it that resolved to documentation, with their offsets in text (see Types that link themselves). A type the source doesn't document is null, never guessed.

For example, this method:

## `fsPromises.readFile(path[, options])`

- `path` {string|URL} The file to read.
- `options` {Object}
  - `encoding` {string|null} **Default:** `null`.
- Returns: {Promise} Fulfills with the contents of the file.

Reads the entire contents of a file.

has Reads the entire contents of a file. as its description, and this signature (each type's links shortened to []):

{
  "parameters": [
    {
      "name": "path",
      "type": { "text": "string | URL", "links": [] },
      "description": "The file to read.",
      "default": null,
      "optional": false,
      "rest": false,
      "properties": []
    },
    {
      "name": "options",
      "type": { "text": "Object", "links": [] },
      "description": "",
      "default": null,
      "optional": true,
      "rest": false,
      "properties": [
        {
          "name": "encoding",
          "type": { "text": "string | null", "links": [] },
          "description": "",
          "default": "null",
          "optional": true,
          "rest": false,
          "properties": []
        }
      ]
    }
  ],
  "returns": {
    "type": { "text": "Promise", "links": [] },
    "description": "Fulfills with the contents of the file."
  }
}

Each links array lists its type's names with where they point and their offsets, such as { "name": "URL", "href": "https://developer.mozilla.org/docs/Web/API/URL", "start": 9, "end": 12 } for URL in string | URL.

Every document's $schema points to the version of the schema it conforms to, such as https://doc-kit.nodejs.org/schemas/api-doc/1.0.1.json. The schema also ships in @doc-kit/core as @doc-kit/core/generators/json/schema.json, with TypeScript types generated from it:

import { readFile } from 'node:fs/promises';

import type {
  Document,
  Node,
} from '@doc-kit/core/generators/json/generated/schema';

const fs: Document = JSON.parse(await readFile('out/fs.json', 'utf-8'));

const listMethods = (nodes: Array<Node>): void => {
  for (const node of nodes) {
    if (node.kind === 'method') {
      console.log(
        node.name,
        node.signature.parameters.map(p => p.name)
      );
    }

    listMethods(node.children);
  }
};

listMethods(fs.children);

For doc-kit contributors: schema.json is the source of truth for the format. When you change it, bump the version in its $id, in SCHEMA_VERSION in constants.mjs, and in the $id of the JSON bundle's schema and its reference to this one, all together. Then regenerate the types with node scripts/generate-json-types.mjs. The tests fail while the versions disagree or the committed types are stale.