chore: clean up build warnings#498
Merged
Merged
Conversation
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) <noreply@anthropic.com>
🚀 Preview DeploymentYour preview deployment is ready! 🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-498 This preview will update automatically when you push new commits. |
kriszyp
approved these changes
May 26, 2026
🧹 Preview CleanupThe preview deployment for this PR has been removed. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What and why
Two unrelated warnings have been firing during every docs build since Phase 1 (#497) landed. Both are now fixed. A third "Excluded N routes by current config" warning remains but is just accurate accounting of intentional exclusions — not noise we need to silence.
Fix 1:
/referenceroute processing failuresrc/pages/reference/index.tsxis a client-side React redirect component that returnsnull— its rendered HTML is an empty Docusaurus shell with no extractable content. The llms-txt plugin was attempting to process it and emitting:Fix: add
/referenceto the plugin'sexcludeRoutesconfig. This is not a content page; it's a routing redirect that should never be considered for the flat-markdown export.Fix 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 anchortransactionfn(parens stripped, dash dropped). The link wanted the semantic nametransaction, not the auto-id.The Docusaurus build was complaining:
Fix: add an explicit
{#transaction}anchor to the heading injavascript-environment.md. This gives the link a stable, human-meaningful target that survives heading-text changes and matches the original author intent. Docusaurus 3.x supports the{#id}syntax natively.Verification
learn: 10,reference: 137,fabric: 10,release-notes: 211)grep 'id="[^"]*transaction[^"]*"' build/reference/v5/components/javascript-environment.htmlnow returnsid="transaction"directly on the headingRemaining warning (intentional, not fixed)
This is the plugin reporting that two routes were filtered:
/— a content-pages route, excluded by default viaincludePages: false/reference— our new explicit exclusionBoth are intentional. Keeping this warning visible is useful signal — it lets us notice if we accidentally exclude more routes in the future.
🤖 Generated with Claude Code