json Generator

The json generator writes one JSON document per source file. Each document is a tree of the file's headings, in document order, with the metadata, signature or type, Markdown body, and code examples of every one of them.

The output is described by a JSON schema, published at the URL every document carries in $schema, and shipped with the package as @doc-kit/core/generators/json/schema.json.

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

Files keep the input's directory layout: doc/api/some/fs.md becomes out/some/fs.json.

{
  "$schema": "https://doc-kit.nodejs.org/schemas/api-doc/1.0.0.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": []
}

• id is the file's path, slugged; path is that path without extension. Cross-document links in Markdown target <path>.html.
• type is the file's type= directive: module (the default), misc, or global. module is the module's name, from the name= directive.
• introducedIn and sourceLink are the introduced_in= and source_link= directives.
• Everything from title on is what every heading carries, described below.
• children are the file's headings, nested by depth.

The document and every node carry:

• title The heading text as authored, inline Markdown included.
• stability The stability index, or null: { index, description }, where index is the text as authored ("1.1") and description the Markdown after it.
• added, deprecated, removed Arrays of version strings, as authored.
• napiVersion An array of numbers.
• changes The change history: { versions, prUrl, commit, description }.
• description The body as Markdown: everything under the heading except its metadata, its stability index, and the typed list a signature or type was taken from. Links are rewritten as they are for HTML output.
• summary A plain-text paragraph: the llm_description when there is one, else the first paragraph.
• examples The fenced code blocks of the body, { language, displayName, code }. They stay in the description too.

Every key is always present. What is missing is null or an empty array.

A node is a heading below the title. Its kind says what the heading documents, and decides which further properties it has:

Every node also has:

• id The heading's slug, and its anchor in HTML output.
• name The bare identifier: readFile, Server, close. A section's plain heading text. A name= directive overrides it.
• scope module, or global for entries typed global.
• overloadOf When several sibling headings document one callable, the id of the first on the second and later ones; otherwise null.
• children The headings nested under it.

"signature": {
  "parameters": [
    {
      "name": "options",
      "type": { "text": "Object | string", "links": [{ "name": "Object", "href": "https://developer.mozilla.org/…", "start": 0, "end": 6 }] },
      "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 upon success." }
}

• A signature's parameters are the ones the heading declares, described by the typed list under it. optional is set for parameters bracketed in the heading or documented with a default; rest for ...args. properties are the nested list items: the properties of an options object, or the arguments of a callback.
• returns is the Returns: item, or null.
• A Type is the annotation's TypeScript text, normalised to one line with | between union members, plus the names in it that resolved to documentation, with their character offsets. A type that was not documented is null, never guessed.
• An event's parameters are the arguments its listeners receive.

schema.json is the source of truth. After changing it, bump its $id and SCHEMA_VERSION in constants.mjs together, and regenerate the types:

node scripts/generate-json-types.mjs