Skip to content

Commit 05bda7c

Browse files
committed
feat: make generator defaults project-neutral
1 parent 6c664f0 commit 05bda7c

29 files changed

Lines changed: 362 additions & 95 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: 25 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -46,16 +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-
--log-level <level> Log level (choices: "debug", "info", "warn", "error",
53-
"fatal", default: "info")
54-
-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
5555
5656
Commands:
57-
generate [options] Generate API docs
58-
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
5964
```
6065

6166
### `generate`
@@ -78,14 +83,14 @@ Options:
7883
(json-simple, legacy-html, legacy-html-all,
7984
man-page, legacy-json, legacy-json-all,
8085
addon-verify, api-links, orama-db, llms-txt,
81-
sitemap, web) or an import specifier for a custom
82-
generator
86+
sitemap, html) or an import specifier for a
87+
custom generator
8388
--ignore <patterns...> Ignore file patterns (glob)
8489
-o, --output <directory> The output directory
8590
-p, --threads <number> Number of threads to use (minimum: 1)
8691
--chunk-size <number> Number of items to process per worker thread
8792
(minimum: 1)
88-
-v, --version <semver> Target Node.js version
93+
-v, --version <semver> Target project version
8994
-c, --changelog <url> Changelog URL or path
9095
--git-ref <ref> Git ref
9196
--index <url> index.md URL or path
@@ -94,6 +99,17 @@ Options:
9499
-h, --help display help for command
95100
```
96101

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+
};
111+
```
112+
97113
### `install`
98114

99115
Built-in generators live in separate packages. `install` adds the packages

‎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 <ref>', 'Git ref'),
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)