From 94e11d529e99a9124afa4ed2bd6336ece872f4df Mon Sep 17 00:00:00 2001 From: Ethan Arrowood Date: Tue, 26 May 2026 13:10:00 -0600 Subject: [PATCH] chore: clean up build warnings Two unrelated warnings have been firing during every docs build since Phase 1 (#497) landed. Both are now fixed; an unrelated third warning ("Excluded N routes by current config") remains but is just accurate accounting of intentional exclusions. 1. /reference route processing failure src/pages/reference/index.tsx is a client-side React redirect component that returns null. Its rendered HTML is an empty Docusaurus shell with no extractable content. The llms-txt plugin was attempting to process it and emitting a warning ("Route Error: Failed to process route '/reference': Failed to convert HTML to Markdown: HTML to Markdown conversion resulted in empty content"). Fix: add '/reference' to the plugin's excludeRoutes config. This is not a real content page; it's a routing redirect that should never be considered for the flat-markdown export. 2. Broken anchor in resource-api.md reference/resources/resource-api.md line 799 linked to `../components/javascript-environment.md#transaction`, but the heading `### \`transaction(fn)\`` in that target file gets the auto-generated anchor `transactionfn` (parens stripped, dash dropped). The link wanted the semantic name `transaction`, not the auto-id. Fix: add an explicit anchor `{#transaction}` to the heading in javascript-environment.md. This gives the link a stable, human- meaningful target that survives heading-text changes and matches the author's original intent. Docusaurus 3.x supports the {#id} syntax natively. Verified: rebuild produces the same 371 documents, both warnings are gone, and grep confirms the rendered HTML now has id="transaction" directly on the heading. The remaining "Excluded 2 routes by current config" warning is the plugin reporting that two routes were filtered: the home page `/` (a content-pages route, excluded by default via includePages: false) and `/reference` (our new explicit exclusion). Both are intentional; the warning is accurate signal, not noise. Co-Authored-By: Claude Opus 4.7 (1M context) --- docusaurus.config.ts | 6 ++++++ reference/components/javascript-environment.md | 2 +- 2 files changed, 7 insertions(+), 1 deletion(-) diff --git a/docusaurus.config.ts b/docusaurus.config.ts index b6b99af5..f58b9566 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -244,6 +244,12 @@ const config: Config = { // conversion sees clean structure. See the script header // for details on what gets transformed. beforeDefaultRehypePlugins: [require('./scripts/rehype-docusaurus-to-llms.mjs').default], + // Explicit exclusions for routes that are not real content. + // /reference is a client-side redirect React component + // (src/pages/reference/index.tsx) that returns null; without + // this entry the plugin tries to process its empty HTML + // shell and emits a warning. + excludeRoutes: ['/reference'], }, }, ], diff --git a/reference/components/javascript-environment.md b/reference/components/javascript-environment.md index 3cc8b317..5942b4d4 100644 --- a/reference/components/javascript-environment.md +++ b/reference/components/javascript-environment.md @@ -46,7 +46,7 @@ An object containing all databases defined in Harper. Each database is an object See [Database API](../database/api.md) for full reference. -### `transaction(fn)` +### `transaction(fn)` {#transaction} Executes a function inside a database transaction. Changes made within the function are committed atomically, or rolled back if an error is thrown.