feat(config): more customization

avivkeller · avivkeller · commit 8cb94af23b8f · 2026-03-15T16:33:51.000-04:00
diff --git a/src/generators/api-links/README.md b/src/generators/api-links/README.md
@@ -6,7 +6,8 @@ The `api-links` generator creates a mapping of publicly accessible functions to
 
 The `api-links` generator accepts the following configuration options:
 
-| Name     | Type      | Default                 | Description                                         |
-| -------- | --------- | ----------------------- | --------------------------------------------------- |
-| `output` | `string`  | -                       | The directory where `apilinks.json` will be written |
-| `minify` | `boolean` | Inherited from `global` | Whether to minify the output JSON                   |
+| Name        | Type      | Default                              | Description                                         |
+| ----------- | --------- | ------------------------------------ | --------------------------------------------------- |
+| `output`    | `string`  | -                                    | The directory where `apilinks.json` will be written |
+| `sourceURL` | `string`  | `'${GITHUB_BLOB_URL}lib/{fileName}'` | URL template for linking to source files            |
+| `minify`    | `boolean` | Inherited from `global`              | Whether to minify the output JSON                   |
diff --git a/src/generators/api-links/generate.mjs b/src/generators/api-links/generate.mjs
@@ -6,11 +6,8 @@ import { checkIndirectReferences } from './utils/checkIndirectReferences.mjs';
 import { extractExports } from './utils/extractExports.mjs';
 import { findDefinitions } from './utils/findDefinitions.mjs';
 import getConfig from '../../utils/configuration/index.mjs';
-import {
-  GITHUB_BLOB_URL,
-  populate,
-} from '../../utils/configuration/templates.mjs';
-import { writeFile } from '../../utils/file.mjs';
+import { populate } from '../../utils/configuration/templates.mjs';
+import { withExt, writeFile } from '../../utils/file.mjs';
 
 /**
  * Generates the `apilinks.json` file.
@@ -33,16 +30,19 @@ export async function generate(input) {
      */
     const nameToLineNumberMap = {};
 
-    // `http.js` -> `http`
-    const baseName = basename(program.path, '.js');
+    const fileName = basename(program.path);
+    const baseName = withExt(fileName);
 
     const exports = extractExports(program, baseName, nameToLineNumberMap);
 
     findDefinitions(program, baseName, nameToLineNumberMap, exports);
 
     checkIndirectReferences(program, exports, nameToLineNumberMap);
 
-    const fullGitUrl = `${populate(GITHUB_BLOB_URL, config)}lib/${baseName}.js`;
+    const fullGitUrl = populate(config.sourceURL, {
+      ...config,
+      fileName,
+    });
 
     // Add the exports we found in this program to our output
     Object.keys(nameToLineNumberMap).forEach(key => {
diff --git a/src/generators/api-links/index.mjs b/src/generators/api-links/index.mjs
@@ -1,5 +1,6 @@
 'use strict';
 
+import { GITHUB_BLOB_URL } from '../../utils/configuration/templates.mjs';
 import { createLazyGenerator } from '../../utils/generators.mjs';
 
 /**
@@ -23,4 +24,8 @@ export default createLazyGenerator({
   // Unlike the rest of the generators, this utilizes Javascript sources being
   // passed into the input field rather than Markdown.
   dependsOn: 'ast-js',
+
+  defaultConfiguration: {
+    sourceURL: `${GITHUB_BLOB_URL}lib/{fileName}`,
+  },
 });
diff --git a/src/generators/api-links/types.d.ts b/src/generators/api-links/types.d.ts
@@ -5,6 +5,8 @@ export interface ProgramExports {
 }
 
 export type Generator = GeneratorMetadata<
-  {},
+  {
+    sourceURL: string;
+  },
   Generate<undefined, Promise<Record<string, string>>>
 >;
diff --git a/src/generators/jsx-ast/README.md b/src/generators/jsx-ast/README.md
@@ -6,7 +6,9 @@ The `jsx-ast` generator converts MDAST (Markdown Abstract Syntax Tree) to JSX AS
 
 The `jsx-ast` generator accepts the following configuration options:
 
-| Name    | Type     | Default  | Description                                                              |
-| ------- | -------- | -------- | ------------------------------------------------------------------------ |
-| `ref`   | `string` | `'main'` | Git reference/branch for linking to source files                         |
-| `index` | `array`  | -        | Array of `{ section, api }` objects defining the documentation structure |
+| Name      | Type     | Default                                       | Description                                                              |
+| --------- | -------- | --------------------------------------------- | ------------------------------------------------------------------------ |
+| `ref`     | `string` | `'main'`                                      | Git reference/branch for linking to source files                         |
+| `pageURL` | `string` | `'{baseURL}/latest-{version}/api{path}.html'` | URL template for documentation page links                                |
+| `editURL` | `string` | `'${GITHUB_EDIT_URL}/doc/api{path}.md'`       | URL template for "edit this page" links                                  |
+| `index`   | `array`  | -                                             | Array of `{ section, api }` objects defining the documentation structure |
diff --git a/src/generators/jsx-ast/index.mjs b/src/generators/jsx-ast/index.mjs
@@ -1,5 +1,6 @@
 'use strict';
 
+import { GITHUB_EDIT_URL } from '../../utils/configuration/templates.mjs';
 import { createLazyGenerator } from '../../utils/generators.mjs';
 
 /**
@@ -18,6 +19,8 @@ export default createLazyGenerator({
 
   defaultConfiguration: {
     ref: 'main',
+    pageURL: '{baseURL}/latest-{version}/api{path}.html',
+    editURL: `${GITHUB_EDIT_URL}/doc/api{path}.md`,
   },
 
   hasParallelProcessor: true,
diff --git a/src/generators/jsx-ast/types.d.ts b/src/generators/jsx-ast/types.d.ts
@@ -2,7 +2,10 @@ import type { MetadataEntry } from '../metadata/types';
 import type { JSXContent } from './utils/buildContent.mjs';
 
 export type Generator = GeneratorMetadata<
-  {},
+  {
+    pageURL: string;
+    editURL: string;
+  },
   Generate<Array<MetadataEntry>, AsyncGenerator<JSXContent>>,
   ProcessChunk<
     { head: MetadataEntry; entries: Array<MetadataEntry> },
diff --git a/src/generators/jsx-ast/utils/__tests__/buildBarProps.test.mjs b/src/generators/jsx-ast/utils/__tests__/buildBarProps.test.mjs
@@ -128,22 +128,20 @@ describe('formatVersionOptions', () => {
       { version: new SemVer('18.0.0'), isLts: false, isCurrent: false },
     ];
 
-    const api = 'http';
-
-    const result = formatVersionOptions(versions, api);
+    const result = formatVersionOptions(versions, '/http');
 
     assert.deepStrictEqual(result, [
       {
+        value: 'https://nodejs.org/docs/latest-v16.x/api/http.html',
         label: 'v16.x (LTS)',
-        value: '/api/16.x/http',
       },
       {
+        value: 'https://nodejs.org/docs/latest-v17.x/api/http.html',
         label: 'v17.x (Current)',
-        value: '/api/17.x/http',
       },
       {
+        value: 'https://nodejs.org/docs/latest-v18.x/api/http.html',
         label: 'v18.x',
-        value: '/api/18.x/http',
       },
     ]);
   });
diff --git a/src/generators/jsx-ast/utils/buildBarProps.mjs b/src/generators/jsx-ast/utils/buildBarProps.mjs
@@ -4,14 +4,10 @@ import readingTime from 'reading-time';
 import { visit } from 'unist-util-visit';
 
 import getConfig from '../../../utils/configuration/index.mjs';
-import {
-  GITHUB_EDIT_URL,
-  populate,
-} from '../../../utils/configuration/templates.mjs';
+import { populate } from '../../../utils/configuration/templates.mjs';
 import {
   getCompatibleVersions,
   getVersionFromSemVer,
-  getVersionURL,
 } from '../../../utils/generators.mjs';
 import { TOC_MAX_HEADING_DEPTH } from '../constants.mjs';
 
@@ -93,7 +89,7 @@ export const buildMetaBarProps = (head, entries) => {
       ['JSON', `${head.basename}.json`],
       ['MD', `${head.basename}.md`],
     ],
-    editThisPage: `${populate(GITHUB_EDIT_URL, config)}${head.path}.md`,
+    editThisPage: populate(config.editURL, { ...config, path: head.path }),
   };
 };
 
@@ -107,10 +103,13 @@ export const formatVersionOptions = (compatibleVersions, path) => {
   const config = getConfig('jsx-ast');
 
   return compatibleVersions.map(({ version, isLts, isCurrent }) => {
-    const parsed = getVersionFromSemVer(version);
-    const value = getVersionURL(parsed, path, config.baseURL);
+    let label = `v${getVersionFromSemVer(version)}`;
 
-    let label = `v${parsed}`;
+    const value = populate(config.pageURL, {
+      ...config,
+      path,
+      version: label,
+    });
 
     if (isLts) {
       label += ' (LTS)';
diff --git a/src/generators/legacy-html/README.md b/src/generators/legacy-html/README.md
@@ -6,11 +6,13 @@ The `legacy-html` generator creates legacy HTML documentation pages for Node.js
 
 The `legacy-html` generator accepts the following configuration options:
 
-| Name                    | Type       | Default                 | Description                                                              |
-| ----------------------- | ---------- | ----------------------- | ------------------------------------------------------------------------ |
-| `output`                | `string`   | -                       | The directory where HTML files and assets will be written                |
-| `templatePath`          | `string`   | `'template.html'`       | Path to the HTML template file                                           |
-| `additionalPathsToCopy` | `string[]` | `['assets']`            | Array of paths to copy to the output directory                           |
-| `ref`                   | `string`   | `'main'`                | Git reference/branch for linking to source files                         |
-| `index`                 | `array`    | -                       | Array of `{ api, section }` objects defining the documentation structure |
-| `minify`                | `boolean`  | Inherited from `global` | Whether to minify the output HTML                                        |
+| Name                    | Type       | Default                                       | Description                                                              |
+| ----------------------- | ---------- | --------------------------------------------- | ------------------------------------------------------------------------ |
+| `output`                | `string`   | -                                             | The directory where HTML files and assets will be written                |
+| `templatePath`          | `string`   | `'template.html'`                             | Path to the HTML template file                                           |
+| `additionalPathsToCopy` | `string[]` | `['assets']`                                  | Array of paths to copy to the output directory                           |
+| `ref`                   | `string`   | `'main'`                                      | Git reference/branch for linking to source files                         |
+| `pageURL`               | `string`   | `'{baseURL}/latest-{version}/api{path}.html'` | URL template for documentation page links                                |
+| `editURL`               | `string`   | `'${GITHUB_EDIT_URL}/doc/api{path}.md'`       | URL template for "edit this page" links                                  |
+| `index`                 | `array`    | -                                             | Array of `{ api, section }` objects defining the documentation structure |
+| `minify`                | `boolean`  | Inherited from `global`                       | Whether to minify the output HTML                                        |
diff --git a/src/generators/legacy-html/index.mjs b/src/generators/legacy-html/index.mjs
@@ -2,6 +2,7 @@
 
 import { join } from 'node:path';
 
+import { GITHUB_EDIT_URL } from '../../utils/configuration/templates.mjs';
 import { createLazyGenerator } from '../../utils/generators.mjs';
 
 /**
@@ -28,6 +29,8 @@ export default createLazyGenerator({
     templatePath: join(import.meta.dirname, 'template.html'),
     additionalPathsToCopy: [join(import.meta.dirname, 'assets')],
     ref: 'main',
+    pageURL: '{baseURL}/latest-{version}/api{path}.html',
+    editURL: `${GITHUB_EDIT_URL}/doc/api{path}.md`,
   },
 
   hasParallelProcessor: true,
diff --git a/src/generators/legacy-html/types.d.ts b/src/generators/legacy-html/types.d.ts
@@ -12,6 +12,8 @@ export interface TemplateValues {
 export type Generator = GeneratorMetadata<
   {
     templatePath: string;
+    pageURL: string;
+    editURL: string;
     additionalPathsToCopy: Array<string>;
   },
   Generate<Array<MetadataEntry>, AsyncGenerator<TemplateValues>>,
diff --git a/src/generators/legacy-html/utils/buildDropdowns.mjs b/src/generators/legacy-html/utils/buildDropdowns.mjs
@@ -1,10 +1,10 @@
 'use strict';
 
 import getConfig from '../../../utils/configuration/index.mjs';
+import { populate } from '../../../utils/configuration/templates.mjs';
 import {
   getCompatibleVersions,
   getVersionFromSemVer,
-  getVersionURL,
 } from '../../../utils/generators.mjs';
 
 /**
@@ -61,10 +61,15 @@ export const buildVersions = (path, added, versions) => {
   // Then we create a `<li>` entry for said version, ensuring we link to the correct API doc
   const versionsAsList = compatibleVersions.map(({ version, isLts }) => {
     const parsedVersion = getVersionFromSemVer(version);
+    const href = populate(config.pageURL, {
+      ...config,
+      path,
+      version: parsedVersion,
+    });
 
     const ltsLabel = isLts ? '<b>LTS</b>' : '';
 
-    return `<li><a href="${getVersionURL(parsedVersion, path, config.baseURL)}">${parsedVersion} ${ltsLabel}</a></li>`;
+    return `<li><a href="${href}">${parsedVersion} ${ltsLabel}</a></li>`;
   });
 
   return (
diff --git a/src/generators/legacy-html/utils/replaceTemplateValues.mjs b/src/generators/legacy-html/utils/replaceTemplateValues.mjs
@@ -7,10 +7,7 @@ import {
   buildGitHub,
 } from './buildDropdowns.mjs';
 import tableOfContents from './tableOfContents.mjs';
-import {
-  GITHUB_EDIT_URL,
-  populate,
-} from '../../../utils/configuration/templates.mjs';
+import { populate } from '../../../utils/configuration/templates.mjs';
 
 /**
  * Replaces the template values in the API template with the given values.
@@ -41,6 +38,6 @@ export const replaceTemplateValues = (
       '__EDIT_ON_GITHUB__',
       skipGitHub
         ? ''
-        : buildGitHub(`${populate(GITHUB_EDIT_URL, config)}${path}.md`)
+        : buildGitHub(populate(config.editURL, { ...config, path }))
     );
 };
diff --git a/src/generators/llms-txt/README.md b/src/generators/llms-txt/README.md
@@ -6,8 +6,8 @@ The `llms-txt` generator creates a `llms.txt` file to provide information to Lar
 
 The `llms-txt` generator accepts the following configuration options:
 
-| Name           | Type     | Default                 | Description                                    |
-| -------------- | -------- | ----------------------- | ---------------------------------------------- |
-| `output`       | `string` | -                       | The directory where `llms.txt` will be written |
-| `templatePath` | `string` | `'template.txt'`        | Path to the template file                      |
-| `baseURL`      | `string` | Inherited from `global` | Base URL for generating documentation links    |
+| Name           | Type     | Default                           | Description                                    |
+| -------------- | -------- | --------------------------------- | ---------------------------------------------- |
+| `output`       | `string` | -                                 | The directory where `llms.txt` will be written |
+| `templatePath` | `string` | `'template.txt'`                  | Path to the template file                      |
+| `pageURL`      | `string` | `'{baseURL}/latest/api{path}.md'` | URL template for documentation page links      |
diff --git a/src/generators/llms-txt/generate.mjs b/src/generators/llms-txt/generate.mjs
@@ -19,7 +19,7 @@ export async function generate(input) {
 
   const apiDocsLinks = input
     .filter(entry => entry.heading.depth === 1)
-    .map(entry => `- ${buildApiDocLink(entry, config.baseURL)}`)
+    .map(entry => `- ${buildApiDocLink(entry, config)}`)
     .join('\n');
 
   const filledTemplate = `${template}${apiDocsLinks}`;
diff --git a/src/generators/llms-txt/index.mjs b/src/generators/llms-txt/index.mjs
@@ -22,5 +22,6 @@ export default createLazyGenerator({
 
   defaultConfiguration: {
     templatePath: join(import.meta.dirname, 'template.txt'),
+    pageURL: '{baseURL}/latest/api{path}.md',
   },
 });
diff --git a/src/generators/llms-txt/types.d.ts b/src/generators/llms-txt/types.d.ts
@@ -3,6 +3,7 @@ import { MetadataEntry } from '../metadata/types';
 export type Generator = GeneratorMetadata<
   {
     templatePath: string;
+    pageURL: string;
   },
   Generate<Array<MetadataEntry>, Promise<string>>
 >;
diff --git a/src/generators/llms-txt/utils/__tests__/buildApiDocLink.test.mjs b/src/generators/llms-txt/utils/__tests__/buildApiDocLink.test.mjs
@@ -69,21 +69,31 @@ describe('buildApiDocLink', () => {
       llm_description: 'Test description',
     };
 
-    const result = buildApiDocLink(entry, 'https://example.com');
+    const config = {
+      baseURL: 'https://example.com',
+      pageURL: '{baseURL}/docs/latest/api{path}.md',
+    };
+
+    const result = buildApiDocLink(entry, config);
     assert.strictEqual(
       result,
       '[Test API](https://example.com/docs/latest/api/test.md): Test description'
     );
   });
 
-  it('handles doc path replacement', () => {
+  it('handles custom pageURL template', () => {
     const entry = {
       heading: { data: { name: 'API Method' } },
       path: '/path',
       content: { children: [] },
     };
 
-    const result = buildApiDocLink(entry, 'https://example.com');
-    assert.ok(result.includes('https://example.com/docs/latest/api/path.md'));
+    const config = {
+      baseURL: 'https://example.com',
+      pageURL: '{baseURL}/api{path}.md',
+    };
+
+    const result = buildApiDocLink(entry, config);
+    assert.ok(result.includes('https://example.com/api/path.md'));
   });
 });
diff --git a/src/generators/llms-txt/utils/buildApiDocLink.mjs b/src/generators/llms-txt/utils/buildApiDocLink.mjs
@@ -1,4 +1,4 @@
-import { buildApiDocURL } from '../../../utils/generators.mjs';
+import { populate } from '../../../utils/configuration/templates.mjs';
 import { transformNodeToString } from '../../../utils/unist.mjs';
 
 /**
@@ -33,13 +33,16 @@ export const getEntryDescription = entry => {
  * Builds a markdown link for an API doc entry
  *
  * @param {import('../../metadata/types').MetadataEntry} entry
- * @param {string} baseURL
+ * @param {import('../../../utils/configuration/types').Configuration['llms-txt']}
  * @returns {string}
  */
-export const buildApiDocLink = (entry, baseURL) => {
+export const buildApiDocLink = (entry, config) => {
   const title = entry.heading.data.name;
 
-  const url = buildApiDocURL(entry, baseURL);
+  const url = populate(config.pageURL, {
+    ...config,
+    path: entry.path,
+  });
 
   const link = `[${title}](${url})`;
 
diff --git a/src/generators/man-page/generate.mjs b/src/generators/man-page/generate.mjs
diff --git a/src/generators/sitemap/README.md b/src/generators/sitemap/README.md
diff --git a/src/generators/sitemap/generate.mjs b/src/generators/sitemap/generate.mjs
diff --git a/src/generators/sitemap/index.mjs b/src/generators/sitemap/index.mjs
diff --git a/src/generators/sitemap/types.d.ts b/src/generators/sitemap/types.d.ts
diff --git a/src/generators/sitemap/utils/createPageSitemapEntry.mjs b/src/generators/sitemap/utils/createPageSitemapEntry.mjs
diff --git a/src/utils/configuration/templates.mjs b/src/utils/configuration/templates.mjs
diff --git a/src/utils/generators.mjs b/src/utils/generators.mjs

Original file line number	Diff line number	Diff line change
`@@ -5,6 +5,8 @@ export interface ProgramExports {`
`5`	`5`	`}`
`6`	`6`
`7`	`7`	`export type Generator = GeneratorMetadata<`
`8`		`- {},`
	`8`	`+ {`
	`9`	`+ sourceURL: string;`
	`10`	`+ },`
`9`	`11`	`Generate<undefined, Promise<Record<string, string>>>`
`10`	`12`	`>;`