{"$schema":"https://doc-kit.nodejs.org/schemas/api-doc/1.0.1.json","id":"generators-metadata","path":"/generators/metadata","type":"module","module":"generators-metadata","title":"API entries","introducedIn":null,"sourceLink":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"The `metadata` stage turns your parsed Markdown into a flat list of API\nentries, one per heading, each with its kind, stability, history and linked\ntypes. Every output except `api-links` is built from these entries, and\nthey're what a generator of your own usually reads.\n\n**Stage:** `metadata` · **Package:** [`@doc-kit/core`](https://doc-kit.nodejs.org/packages/core) · **Reads:** [Parsing Markdown](https://doc-kit.nodejs.org/generators/ast) · **Writes:** no files","summary":"The `metadata` stage turns your parsed Markdown into a flat list of API entries, one per heading, each with its kind, stability, history and linked types. Every output except `api-links` is built from these entries, and they're what a generator of your own usually reads.","examples":[],"children":[{"kind":"section","id":"usage","name":"Usage","title":"Usage","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"You don't ask for this stage: any target that reads API entries runs it, once\nper run. The one thing to give it is a type map, so the types your docs\nmention link to the pages documenting them:\n\n```bash\nnpx doc-kit generate -t html -i \"docs/**/*.md\" -o out --type-map docs/type-map.json\n```\n\nTo look at the entries themselves, run the\n[Debug JSON](https://doc-kit.nodejs.org/generators/json#debug-json) target,\nwhich writes them to `api-docs.json`.","summary":"You don't ask for this stage: any target that reads API entries runs it, once per run. The one thing to give it is a type map, so the types your docs mention link to the pages documenting them:","examples":[{"language":"bash","displayName":null,"code":"npx doc-kit generate -t html -i \"docs/**/*.md\" -o out --type-map docs/type-map.json"}],"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 `metadata` section of the\n[configuration file](https://doc-kit.nodejs.org/configuration):\n\n```js displayName=\"doc-kit.config.mjs\"\nexport default {\n metadata: {\n typeMap: 'docs/type-map.json',\n },\n};\n```\n\n* `typeMap` {string} The path or URL of a JSON file mapping type names to the\n pages documenting them, relative to the working directory. `--type-map`\n sets it too. Without one, only JavaScript built-ins, web APIs and dotted\n names such as `vm.Module` get links. See [Type links](#type-links).\n* `markdown` {Object} [Markdown plugins](https://doc-kit.nodejs.org/configuration#markdown-plugins)\n for this stage, added after the ones in `global.markdown`.\n * `remarkPlugins` {Array} Plugins for parsing the Markdown the stage\n writes itself, such as the links for man page references. Only their\n syntax extensions apply.\n\nThe stage works in chunks of `chunkSize` files across `threads` worker threads\n(see [Execution options](https://doc-kit.nodejs.org/configuration#execution-options)).","summary":"Options go in the `metadata` section of the configuration file:","examples":[{"language":"js","displayName":"doc-kit.config.mjs","code":"export default {\n metadata: {\n typeMap: 'docs/type-map.json',\n },\n};"}],"children":[]},{"kind":"section","id":"what-an-entry-holds","name":"What an entry holds","title":"What an entry holds","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"Each heading of level 1 to 5 starts an entry, which runs until the next such\nheading, whatever its level. Unlike an entry in the\n[specification](https://doc-kit.nodejs.org/specification#12-definitions), it\ndoesn't hold the entries below it: outputs rebuild the hierarchy from the\nheading levels. Anything before a file's first heading belongs to its\nfirst entry, and a file without headings gets one entry, under an empty\nlevel-1 heading that isn't rendered.\n\nEvery entry has these fields:\n\n| Field | Type | Holds |\n| ----------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------- |\n| `api` | `string` | The file's identifier, made from its path: `/guide/widgets` becomes `guide-widgets`. Every entry of a file shares it. |\n| `path` | `string` | The file's path without its extension, from the directory its `input` glob starts at: `docs/guide/widgets.md` is `/guide/widgets`. |\n| `basename` | `string` | The last segment of `path`, such as `widgets`. |\n| `mdx` | `boolean` | Whether the file was parsed as MDX. |\n| `heading` | `Object` | The heading, as an mdast `heading` node. Its `depth` is its level, and its `data` holds the fields below. |\n| `stability` | `Object` | The section's stability index, as its blockquote node, when it has one. Its `data` holds the fields below. |\n| `content` | `Object` | The section as an mdast `root` node: the heading, then everything up to the next entry, without its metadata comments. |\n\nThe `data` of `heading` and `stability` holds:\n\n| Field | Holds |\n| ---------------------------- | ------------------------------------------------------------------------------------- |\n| `heading.data.text` | The heading's text, code spans included, such as `` `widget.spin(speed)` ``. |\n| `heading.data.name` | The name of the API it documents, such as `spin`, or its text when it documents none. |\n| `heading.data.slug` | Its anchor, such as `widgetspinspeed`. |\n| `heading.data.type` | Its [kind](#heading-kinds), when it has one. |\n| `stability.data.index` | The level, such as `'2'` or `'1.1'`. |\n| `stability.data.description` | The text after the level, on one line, such as `'Stable'`. |\n\nThe keys of the section's [metadata comments](#stability-and-metadata) are\nfields of the entry too. These are the ones doc-kit's outputs use:\n\n| Field | Type | Holds |\n| -------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------- |\n| `added`, `deprecated`, `removed` | `string\\|string[]` | The version or versions the API was added, deprecated or removed in. |\n| `changes` | `Object[]` | Its history, each change with `version` (`string\\|string[]`), `pr-url` and `description` (Markdown). |\n| `introduced_in` | `string` | The version the page's module was introduced in. |\n| `napiVersion` | `string` | The Node-API version the API needs. |\n| `source_link` | `string` | The path of the API's source file. |\n| `llm_description` | `string` | A plain-text summary, which outputs such as `llms.txt` and the JSON use instead of the first paragraph. |\n| `type` | `string` | A kind that replaces the heading's. |\n| `tags` | `string[]` | The text of the section's plain comments. |\n\nLater stages add a few fields of their own: `synthetic` and `chunk` on pages\nthey create, and `isOverload` and `overloadOf` on the headings of overloaded\nfunctions. The `MetadataEntry` type in\n[`types.d.ts`](https://github.com/nodejs/doc-kit/blob/main/packages/core/src/generators/metadata/types.d.ts)\ndescribes the whole shape; a generator imports it from\n`@doc-kit/core/generators/metadata/types`.","summary":"Each heading of level 1 to 5 starts an entry, which runs until the next such heading, whatever its level. Unlike an entry in the specification, it doesn't hold the entries below it: outputs rebuild the hierarchy from the heading levels. Anything before a file's first heading belongs to its first entry, and a file without headings gets one entry, under an empty level-1 heading that isn't rendered.","examples":[],"children":[]},{"kind":"section","id":"heading-kinds","name":"Heading kinds","title":"Heading kinds","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"A heading documents an API when its text matches one of these patterns,\nignoring case. The pattern sets the heading's `type`, and its `name` comes\nfrom the code span:\n\n| Heading | `type` | `name` |\n| ---------------------------------------------- | ------------- | ---------- |\n| `` `fs.readFile(path[, options], callback)` `` | `method` | `readFile` |\n| `` Event: `'close'` `` | `event` | `close` |\n| `` Class: `Widget` `` | `class` | `Widget` |\n| `` `new Widget([options])` `` | `ctor` | `Widget` |\n| `` Static method: `Widget.from(value)` `` | `classMethod` | `from` |\n| `` `widget.size` `` | `property` | `size` |\n\nAny other heading, such as `Getting started`, is an entry without a `type`,\nnamed after its text, so guides and prose sections reach every output like the\nAPI reference does. A `type` key in the section's metadata replaces the kind:\nthis is how `` makes a Node.js page's first heading a\n`module`, and how an entry becomes a `global`.\n\nSlugs follow GitHub's rules, with a few changes that match the anchors of the\nNode.js docs, and are unique within a file: a second `Options` heading gets\n`options-1`. A heading that starts with a deprecation code, such as\n`DEP0005: Buffer() constructor`, takes the code as its slug.","summary":"A heading documents an API when its text matches one of these patterns, ignoring case. The pattern sets the heading's `type`, and its `name` comes from the code span:","examples":[],"children":[]},{"kind":"section","id":"stability-and-metadata","name":"Stability and metadata","title":"Stability and metadata","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"A blockquote that starts with a stability level, such as\n`> [Stability: 1](documentation.html#stability-index) - Experimental`, sets the entry's `stability`. The exception is\n`documentation.md` at the root of the input, where Node.js defines the levels:\nits stability blockquotes aren't attached to entries.\n\nMetadata lives in HTML comments in the section, which are taken out of its\ncontent:\n\n```markdown\n## `widget.spin(speed)`\n\n\n```\n\n* A comment that starts with `YAML` holds YAML, whose keys become the entry's\n fields.\n* A one-line comment is read as YAML too, and `key=value` works in it for\n `introduced_in`, `source_link`, `type`, `name` and `llm_description`, as in\n ``. Plain text, such as ``, adds\n that text to `tags`.\n* Front matter at the top of a file counts as YAML for its first entry.\n* When a section has several comments, lists such as `changes` and `tags` add\n up, and other keys take the last value.\n\n[Writing documentation](https://doc-kit.nodejs.org/writing-docs#recording-history)\nshows how to write them, and the\n[Markdown specification](https://doc-kit.nodejs.org/specification) defines the\nfull syntax of headings, stability indexes and metadata.","summary":"A blockquote that starts with a stability level, such as `> [Stability: 1](documentation.html#stability-index) - Experimental`, sets the entry's `stability`. The exception is `documentation.md` at the root of the input, where Node.js defines the levels: its stability blockquotes aren't attached to entries.","examples":[{"language":"markdown","displayName":null,"code":"## `widget.spin(speed)`\n\n"}],"children":[]},{"kind":"section","id":"type-links","name":"Type links","title":"Type links","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"Each type annotation, a type in braces such as `{string}`, gets links to the\ndocs of the types it names. doc-kit first looks the whole annotation up, so the\nkeys of your type map can be display names such as `Widget options`. Otherwise,\neach name in the type resolves through the first of these that knows it:\n\n1. Your type map, by exact name.\n2. JavaScript's built-in types and objects, ignoring case.\n3. Web APIs documented on MDN, ignoring case.\n4. A dotted name, linked the way the Node.js docs are laid out: `vm.Module`\n links to `vm.html#class-vmmodule`, and `fs.readFile` to\n `fs.html#fsreadfile`.\n\nA name nothing resolves stays plain, which isn't an error. An annotation that\nisn't valid TypeScript is split on `|` and each part looked up on its own; when\nnone resolves, doc-kit warns `Invalid type annotation` with its location.\nAnnotations in MDX files aren't resolved, since braces there hold JavaScript.\n\nA type map is a JSON object of names and links (see\n[The type map](https://doc-kit.nodejs.org/writing-docs#the-type-map) for when\nto write one):\n\n```json displayName=\"docs/type-map.json\"\n{\n \"Widget\": \"api/widget.html\",\n \"Widget options\": \"api/widget.html#options\",\n \"Buffer\": \"https://nodejs.org/api/buffer.html#class-buffer\"\n}\n```\n\nA full URL, such as the one for `Buffer`, is used as it is. Any other link is a\npath from the root of your input, which doc-kit makes relative to each page: on\n`/guide/start`, `Widget` links to `../api/widget.html`. The\n[TypeDoc plugin](https://doc-kit.nodejs.org/packages/typedoc) writes a type map\nfor the types it documents, and Node.js keeps\n[its own](https://github.com/nodejs/node/blob/main/doc/type-map.json).\n\nIn `content`, each annotation is a `typeAnnotation` node, whose `data.links`\nlists the linked ranges of its `value` as `start`, `end`, `text` and `href`.","summary":"Each type annotation, a type in braces such as `{string}`, gets links to the docs of the types it names. doc-kit first looks the whole annotation up, so the keys of your type map can be display names such as `Widget options`. Otherwise, each name in the type resolves through the first of these that knows it:","examples":[{"language":"json","displayName":"docs/type-map.json","code":"{\n \"Widget\": \"api/widget.html\",\n \"Widget options\": \"api/widget.html#options\",\n \"Buffer\": \"https://nodejs.org/api/buffer.html#class-buffer\"\n}"}],"children":[]},{"kind":"section","id":"other-changes-to-the-content","name":"Other changes to the content","title":"Other changes to the content","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"The stage also tidies each section's Markdown for the outputs:\n\n* Reference-style links become plain links, and their definitions are removed.\n* Links to `.md` files point to `.html` files instead, so `./fs.md#options`\n becomes `./fs.html#options`. Links with a scheme are left alone.\n* A man page reference in prose, outside code spans, such as `open(2)`, links\n to its page on man7.org.","summary":"The stage also tidies each section's Markdown for the outputs:","examples":[],"children":[]},{"kind":"section","id":"what-it-produces","name":"What it produces","title":"What it produces","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"A generator reads the entries by declaring\n`dependsOn: '@doc-kit/core/metadata'`, as\n[Creating generators](https://doc-kit.nodejs.org/creating-generators#input-and-output)\nshows. It receives every entry in one array. Each file's entries stay together,\nin document order, but files arrive in the order their chunks finish, not the\norder of `input`.","summary":"A generator reads the entries by declaring `dependsOn: '@doc-kit/core/metadata'`, as Creating generators shows. It receives every entry in one array. Each file's entries stay together, in document order, but files arrive in the order their chunks finish, not the order of `input`.","examples":[],"children":[]}]}