feat(404): add customizable not found page text and link options

src/generators/jsx-ast/README.md

@@ -6,10 +6,13 @@ 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 |
-| `generateAllPage`      | `boolean` | `true`   | When `true`, creates a synthetic JSX AST entry for `all.html`            |
-| `generateIndexPage`    | `boolean` | `true`   | When `true`, creates a synthetic JSX AST entry for `index.html`          |
-| `generateNotFoundPage` | `boolean` | `true`   | When `true`, creates a synthetic JSX AST entry for `404.html`            |
+| 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 |
+| `generateAllPage`      | `boolean` | `true`                                                                                                                             | When `true`, creates a synthetic JSX AST entry for `all.html`            |
+| `generateIndexPage`    | `boolean` | `true`                                                                                                                             | When `true`, creates a synthetic JSX AST entry for `index.html`          |
+| `generateNotFoundPage` | `boolean` | `true`                                                                                                                             | When `true`, creates a synthetic JSX AST entry for `404.html`            |
+| `notFoundText`         | `string`  | `'The page you requested could not be found. Use the navigation to find the documentation you are looking for, or return to the '` | Lead-in text shown before the link on the synthetic `404.html` page      |
+| `notFoundLinkUrl`      | `string`  | `'index.html'`                                                                                                                     | URL of the link shown on the synthetic `404.html` page                   |
+| `notFoundLinkText`     | `string`  | `'API index'`                                                                                                                      | Text of the link shown on the synthetic `404.html` page                  |

src/generators/jsx-ast/generate.mjs

@@ -22,7 +22,7 @@ const buildSyntheticDescriptors = input => {
   return [
     config.generateAllPage && buildAllPage(input),
     config.generateIndexPage && buildIndexPage(input),
-    config.generateNotFoundPage && buildNotFoundPage(),
+    config.generateNotFoundPage && buildNotFoundPage(config),
   ].filter(Boolean);
 };
 

src/generators/jsx-ast/index.mjs

@@ -1,5 +1,6 @@
 'use strict';
 
+import { NOT_FOUND_DEFAULTS } from './utils/synthetic/404.mjs';
 import { createLazyGenerator } from '../../utils/generators.mjs';
 
 /**
@@ -21,6 +22,7 @@ export default createLazyGenerator({
     generateAllPage: true,
     generateIndexPage: true,
     generateNotFoundPage: true,
+    ...NOT_FOUND_DEFAULTS,
   },
 
   hasParallelProcessor: true,

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

@@ -7,6 +7,9 @@ export type Generator = GeneratorMetadata<
     generateAllPage: boolean;
     generateIndexPage: boolean;
     generateNotFoundPage: boolean;
+    notFoundText: string;
+    notFoundLinkUrl: string;
+    notFoundLinkText: string;
   },
   Generate<Array<MetadataEntry>, AsyncGenerator<JSXContent>>,
   ProcessChunk<

src/generators/jsx-ast/utils/synthetic/404.mjs

@@ -2,10 +2,30 @@
 
 import { createSyntheticHead, wrapAsEntry } from './synthetic.mjs';
 
+/**
+ * Default configuration for the synthetic `404.html` page. Re-exported so the
+ * `jsx-ast` generator's `defaultConfiguration` can reuse the same values
+ * instead of duplicating them.
+ */
+export const NOT_FOUND_DEFAULTS = {
+  notFoundText:
+    'The page you requested could not be found. Use the navigation to find the documentation you are looking for, or return to the ',
+  notFoundLinkUrl: 'index.html',
+  notFoundLinkText: 'API index',
+};
+
 /**
  * Builds the page descriptor for `404.html`
+ *
+ * @param {Partial<Pick<import('../../types').Generator['defaultConfiguration'], 'notFoundText' | 'notFoundLinkUrl' | 'notFoundLinkText'>>} config
  */
-export const buildNotFoundPage = () => {
+export const buildNotFoundPage = (config = {}) => {
+  const {
+    notFoundText = NOT_FOUND_DEFAULTS.notFoundText,
+    notFoundLinkUrl = NOT_FOUND_DEFAULTS.notFoundLinkUrl,
+    notFoundLinkText = NOT_FOUND_DEFAULTS.notFoundLinkText,
+  } = config;
+
   const head = createSyntheticHead('404', 'Page Not Found');
 
   return {
@@ -17,13 +37,12 @@ export const buildNotFoundPage = () => {
           children: [
             {
               type: 'text',
-              value:
-                'The page you requested could not be found. Use the navigation to find the documentation you are looking for, or return to the ',
+              value: notFoundText,
             },
             {
               type: 'link',
-              url: 'index.html',
-              children: [{ type: 'text', value: 'API index' }],
+              url: notFoundLinkUrl,
+              children: [{ type: 'text', value: notFoundLinkText }],
             },
             {
               type: 'text',

src/generators/jsx-ast/utils/synthetic/__tests__/404.test.mjs

@@ -45,4 +45,23 @@ describe('buildNotFoundPage', () => {
     assert.deepEqual(a.head, b.head);
     assert.equal(a.entries.length, b.entries.length);
   });
+
+  it('honors custom text and link configuration', () => {
+    const { entries } = buildNotFoundPage({
+      notFoundText: 'Nothing here. Go back to the ',
+      notFoundLinkUrl: 'home.html',
+      notFoundLinkText: 'homepage',
+    });
+
+    const paragraph = entries[0].content.children.find(
+      child => child.type === 'paragraph'
+    );
+
+    assert.equal(paragraph.children[0].value, 'Nothing here. Go back to the ');
+
+    const link = paragraph.children.find(child => child.type === 'link');
+
+    assert.equal(link.url, 'home.html');
+    assert.equal(link.children[0].value, 'homepage');
+  });
 });