{"$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/cli 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/cli 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-all)   |\n| `json-simple` | The API entries in one `api-docs.json`, for debugging doc-kit | [Debug JSON](https://doc-kit.nodejs.org/generators/json-simple) |\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 come from companion packages; the\n[generators overview](https://doc-kit.nodejs.org/generators) lists which\npackage provides each.","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, merges it with the command-line\noptions and the defaults, and hands each generator its options.\n[Configuration](https://doc-kit.nodejs.org/configuration) covers\n[targets](https://doc-kit.nodejs.org/configuration#targets),\n[execution options](https://doc-kit.nodejs.org/configuration#execution-options)\nand [extending presets](https://doc-kit.nodejs.org/configuration#extending-presets).","summary":"This package finds the configuration file, merges it with the command-line options and the defaults, and hands each generator its options. Configuration covers targets, execution options and extending presets.","examples":[],"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 and each key of its default export, with worker threads,\nstreaming and dependents.","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 and each key of its default export, 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":"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\npnpm test\n\n# Re-run the tests on every change\npnpm run test:watch\n```","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\npnpm test\n\n# Re-run the tests on every change\npnpm run test:watch"}],"children":[]}]}