feat(config): more customization

package.json

@@ -1,7 +1,7 @@
 {
   "name": "@node-core/doc-kit",
   "type": "module",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nodejs/doc-kit.git"
@@ -57,6 +57,7 @@
     "estree-util-to-js": "^2.0.0",
     "estree-util-visit": "^2.0.0",
     "github-slugger": "^2.0.0",
+    "glob-parent": "^6.0.2",
     "globals": "^17.3.0",
     "hast-util-to-string": "^3.0.1",
     "hastscript": "^9.0.1",
@@ -85,7 +86,6 @@
     "unist-util-remove": "^4.0.0",
     "unist-util-select": "^5.1.0",
     "unist-util-visit": "^5.1.0",
-    "vfile": "^6.0.3",
     "yaml": "^2.8.2"
   }
 }

src/generators/addon-verify/generate.mjs

@@ -1,6 +1,6 @@
 'use strict';
 
-import { mkdir, writeFile } from 'node:fs/promises';
+import { mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
 
 import { visit } from 'unist-util-visit';
@@ -13,6 +13,7 @@ import {
   normalizeSectionName,
 } from './utils/section.mjs';
 import getConfig from '../../utils/configuration/index.mjs';
+import { writeFile } from '../../utils/file.mjs';
 
 /**
  * Generates a file list from code blocks.

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                   |

src/generators/api-links/generate.mjs

@@ -1,16 +1,13 @@
 'use strict';
 
-import { writeFile } from 'node:fs/promises';
 import { basename, join } from 'node:path';
 
 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 { 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 => {

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}`,
+  },
 });

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>>>
 >;

src/generators/ast/generate.mjs

@@ -1,13 +1,14 @@
 'use strict';
 
 import { readFile } from 'node:fs/promises';
-import { extname } from 'node:path';
+import { relative, sep } from 'node:path/posix';
 
+import globParent from 'glob-parent';
 import { globSync } from 'tinyglobby';
-import { VFile } from 'vfile';
 
 import { STABILITY_INDEX_URL } from './constants.mjs';
 import getConfig from '../../utils/configuration/index.mjs';
+import { withExt } from '../../utils/file.mjs';
 import { QUERIES } from '../../utils/queries/index.mjs';
 import { getRemark } from '../../utils/remark.mjs';
 
@@ -24,19 +25,19 @@ export async function processChunk(inputSlice, itemIndices) {
 
   const results = [];
 
-  for (const path of filePaths) {
+  for (const [path, parent] of filePaths) {
     const content = await readFile(path, 'utf-8');
-    const vfile = new VFile({
-      path,
-      value: content.replace(
-        QUERIES.stabilityIndexPrefix,
-        match => `[${match}](${STABILITY_INDEX_URL})`
-      ),
-    });
+    const value = content.replace(
+      QUERIES.stabilityIndexPrefix,
+      match => `[${match}](${STABILITY_INDEX_URL})`
+    );
+
+    const relativePath = sep + withExt(relative(parent, path));
 
     results.push({
-      tree: remarkProcessor.parse(vfile),
-      file: { stem: vfile.stem, basename: vfile.basename },
+      tree: remarkProcessor.parse(value),
+      // The path is the relative path minus the extension
+      path: relativePath,
     });
   }
 
@@ -51,9 +52,14 @@ export async function processChunk(inputSlice, itemIndices) {
 export async function* generate(_, worker) {
   const { ast: config } = getConfig();
 
-  const files = globSync(config.input, { ignore: config.ignore }).filter(
-    p => extname(p) === '.md'
-  );
+  const files = config.input.flatMap(input => {
+    const parent = globParent(input);
+
+    return globSync(input, { ignore: config.ignore }).map(child => [
+      child,
+      parent,
+    ]);
+  });
 
   // Parse markdown files in parallel using worker threads
   for await (const chunkResult of worker.stream(files)) {

src/generators/json-simple/generate.mjs

@@ -1,11 +1,11 @@
 'use strict';
 
-import { writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 
 import { remove } from 'unist-util-remove';
 
 import getConfig from '../../utils/configuration/index.mjs';
+import { writeFile } from '../../utils/file.mjs';
 import { UNIST } from '../../utils/queries/index.mjs';
 
 /**

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 |

src/generators/jsx-ast/generate.mjs

@@ -1,7 +1,7 @@
 import { buildSideBarProps } from './utils/buildBarProps.mjs';
 import buildContent from './utils/buildContent.mjs';
 import { getSortedHeadNodes } from './utils/getSortedHeadNodes.mjs';
-import getConfig from '../../utils/configuration/index.mjs';
+import { href } from '../../utils/file.mjs';
 import { groupNodesByModule } from '../../utils/generators.mjs';
 import { getRemarkRecma } from '../../utils/remark.mjs';
 
@@ -22,7 +22,15 @@ export async function processChunk(slicedInput, itemIndices, docPages) {
   for (const idx of itemIndices) {
     const { head, entries } = slicedInput[idx];
 
-    const sideBarProps = buildSideBarProps(head, docPages);
+    const sideBarProps = buildSideBarProps(
+      head,
+      docPages.map(([heading, path]) => [
+        heading,
+        head.path === path
+          ? `${head.basename}.html`
+          : `${href(path, head.path)}.html`,
+      ])
+    );
 
     const content = await buildContent(
       entries,
@@ -43,17 +51,11 @@ export async function processChunk(slicedInput, itemIndices, docPages) {
  * @type {import('./types').Generator['generate']}
  */
 export async function* generate(input, worker) {
-  const config = getConfig('jsx-ast');
-
   const groupedModules = groupNodesByModule(input);
 
   const headNodes = getSortedHeadNodes(input);
 
-  // Pre-compute docPages once in main thread
-  // TODO(@avivkeller): Load the index file here instead of during configuration
-  const docPages = config.index
-    ? config.index.map(({ section, api }) => [section, `${api}.html`])
-    : headNodes.map(node => [node.heading.data.name, `${node.api}.html`]);
+  const docPages = headNodes.map(node => [node.heading.data.name, node.path]);
 
   // Create sliced input: each item contains head + its module's entries
   // This avoids sending all 4700+ entries to every worker