Skip to content

feat: improve docs for newcomers #1005

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
avivkeller wants to merge 3 commits into
base: main
Choose a base branch
from
Open

feat: improve docs for newcomers #1005

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
afc5c6a
feat: improve docs for newcomers
avivkeller Aug 5, 2026
fde7bb3
fixup!
avivkeller Aug 5, 2026
6024718
fixup!
avivkeller Aug 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 40 additions & 0 deletions docs/cli.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
# CLI

The `doc-kit` command-line interface. Every option that maps to
configuration can also live in a [configuration file](./configuration.md);
when both are present, CLI flags win (rule of specifity).

```sh
npx doc-kit [command] [options]
```

One option applies to every command:

| Option | Description |
| --------------------- | ------------------------------------------------------ |
| `--log-level <level>` | `debug`, `info` (default), `warn`, `error`, or `fatal` |

## `doc-kit generate`

```sh
npx doc-kit generate [options]
```

Runs the generators and writes their output. Requires a `target` and an
`input`, from flags or the configuration file.

| Option | Description |
| ----------------------------- | ------------------------------------------------------------- |
| `--config-file <path>` | Use a specific configuration file instead of searching |
| `-i`, `--input <patterns...>` | Input file patterns (glob) |
| `-t`, `--target <name...>` | Generator name(s), or import specifiers for custom generators |
| `--ignore <patterns...>` | Input patterns to skip |
| `-o`, `--output <dir>` | The output directory |
| `-v`, `--version <semver>` | The version of the project being documented |
| `-c`, `--changelog <url>` | Changelog URL or path (release history for version selectors) |
| `--git-ref <ref>` | Git ref used in source links |
| `--index <url>` | `index.md` URL or path |
| `--minify` | Minify the output |
| `--type-map <url>` | Type map URL or path (custom type-name → URL links) |
| `-p`, `--threads <n>` | Worker threads to use (minimum 1) |
| `--chunk-size <n>` | Items per worker thread (minimum 1) |
183 changes: 63 additions & 120 deletions docs/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,143 +1,86 @@
# Configuration

