API entries

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.

You don't ask for this stage: any target that reads API entries runs it, once per run. To look at the entries themselves, run the Debug JSON target.

Configuring

Attributes

typeMap:string

The path or URL of a JSON file mapping type names to the pages documenting them. --type-map sets it too. See Types that link themselves and The type map.

What an entry holds

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.

Field	Type	Holds
`api`	`string`	The file's identifier, made from its path: `/guide/widgets` becomes `guide-widgets`. Every entry of a file shares it.
`path`	`string`	The file's path without its extension, from the directory its `input` glob starts at: `docs/guide/widgets.md` is `/guide/widgets`.
`basename`	`string`	The last segment of `path`, such as `widgets`.
`mdx`	`boolean`	Whether the file was parsed as MDX.
`heading`	`Object`	The heading, as an mdast `heading` node. Its `data` holds its `text`, `name`, `slug` and kind (`type`).
`stability`	`Object`	The section's stability index, as its blockquote node, when it has one. Its `data` holds `index` and `description`.
`content`	`Object`	The section as an mdast `root` node: the heading, then everything up to the next entry, without its metadata comments.

The keys of the section's metadata comments, such as added, changes and llm_description, are fields of the entry too. The MetadataEntry type in types.d.ts describes the whole shape; a generator imports it from @doc-kit/core/generators/metadata/types.

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.