Documentation Pipeline & Live Reload

This guide explains how our docs system works end‑to‑end:

• Inputs: Markdown in docs/
• Build pipelines: external doc builder vs. internal SPA generator
• Serving: how HTML is exposed to the app
• Auto‑refresh: how updates appear instantly in the UI
• Key files, paths, and troubleshooting

Source of Truth

• Docs source lives under docs/ (including docs/prompts, docs/guides, docs/specialists, docs/system).
• Per‑project docs live outside of this and are unrelated to the rendered HTML site.

Two Pipelines, One Served Output

We maintain two ways to generate HTML. The app serves the “static” output folder.

1. External Builder (full site)

• Command: npx @knowcode/doc-builder -c doc-builder.config.js
• Config: doc-builder.config.js (docsDir: "docs", outputDir: "html", staticOutputDir: "html-static")
• Output folders: html/ (full app) and html-static/ (static build)
• Typical use: Ad‑hoc full builds and deployments

2. Internal SPA Generator (what the app uses)

• Entrypoint: claudecodeui/scripts/generate-spa-html.js
• Reads Markdown from:
  • Docker: /home/nodejs/all-project-files/docs
  • Local: ~/all-project-files/docs
• Writes HTML to:
  • Docker: /home/nodejs/all-project-files/html-static
  • Local: ~/all-project-files/html-static
• Produces:
  • Content files mirrored from docs with .html extension
  • SPA shell index.html
  • Copies shared assets: html-static/css/notion-style.css, html-static/js/{main.js, docs-router.js}
• Markdown processing:
  • Parser: marked
  • Frontmatter: gray-matter
  • Emoji → icons: claudecodeui/scripts/lib/emoji-mapper.js

How the App Serves Docs

• Express serves GET /api/docs-content/* from html-static/ with friendly iframe headers.
• Navigation is generated dynamically via GET /api/navigation by scanning docs/ for Markdown, extracting headings/frontmatter.
• The SPA shell (html-static/index.html) loads:
  • html-static/js/docs-router.js for client‑side navigation
  • Content pages from /api/docs-content/<path>.html

How Updates Flow (Auto‑Refresh)

Multiple sources can change the generated HTML. We keep the iframe in sync with a small WebSocket‑based live reload.

Sources of changes

• Manual generate (UI):
  • Click “Generate HTML” in Files view
  • Calls POST /api/files/generate-reports → runs the SPA generator script
  • On success, the server broadcasts a live‑reload signal
• Startup generate (Docker):
  • On container boot, the server may run the SPA generator once if docs exist
  • Subsequent writes are covered by the file watcher below
• External changes:
  • Git pull, file edits, or other processes writing to html-static/
  • A watcher detects changes and triggers a reload broadcast

Always‑on live reload

• Client: claudecodeui/src/components/DocsPanel.jsx opens a WS to /live-reload and refreshes the iframe on reload
• Debounce: client enforces a 1.5s minimum between refreshes to avoid flashing
• Server broadcasts:
  • After generation: server/routes/files.js calls broadcastLiveReload() when generation completes
  • On file changes: server/index.js runs a chokidar watcher on html-static/**/*.html and debounces broadcasts (1s)
• Server WS endpoint: handled in server/index.js (/live-reload path) using utilities from server/utils/live-reload.js

Layout & Styling Notes

• Breadcrumbs: compact static breadcrumbs are used to avoid extra top whitespace
  • Shell nav markup comes from the SPA generator
  • Styles live in html-static/css/notion-style.css
• Sidebar search: the search header is sticky while scrolling the nav
• Content spacing: reduced paddings and heading margins for denser pages

Key Files & Paths

• Generator: claudecodeui/scripts/generate-spa-html.js
• Router (client): claudecodeui/html-static/js/docs-router.js
• Styles: claudecodeui/html-static/css/notion-style.css
• Live reload utilities: claudecodeui/server/utils/live-reload.js
• Server mounting:
  • server/index.js → serves /api/docs-content/*, /api/navigation, WS /live-reload, and watches html-static/
  • server/routes/files.js → POST /api/files/generate-reports

Typical Tasks

• Regenerate all docs from UI:
  • Files panel → “Generate HTML” → iframe refreshes automatically
• Add a new doc:
  • Create a .md file anywhere under docs/
  • Run generate from UI (or wait for scheduled/triggered runs)
  • The page appears in the nav (sorted), and you can visit it immediately

Limitations & Future Improvements

• Code highlighting: currently basic. Consider adding highlight.js and invoking it after content load.
• Heading anchors/TOC: add heading IDs and anchor links for deep linking and optional per‑page TOC.
• Links/assets: relative .md links aren’t rewritten; assets must be resolvable. Add rewriting and asset copy where needed.
• Search: current search input filters the nav; a full‑text index could be added later.

Troubleshooting

• Docs not refreshing:
  • Check browser console for WS logs (connect/open/close)
  • Server logs should show [HTML Watcher] events and 📢 Broadcasting reload
  • Try clicking “Generate HTML” and watch for success message + reload
• Missing page:
  • Confirm the .md exists under docs/ and has a proper filename
  • Regenerate from UI and look for ✅ Generated: lines in server output
• Path issues (local vs Docker):
  • The server and generator resolve paths automatically; verify that the expected docs/ and html-static/ exist for your environment

---

Questions or improvements you want? Add them here and we’ll keep this guide current.