Docs site setup

[rbessin]

Changes

Documentation Site Setup

Set up a Docusaurus-based documentation site that automatically generates developer documentation from SKILL.md files in .claude/skills/.

Key Implementation Details:

• Workspace Integration: Added docs-site to yarn workspaces for unified dependency management
• Automated Generation: Created prepare-docs.js script that:
  • Recursively finds all SKILL.md files in .claude/skills/
  • Transforms Claude-format YAML frontmatter to Docusaurus format
  • Flattens folder structure (folder/file/SKILL.md → folder/file.md)
  • Auto-generates sidebars.js from folder hierarchy
  • Transforms internal SKILL.md links to work with flattened structure
• Single Source of Truth: SKILL.md files serve both Claude AI and human developers
• Error Handling: Added comprehensive error handling and validation to build script
• Configuration Updates:
  • Fixed "Edit this page" links to point to actual SKILL.md source files
  • Migrated to Docusaurus v4-compatible markdown config
  • Added NER logo and favicon
  • Set up production-ready URLs
• Root Commands: Added yarn docs:dev, yarn docs:build, yarn docs:serve, yarn docs:prepare

Developer Workflow:

1. Edit SKILL.md files in .claude/skills/
2. Run yarn docs:dev (automatically runs prepare-docs and starts dev server)
3. Documentation and sidebar regenerate automatically

Notes

• yarn.lock changes are expected and safe: Added docs-site to workspaces, which caused Yarn to reorganize/hoist shared dependencies. No version bumps, only structural changes.
• Documentation source lives in .claude/skills/ - do NOT edit generated files in docs-site/docs/
• Sidebar structure automatically mirrors folder structure in .claude/skills/
• All generated files (docs/, sidebars.js, .docusaurus/, build/) are gitignored

Test Cases

Build & Generation

• yarn docs:prepare generates docs from SKILL.md files without errors
• yarn docs:dev starts dev server successfully
• yarn docs:build produces production build without errors
• No TypeScript/linting errors in docs-site files

Documentation Structure

• All 4 existing SKILL.md files processed correctly
• Sidebar auto-generated with correct hierarchy
• "General Practices" category appears with all 4 docs
• Introduction page renders correctly

Links & Navigation

• Internal links between docs work (e.g., backend-endpoints → query-args-and-transformers)
• No broken markdown link warnings
• "Edit this page" links point to correct .claude/skills/ files
• Logo and favicon display correctly
• Clicking logo navigates to intro page

Workspace Integration

• yarn install from root installs docs-site dependencies
• yarn workspace finishline-docs commands work
• No duplicate React/Docusaurus dependencies
• Root commands (yarn docs:dev) work from any directory

Edge Cases

• Script handles missing .claude/skills/ directory gracefully
• Script handles SKILL.md files with no frontmatter
• Generated sidebars.js has proper formatting and TypeScript types

Screenshots

Desktop View (Normal Window)

Checklist

• All commits are tagged with the ticket number
• No linting errors / newline at end of file warnings
• All code follows repository-configured prettier formatting
• No merge conflicts
• All checks passing
• Screenshots of UI changes (see Screenshots section)
• Remove any non-applicable sections of this template
• Assign the PR to yourself
• No yarn.lock changes - yarn.lock changes are EXPECTED due to workspace integration (see Notes)
• Request reviewers & ping on Slack
• PR is linked to the ticket (fill in the closes line below)

Closes #3978