{"$schema":"https://doc-kit.nodejs.org/schemas/api-doc/1.0.1.json","id":"generators-json","path":"/generators/json","type":"module","module":"generators-json","title":"JSON","introducedIn":null,"sourceLink":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"The `json` generator writes each source file as a JSON document: a tree of\nits headings, each with its metadata, signature or type, Markdown and code\nexamples, in a format a published JSON schema describes. Use it when a program\nneeds your API as data, such as an editor integration, a linter or a site of\nyour own.\n\nThis page also covers the [JSON bundle](#json-bundle) (`json-all`), which puts\nevery document in one file, and [Debug JSON](#debug-json) (`json-simple`), a\ndump of the API entries for debugging the pipeline.\n\n**Target:** `json` · **Package:** [`@doc-kit/core`](https://doc-kit.nodejs.org/packages/core) · **Reads:** [API entries](https://doc-kit.nodejs.org/generators/metadata) · **Writes:** one `.json` file per source file","summary":"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.","examples":[],"children":[{"kind":"section","id":"usage","name":"Usage","title":"Usage","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"`@doc-kit/core` comes with the CLI, so there's nothing else to install:\n\n```bash\nnpx doc-kit generate -t json -i \"doc/api/**/*.md\" -o out\n```\n\nThe documents keep the input's directory layout, from where the glob starts:\n`doc/api/fs.md` becomes `out/fs.json`, and `doc/api/guides/streams.md` becomes\n`out/guides/streams.json`.","summary":"`@doc-kit/core` comes with the CLI, so there's nothing else to install:","examples":[{"language":"bash","displayName":null,"code":"npx doc-kit generate -t json -i \"doc/api/**/*.md\" -o out"}],"children":[]},{"kind":"section","id":"configuring","name":"Configuring","title":"Configuring","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"Options go in the `json` section of the\n[configuration file](https://doc-kit.nodejs.org/configuration):\n\n```js displayName=\"doc-kit.config.mjs\"\nexport default {\n  global: {\n    repository: 'nodejs/node',\n    ref: 'main',\n  },\n  json: {\n    minify: true,\n  },\n};\n```\n\n* `output` {string} The directory to write the documents to. Without one,\n  nothing is written, and the documents only go to the generators that read\n  them, such as the JSON bundle. **Default:** from `global.output`\n  (`--output`).\n* `minify` {boolean} Write the documents without indentation.\n  **Default:** `false`, from `global.minify` (`--minify`).\n* `repository` {string} The GitHub repository, as `owner/name`, that\n  `sourceLink.url` points into. Without one, `sourceLink.url` is `null`.\n  **Default:** from `global.repository`.\n* `ref` {string} The Git ref `sourceLink.url` points at. **Default:**\n  `'HEAD'`, from `global.ref` (`--git-ref`).\n* `schemaURL` {string} The URL every document carries in `$schema`.\n  `{schemaVersion}` is the schema's version, and other placeholders, such as\n  `{repository}`, take configuration values. **Default:**\n  `'https://doc-kit.nodejs.org/schemas/api-doc/{schemaVersion}.json'`.\n* `markdown` {Object} [Markdown plugins](https://doc-kit.nodejs.org/configuration#markdown-plugins)\n  for this generator, added after the ones in `global.markdown`.\n  * `remarkPlugins` {Array} Plugins for writing descriptions back to Markdown.\n    Only what they add to the serializer applies, such as a handler for a node\n    type: their transforms don't run, since the sources were already parsed.","summary":"Options go in the `json` section of the configuration file:","examples":[{"language":"js","displayName":"doc-kit.config.mjs","code":"export default {\n  global: {\n    repository: 'nodejs/node',\n    ref: 'main',\n  },\n  json: {\n    minify: true,\n  },\n};"}],"children":[]},{"kind":"section","id":"the-document","name":"The document","title":"The document","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"```json displayName=\"out/fs.json\"\n{\n  \"$schema\": \"https://doc-kit.nodejs.org/schemas/api-doc/1.0.1.json\",\n  \"id\": \"fs\",\n  \"path\": \"/fs\",\n  \"type\": \"module\",\n  \"module\": \"fs\",\n  \"title\": \"File system\",\n  \"introducedIn\": \"v0.10.0\",\n  \"sourceLink\": {\n    \"path\": \"lib/fs.js\",\n    \"url\": \"https://github.com/nodejs/node/blob/main/lib/fs.js\"\n  },\n  \"stability\": { \"index\": \"2\", \"description\": \"Stable\" },\n  \"added\": [],\n  \"deprecated\": [],\n  \"removed\": [],\n  \"napiVersion\": [],\n  \"changes\": [],\n  \"description\": \"The `node:fs` module enables interacting with the file system in a\\nway modeled on standard POSIX functions.\\n\\n…\",\n  \"summary\": \"The `node:fs` module enables interacting with the file system in a way modeled on standard POSIX functions.\",\n  \"examples\": [],\n  \"children\": []\n}\n```\n\nA document stands for a source file and its title heading. Besides the\n[fields every entry has](#fields-every-entry-has), it carries these, most from\nthe file's [page metadata](https://doc-kit.nodejs.org/writing-docs#page-metadata):\n\n| Field          | Type             | Holds                                                                                                                      |\n| -------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------- |\n| `$schema`      | `string`         | The URL of the schema the document conforms to, from `schemaURL`. Its last path segment is the schema version.             |\n| `id`           | `string`         | The file's path in the input tree, slugged: `fs`, `guides-streams`.                                                        |\n| `path`         | `string`         | The file's path in the input tree, without extension: `/fs`.                                                               |\n| `type`         | `string`         | The file's `type=` directive: `module` (the default), `misc` or `global`.                                                  |\n| `module`       | `string \\| null` | The `name=` directive. Without one, the `id` of a `module` document, and `null` for the others.                            |\n| `introducedIn` | `string \\| null` | The `introduced_in=` directive.                                                                                            |\n| `sourceLink`   | `object \\| null` | The `source_link=` directive: `path`, as authored, and `url`, the file on GitHub at `ref` (`null` without a `repository`). |\n| `children`     | `Node[]`         | The file's other headings, as [nodes](#nodes) nested by depth, in document order.                                          |","summary":"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:","examples":[{"language":"json","displayName":"out/fs.json","code":"{\n  \"$schema\": \"https://doc-kit.nodejs.org/schemas/api-doc/1.0.1.json\",\n  \"id\": \"fs\",\n  \"path\": \"/fs\",\n  \"type\": \"module\",\n  \"module\": \"fs\",\n  \"title\": \"File system\",\n  \"introducedIn\": \"v0.10.0\",\n  \"sourceLink\": {\n    \"path\": \"lib/fs.js\",\n    \"url\": \"https://github.com/nodejs/node/blob/main/lib/fs.js\"\n  },\n  \"stability\": { \"index\": \"2\", \"description\": \"Stable\" },\n  \"added\": [],\n  \"deprecated\": [],\n  \"removed\": [],\n  \"napiVersion\": [],\n  \"changes\": [],\n  \"description\": \"The `node:fs` module enables interacting with the file system in a\\nway modeled on standard POSIX functions.\\n\\n…\",\n  \"summary\": \"The `node:fs` module enables interacting with the file system in a way modeled on standard POSIX functions.\",\n  \"examples\": [],\n  \"children\": []\n}"}],"children":[{"kind":"section","id":"fields-every-entry-has","name":"Fields every entry has","title":"Fields every entry has","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"The document and every node carry:\n\n| Field                            | Type             | Holds                                                                                                                                                                                                                                                                           |\n| -------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `title`                          | `string`         | The heading text as authored, inline Markdown included.                                                                                                                                                                                                                         |\n| `stability`                      | `object \\| null` | The stability index: `index`, as authored (`\"1.1\"`), and `description`, the Markdown after it.                                                                                                                                                                                  |\n| `added`, `deprecated`, `removed` | `string[]`       | Versions, as authored.                                                                                                                                                                                                                                                          |\n| `napiVersion`                    | `number[]`       | The Node-API versions the entry is available in.                                                                                                                                                                                                                                |\n| `changes`                        | `object[]`       | The change history, one record per change: `versions`, `prUrl`, `commit` and `description`.                                                                                                                                                                                     |\n| `description`                    | `string`         | The body as Markdown (MDX, from MDX sources): everything under the heading except its metadata, its stability index and the typed list a signature or type was taken from. Reference links are inlined, and links to `.md` files point to the `.html` pages, as on the website. |\n| `summary`                        | `string`         | A one-paragraph summary: the `llm_description` when there is one, else the first paragraph on one line, with links reduced to their text.                                                                                                                                       |\n| `examples`                       | `object[]`       | The fenced code blocks of the body, as `language`, `displayName` and `code`. They stay in `description` too.                                                                                                                                                                    |\n\nEvery field is always present: what a source doesn't declare is `null`, an\nempty string or an empty array.","summary":"The document and every node carry:","examples":[],"children":[]}]},{"kind":"section","id":"nodes","name":"Nodes","title":"Nodes","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"A node is a heading below the title. Its `kind` says what the heading\ndocuments\n([how headings are classified](https://doc-kit.nodejs.org/writing-docs#how-headings-are-classified))\nand decides which further fields the node has:\n\n| `kind`         | Heading                                        | Further fields    |\n| -------------- | ---------------------------------------------- | ----------------- |\n| `section`      | Anything else: prose, `DEP0005: …`, `--flag`   | none              |\n| `class`        | `` Class: `net.Server` ``                      | `extends`         |\n| `constructor`  | `` `new Agent([options])` ``                   | `signature`       |\n| `method`       | `` `fs.readFile(path[, options], callback)` `` | `signature`       |\n| `staticMethod` | `` Static method: `Buffer.from(string)` ``     | `signature`       |\n| `property`     | `` `buf.length` ``                             | `type`, `default` |\n| `event`        | `` Event: `'close'` ``                         | `parameters`      |\n\nEvery node also carries:\n\n| Field        | Type             | Holds                                                                                                                             |\n| ------------ | ---------------- | --------------------------------------------------------------------------------------------------------------------------------- |\n| `id`         | `string`         | The heading's slug, unique within the document. It's the heading's anchor on the website.                                         |\n| `name`       | `string`         | The bare identifier: `readFile`, `Server`, `close`. A section's heading text. A `name=` directive under the heading overrides it. |\n| `scope`      | `string`         | `global` for headings typed `global` and in `global` documents, `module` otherwise.                                               |\n| `overloadOf` | `string \\| null` | On the second and later of consecutive sibling headings documenting the same callable, the `id` of the first.                     |\n| `children`   | `Node[]`         | The headings nested under this one.                                                                                               |","summary":"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:","examples":[],"children":[]},{"kind":"section","id":"signatures-and-types","name":"Signatures and types","title":"Signatures and types","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"The further fields come from the heading and the\n[typed list](https://doc-kit.nodejs.org/writing-docs#parameters-return-values-and-defaults)\nunder it:\n\n| Field        | On                                       | Holds                                                                                                                                                                |\n| ------------ | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `signature`  | constructors, methods and static methods | `parameters`, every parameter the heading declares, in order, and `returns`, the `Returns:` item or `null`. A parameter the list doesn't describe has a `null` type. |\n| `extends`    | classes                                  | The type of the `Extends:` item, else the `extends` in the heading (`` Class: `Foo extends Bar` ``), else `null`.                                                    |\n| `type`       | properties                               | The type of the `Type:` item. Its description goes first in the node's `description`.                                                                                |\n| `default`    | properties                               | The default of the `Type:` item.                                                                                                                                     |\n| `parameters` | events                                   | The arguments the listeners receive.                                                                                                                                 |\n\nA parameter has a `name`, without `...`, a `type`, a `description`, and:\n\n* `default`: the value as authored, without its code span, or `null`.\n* `optional`: `true` when the parameter is bracketed in the heading or has a\n  default.\n* `rest`: `true` when it's declared as `...args`.\n* `properties`: its nested items, such as the properties of an options object\n  or the arguments of a callback, each a parameter too.\n\nA type has `text`, the annotation as a TypeScript type on one line, with `|`\nbetween union members, and `links`, the names in it that resolved to\ndocumentation, with their offsets in `text`. Names resolve through the\n[type map](https://doc-kit.nodejs.org/generators/metadata#type-links), then the\nbuilt-in ones; a dotted name no map has, such as `fs.Stats`, links to its\nmodule's page (`fs.html#class-fsstats`). A type the source doesn't document is\n`null`, never guessed.\n\nFor example, this method:\n\n```markdown displayName=\"doc/api/fs.md\"\n## `fsPromises.readFile(path[, options])`\n\n- `path` {string|URL} The file to read.\n- `options` {Object}\n  - `encoding` {string|null} **Default:** `null`.\n- Returns: {Promise} Fulfills with the contents of the file.\n\nReads the entire contents of a file.\n```\n\nhas `Reads the entire contents of a file.` as its `description`, and this\n`signature` (each type's `links` shortened to `[]`):\n\n```json\n{\n  \"parameters\": [\n    {\n      \"name\": \"path\",\n      \"type\": { \"text\": \"string | URL\", \"links\": [] },\n      \"description\": \"The file to read.\",\n      \"default\": null,\n      \"optional\": false,\n      \"rest\": false,\n      \"properties\": []\n    },\n    {\n      \"name\": \"options\",\n      \"type\": { \"text\": \"Object\", \"links\": [] },\n      \"description\": \"\",\n      \"default\": null,\n      \"optional\": true,\n      \"rest\": false,\n      \"properties\": [\n        {\n          \"name\": \"encoding\",\n          \"type\": { \"text\": \"string | null\", \"links\": [] },\n          \"description\": \"\",\n          \"default\": \"null\",\n          \"optional\": true,\n          \"rest\": false,\n          \"properties\": []\n        }\n      ]\n    }\n  ],\n  \"returns\": {\n    \"type\": { \"text\": \"Promise\", \"links\": [] },\n    \"description\": \"Fulfills with the contents of the file.\"\n  }\n}\n```\n\nEach `links` array lists its type's names with where they point and their\noffsets, such as\n`{ \"name\": \"URL\", \"href\": \"https://developer.mozilla.org/docs/Web/API/URL\", \"start\": 9, \"end\": 12 }`\nfor `URL` in `string | URL`.","summary":"The further fields come from the heading and the typed list under it:","examples":[{"language":"markdown","displayName":"doc/api/fs.md","code":"## `fsPromises.readFile(path[, options])`\n\n- `path` {string|URL} The file to read.\n- `options` {Object}\n  - `encoding` {string|null} **Default:** `null`.\n- Returns: {Promise} Fulfills with the contents of the file.\n\nReads the entire contents of a file."},{"language":"json","displayName":null,"code":"{\n  \"parameters\": [\n    {\n      \"name\": \"path\",\n      \"type\": { \"text\": \"string | URL\", \"links\": [] },\n      \"description\": \"The file to read.\",\n      \"default\": null,\n      \"optional\": false,\n      \"rest\": false,\n      \"properties\": []\n    },\n    {\n      \"name\": \"options\",\n      \"type\": { \"text\": \"Object\", \"links\": [] },\n      \"description\": \"\",\n      \"default\": null,\n      \"optional\": true,\n      \"rest\": false,\n      \"properties\": [\n        {\n          \"name\": \"encoding\",\n          \"type\": { \"text\": \"string | null\", \"links\": [] },\n          \"description\": \"\",\n          \"default\": \"null\",\n          \"optional\": true,\n          \"rest\": false,\n          \"properties\": []\n        }\n      ]\n    }\n  ],\n  \"returns\": {\n    \"type\": { \"text\": \"Promise\", \"links\": [] },\n    \"description\": \"Fulfills with the contents of the file.\"\n  }\n}"}],"children":[]},{"kind":"section","id":"using-the-schema","name":"Using the schema","title":"Using the schema","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"Every document's `$schema` points to the version of the schema it conforms to,\nsuch as `https://doc-kit.nodejs.org/schemas/api-doc/1.0.1.json`. The schema\nalso ships in `@doc-kit/core` as `@doc-kit/core/generators/json/schema.json`,\nwith TypeScript types generated from it:\n\n```ts displayName=\"list-methods.ts\"\nimport { readFile } from 'node:fs/promises';\n\nimport type {\n  Document,\n  Node,\n} from '@doc-kit/core/generators/json/generated/schema';\n\nconst fs: Document = JSON.parse(await readFile('out/fs.json', 'utf-8'));\n\nconst listMethods = (nodes: Array<Node>): void => {\n  for (const node of nodes) {\n    if (node.kind === 'method') {\n      console.log(\n        node.name,\n        node.signature.parameters.map(p => p.name)\n      );\n    }\n\n    listMethods(node.children);\n  }\n};\n\nlistMethods(fs.children);\n```","summary":"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:","examples":[{"language":"ts","displayName":"list-methods.ts","code":"import { readFile } from 'node:fs/promises';\n\nimport type {\n  Document,\n  Node,\n} from '@doc-kit/core/generators/json/generated/schema';\n\nconst fs: Document = JSON.parse(await readFile('out/fs.json', 'utf-8'));\n\nconst listMethods = (nodes: Array<Node>): void => {\n  for (const node of nodes) {\n    if (node.kind === 'method') {\n      console.log(\n        node.name,\n        node.signature.parameters.map(p => p.name)\n      );\n    }\n\n    listMethods(node.children);\n  }\n};\n\nlistMethods(fs.children);"}],"children":[{"kind":"section","id":"changing-the-schema","name":"Changing the schema","title":"Changing the schema","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"For doc-kit contributors: `schema.json` is the source of truth for the format.\nWhen you change it, bump the version in its `$id`, in `SCHEMA_VERSION` in\n`constants.mjs`, and in the `$id` of the JSON bundle's schema and its\nreference to this one, all together. Then regenerate the types with\n`node scripts/generate-json-types.mjs`. The tests fail while the versions\ndisagree or the committed types are stale.","summary":"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.","examples":[],"children":[]}]},{"kind":"section","id":"json-bundle","name":"JSON bundle","title":"JSON bundle","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"The `json-all` generator writes every `json` document into a single\n`all.json`, for tools that would rather load your whole API from one file.\n\n**Target:** `json-all` · **Package:** [`@doc-kit/core`](https://doc-kit.nodejs.org/packages/core) · **Reads:** `json` · **Writes:** `all.json`","summary":"The `json-all` generator writes every `json` document into a single `all.json`, for tools that would rather load your whole API from one file.","examples":[],"children":[{"kind":"section","id":"using-the-bundle","name":"Using the bundle","title":"Using the bundle","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"```bash\nnpx doc-kit generate -t json-all -i \"docs/**/*.md\" -o out\n```\n\nThis writes `out/all.json`. `json` runs first without being listed, and writes\nits own files to the same directory, such as `out/getting-started.json`. To\nleave those out, see [Writing only the bundle](#writing-only-the-bundle).","summary":"This writes `out/all.json`. `json` runs first without being listed, and writes its own files to the same directory, such as `out/getting-started.json`. To leave those out, see Writing only the bundle.","examples":[{"language":"bash","displayName":null,"code":"npx doc-kit generate -t json-all -i \"docs/**/*.md\" -o out"}],"children":[]},{"kind":"section","id":"configuring-the-bundle","name":"Configuring the bundle","title":"Configuring the bundle","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"Options go in the `json-all` section of the configuration file:\n\n```js displayName=\"doc-kit.config.mjs\"\nexport default {\n  'json-all': {\n    minify: true,\n  },\n};\n```\n\n* `output` {string} The directory to write `all.json` to. Without one,\n  nothing is written. **Default:** from `global.output` (`--output`).\n* `minify` {boolean} Write the bundle on one line, without indentation.\n  **Default:** `false`, from `global.minify` (`--minify`).\n* `index` {string | Array} The path or URL of an `index.md` whose links set the\n  order of the documents, or the parsed list of `{ section, api }` objects.\n  See [Document order](#document-order). **Default:** from `global.index`\n  (`--index`).\n* `schemaURL` {string} URL template for the bundle's `$schema`.\n  `{schemaVersion}` is the schema's version, and other placeholders, such as\n  `{project}`, take configuration values. The documents inside keep the\n  `$schema` from `json.schemaURL`. **Default:**\n  `'https://doc-kit.nodejs.org/schemas/api-doc-all/{schemaVersion}.json'`.","summary":"Options go in the `json-all` section of the configuration file:","examples":[{"language":"js","displayName":"doc-kit.config.mjs","code":"export default {\n  'json-all': {\n    minify: true,\n  },\n};"}],"children":[]},{"kind":"section","id":"what-the-bundle-holds","name":"What the bundle holds","title":"What the bundle holds","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"```json displayName=\"out/all.json\"\n{\n  \"$schema\": \"https://doc-kit.nodejs.org/schemas/api-doc-all/1.0.1.json\",\n  \"documents\": [\n    {\n      \"$schema\": \"https://doc-kit.nodejs.org/schemas/api-doc/1.0.1.json\",\n      \"id\": \"getting-started\",\n      \"path\": \"/getting-started\",\n      \"type\": \"module\",\n      \"module\": \"getting-started\",\n      \"title\": \"Getting started\",\n      \"introducedIn\": null,\n      \"sourceLink\": null,\n      \"stability\": null,\n      \"added\": [],\n      \"deprecated\": [],\n      \"removed\": [],\n      \"napiVersion\": [],\n      \"changes\": [],\n      \"description\": \"Install the package, then run it.\",\n      \"summary\": \"Install the package, then run it.\",\n      \"examples\": [],\n      \"children\": []\n    }\n  ]\n}\n```\n\n* `$schema` {string} The URL of the schema the bundle conforms to, from\n  `schemaURL`. With the default, its file name is the schema version.\n* `documents` {Array} Every `json` document, exactly as `json` writes it to its\n  own file (see [The document](#the-document)), in the\n  [document order](#document-order).\n\nThe bundle's schema ships as `@doc-kit/core/generators/json-all/schema.json`\nand is published at the default `$schema` URL. For the documents, it refers to\nthe `json` schema of the same version.","summary":"The bundle's schema ships as `@doc-kit/core/generators/json-all/schema.json` and is published at the default `$schema` URL. For the documents, it refers to the `json` schema of the same version.","examples":[{"language":"json","displayName":"out/all.json","code":"{\n  \"$schema\": \"https://doc-kit.nodejs.org/schemas/api-doc-all/1.0.1.json\",\n  \"documents\": [\n    {\n      \"$schema\": \"https://doc-kit.nodejs.org/schemas/api-doc/1.0.1.json\",\n      \"id\": \"getting-started\",\n      \"path\": \"/getting-started\",\n      \"type\": \"module\",\n      \"module\": \"getting-started\",\n      \"title\": \"Getting started\",\n      \"introducedIn\": null,\n      \"sourceLink\": null,\n      \"stability\": null,\n      \"added\": [],\n      \"deprecated\": [],\n      \"removed\": [],\n      \"napiVersion\": [],\n      \"changes\": [],\n      \"description\": \"Install the package, then run it.\",\n      \"summary\": \"Install the package, then run it.\",\n      \"examples\": [],\n      \"children\": []\n    }\n  ]\n}"}],"children":[]},{"kind":"section","id":"document-order","name":"Document order","title":"Document order","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"Without an index, the documents are sorted by `id`. To choose the order, pass\nan `index.md` with `--index`:\n\n```bash\nnpx doc-kit generate -t json-all -i \"docs/**/*.md\" -o out --index docs/index.md\n```\n\nThe documents its links point to come first, in the order of the links, and\nthe rest follow by `id`:\n\n```text displayName=\"docs/index.md\"\n# My library\n\n* [Getting started](getting-started.md)\n* [Configuration](configuration.md)\n```\n\n* Only list items written with an asterisk, `* [Title](file.md)`, count.\n  `- [Title](file.md)` is skipped.\n* A link places the document whose `id` is the link's target without `.md`:\n  `getting-started.md` matches the document of `docs/getting-started.md`.\n* A file in a subdirectory, such as `docs/guide/intro.md`, has the `id`\n  `guide-intro`. A link to `guide/intro.md` doesn't match it, so it's ordered\n  with the rest.\n* Links to files that aren't in your input are ignored.\n* `index.md` is a document too when your input matches it, ordered with the\n  rest. Leave it out with `--ignore docs/index.md`.","summary":"Without an index, the documents are sorted by `id`. To choose the order, pass an `index.md` with `--index`:","examples":[{"language":"bash","displayName":null,"code":"npx doc-kit generate -t json-all -i \"docs/**/*.md\" -o out --index docs/index.md"},{"language":"text","displayName":"docs/index.md","code":"# My library\n\n* [Getting started](getting-started.md)\n* [Configuration](configuration.md)"}],"children":[]},{"kind":"section","id":"writing-only-the-bundle","name":"Writing only the bundle","title":"Writing only the bundle","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"`json` writes its documents to its own `output`, which is `global.output`\nunless you set one under `json`. To write `all.json` alone, set it to `null`;\n`-o out` still sets where the bundle goes:\n\n```js displayName=\"doc-kit.config.mjs\"\nexport default {\n  json: {\n    output: null,\n  },\n};\n```\n\n> \\[!NOTE]\n> A source file named `all.md` at the top of your input becomes `all.json` as\n> well, and the bundle overwrites it. To keep both, give the bundle a directory\n> of its own with `json-all.output`, such as `'out/bundle'`.","summary":"`json` writes its documents to its own `output`, which is `global.output` unless you set one under `json`. To write `all.json` alone, set it to `null`; `-o out` still sets where the bundle goes:","examples":[{"language":"js","displayName":"doc-kit.config.mjs","code":"export default {\n  json: {\n    output: null,\n  },\n};"}],"children":[]}]},{"kind":"section","id":"debug-json","name":"Debug JSON","title":"Debug JSON","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"The `json-simple` generator dumps the API entries doc-kit parsed from your\nsources into one JSON file. Almost every other generator reads these entries,\nso when an output looks wrong, this file tells you whether the entry itself is\nwrong or the generator that rendered it.\n\n**Target:** `json-simple` · **Package:** [`@doc-kit/core`](https://doc-kit.nodejs.org/packages/core) · **Reads:** [API entries](https://doc-kit.nodejs.org/generators/metadata) · **Writes:** `api-docs.json`","summary":"The `json-simple` generator dumps the API entries doc-kit parsed from your sources into one JSON file. Almost every other generator reads these entries, so when an output looks wrong, this file tells you whether the entry itself is wrong or the generator that rendered it.","examples":[],"children":[{"kind":"section","id":"using-the-dump","name":"Using the dump","title":"Using the dump","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"```bash\nnpx doc-kit generate -t json-simple -i \"docs/**/*.md\" -o out\n```\n\nThis writes `out/api-docs.json`. To see what another output is built from, run\n`json-simple` on its own, with the same inputs as that output.\n\n> \\[!WARNING]\n> Don't add `json-simple` to a run that builds other targets. It removes the\n> heading and the stability index from each entry's `content` in place, and\n> every target in the run reads those same entries, so their output comes out\n> wrong: the website, for example, loses all of its headings and stability\n> indexes.","summary":"This writes `out/api-docs.json`. To see what another output is built from, run `json-simple` on its own, with the same inputs as that output.","examples":[{"language":"bash","displayName":null,"code":"npx doc-kit generate -t json-simple -i \"docs/**/*.md\" -o out"}],"children":[]},{"kind":"section","id":"configuring-the-dump","name":"Configuring the dump","title":"Configuring the dump","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"`json-simple` has no options of its own. It reads these global options, which\nyou can also set in a `json-simple` section to apply to it alone:\n\n* `output` {string} The directory to write `api-docs.json` to. Without one,\n  nothing is written. **Default:** from `global.output` (`--output`).\n* `minify` {boolean} Write the JSON on a single line instead of indented.\n  **Default:** `false`, from `global.minify` (`--minify`).\n\nTo dump the entries behind a configured site without writing into the\ndirectory you publish, give the dump its own `output`, then build the site and\nthe dump in separate runs. A `-t` on the command line replaces the file's\n`target`, so the second run reads the same inputs and builds only the dump:\n\n```mjs displayName=\"doc-kit.config.mjs\"\nexport default {\n  target: ['html'],\n  global: {\n    input: ['docs/**/*.md'],\n    output: 'out',\n  },\n  'json-simple': {\n    output: 'debug',\n  },\n};\n```\n\n```bash\nnpx doc-kit generate                 # builds the site into out/\nnpx doc-kit generate -t json-simple  # writes debug/api-docs.json\n```","summary":"`json-simple` has no options of its own. It reads these global options, which you can also set in a `json-simple` section to apply to it alone:","examples":[{"language":"mjs","displayName":"doc-kit.config.mjs","code":"export default {\n  target: ['html'],\n  global: {\n    input: ['docs/**/*.md'],\n    output: 'out',\n  },\n  'json-simple': {\n    output: 'debug',\n  },\n};"},{"language":"bash","displayName":null,"code":"npx doc-kit generate                 # builds the site into out/\nnpx doc-kit generate -t json-simple  # writes debug/api-docs.json"}],"children":[]},{"kind":"section","id":"what-the-dump-holds","name":"What the dump holds","title":"What the dump holds","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"An array of [API entries](https://doc-kit.nodejs.org/generators/metadata), one\nfor each heading in your sources, as the `metadata` stage built them, except\nthat each entry's `content` no longer contains its heading or its stability\nindex, since `heading` and `stability` already hold them. Here is the entry for\nan `fs.readFile()` heading, with every node's `position` and the body's nodes\nleft out:\n\n```json\n{\n  \"api\": \"fs\",\n  \"path\": \"/fs\",\n  \"mdx\": false,\n  \"basename\": \"fs\",\n  \"heading\": {\n    \"type\": \"heading\",\n    \"depth\": 2,\n    \"children\": [\n      {\n        \"type\": \"inlineCode\",\n        \"value\": \"fs.readFile(path[, options], callback)\"\n      }\n    ],\n    \"data\": {\n      \"text\": \"`fs.readFile(path[, options], callback)`\",\n      \"type\": \"method\",\n      \"name\": \"readFile\",\n      \"slug\": \"fsreadfilepath-options-callback\"\n    }\n  },\n  \"added\": \"v0.1.29\",\n  \"content\": { \"type\": \"root\", \"children\": [] }\n}\n```\n\n[What an entry holds](https://doc-kit.nodejs.org/generators/metadata#what-an-entry-holds)\ndescribes every field. Nodes keep their `position` (line, column and offset in\nthe source file), which traces a node back to the Markdown it came from, and\nmakes the file large.\n\n> \\[!WARNING]\n> `api-docs.json` is not a stable format. It has no schema and mirrors\n> doc-kit's internal entries, so its shape changes whenever the pipeline does.\n> To build tools on your API data, use the `json` generator, whose output a\n> versioned schema describes.","summary":"An array of API entries, one for each heading in your sources, as the `metadata` stage built them, except that each entry's `content` no longer contains its heading or its stability index, since `heading` and `stability` already hold them. Here is the entry for an `fs.readFile()` heading, with every node's `position` and the body's nodes left out:","examples":[{"language":"json","displayName":null,"code":"{\n  \"api\": \"fs\",\n  \"path\": \"/fs\",\n  \"mdx\": false,\n  \"basename\": \"fs\",\n  \"heading\": {\n    \"type\": \"heading\",\n    \"depth\": 2,\n    \"children\": [\n      {\n        \"type\": \"inlineCode\",\n        \"value\": \"fs.readFile(path[, options], callback)\"\n      }\n    ],\n    \"data\": {\n      \"text\": \"`fs.readFile(path[, options], callback)`\",\n      \"type\": \"method\",\n      \"name\": \"readFile\",\n      \"slug\": \"fsreadfilepath-options-callback\"\n    }\n  },\n  \"added\": \"v0.1.29\",\n  \"content\": { \"type\": \"root\", \"children\": [] }\n}"}],"children":[]}]}]}