Skip to content

Commit 7358447

Browse files
committed
feat: make generator defaults project-neutral
1 parent b6417dc commit 7358447

29 files changed

Lines changed: 379 additions & 99 deletions

File tree

‎.changeset/node-preset.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
'@node-core/doc-kit': minor
3+
---
4+
5+
Add the `@node-core/doc-kit/config` preset

‎.changeset/plain-defaults.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
'@nodejs/doc-kit': patch
3+
'@nodejs/doc-kit-generator-react': minor
4+
---
5+
6+
Defaults are now project-neutral instead of Node.js-specific

‎.github/workflows/ci.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -141,7 +141,7 @@ jobs:
141141
path: node
142142

143143
- name: Build docs
144-
run: npx doc-kit generate -t web -i "./node/doc/api/assert.md" -o out
144+
run: npx doc-kit generate -t web -i "./node/doc/api/assert.md" -o out --config-file ./e2e/doc-kit.config.mjs
145145

146146
- name: Install Playwright browsers
147147
run: npx playwright install --with-deps

‎README.md‎

Lines changed: 42 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -46,14 +46,21 @@ $ node packages/core/bin/cli.mjs --help
4646
```
4747
Usage: @nodejs/doc-kit [options] [command]
4848
49-
CLI tool to generate the Node.js API documentation
49+
CLI tool to generate API documentation
5050
5151
Options:
52-
-h, --help display help for command
52+
--log-level <level> Log level (choices: "debug", "info",
53+
"warn", "error", "fatal", default: "info")
54+
-h, --help display help for command
5355
5456
Commands:
55-
generate [options] Generate API docs
56-
help [command] display help for command
57+
generate [options] Generate API docs
58+
install [options] [generators...] Install the packages providing built-in
59+
generators (defaults to the targets in your
60+
configuration file)
61+
serve [options] Generate API docs, serve them locally, and
62+
regenerate on changes
63+
help [command] display help for command
5764
```
5865

5966
### `generate`
@@ -70,15 +77,37 @@ Usage: @nodejs/doc-kit generate [options]
7077
Generate API docs
7178
7279
Options:
73-
-i, --input <patterns...> Input file patterns (glob)
74-
--ignore [patterns...] Ignore patterns (comma-separated)
75-
-o, --output <dir> Output directory
76-
-p, --threads <number> (default: "12")
77-
-v, --version <semver> Target Node.js version (default: "v22.14.0")
78-
-c, --changelog <url> Changelog URL or path (default: "https://raw.githubusercontent.com/nodejs/node/HEAD/CHANGELOG.md")
79-
--git-ref <url> Git ref/commit URL (default: "https://github.com/nodejs/node/tree/HEAD")
80-
-t, --target [modes...] Target generator modes (choices: "json-simple", "legacy-html", "legacy-html-all", "man-page", "legacy-json", "legacy-json-all", "addon-verify", "api-links", "orama-db", "llms-txt")
81-
-h, --help display help for command
80+
--config-file <path> Config file
81+
-i, --input <patterns...> Input file patterns (glob)
82+
-t, --target <generator...> Target generator(s): a built-in name
83+
(json-simple, legacy-html, legacy-html-all,
84+
man-page, legacy-json, legacy-json-all,
85+
addon-verify, api-links, orama-db, llms-txt,
86+
sitemap, html) or an import specifier for a
87+
custom generator
88+
--ignore <patterns...> Ignore file patterns (glob)
89+
-o, --output <directory> The output directory
90+
-p, --threads <number> Number of threads to use (minimum: 1)
91+
--chunk-size <number> Number of items to process per worker thread
92+
(minimum: 1)
93+
-v, --version <semver> Target project version
94+
-c, --changelog <url> Changelog URL or path
95+
--git-ref Git ref URL
96+
--index <url> index.md URL or path
97+
--minify Minify?
98+
--type-map <url> Type map URL or path
99+
-h, --help display help for command
100+
```
101+
102+
The defaults are project-neutral. To produce output styled and structured the
103+
way [nodejs.org](https://nodejs.org) builds its API docs, extend the Node.js
104+
preset in your configuration file — see
105+
[the configuration guide](docs/configuration.md#extending-presets):
106+
107+
```mjs
108+
export default {
109+
extends: '@node-core/doc-kit/config',
110+
};
82111
```
83112

84113
### `install`

‎beta/doc-kit.config.mjs‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
11
export default {
2+
extends: '@node-core/doc-kit/config',
3+
24
html: {
35
remoteConfigUrl:
46
'https://raw.githubusercontent.com/nodejs/doc-kit/main/beta/site.json',

‎docs/configuration.md‎

Lines changed: 30 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -114,14 +114,43 @@ export default {
114114
};
115115
```
116116

