From 4ed557c82595b113b112ea93807e13a58a793d8f Mon Sep 17 00:00:00 2001 From: Brian Muenzenmeyer Date: Thu, 2 Jul 2026 10:18:20 -0500 Subject: [PATCH 1/2] feat(404): add customizable not found page text and link options --- src/generators/jsx-ast/README.md | 3 ++ src/generators/jsx-ast/generate.mjs | 2 +- src/generators/jsx-ast/index.mjs | 2 ++ src/generators/jsx-ast/types.d.ts | 3 ++ .../jsx-ast/utils/synthetic/404.mjs | 29 +++++++++++++++---- .../utils/synthetic/__tests__/404.test.mjs | 19 ++++++++++++ 6 files changed, 52 insertions(+), 6 deletions(-) diff --git a/src/generators/jsx-ast/README.md b/src/generators/jsx-ast/README.md index fcc902a5..97b7815e 100644 --- a/src/generators/jsx-ast/README.md +++ b/src/generators/jsx-ast/README.md @@ -13,3 +13,6 @@ The `jsx-ast` generator accepts the following configuration options: | `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 | diff --git a/src/generators/jsx-ast/generate.mjs b/src/generators/jsx-ast/generate.mjs index 055e0efb..309025da 100644 --- a/src/generators/jsx-ast/generate.mjs +++ b/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); }; diff --git a/src/generators/jsx-ast/index.mjs b/src/generators/jsx-ast/index.mjs index d6711061..92e16bcd 100644 --- a/src/generators/jsx-ast/index.mjs +++ b/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, diff --git a/src/generators/jsx-ast/types.d.ts b/src/generators/jsx-ast/types.d.ts index 672c5a4f..c37f6e24 100644 --- a/src/generators/jsx-ast/types.d.ts +++ b/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, AsyncGenerator>, ProcessChunk< diff --git a/src/generators/jsx-ast/utils/synthetic/404.mjs b/src/generators/jsx-ast/utils/synthetic/404.mjs index a543d415..0f31533c 100644 --- a/src/generators/jsx-ast/utils/synthetic/404.mjs +++ b/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>} 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', diff --git a/src/generators/jsx-ast/utils/synthetic/__tests__/404.test.mjs b/src/generators/jsx-ast/utils/synthetic/__tests__/404.test.mjs index ab006639..947f8aa3 100644 --- a/src/generators/jsx-ast/utils/synthetic/__tests__/404.test.mjs +++ b/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'); + }); }); From 535fb7300cde80839e3f720fc80652954bf4ade3 Mon Sep 17 00:00:00 2001 From: Brian Muenzenmeyer Date: Thu, 2 Jul 2026 10:25:32 -0500 Subject: [PATCH 2/2] fix lint in README --- src/generators/jsx-ast/README.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/src/generators/jsx-ast/README.md b/src/generators/jsx-ast/README.md index 97b7815e..388c80a8 100644 --- a/src/generators/jsx-ast/README.md +++ b/src/generators/jsx-ast/README.md @@ -6,13 +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` | -| `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 | +| 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 |