Skip to main content

Gotchas: hbf-developer-docs

Package-specific non-obvious patterns and pitfalls. Loaded on demand when working on this package.

  • Docusaurus v3 SSG crashes on symlinked .md files: Must copy, not symlink, source docs into the Docusaurus tree.
  • Architecture diagrams use flowchart LR/TD only: C4 syntax was removed from all repos. patch-mermaid-clicks.ts now only runs addFlowchartClicks (C4 code removed).
  • Mermaid container class is .docusaurus-mermaid-container: @docusaurus/theme-mermaid renders diagrams in div.docusaurus-mermaid-container (NOT .mermaid). The .mermaid class does not exist in the DOM. Any client-side code targeting Mermaid SVGs must use .docusaurus-mermaid-container.
  • @docusaurus/theme-mermaid must be in the themes array: Not plugins. Missing it causes diagrams to render as raw code blocks.
  • securityLevel: 'loose' required: Needed in Mermaid config for click handlers in flowchart diagrams.
  • Source docs relative links break on relocation: Source docs from service repos have relative links (e.g. ../../docs/architecture/auth-flows.md) that break when relocated. The setup-symlinks.ts copy script rewrites these to absolute /docs/ paths.
  • docs/architecture/*.md are gitignored: These are generated copies. Edit source files in the framework or service repos, not here.
  • Service index pages must be inside a folder: Use docs/services/<name>/index.mdx (NOT docs/services/<name>.mdx). A standalone .mdx at the sibling level causes duplicate sidebar entries.
  • Flow file slugs don't match filenames: Source doc slugs differ from actual filenames: rag-knowledge-query vs rag-query, live-chat-handover vs live-chat, broadcast-campaign vs broadcast, analytics-ingestion vs analytics.
  • GPG signing unavailable in Docker/CI: Use -c commit.gpgsign=false for commits in those environments.