Diagnosed Docusaurus sidebar and category link failures

2 min read

Diagnosed Docusaurus sidebar and category link failures

  • Day: 2026-05-06
  • Time: 10:54 to 11:20
  • Project: Dev
  • Workspace: WP 2: Operational
  • Status: Completed
  • Priority: HIGH
  • Assignee: Matías Nehuen Iglesias
  • Tags: Docusaurus, Vercel, Sidebar, Category-Json, Build-Failure, Sop

Description

Session Goal

Investigate recurring Docusaurus/Vercel documentation build failures and turn the findings into reusable repair guidance for future maintenance.

Key Activities

  • Reviewed multiple troubleshooting artifacts focused on Docusaurus sidebar generation, Vercel deployment errors, and docs build failures.
  • Compared likely failure surfaces: sidebars.ts, autogenerated sidebar discovery, TypeScript/ESM/runtime config issues, JSON validity, and category metadata.
  • Traced one concrete root cause pattern: generated _category_.[[json]] files were hard-coding doc IDs that do not match Docusaurus-normalized IDs, especially when folder names include numeric prefixes.
  • Identified that some failures were also caused by stale or misrouted generator execution, where the intended patch did not appear because the referenced script path was wrong and the real generator was not run.
  • Consolidated the debugging approach into a local-first SOP: reproduce locally, isolate sidebar/category config, inspect generated docs diffs, verify doc IDs, then rebuild and redeploy.

Achievements

  • Clarified that the most probable issue is not missing docs themselves, but unstable or incorrect generated links in category metadata.
  • Established a practical fix strategy: remove explicit category doc links, let Docusaurus resolve IDs automatically, and harden the generator so it stops guessing doc IDs from folder slugs.
  • Captured a reusable checklist/SOP for future incidents, including verification steps and evidence collection before redeployment.

Pending Tasks

  • Patch the docs generator to stop emitting hard-coded link blocks in _category_.[[json]].
  • Regenerate the docs and confirm the build succeeds locally and on Vercel.
  • Add a permanent SOP rule for sidebar/category validation after docs replacement or regeneration.
  • If needed, create a fallback CommonJS sidebar test to isolate ESM/TypeScript runtime issues.

Evidence

  • source_file=2026-05-06.sessions.jsonl, line_number=3, event_count=0, session_id=58fbfef78c59517feced9966eb969076fe0913978e23bebe22746ff329833d75
  • event_ids: []

Graph View

Backlinks