{"$schema":"https://doc-kit.nodejs.org/schemas/api-doc/1.0.1.json","id":"packages-core","path":"/packages/core","type":"module","module":"packages-core","title":"`@doc-kit/core`","introducedIn":null,"sourceLink":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"The engine of [doc-kit](https://doc-kit.nodejs.org). It loads your\nconfiguration, runs generators in dependency order across worker threads, and\nprovides the JSON generators and the parsing stages that every output builds\non.\n\nYou usually reach it through the\n[`doc-kit` CLI](https://doc-kit.nodejs.org/packages/cli), which depends on it.\nImport it yourself to [run doc-kit from a script](#running-it-from-code) or to\n[write a generator](#writing-a-generator).","summary":"The engine of doc-kit. It loads your configuration, runs generators in dependency order across worker threads, and provides the JSON generators and the parsing stages that every output builds on.","examples":[],"children":[{"kind":"section","id":"install","name":"Install","title":"Install","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"```sh\nnpm install --save-dev @doc-kit/cli\n```\n\nInstalling the CLI installs this package, and with it the JSON generators.\nThis command writes one JSON document per Markdown file to `out/`:\n\n```sh\nnpx doc-kit generate -t json -i \"docs/**/*.md\" -o out\n```\n\nTo import `@doc-kit/core` from your own code, add it to your own dependencies\ntoo. Package managers that don't hoist dependencies, such as pnpm, won't let\nyou import it otherwise:\n\n```sh\nnpm install --save-dev @doc-kit/core\n```","summary":"Installing the CLI installs this package, and with it the JSON generators. This command writes one JSON document per Markdown file to `out/`:","examples":[{"language":"sh","displayName":null,"code":"npm install --save-dev @doc-kit/cli"},{"language":"sh","displayName":null,"code":"npx doc-kit generate -t json -i \"docs/**/*.md\" -o out"},{"language":"sh","displayName":null,"code":"npm install --save-dev @doc-kit/core"}],"children":[]},{"kind":"section","id":"how-it-runs","name":"How it runs","title":"How it runs","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"Every output comes from a generator, and each generator names the one it reads\nfrom with `dependsOn`. On every run, doc-kit:\n\n1. Merges the configuration: command-line options override the configuration\n   file, which overrides the defaults.\n2. Resolves each target: a built-in name such as `json` to the package that\n   provides it, a path to that file, and anything else to a package import.\n3. Loads the targets and every generator they depend on, and runs each one\n   once, as soon as its input is ready. Your sources are parsed once, however\n   many outputs read them, and independent generators run at the same time.\n4. Splits per-file work into chunks of `chunkSize` items across up to\n   `threads` worker threads, and frees each result once the last generator\n   reading it has it.","summary":"Every output comes from a generator, and each generator names the one it reads from with `dependsOn`. On every run, doc-kit:","examples":[],"children":[]},{"kind":"section","id":"generators","name":"Generators","title":"Generators","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"This package provides the JSON targets:\n\n| Target        | Writes                                                        | Reference                                                             |\n| ------------- | ------------------------------------------------------------- | --------------------------------------------------------------------- |\n| `json`        | One JSON document per source file, described by a JSON schema | [JSON](https://doc-kit.nodejs.org/generators/json)                    |\n| `json-all`    | Every `json` document, bundled in one `all.json`              | [JSON bundle](https://doc-kit.nodejs.org/generators/json#json-bundle) |\n| `json-simple` | The API entries in one `api-docs.json`, for debugging doc-kit | [Debug JSON](https://doc-kit.nodejs.org/generators/json#debug-json)   |\n\nIt also provides the pipeline stages. They write nothing, and run whenever a\ngenerator you ask for depends on them:\n\n| Stage      | What it does                                                           | Reference                                                          |\n| ---------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------ |\n| `ast`      | Parses the Markdown and MDX files matched by `input` into syntax trees | [Parsing Markdown](https://doc-kit.nodejs.org/generators/ast)      |\n| `metadata` | Turns those trees into typed API entries, which most generators read   | [API entries](https://doc-kit.nodejs.org/generators/metadata)      |\n| `ast-js`   | Parses the `.js` files matched by `input`, for `api-links`             | [Parsing JavaScript](https://doc-kit.nodejs.org/generators/ast-js) |\n\nThe other generators, and the rest of doc-kit, live in companion packages:\n\n| Package                                                                 | Provides                                                                                                                              |\n| ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |\n| [`@doc-kit/cli`](https://doc-kit.nodejs.org/packages/cli)               | The `doc-kit` command, which runs this package                                                                                        |\n| [`@doc-kit/generator-react`](https://doc-kit.nodejs.org/packages/react) | `html` (the website), `section-pages`, `orama-db` (the search index), `sitemap`, `llms-txt`, `llms-txt-full`, and the `jsx-ast` stage |\n| [`@node-core/doc-kit`](https://doc-kit.nodejs.org/packages/node)        | `man-page`, `api-links` and `addon-verify`, for building Node.js itself                                                               |\n| [`@doc-kit/typedoc`](https://doc-kit.nodejs.org/packages/typedoc)       | A TypeDoc plugin that writes the API of a TypeScript or JSDoc project as doc-kit Markdown                                             |\n\nThe [generators overview](https://doc-kit.nodejs.org/generators) describes them\nall.","summary":"This package provides the JSON targets:","examples":[],"children":[]},{"kind":"section","id":"configuration","name":"Configuration","title":"Configuration","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"This package finds the configuration file\n([where it looks](https://doc-kit.nodejs.org/configuration#where-configuration-lives)),\nmerges it with the command-line options and the defaults, and hands each\ngenerator its options. The file's top level takes:\n\n```js displayName=\"doc-kit.config.mjs\"\nexport default {\n  target: ['json', 'json-all'],\n  global: {\n    input: ['docs/**/*.md'],\n    output: 'out',\n  },\n  // A generator's own options override the global ones for it\n  'json-all': { minify: true },\n};\n```\n\n* `target` {string | string[]} The generators to run: built-in names, paths, or\n  import specifiers.\n* `global` {Object} The options every generator reads, such as `input`,\n  `output`, `project` and `repository`. See\n  [Configuration](https://doc-kit.nodejs.org/configuration) for all of them.\n* `threads` {number} The most worker threads to use. **Default:** the number of\n  CPUs, at most `4` (`1` on riscv64).\n* `chunkSize` {number} How many items each worker task processes.\n  **Default:** `10`.\n* `extends` {string | string[]} Presets to build on: modules whose default export\n  is a configuration. Paths resolve from the configuration file. The file's own\n  options override its presets', and a later preset overrides an earlier one.\n\nEach generator's own options go in a section named after it, such as `json` or\n`html`. A generator takes whatever its section leaves out from `global`.","summary":"This package finds the configuration file (where it looks), merges it with the command-line options and the defaults, and hands each generator its options. The file's top level takes:","examples":[{"language":"js","displayName":"doc-kit.config.mjs","code":"export default {\n  target: ['json', 'json-all'],\n  global: {\n    input: ['docs/**/*.md'],\n    output: 'out',\n  },\n  // A generator's own options override the global ones for it\n  'json-all': { minify: true },\n};"}],"children":[]},{"kind":"section","id":"running-it-from-code","name":"Running it from code","title":"Running it from code","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"The CLI's `generate` command comes down to two calls, which you can make\nyourself:\n\n```js displayName=\"build-docs.mjs\"\nimport createGenerator from '@doc-kit/core';\nimport { setConfig } from '@doc-kit/core/utils/configuration/index.mjs';\n\n// The options of `doc-kit generate`, in camelCase. The configuration file is\n// found and merged as on the command line.\nconst config = await setConfig({\n  input: ['docs/**/*.md'],\n  target: ['json', 'json-all'],\n  output: 'out',\n});\n\nconst { runGenerators } = createGenerator();\n\n// One result per target, in the order given\nconst [documents, bundle] = await runGenerators(config);\n```\n\n`setConfig()` takes the options of `doc-kit generate`: `input`, `target`,\n`output`, `ignore`, `threads`, `chunkSize`, `version`, `changelog`, `gitRef`,\n`index`, `minify`, `typeMap` and `configFile`. It ignores anything else, so\noptions such as `project`, `repository` or a generator's own section go in the\nconfiguration file. It also stores the configuration generators read with\n`getConfig()`, so a process runs one configuration at a time.\n\nWithout an `output`, the JSON generators write nothing and only return their\nresults.","summary":"The CLI's `generate` command comes down to two calls, which you can make yourself:","examples":[{"language":"js","displayName":"build-docs.mjs","code":"import createGenerator from '@doc-kit/core';\nimport { setConfig } from '@doc-kit/core/utils/configuration/index.mjs';\n\n// The options of `doc-kit generate`, in camelCase. The configuration file is\n// found and merged as on the command line.\nconst config = await setConfig({\n  input: ['docs/**/*.md'],\n  target: ['json', 'json-all'],\n  output: 'out',\n});\n\nconst { runGenerators } = createGenerator();\n\n// One result per target, in the order given\nconst [documents, bundle] = await runGenerators(config);"}],"children":[]},{"kind":"section","id":"writing-a-generator","name":"Writing a generator","title":"Writing a generator","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"A generator is a module whose default export describes it, passed to the CLI\nby its path (`-t ./my-generator.mjs`).\n[Creating generators](https://doc-kit.nodejs.org/creating-generators) walks\nthrough writing one, with worker threads, streaming and dependents.\n\nThe default export needs:\n\n* `name` {string} The generator's name, which is also the name of its\n  configuration section and what `getConfig()` takes.\n* `generate` {Function} `generate(input, worker)` builds the output from\n  `input`, the result of its `dependsOn` (`undefined` without one). It returns\n  the result, or an async generator yielding arrays of results, which\n  generators reading it receive joined into one array.\n\nIt can also have:\n\n* `description` {string} What it makes, in one line.\n* `dependsOn` {string} The generator it reads from: an import specifier such as\n  `@doc-kit/core/metadata`, or a built-in name.\n* `dependent` {string | string[]} Generators to deliver its output through. It is\n  spliced into each one's pipeline, in front of the first generator there that\n  reads the same `dependsOn`, and asking for it runs them.\n* `defaultConfiguration` {Object | Function} The defaults of its configuration\n  section, or a function taking the user's configuration and returning them.\n* `hasParallelProcessor` {boolean} Whether `generate` gets a `worker`, whose\n  `worker.stream(items, extra)` runs `processChunk` on worker threads and yields\n  each chunk's results as it completes. **Default:** `false`.\n* `processChunk` {Function} `processChunk(items, indices, extra)` processes the\n  `items` at `indices` on a worker thread, and returns an array of results.\n  `extra` is copied to the thread, so it must be cloneable.\n* `markdown` {Object} The unified plugins it processes Markdown with, as\n  `remarkPlugins`, `rehypePlugins` and `recmaPlugins` lists, with `'...'` where\n  the configured plugins go.","summary":"A generator is a module whose default export describes it, passed to the CLI by its path (`-t ./my-generator.mjs`). Creating generators walks through writing one, with worker threads, streaming and dependents.","examples":[],"children":[]},{"kind":"section","id":"exports","name":"Exports","title":"Exports","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"| Import                                        | Provides                                                                                                     |\n| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |\n| `@doc-kit/core`                               | `createGenerator()`, the default export, which returns `{ runGenerators }`                                   |\n| `@doc-kit/core/<name>`                        | Each generator and stage above (`json`, `metadata`, …) as the default export, for a generator's `dependsOn`  |\n| `@doc-kit/core/utils/configuration/index.mjs` | `setConfig(options)`, and `getConfig(name)`, the default export: a generator's options, merged with `global` |\n| `@doc-kit/core/utils/file.mjs`                | `writeFile()` and `writeJSON()`, which create missing directories                                            |\n| `@doc-kit/core/utils/markdown/processor.mjs`  | `getProcessor(name)`: the unified processor of a generator's `markdown`                                      |\n| `@doc-kit/core/plugins/shiki/highlighter.mjs` | `getHighlighter(name)`: the code highlighter of a generator's `markdown`                                     |\n| `@doc-kit/core/logger/index.mjs`              | The logger, with `logger.child(name)` for one of your own                                                    |\n| `@doc-kit/core/generators/types`              | The generator types, such as `GeneratorMetadata` and `ParallelWorker`, declared as globals                   |","summary":"","examples":[],"children":[]},{"kind":"section","id":"learn-more","name":"Learn more","title":"Learn more","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"* [Getting started](https://doc-kit.nodejs.org/getting-started)\n* [Configuration](https://doc-kit.nodejs.org/configuration)\n* [CLI](https://doc-kit.nodejs.org/cli)\n* [Creating generators](https://doc-kit.nodejs.org/creating-generators)\n* [Changelog](https://github.com/nodejs/doc-kit/blob/main/packages/core/CHANGELOG.md)","summary":"","examples":[],"children":[]},{"kind":"section","id":"contributing","name":"Contributing","title":"Contributing","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"This package lives in the [nodejs/doc-kit](https://github.com/nodejs/doc-kit)\nmonorepo. Set it up as the\n[contributing guide](https://github.com/nodejs/doc-kit/blob/main/CONTRIBUTING.md)\ndescribes, then, from this directory:\n\n```sh\n# Run this package's tests, once or on every change\nnode --run test\nnode --run test:watch\n\n# Measure their coverage\nnode --run test:coverage\n\n# Update the snapshots after changing an output on purpose\nnode --run test:update-snapshots\n```\n\nFrom the repository root, `node --run test` runs the tests of every package.\nA change to published behavior needs a changeset: run `node --run changeset`\nat the root.","summary":"This package lives in the nodejs/doc-kit monorepo. Set it up as the contributing guide describes, then, from this directory:","examples":[{"language":"sh","displayName":null,"code":"# Run this package's tests, once or on every change\nnode --run test\nnode --run test:watch\n\n# Measure their coverage\nnode --run test:coverage\n\n# Update the snapshots after changing an output on purpose\nnode --run test:update-snapshots"}],"children":[]}]}