Configuration

doc-kit uses cosmiconfig to discover and load configuration. Run the CLI from your project directory and it will automatically look for a doc-kit property in package.json, rc files such as .doc-kitrc.yml, and module files such as doc-kit.config.mjs.

Use --config-file <path> to load a specific file instead of searching.

Configuration files can be either:

• JavaScript (.js, .mjs, .cjs)
• TypeScript (.ts, when typescript is installed in the project)
• JSON (.json)
• YAML (.yaml, .yml, or an extensionless rc file)

JavaScript and TypeScript configuration files export the configuration object. JSON and YAML files contain the object directly. A package.json configuration uses the doc-kit property:

{
  "doc-kit": {
    "target": ["json-simple"],
    "global": {
      "input": "doc/api/*.md",
      "output": "out"
    }
  }
}

export default {
  // Targets, alternatively supplied by command line flags. Each entry is
  // either a built-in shorthand name or an import specifier resolving to a
  // generator module (e.g. '@my-scope/my-package/my-generator').
  target: ['orama-db', 'html'],
  global: {
    project: 'My Project',
    version: '1.2.0',
    input: 'docs/**/*.md',
    output: 'dist/',
    ignore: ['node_modules/', 'test/'],
    baseURL: 'https://example.com/docs/',
  },

  threads: 4,
  chunkSize: 10,

  // Generator-specific configurations
  html: {
    title: '{project} Documentation',
  },

  metadata: {
    typeMap: {
      MyThing: 'https://example.com/docs/my-thing.html',
    },
  },
};

A configuration file may declare extends: one or more presets whose values are merged underneath its own. Each entry is either an import specifier of a module whose default export is a configuration object, or a path relative to the configuration file:

export default {
  // Build the docs the way nodejs.org does — branding, URL layouts,
  // and release history included
  extends: '@node-core/doc-kit/config',

  html: {
    // Your own values still win over the preset
    title: '{project} {version} API Reference',
  },
};

extends also accepts an array; later presets take precedence over earlier ones, and the configuration file itself wins over all of them.

The built-in defaults are deliberately project-neutral: no repository, site URL, release history, or branding is assumed. The @node-core/doc-kit/config preset opts back into everything Node.js-specific.

Three sources, in order of precedence:

1. CLI flags (see the CLI reference) override
2. the configuration file, which overrides
3. built-in defaults.

Everything under the global key applies to every generator:

A generator's own section (e.g., html, legacy-json) can override any of these for that generator alone.

Top-level, alongside target and global:

Each generator documents its own options on its reference page — see the generators overview. Two commonly configured ones:

export default {
  global: {
    version: '1.2.0',
    minify: true,
  },

  metadata: {
    typeMap: {
      MyThing: 'https://example.com/docs/my-thing.html',
    },
  },
};

Configurations are merged in the following order (higher sources take precedence):

1. CLI options (command-line arguments)
2. Configuration file (discovered or selected with --config-file)
3. Presets (listed in the configuration file's extends)
4. Default values (built-in defaults)

CLI options map to configuration properties: