Docs site

The Markdown files in docs/ are published as a documentation site at https://docs.clearexchange.ai, and at /docs on the main site. The same process that serves the API serves the docs. There is no separate build, so the published docs are always the docs/ folder of the commit that was last deployed.

How it works#

• At startup, src/docs/site.ts reads every docs/*.md file and renders it to HTML with the small renderer in src/docs/markdown.ts. It covers the Markdown the docs use: headings with GitHub-style anchors, tables, fenced code, lists, blockquotes, links and emphasis. Raw HTML is escaped, never passed through. There are no dependencies.
• Pages are held in memory and served with the same strict Content-Security-Policy, ETags and security headers as the web UI. Styles are in web/docs.css and take every value from web/tokens.css, so the docs follow the site's design and any rebrand. web/docs.js adds search, copy buttons on code blocks and the contents menu on small screens. Without it, the pages still read and navigate normally.
• Search runs in the browser over /ui/docs-search.json, an index of every section's heading and text that is built at startup. It is fetched the first time the search box gets focus. Press / to focus the search box.
• The image copies docs/ (see Dockerfile) and every merge to main deploys a new image, so the docs update on every deploy.

Adding or changing a page#

1. Write or edit docs/<name>.md. The name must be lower case letters, digits and hyphens. The page is published at /docs/<name> and https://docs.clearexchange.ai/<name>.
2. Add a line linking to it in docs/README.md. That file is the docs home page, and its **Group** lines and links make the left-hand navigation, in order.
3. Link between pages as you would on GitHub ([Telemetry](telemetry.md#events)). Links are rewritten for the site. Links to files outside docs/ (for example ../src/config.ts) go to the file on GitHub.

npm test fails if a page is missing from docs/README.md or if any link between pages or anchor is broken. Run npm start and open http://127.0.0.1:8080/docs/ to preview. Restart the server to pick up edits.

Hostnames#

Docs hostnames are set by DOCS_HOSTS in fly.toml, a comma-separated list. Routing uses the request's Host header. Pages carry a canonical link to the first docs hostname, so search engines index one copy. On the docs hostname the header links to the landing page (https://clearexchange.ai) and the app (https://app.clearexchange.ai).

The TLS certificate, the DNS record and the other hostnames are covered in Hostnames and DNS.