|
1 | 1 | # Configuration |
2 | 2 |
|
3 | | -`doc-kit` uses [`cosmiconfig`](https://github.com/cosmiconfig/cosmiconfig) to |
4 | | -discover and load configuration. Run the CLI from your project directory and it |
5 | | -will automatically look for a `doc-kit` property in `package.json`, rc files |
6 | | -such as `.doc-kitrc.yml`, and module files such as `doc-kit.config.mjs`. |
7 | | - |
8 | | -Use `--config-file <path>` to load a specific file instead of searching. |
9 | | - |
10 | | -## Configuration File Format |
11 | | - |
12 | | -Configuration files can be either: |
13 | | - |
14 | | -- **JavaScript** (`.js`, `.mjs`, `.cjs`) |
15 | | -- **TypeScript** (`.ts`, when `typescript` is installed in the project) |
16 | | -- **JSON** (`.json`) |
17 | | -- **YAML** (`.yaml`, `.yml`, or an extensionless rc file) |
18 | | - |
19 | | -JavaScript and TypeScript configuration files export the configuration object. |
20 | | -JSON and YAML files contain the object directly. A `package.json` configuration |
21 | | -uses the `doc-kit` property: |
22 | | - |
23 | | -```json |
24 | | -{ |
25 | | - "doc-kit": { |
26 | | - "target": ["json"], |
27 | | - "global": { |
28 | | - "input": "doc/api/*.md", |
29 | | - "output": "out" |
30 | | - } |
31 | | - } |
32 | | -} |
33 | | -``` |
34 | | - |
35 | | -### Basic Example |
36 | | - |
37 | | -```javascript |
| 3 | +`doc-kit` discovers configuration with |
| 4 | +[`cosmiconfig`](https://github.com/cosmiconfig/cosmiconfig): run the CLI |
| 5 | +from your project directory and it looks for a `doc-kit.config.mjs` (or |
| 6 | +`.js`/`.cjs`/`.ts`), a `.doc-kitrc` file (JSON or YAML, with any of the |
| 7 | +usual extensions), or a `doc-kit` property in `package.json`. Use |
| 8 | +`--config-file <path>` to load a specific file instead of searching. |
| 9 | + |
| 10 | +```mjs displayName="doc-kit.config.mjs" |
| 11 | +/** @type {import('@nodejs/doc-kit/utils/configuration/types').Configuration} */ |
38 | 12 | export default { |
39 | | - // Targets, alternatively supplied by command line flags. Each entry is |
40 | | - // either a built-in shorthand name or an import specifier resolving to a |
41 | | - // generator module (e.g. '@my-scope/my-package/my-generator'). |
42 | | - target: ['orama-db', 'html'], |
43 | | - global: { |
44 | | - version: '20.0.0', |
45 | | - minify: true, |
46 | | - repository: 'nodejs/node', |
47 | | - ref: 'main', |
48 | | - baseURL: 'https://nodejs.org/docs/', |
49 | | - input: 'src/', |
50 | | - output: 'dist/', |
51 | | - ignore: ['node_modules/', 'test/'], |
52 | | - changelog: |
53 | | - 'https://raw.githubusercontent.com/nodejs/node/main/CHANGELOG.md', |
54 | | - index: |
55 | | - 'https://raw.githubusercontent.com/nodejs/node/main/doc/api/index.md', |
56 | | - }, |
57 | | - |
58 | | - threads: 4, |
59 | | - chunkSize: 10, |
| 13 | + // Which generators to run. Built-in names, or import specifiers |
| 14 | + // resolving to custom generator modules. |
| 15 | + target: ['html', 'orama-db'], |
60 | 16 |
|
61 | | - // Generator-specific configurations |
62 | | - json: { |
63 | | - format: 'json', |
64 | | - minify: false, // Override global setting |
| 17 | + global: { |
| 18 | + input: ['docs/**/*.md'], |
| 19 | + output: 'out', |
| 20 | + version: '1.2.0', |
| 21 | + baseURL: 'https://example.com/docs', |
| 22 | + changelog: [], |
65 | 23 | }, |
66 | 24 |
|
| 25 | + // Generator-specific sections, keyed by generator name |
67 | 26 | html: { |
68 | | - format: 'html', |
69 | | - }, |
70 | | - |
71 | | - metadata: { |
72 | | - typeMap: { |
73 | | - String: 'string', |
74 | | - Number: 'number', |
75 | | - Boolean: 'boolean', |
76 | | - }, |
| 27 | + project: 'My Project', |
77 | 28 | }, |
78 | 29 | }; |
79 | 30 | ``` |
80 | 31 |
|
81 | | -## Configuration Structure |
| 32 | +## How values merge |
82 | 33 |
|
83 | | -### Global Configuration |
| 34 | +Three sources, in order of precedence: |
84 | 35 |
|
85 | | -The `global` object contains settings that apply to all generators unless overridden: |
| 36 | +1. **CLI flags** (see the [CLI reference](./cli.md)) override |
| 37 | +2. **the configuration file**, which overrides |
| 38 | +3. **built-in defaults**. |
86 | 39 |
|
87 | | -| Property | Type | Description | Default | |
88 | | -| ------------ | ------------------ | ------------------------------------------ | -------------------------------------------------- | |
89 | | -| `version` | `string \| SemVer` | Documentation version | `process.version` | |
90 | | -| `minify` | `boolean` | Whether to minify output | `true` | |
91 | | -| `repository` | `string` | GitHub repository in `owner/repo` format | `'nodejs/node'` | |
92 | | -| `ref` | `string` | Git reference (branch, tag, or commit SHA) | `'HEAD'` | |
93 | | -| `baseURL` | `string \| URL` | Base URL for documentation | `'https://nodejs.org/docs'` | |
94 | | -| `input` | `string[]` | Input directory path | - | |
95 | | -| `output` | `string` | Output directory path | - | |
96 | | -| `ignore` | `string[]` | Patterns to ignore | `[]` | |
97 | | -| `changelog` | `string \| URL` | Changelog URL | Auto-generated URL based on `ref` and `repository` | |
98 | | -| `index` | `string \| URL` | Index URL | - | |
| 40 | +Each generator's section starts from its own defaults, then inherits every |
| 41 | +`global` value it doesn't override. So `global.minify` applies to all |
| 42 | +targets, while `'legacy-json': { minify: false }` exempts one. |
99 | 43 |
|
100 | | -### Generator-Specific Configuration |
| 44 | +## Global options |
101 | 45 |
|
102 | | -Each generator (e.g., `json`, `html`, `markdown`) can have its own configuration that overrides global settings: |
| 46 | +| Property | Type | Description | Default | |
| 47 | +| ------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | |
| 48 | +| `input` | `string \| string[]` | Glob patterns for the source Markdown files. Required (with `target`) to run. | — | |
| 49 | +| `output` | `string` | The directory generated files are written to. | — | |
| 50 | +| `ignore` | `string \| string[]` | Glob patterns excluded from `input`. | — | |
| 51 | +| `version` | `string` | The version of the project being documented (coerced to semver). | `process.version` | |
| 52 | +| `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` | |
| 53 | +| `index` | `string \| URL \| Array` | An `index.md` listing section titles, or a pre-parsed array. | — | |
| 54 | +| `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'` | |
| 55 | +| `repository` | `string` | GitHub repository in `owner/repo` form, used for source and edit links. | `'nodejs/node'` | |
| 56 | +| `ref` | `string` | Git ref (branch, tag, or SHA) used in source links. | `'HEAD'` | |
| 57 | +| `minify` | `boolean` | Minify the output, in whatever form it takes. | `true` | |
| 58 | +| `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']` | |
103 | 59 |
|
104 | | -```javascript |
| 60 | +## Execution options |
| 61 | + |
| 62 | +Top-level, alongside `target` and `global`: |
| 63 | + |
| 64 | +| Property | Type | Description | Default | |
| 65 | +| ----------- | -------- | ----------------------------------- | -------------- | |
| 66 | +| `threads` | `number` | Worker threads used for generation. | Your CPU count | |
| 67 | +| `chunkSize` | `number` | Items processed per worker thread. | `10` | |
| 68 | + |
| 69 | +## Generator options |
| 70 | + |
| 71 | +Each generator documents its own options on its reference page — see the |
| 72 | +[generators overview](./generators.md). Two commonly configured ones: |
| 73 | + |
| 74 | +```js |
105 | 75 | export default { |
106 | | - global: { |
107 | | - version: '20.0.0', |
108 | | - minify: true, |
| 76 | + html: { |
| 77 | + project: 'My Project', |
109 | 78 | }, |
110 | 79 |
|
111 | | - 'legacy-json': { |
112 | | - minify: false, // Override: JSON output won't be minified |
| 80 | + metadata: { |
| 81 | + typeMap: { |
| 82 | + MyThing: 'https://example.com/docs/my-thing.html', |
| 83 | + }, |
113 | 84 | }, |
114 | 85 | }; |
115 | 86 | ``` |
116 | | - |
117 | | -## Configuration Merging |
118 | | - |
119 | | -Configurations are merged in the following order (higher sources take |
120 | | -precedence): |
121 | | - |
122 | | -1. **CLI options** (command-line arguments) |
123 | | -2. **Configuration file** (discovered or selected with `--config-file`) |
124 | | -3. **Default values** (built-in defaults) |
125 | | - |
126 | | -## CLI Options Mapping |
127 | | - |
128 | | -CLI options map to configuration properties: |
129 | | - |
130 | | -| CLI Option | Config Property | Example | |
131 | | -| ---------------------- | ------------------ | ------------------------- | |
132 | | -| `--input <path>` | `global.input` | `--input src/` | |
133 | | -| `--output <path>` | `global.output` | `--output dist/` | |
134 | | -| `--ignore <pattern>` | `global.ignore[]` | `--ignore test/` | |
135 | | -| `--minify` | `global.minify` | `--minify` | |
136 | | -| `--git-ref <ref>` | `global.ref` | `--git-ref v20.0.0` | |
137 | | -| `--version <version>` | `global.version` | `--version 20.0.0` | |
138 | | -| `--changelog <url>` | `global.changelog` | `--changelog https://...` | |
139 | | -| `--index <url>` | `global.index` | `--index file://...` | |
140 | | -| `--type-map <map>` | `metadata.typeMap` | `--type-map file://...` | |
141 | | -| `--target <generator>` | `target` | `--target json` | |
142 | | -| `--threads <n>` | `threads` | `--threads 4` | |
143 | | -| `--chunk-size <n>` | `chunkSize` | `--chunk-size 10` | |
0 commit comments