117+
## Extending Presets
118+
119+
A configuration file may declare `extends`: one or more presets whose values
120+
are merged underneath its own. Each entry is either an import specifier of a
121+
module whose default export is a configuration object, or a path relative to
122+
the configuration file:
123+
124+
```mjs
125+
export default {
126+
// Build the docs the way nodejs.org does — branding, URL layouts,
127+
// and release history included
128+
extends: '@node-core/doc-kit/config',
129+
130+
html: {
131+
// Your own values still win over the preset
132+
title: '{project} {version} API Reference',
133+
},
134+
};
135+
```
136+
137+
`extends` also accepts an array; later presets take precedence over earlier
138+
ones, and the configuration file itself wins over all of them.
139+
140+
The built-in defaults are deliberately project-neutral: no repository,
141+
site URL, release history, or branding is assumed. The
142+
[`@node-core/doc-kit/config`](https://github.com/nodejs/doc-kit/tree/main/packages/node)
143+
preset opts back into everything Node.js-specific.
144+
117145
## Configuration Merging
118146

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

122150
1. **CLI options** (command-line arguments)
123151
2. **Configuration file** (discovered or selected with `--config-file`)
124-
3. **Default values** (built-in defaults)
152+
3. **Presets** (listed in the configuration file's `extends`)
153+
4. **Default values** (built-in defaults)
125154

126155
## CLI Options Mapping
127156

‎e2e/doc-kit.config.mjs‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
export default {
2+
extends: '@node-core/doc-kit/config',
3+
};

‎packages/core/bin/cli.mjs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ import logger from '../src/logger/index.mjs';
1010

1111
const program = new Command()
1212
.name('@nodejs/doc-kit')
13-
.description('CLI tool to generate the Node.js API documentation')
13+
.description('CLI tool to generate API documentation')
1414
.addOption(
1515
new Option('--log-level <level>', 'Log level')
1616
.default('info')

‎packages/core/bin/commands/options.mjs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@ export const createConfigurationOptions = () => [
3030
'--chunk-size <number>',
3131
'Number of items to process per worker thread (minimum: 1)'
3232
),
33-
new Option('-v, --version <semver>', 'Target Node.js version'),
33+
new Option('-v, --version <semver>', 'Target project version'),
3434
new Option('-c, --changelog <url>', 'Changelog URL or path'),
3535
new Option('--git-ref', 'Git ref URL'),
3636
new Option('--index <url>', 'index.md URL or path'),

‎packages/core/src/utils/configuration/__tests__/index.test.mjs‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,7 @@
11
import assert from 'node:assert';
2+
import { mkdtempSync, writeFileSync } from 'node:fs';
3+
import { tmpdir } from 'node:os';
4+
import { join } from 'node:path';
25
import { describe, it, mock, beforeEach } from 'node:test';
36

47
// Mock dependencies
@@ -96,6 +99,47 @@ describe('config.mjs', () => {
9699
);
97100
assert.strictEqual(mockConfigSearch.mock.calls.length, 0);
98101
});
102+
103+
it('should merge extends presets underneath the config file', async () => {
104+
const dir = mkdtempSync(join(tmpdir(), 'doc-kit-config-'));
105+
106+
writeFileSync(
107+
join(dir, 'base.mjs'),
108+
'export default { global: { project: "Base", ref: "base" }, html: { a: 1 } };'
109+
);
110+
writeFileSync(
111+
join(dir, 'other.mjs'),
112+
'export default { global: { project: "Other" }, html: { b: 2 } };'
113+
);
114+
115+
mockConfigLoad.mock.mockImplementationOnce(async () => ({
116+
config: {
117+
extends: ['./base.mjs', './other.mjs'],
118+
global: { ref: 'own' },
119+
},
120+
filepath: join(dir, 'doc-kit.config.mjs'),
121+
}));
122+
123+
const result = await loadConfigFile('any');
124+
125+
// Later presets win over earlier ones; the file itself wins over all
126+
assert.deepStrictEqual(result, {
127+
global: { project: 'Other', ref: 'own' },
128+
html: { a: 1, b: 2 },
129+
});
130+
});
131+
132+
it('should resolve extends package specifiers from the config file', async () => {
133+
mockConfigLoad.mock.mockImplementationOnce(async () => ({
134+
config: { extends: '@node-core/doc-kit/config' },
135+
filepath: join(process.cwd(), 'doc-kit.config.mjs'),
136+
}));
137+
138+
const result = await loadConfigFile('any');
139+
140+
assert.strictEqual(result.global.project, 'Node.js');
141+
assert.strictEqual(result.global.repository, 'nodejs/node');
142+
});
99143
});
100144

101145
describe('createConfigFromCLIOptions', () => {
@@ -250,6 +294,17 @@ describe('config.mjs', () => {
250294
assert.strictEqual(mockConfigSearch.mock.calls.length, 1);
251295
});
252296

297+
it('should default to project-neutral values', async () => {
298+
const config = await createRunConfiguration({});
299+
300+
// No repository, site, or release history is assumed; presets such as
301+
// @node-core/doc-kit/config opt back into the Node.js values
302+
assert.strictEqual(config.global.repository, undefined);
303+
assert.strictEqual(config.global.baseURL, undefined);
304+
assert.deepStrictEqual(config.global.changelog, []);
305+
assert.strictEqual(typeof config.global.project, 'string');
306+
});
307+
253308
it('should handle generator-specific overrides', async () => {
254309
mockConfigLoad.mock.mockImplementationOnce(async () => ({
255310
config: createMockConfig({

0 commit comments

Comments
 (0)