@doc-kit/core

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.

You usually reach it through the doc-kit CLI, which depends on it. Import it yourself to run doc-kit from a script or to write a generator.

npm install --save-dev @doc-kit/cli

Installing the CLI installs this package, and with it the JSON generators. This command writes one JSON document per Markdown file to out/:

npx @doc-kit/cli generate -t json -i "docs/**/*.md" -o out

To import @doc-kit/core from your own code, add it to your own dependencies too. Package managers that don't hoist dependencies, such as pnpm, won't let you import it otherwise:

npm install --save-dev @doc-kit/core

Every output comes from a generator, and each generator names the one it reads from with dependsOn. On every run, doc-kit:

1. Merges the configuration: command-line options override the configuration file, which overrides the defaults.
2. Resolves each target: a built-in name such as json to the package that provides it, a path to that file, and anything else to a package import.
3. Loads the targets and every generator they depend on, and runs each one once, as soon as its input is ready. Your sources are parsed once, however many outputs read them, and independent generators run at the same time.
4. Splits per-file work into chunks of chunkSize items across up to threads worker threads, and frees each result once the last generator reading it has it.

This package provides the JSON targets:

It also provides the pipeline stages. They write nothing, and run whenever a generator you ask for depends on them:

The other generators come from companion packages; the generators overview lists which package provides each.

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.

The CLI's generate command comes down to two calls, which you can make yourself:

import createGenerator from '@doc-kit/core';
import { setConfig } from '@doc-kit/core/utils/configuration/index.mjs';

// The options of `doc-kit generate`, in camelCase. The configuration file is
// found and merged as on the command line.
const config = await setConfig({
  input: ['docs/**/*.md'],
  target: ['json', 'json-all'],
  output: 'out',
});

const { runGenerators } = createGenerator();

// One result per target, in the order given
const [documents, bundle] = await runGenerators(config);

setConfig() takes the options of doc-kit generate: input, target, output, ignore, threads, chunkSize, version, changelog, gitRef, index, minify, typeMap and configFile. It ignores anything else, so options such as project, repository or a generator's own section go in the configuration file. It also stores the configuration generators read with getConfig(), so a process runs one configuration at a time.

Without an output, the JSON generators write nothing and only return their results.

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.

This package lives in the nodejs/doc-kit monorepo. Set it up as the contributing guide describes, then, from this directory:

# Run this package's tests
pnpm test

# Re-run the tests on every change
pnpm run test:watch