Skip to content

Commit 140d5c0

Browse files
authored
feat: improve docs for newcomers (#1005)
* feat: improve docs for newcomers * fixup! * fixup!
1 parent 4bafb28 commit 140d5c0

15 files changed

Lines changed: 1294 additions & 849 deletions

‎docs/cli.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# CLI
2+
3+
The `doc-kit` command-line interface. Every option that maps to
4+
configuration can also live in a [configuration file](./configuration.md);
5+
when both are present, CLI flags win (rule of specifity).
6+
7+
```sh
8+
npx doc-kit [command] [options]
9+
```
10+
11+
One option applies to every command:
12+
13+
| Option | Description |
14+
| --------------------- | ------------------------------------------------------ |
15+
| `--log-level <level>` | `debug`, `info` (default), `warn`, `error`, or `fatal` |
16+
17+
## `doc-kit generate`
18+
19+
```sh
20+
npx doc-kit generate [options]
21+
```
22+
23+
Runs the generators and writes their output. Requires a `target` and an
24+
`input`, from flags or the configuration file.
25+
26+
| Option | Description |
27+
| ----------------------------- | ------------------------------------------------------------- |
28+
| `--config-file <path>` | Use a specific configuration file instead of searching |
29+
| `-i`, `--input <patterns...>` | Input file patterns (glob) |
30+
| `-t`, `--target <name...>` | Generator name(s), or import specifiers for custom generators |
31+
| `--ignore <patterns...>` | Input patterns to skip |
32+
| `-o`, `--output <dir>` | The output directory |
33+
| `-v`, `--version <semver>` | The version of the project being documented |
34+
| `-c`, `--changelog <url>` | Changelog URL or path (release history for version selectors) |
35+
| `--git-ref <ref>` | Git ref used in source links |
36+
| `--index <url>` | `index.md` URL or path |
37+
| `--minify` | Minify the output |
38+
| `--type-map <url>` | Type map URL or path (custom type-name → URL links) |
39+
| `-p`, `--threads <n>` | Worker threads to use (minimum 1) |
40+
| `--chunk-size <n>` | Items per worker thread (minimum 1) |

‎docs/configuration.md‎

Lines changed: 63 additions & 120 deletions
Original file line numberDiff line numberDiff line change
@@ -1,143 +1,86 @@
11
# Configuration
22

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} */
3812
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'],
6016

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: [],
6523
},
6624

25+
// Generator-specific sections, keyed by generator name
6726
html: {
68-
format: 'html',
69-
},
70-
71-
metadata: {
72-
typeMap: {
73-
String: 'string',
74-
Number: 'number',
75-
Boolean: 'boolean',
76-
},
27+
project: 'My Project',
7728
},
7829
};
7930
```
8031

81-
## Configuration Structure
32+
## How values merge
8233

83-
### Global Configuration
34+
Three sources, in order of precedence:
8435

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**.
8639

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.
9943

100-
### Generator-Specific Configuration
44+
## Global options
10145

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']` |
10359

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
10575
export default {
106-
global: {
107-
version: '20.0.0',
108-
minify: true,
76+
html: {
77+
project: 'My Project',
10978
},
11079

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+
},
11384
},
11485
};
11586
```
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

Comments
 (0)