Skip to content

chore: clean up build warnings#498

Merged
Ethan-Arrowood merged 1 commit into
mainfrom
chore/cleanup-build-warnings
May 26, 2026
Merged

chore: clean up build warnings#498
Ethan-Arrowood merged 1 commit into
mainfrom
chore/cleanup-build-warnings

Conversation

@Ethan-Arrowood
Copy link
Copy Markdown
Member

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: /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:

[WARNING] [docusaurus-plugin-llms-txt] Route Error: Failed to process route "/reference":
Failed to convert HTML to Markdown: HTML to Markdown conversion resulted in empty content
for "reference.html". This usually means your contentSelectors didn't match any elements...

Fix: add /reference to the plugin's excludeRoutes config. 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 anchor transactionfn (parens stripped, dash dropped). The link wanted the semantic name transaction, not the auto-id.

The Docusaurus build was complaining:

[WARNING] Docusaurus found broken anchors!
- Broken anchor on source page path = /reference/v5/resources/resource-api:
   -> linking to /reference/v5/components/javascript-environment#transaction

Fix: add an explicit {#transaction} anchor to the heading in javascript-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

  • Rebuild produces the same 371 documents across all four docs plugin instances (learn: 10, reference: 137, fabric: 10, release-notes: 211)
  • Both targeted warnings are gone
  • grep 'id="[^"]*transaction[^"]*"' build/reference/v5/components/javascript-environment.html now returns id="transaction" directly on the heading

Remaining warning (intentional, not fixed)

[WARNING] [docusaurus-plugin-llms-txt] WARNING: Excluded 2 routes by current config

This is the plugin reporting that two routes were filtered:

  • The home page / — a content-pages route, excluded by default via includePages: false
  • /reference — our new explicit exclusion

Both 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

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>
@Ethan-Arrowood Ethan-Arrowood requested a review from a team as a code owner May 26, 2026 19:10
@github-actions github-actions Bot temporarily deployed to pr-498 May 26, 2026 19:12 Inactive
@github-actions
Copy link
Copy Markdown

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-498

This preview will update automatically when you push new commits.

@Ethan-Arrowood Ethan-Arrowood merged commit e8fc9e5 into main May 26, 2026
7 checks passed
@Ethan-Arrowood Ethan-Arrowood deleted the chore/cleanup-build-warnings branch May 26, 2026 19:27
@github-actions
Copy link
Copy Markdown

🧹 Preview Cleanup

The preview deployment for this PR has been removed.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants