Plan

Fix Documentation 404 Errors — Implementation Plan

What Was Merged

PR #16 (feat/help-center-seeding-pipeline) batch-converted 337 new MDX pages from the Intercom help center and added 61 index pages (navigation hubs), bringing the site to 428 total pages across these categories:

Category	New Pages	Modules
Core Platform	235	invoices-estimates (45), general-ui-ux (39), reporting (32), scheduling (25), jobs (21), inventory (15), commission (6), custom-status-workflow (7), user-management (7), purchase-orders (4), projects (3), material-list (3), dynamic-proposals (3), clearpath (3), time-sheets (3), comments (2), assets (2), +12 single-page modules
Growth	45	engage (25), fp-payments (6), custom-forms (4), payment (4), pricebook (3), operator-ai (2), pdf-form-filler (1)
Integrations	29	other (22), reece-anz (4), reece-us (3)
Accounting	28	quickbooks-online (13), quickbooks-desktop (8), xero (5), myob (2)

---

Root Causes of 404 Errors

The files all exist on disk and docs.json navigation is structurally valid (428 pages, 0 missing files, 0 duplicates). The 404s are caused by MDX build/parse failures — when Mintlify can’t compile a page, it silently drops it and the URL returns 404. There are 7 distinct issue categories:

---

Issue 1: Raw { } Characters in Content (HIGH — Build Breaker)

• Count: 64 files affected
• Cause: MDX interprets { as a JavaScript expression delimiter. Raw curly braces in article text crash the MDX compiler.
• Examples:
  • accounting/xero/pre-sync-xero.mdx — < > { } " in text about special characters
  • accounting/quickbooks-desktop/pre-sync-quickbooks-desktop.mdx — {,},: in text
• Fix: Escape as \{ and \}, or wrap in backticks as inline code.

Issue 2: Raw < > Characters in Content (HIGH — Build Breaker)

• Count: 3+ files with definite breaks, plus ~30 files with > in navigation breadcrumb text (e.g., Settings > Jobs > General)
• Cause: MDX interprets < as JSX tag opener. Bare <30, <>, <-- crash the compiler.
• Critical files:
  • integrations/reece-us/reece-us-product-categories.mdx — <30 Gallon, 30< Gallon, 50< Gallon
  • integrations/other/companycam.mdx — CompanyCam <> FieldPulse (JSX fragment)
  • growth/custom-forms/custom-forms-streamline-your-workflow-and-save-time.mdx — <-- arrow
  • accounting/xero/pre-sync-xero.mdx — < > { } in text
• Fix: Escape as < / >, or rephrase. For > in breadcrumbs, use → or >.

Issue 3: Duplicate/Malformed Table Rows (MEDIUM — Build Breaker)

• Count: 29 files
• Cause: The crawl pipeline produced duplicate table content — rows prefixed with - | instead of |. This creates malformed markdown that may break Mintlify’s parser or render as garbage.
• Worst offenders: quickbooks-online-errors.mdx (61 duplicate rows), quickbooks-desktop-errors.mdx (34), post-sync-quickbooks-online.mdx (18)
• Fix: Script to remove all lines matching ^- \| pattern (they’re exact duplicates of properly formatted rows above them).

Issue 4: Loom/Video Scrape Artifacts (MEDIUM — Content Quality)

• Count: 138 files
• Cause: The Firecrawl scraper captured Loom player UI text as content: speed selectors (1×, 2 min 20 sec⚡️2 min 55 sec...), Copy link, Your user agent does not support the HTML5 Video element.
• Fix: Script to strip known Loom artifact patterns. These were partially addressed in PR #5 but the batch conversion reintroduced them for all 336 articles.

Issue 5: Unrewritten Help Center Links (MEDIUM — Broken Navigation)

• Count: 39 links across ~25 files pointing to help.fieldpulse.com in body content
• Cause: The link rewriter (PR commit 21a6c0a) only ran on the Customers module. The remaining modules still have links pointing to the old Intercom help center instead of internal Mintlify paths.
• Examples: Links to collections (/en/collections/7820969-accounting-integrations), individual articles (/en/articles/9071956-...), and the help center root.
• Fix: Map known help center URLs → internal Mintlify paths and rewrite. Unmappable URLs should point to the closest internal equivalent or be removed.

Issue 6: Broken Intercom Anchor Links (LOW — Broken In-Page Links)

• Count: 28 anchor references across 18 files using #h_ prefix (e.g., #h_5403add395)
• Cause: Intercom uses opaque hex anchor IDs. These don’t exist in the converted MDX headings.
• Fix: Strip the anchor fragment to link to the page root, or map to actual MDX heading slugs.

Issue 7: Non-Self-Closing <br> Tags (LOW — May Break Some Pages)

• Count: 9 files, but heavily used (100+ instances total, mostly in table cells)
• Cause: MDX requires void HTML elements to be self-closing (<br />). Plain <br> may fail depending on Mintlify’s MDX version.
• Fix: Global find-replace <br> → <br />.

---

Fix Strategy

Phase 1: MDX Build-Breaker Fixes (Issues 1, 2, 3, 7)

Goal: Eliminate all compilation failures so pages stop 404-ing.

Step 1a — Escape raw { } in content

• Write a script or use targeted sed to escape bare curly braces in article body text
• Preserve valid JSX expressions (style={{...}}, cols={2}, {/* comments */})
• Scope: 64 files

Step 1b — Escape raw < > in content

• Fix the 3 critical files with <30, <>, <-- patterns
• Audit > usage in breadcrumb-style text (Settings > Jobs) and escape or replace
• Scope: ~30 files

Step 1c — Remove duplicate table rows

• Remove all lines matching ^- \| (dash-prefixed table rows that duplicate the real rows)
• Scope: 29 files

Step 1d — Fix <br> → <br />

• Global replace across all files
• Scope: 9 files, ~100+ instances

Phase 2: Content Cleanup (Issues 4, 5, 6)

Goal: Fix broken links and remove scrape artifacts.

Step 2a — Strip Loom/video scrape artifacts

• Remove patterns: Copy link, Your user agent does not support..., speed selector text, Open video in Loom standalone lines
• Scope: 138 files

Step 2b — Rewrite remaining help center links

• Map help.fieldpulse.com URLs → internal paths using the article-taxonomy-map.json
• Scope: 39 links across ~25 files

Step 2c — Fix Intercom anchor links

• Strip #h_xxxx fragments from internal links
• Scope: 28 anchors across 18 files

Phase 3: Quality Sweep

Goal: Polish remaining artifacts.

Step 3a — Remove “Updated yesterday” timestamps (9 files) Step 3b — Clean up * * * Intercom separators — replace with --- or remove (356 files) Step 3c — Review 31 low/medium-confidence article classifications (from _meta/articles-needing-review.md)

---

Execution Order

1. Phase 1 first — this directly fixes the 404s
2. Phase 2 next — fixes broken navigation for users who land on pages
3. Phase 3 as time allows — cosmetic improvements

Each phase should be a separate commit for clean git history and easy rollback.