feat: project-neutral defaults + @node-core/doc-kit/config preset

Author: avivkeller

.changeset/node-preset.md

@@ -0,0 +1,5 @@
+---
+'@node-core/doc-kit': minor
+---
+
+Add the `@node-core/doc-kit/config` preset

.changeset/plain-defaults.md

@@ -0,0 +1,6 @@
+---
+'@nodejs/doc-kit': patch
+'@nodejs/doc-kit-generator-react': minor
+---
+
+Defaults are now project-neutral instead of Node.js-specific

beta/doc-kit.config.mjs

@@ -1,4 +1,6 @@
 export default {
+  extends: '@node-core/doc-kit/config',
+
   html: {
     remoteConfigUrl:
       'https://raw.githubusercontent.com/nodejs/doc-kit/main/beta/site.json',

docs/configuration.md

@@ -17,50 +17,75 @@ export default {
   global: {
     input: ['docs/**/*.md'],
     output: 'out',
+    project: 'My Project',
     version: '1.2.0',
     baseURL: 'https://example.com/docs',
-    changelog: [],
   },
 
   // Generator-specific sections, keyed by generator name
   html: {
-    project: 'My Project',
+    title: '{project} Documentation',
   },
 };
 ```
 
+## Presets (`extends`)
+
+A configuration file may declare `extends`: one or more presets whose values
+are merged underneath its own. Each entry is either an import specifier of a
+module whose default export is a configuration object, or a path relative to
+the configuration file:
+
+```mjs displayName="doc-kit.config.mjs"
+export default {
+  // Build the docs the way nodejs.org does — branding, URL layouts,
+  // and release history included
+  extends: '@node-core/doc-kit/config',
+
+  html: {
+    // Your own values still win over the preset
+    title: '{project} {version} API Reference',
+  },
+};
+```
+
+`extends` also accepts an array; later presets take precedence over earlier
+ones, and the configuration file itself wins over all of them.
+
+The built-in defaults are deliberately project-neutral: no repository, site
+URL, release history, or branding is assumed. The
+[`@node-core/doc-kit/config`](./packages/node.md) preset opts back into
+everything Node.js-specific.
+
 ## How values merge
 
-Three sources, in order of precedence:
+Four sources, in order of precedence:
 
 1. **CLI flags** (see the [CLI reference](./cli.md)) override
 2. **the configuration file**, which overrides
-3. **built-in defaults**.
+3. **presets** (listed in the file's `extends`), which override
+4. **built-in defaults**.
 
 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.
 
 ## Global options
 
-| 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']` |
-
-> The defaults still reflect doc-kit's Node.js origins: `changelog`,
-> `repository`, and `baseURL` point at the Node.js project unless you set
-> them. `doc-kit bootstrap` writes a configuration that overrides the ones
-> your project needs.
+| 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`                 |
+| `project`     | `string`                  | The name of the project being documented, used in titles, logos, and templated text.                                                                                               | The `name` in your `package.json` |
+| `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.                                                                | `[]` (single-version output)      |
+| `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).                                                             | —                                 |
+| `repository`  | `string`                  | GitHub repository in `owner/repo` form, used for source and edit links; without one, repository-specific UI (like the GitHub link) is omitted.                                     | —                                 |
+| `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']`  |
 
 ## Execution options
 
@@ -79,7 +104,7 @@ Each generator documents its own options on its reference page — see the
 ```js
 export default {
   html: {
-    project: 'My Project',
+    title: '{project} Documentation',
   },
 
   metadata: {

docs/customization.md

@@ -4,7 +4,7 @@ This page walks the customizations most projects make, in the
 order they usually make them. The complete option list lives in the
 [`html` generator reference](./generators/html.md).
 
-All of it goes in the `html` section of your configuration file:
+Most of it goes in the `html` section of your configuration file:
 
 ```js
 // doc-kit.config.mjs
@@ -24,17 +24,18 @@ export default {
 ## Name and titles
 
 ```js
+global: {
+  project: 'My Project', // Used in page titles, the logo, and the version selector
+},
+
 html: {
-  project: 'My Project', // Used in page titles and the version selector
   title: '{project} Documentation', // Browser-tab title template
-  // Suppress the Node.js announcement banner fetched at runtime
-  remoteConfigUrl: '',
 },
 ```
 
-`title` supports `{project}` and `{version}` placeholders. Projects that
-bootstrap with `doc-kit bootstrap` get `project` wired to their
-`package.json` automatically.
+`project` defaults to the `name` in your `package.json` (and `doc-kit
+bootstrap` writes it into the configuration explicitly); `title` supports
+`{project}` and `{version}` placeholders.
 
 ## The `<head>`
 
@@ -96,8 +97,9 @@ sidebar also shows a version selector when your configuration provides a
 
 ## Logo and theme components
 
-The page chrome is built from swappable components. Override any `#theme/*`
-alias with a path to your own:
+By default the logo slot renders your project's name as plain text. The page
+chrome is built from swappable components — give it a real logo (or replace
+any other part) by overriding a `#theme/*` alias with a path to your own:
 
 ```js
 html: {

docs/troubleshooting.md

@@ -25,22 +25,6 @@ The search box queries an index built by the `orama-db` generator. Generate
 it alongside the site — `target: ['html', 'orama-db']` — and make sure
 you're serving over HTTP, not `file://`.
 
-## The build fetches from nodejs.org (or fails offline)
-
-Two defaults reach for the network: `changelog` and `index` point at the
-Node.js repository unless you say otherwise. A project without a release
-history can short-circuit both with empty values:
-
-```js
-global: {
-  changelog: [],
-  index: [],
-},
-```
-
-Or point them at your own files — see the
-[configuration reference](./configuration.md).
-
 ## `bootstrap` or `install` couldn't install packages
 
 Package installation runs through your package manager, so registry issues

packages/core/bin/commands/bootstrap.mjs

@@ -138,7 +138,7 @@ export default new Command('bootstrap')
           })
         );
         bootstrapLogger.info(
-          'Created doc-kit.config.mjs (wired to your package.json)'
+          'Created doc-kit.config.mjs (naming and versioning follow your package.json)'
         );
 
         // 4. Ignore the output directory

packages/core/src/utils/__tests__/bootstrap.test.mjs

@@ -89,18 +89,6 @@ describe('buildConfigSource', () => {
     assert.match(source, /\/\/ baseURL: /);
     assert.doesNotMatch(source, /baseURL: packageJson.homepage/);
   });
-
-  it('should only emit the html block when html is targeted', () => {
-    const source = buildConfigSource({
-      targets: ['llms-txt'],
-      docsDir: 'docs',
-      output: 'out',
-      hasHomepage: false,
-    });
-
-    assert.doesNotMatch(source, /html: \{/);
-    assert.doesNotMatch(source, /project:/);
-  });
 });
 
 describe('addIgnoredOutput', () => {

packages/core/src/utils/bootstrap.mjs

@@ -112,31 +112,21 @@ export const buildConfigSource = ({
     // sitemaps, and llms.txt page URLs
     // baseURL: 'https://example.com/docs',`;
 
-  // The project name is an html-generator option, so it only belongs in a
-  // configuration that targets html
-  const html = targets.includes('html')
-    ? `
-
-  html: {
-    // The name shown in page titles, the logo, and the version picker
-    project: packageJson.name,
-  },`
-    : '';
-
   return `import packageJson from './package.json' with { type: 'json' };
 
 /** @type {import('@nodejs/doc-kit/utils/configuration/types').Configuration} */
 export default {
   target: ${JSON.stringify(targets)},
 
   global: {
-    // Versioning follows package.json
+    // Naming and versioning follow package.json
+    project: packageJson.name,
     version: packageJson.version,
 
     input: [${JSON.stringify(`${docsDir}/**/*.md`)}],
     output: ${JSON.stringify(output)},
 ${baseURL}
-  },${html}
+  },
 };
 `;
 };

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

@@ -1,4 +1,7 @@
 import assert from 'node:assert';
+import { mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
 import { describe, it, mock, beforeEach } from 'node:test';
 
 // Mock dependencies
@@ -96,6 +99,47 @@ describe('config.mjs', () => {
       );
       assert.strictEqual(mockConfigSearch.mock.calls.length, 0);
     });
+
+    it('should merge extends presets underneath the config file', async () => {
+      const dir = mkdtempSync(join(tmpdir(), 'doc-kit-config-'));
+
+      writeFileSync(
+        join(dir, 'base.mjs'),
+        'export default { global: { project: "Base", ref: "base" }, html: { a: 1 } };'
+      );
+      writeFileSync(
+        join(dir, 'other.mjs'),
+        'export default { global: { project: "Other" }, html: { b: 2 } };'
+      );
+
+      mockConfigLoad.mock.mockImplementationOnce(async () => ({
+        config: {
+          extends: ['./base.mjs', './other.mjs'],
+          global: { ref: 'own' },
+        },
+        filepath: join(dir, 'doc-kit.config.mjs'),
+      }));
+
+      const result = await loadConfigFile('any');
+
+      // Later presets win over earlier ones; the file itself wins over all
+      assert.deepStrictEqual(result, {
+        global: { project: 'Other', ref: 'own' },
+        html: { a: 1, b: 2 },
+      });
+    });
+
+    it('should resolve extends package specifiers from the config file', async () => {
+      mockConfigLoad.mock.mockImplementationOnce(async () => ({
+        config: { extends: '@node-core/doc-kit/config' },
+        filepath: join(process.cwd(), 'doc-kit.config.mjs'),
+      }));
+
+      const result = await loadConfigFile('any');
+
+      assert.strictEqual(result.global.project, 'Node.js');
+      assert.strictEqual(result.global.repository, 'nodejs/node');
+    });
   });
 
   describe('createConfigFromCLIOptions', () => {
@@ -250,6 +294,17 @@ describe('config.mjs', () => {
       assert.strictEqual(mockConfigSearch.mock.calls.length, 1);
     });
 
+    it('should default to project-neutral values', async () => {
+      const config = await createRunConfiguration({});
+
+      // No repository, site, or release history is assumed; presets such as
+      // @node-core/doc-kit/config opt back into the Node.js values
+      assert.strictEqual(config.global.repository, undefined);
+      assert.strictEqual(config.global.baseURL, undefined);
+      assert.deepStrictEqual(config.global.changelog, []);
+      assert.strictEqual(typeof config.global.project, 'string');
+    });
+
     it('should handle generator-specific overrides', async () => {
       mockConfigLoad.mock.mockImplementationOnce(async () => ({
         config: createMockConfig({