OpenMates Docs Open Chat

Docs Web App

Docs Web App Documentation system integrated into the main web app at , rendering repository markdown files with fast static payloads, search, navigation, an...

[T:documentation.sender_name]

Docs Web App

Documentation system integrated into the main web app at openmates.org/docs, rendering repository markdown files with fast static payloads, search, navigation, and API reference.

Why This Exists

Keeps all documentation in a single codebase (/docs/**/*.md) and serves it through the web app rather than a separate docs site. The runtime architecture optimizes first load by shipping a small navigation manifest up front, then loading only the current page or search index when needed.

How It Works

Build Pipeline (process-docs.js)

  1. Scans /docs/**/*.md (respects .docsignore exclusion patterns)
  2. Converts markdown to HTML using markdown-it with highlight.js syntax highlighting
  3. Generates heading IDs for anchor links, resolves relative links, fixes image paths
  4. Outputs src/lib/generated/docs-manifest.json containing only navigation metadata: titles, slugs, descriptions, word counts, and static payload URLs.
  5. Outputs one static JSON payload per page under static/generated/docs/pages/ containing rendered HTML and original markdown for download/copy.
  6. Outputs static/generated/docs/search.json for full-text search. This file is loaded only when search is used.

Dev Mode (vite-plugin-docs.js)

Vite plugin watches /docs directory and hot-reloads on markdown changes using the same processing pipeline.

Frontend Components

Located in frontend/apps/web_app/src/lib/components/docs/:

Component Purpose
DocsSidebar.svelte Collapsible tree navigation, active page highlighting, mobile drawer, lazy full-text search
DocsMessage.svelte Static HTML renderer styled like an assistant docs message; Mermaid is enhanced on demand

Layout

The docs layout (+layout.svelte) mirrors the main chat page pattern:

  • Fixed-position sidebar (325px) with slide transition
  • Main content area offset by sidebar width
  • Responsive: sidebar slides off-screen on mobile

Individual doc pages ([...slug]/+page.svelte) render content as a single assistant-style docs message using build-time HTML. The docs route intentionally does not use TipTap or chat message parsing so the first load stays small.

URL Structure

/docs                      -- Documentation index
/docs/architecture/chats   -- Specific doc page
/docs/api                  -- Interactive API reference (OpenAPI from FastAPI)

Authentication Integration

  • Logged-in users: API docs auto-inject user’s API key for “Try it” functionality
  • Public access: All docs are readable without login; API testing prompts login

Offline Support

The docs page does not provide a dedicated offline mode. The web app’s legacy service worker unregisters itself, and docs assets rely on normal browser/CDN caching. This keeps the docs implementation simpler and prioritizes fast online loading.