`doc-kit` uses [`cosmiconfig`](https://github.com/cosmiconfig/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 File Format

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:

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

### Basic Example

```javascript
`doc-kit` discovers configuration with
[`cosmiconfig`](https://github.com/cosmiconfig/cosmiconfig): run the CLI
from your project directory and it looks for a `doc-kit.config.mjs` (or
`.js`/`.cjs`/`.ts`), a `.doc-kitrc` file (JSON or YAML, with any of the
usual extensions), or a `doc-kit` property in `package.json`. Use
`--config-file <path>` to load a specific file instead of searching.

```mjs displayName="doc-kit.config.mjs"
/** @type {import('@nodejs/doc-kit/utils/configuration/types').Configuration} */
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: {
version: '20.0.0',
minify: true,
repository: 'nodejs/node',
ref: 'main',
baseURL: 'https://nodejs.org/docs/',
input: 'src/',
output: 'dist/',
ignore: ['node_modules/', 'test/'],
changelog:
'https://raw.githubusercontent.com/nodejs/node/main/CHANGELOG.md',
index:
'https://raw.githubusercontent.com/nodejs/node/main/doc/api/index.md',
},

threads: 4,
chunkSize: 10,
// Which generators to run. Built-in names, or import specifiers
// resolving to custom generator modules.
target: ['html', 'orama-db'],

// Generator-specific configurations
json: {
format: 'json',
minify: false, // Override global setting
global: {
input: ['docs/**/*.md'],
output: 'out',
version: '1.2.0',
baseURL: 'https://example.com/docs',
changelog: [],
},

// Generator-specific sections, keyed by generator name
html: {
format: 'html',
},

metadata: {
typeMap: {
String: 'string',
Number: 'number',
Boolean: 'boolean',
},
project: 'My Project',
},
};
```

## Configuration Structure
## How values merge

### Global Configuration
Three sources, in order of precedence:

The `global` object contains settings that apply to all generators unless overridden:
1. **CLI flags** (see the [CLI reference](./cli.md)) override
2. **the configuration file**, which overrides
3. **built-in defaults**.

| Property | Type | Description | Default |
| ------------ | ------------------ | ------------------------------------------ | -------------------------------------------------- |
| `version` | `string \| SemVer` | Documentation version | `process.version` |
| `minify` | `boolean` | Whether to minify output | `true` |
| `repository` | `string` | GitHub repository in `owner/repo` format | `'nodejs/node'` |
| `ref` | `string` | Git reference (branch, tag, or commit SHA) | `'HEAD'` |
| `baseURL` | `string \| URL` | Base URL for documentation | `'https://nodejs.org/docs'` |
| `input` | `string[]` | Input directory path | - |
| `output` | `string` | Output directory path | - |
| `ignore` | `string[]` | Patterns to ignore | `[]` |
| `changelog` | `string \| URL` | Changelog URL | Auto-generated URL based on `ref` and `repository` |
| `index` | `string \| URL` | Index URL | - |
Each generator's section starts from its own defaults, then inherits every
`global` value it doesn't override. So `global.minify` applies to all
targets, while `'legacy-json': { minify: false }` exempts one.

### Generator-Specific Configuration
## Global options

Each generator (e.g., `json`, `html`, `markdown`) can have its own configuration that overrides global settings:
| Property | Type | Description | Default |
| ------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
| `input` | `string \| string[]` | Glob patterns for the source Markdown files. Required (with `target`) to run. | — |
| `output` | `string` | The directory generated files are written to. | — |
| `ignore` | `string \| string[]` | Glob patterns excluded from `input`. | — |
| `version` | `string` | The version of the project being documented (coerced to semver). | `process.version` |
| `changelog` | `string \| URL \| Array` | Release history used to build version selectors. A URL or path to a `CHANGELOG.md` to parse, or a pre-parsed array — `[]` disables versioning (and the network fetch). | The Node.js `CHANGELOG.md` |
| `index` | `string \| URL \| Array` | An `index.md` listing section titles, or a pre-parsed array. | — |
| `baseURL` | `string \| URL` | The public URL of the published site; used wherever absolute links are needed (sitemaps, `llms.txt`, social metadata). | `'https://nodejs.org/docs'` |
| `repository` | `string` | GitHub repository in `owner/repo` form, used for source and edit links. | `'nodejs/node'` |
| `ref` | `string` | Git ref (branch, tag, or SHA) used in source links. | `'HEAD'` |
| `minify` | `boolean` | Minify the output, in whatever form it takes. | `true` |
| `pathsToCopy` | `Array<string \| Object>` | Extra files or directories copied into the output. A string copies to `output/<basename>`; a `{ source: destination }` object controls the target path. Missing paths are skipped. | `['assets', 'public', 'static']` |

```javascript
## Execution options

Top-level, alongside `target` and `global`:

| Property | Type | Description | Default |
| ----------- | -------- | ----------------------------------- | -------------- |
| `threads` | `number` | Worker threads used for generation. | Your CPU count |
| `chunkSize` | `number` | Items processed per worker thread. | `10` |

## Generator options

Each generator documents its own options on its reference page — see the
[generators overview](./generators.md). Two commonly configured ones:

```js
export default {
global: {
version: '20.0.0',
minify: true,
html: {
project: 'My Project',
},

'legacy-json': {
minify: false, // Override: JSON output won't be minified
metadata: {
typeMap: {
MyThing: 'https://example.com/docs/my-thing.html',
},
},
};
```

## Configuration Merging

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. **Default values** (built-in defaults)

## CLI Options Mapping

CLI options map to configuration properties:

| CLI Option | Config Property | Example |
| ---------------------- | ------------------ | ------------------------- |
| `--input <path>` | `global.input` | `--input src/` |
| `--output <path>` | `global.output` | `--output dist/` |
| `--ignore <pattern>` | `global.ignore[]` | `--ignore test/` |
| `--minify` | `global.minify` | `--minify` |
| `--git-ref <ref>` | `global.ref` | `--git-ref v20.0.0` |
| `--version <version>` | `global.version` | `--version 20.0.0` |
| `--changelog <url>` | `global.changelog` | `--changelog https://...` |
| `--index <url>` | `global.index` | `--index file://...` |
| `--type-map <map>` | `metadata.typeMap` | `--type-map file://...` |
| `--target <generator>` | `target` | `--target json` |
| `--threads <n>` | `threads` | `--threads 4` |
| `--chunk-size <n>` | `chunkSize` | `--chunk-size 10` |
Loading
Loading