feat(config): more customization (#682)

* feat(config): more customization

* fixup!

* bump version

Author: avivkeller

package-lock.json

@@ -1,7 +1,7 @@
 {
   "name": "@node-core/doc-kit",
   "type": "module",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nodejs/doc-kit.git"

package.json

@@ -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/README.md

@@ -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 => {

src/generators/api-links/generate.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/index.mjs

@@ -5,6 +5,8 @@ export interface ProgramExports {
 }
 
 export type Generator = GeneratorMetadata<
-  {},
+  {
+    sourceURL: string;
+  },
   Generate<undefined, Promise<Record<string, string>>>
 >;

src/generators/api-links/types.d.ts

@@ -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/README.md

@@ -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,

src/generators/jsx-ast/index.mjs

@@ -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> },

src/generators/jsx-ast/types.d.ts

@@ -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',
       },
     ]);
   });