The documentation site for mqlite — plain static HTML, no framework, no build step to serve (the repo root is the site root).
Public documentation: https://mqlitehq.github.io/. The site tracks mqlite/main,
including changes not yet released; use the version labels and release notes to
choose documentation matching an installed binary.
| File | What | Maintained how |
|---|---|---|
index.html |
landing page | generated from templates/index.html and source facts |
agents.html |
AI-agent guide (MCP + copy-paste prompt) | generated from templates/agents.html and source facts |
concepts.html |
the mqlite model | generated from mqlite/docs/concepts.md |
internals.html |
how mqlite is built | generated from mqlite/docs/internals.md |
api.html |
HTTP API reference | generated from mqlite/docs/api-reference.md |
cli.html |
CLI reference | generated from mqlite/docs/cli.md |
access-keys.html |
permissions, issuance, rotation and revocation | generated from mqlite/docs/access-keys.md |
deployment.html |
installation and configuration | generated from mqlite/docs/deployment.md |
observability.html |
metrics and operational alerts | generated from mqlite/docs/observability.md |
observability-cloud.html |
authenticated cloud and Kubernetes metric collection | generated from mqlite/docs/observability-cloud.md |
operations.html |
backup, restore, upgrades and incident response | generated from mqlite/docs/operations.md |
llms.txt |
one-page machine-readable summary | generated from templates/llms.txt and source facts |
llms-full.txt |
full docs bundle (markdown) | generated (all rendered references + Turso, retention, benchmark, conformance, dependencies, MCP and examples) |
site-metadata.json |
source version, latest supported release, API/MCP/CLI surface, output inventory | generated from canonical source |
assets/site.css |
shared chrome (true-black, mono, amber accent) | by hand |
assets/site.js |
copy buttons · line numbers · tabs · highlight init | by hand |
assets/demo.css · assets/demo.js |
accessible, one-shot landing-page product demo | by hand; loaded by index.html only |
assets/highlight.min.js |
syntax highlighting, vendored (no CDN) | generated (copied from @highlightjs/cdn-assets) |
assets/fig-overview.svg |
overview for concepts and the no-script landing page | generated from the reviewed SVG source |
tools/diagrams/ |
reviewed English SVG geometry, exhaustive Chinese text catalogs, captions and canonical diagram fingerprints | update together after bilingual diagram review |
assets/concepts-*.svg · assets/zh-CN/*.svg |
English and Chinese concepts illustrations | generated from shared SVG geometry and reviewed text catalogs |
tools/explanatory-figures.mjs |
bilingual monitoring flow, capacity table, validation lanes, shutdown formula and creation map | exact source pairing; original text remains expandable |
tools/build.mjs |
the generator | — |
tools/build.test.mjs |
generation and rejection contracts | Node's built-in test runner; no test dependencies |
tools/site-index.json |
every public file, locale and maintained source | reviewed publishing allowlist; new pages and assets must be registered |
tools/version-references.json |
classified literal version references | exact text, repeated occurrences, current-value bindings and historical reasons |
tools/site-audit.mjs |
whole-site source and version checks | PR and hourly read-only CI; JSON artifact and job-summary index |
Generated pages carry separate source version and latest supported release
stamps and must never be edited by hand. The source version comes from
internal/version/version.go; the latest supported release comes from the first
dated supported stable heading in CHANGELOG.md whose tag exists in the canonical
checkout, excluding release candidates and withdrawn/retracted/unsupported entries.
A prepared dated heading without a tag cannot announce an available release.
This is a tagged documentation baseline, not a live registry lookup. Nonempty
Unreleased notes or tracked tree differences from the selected tag mark the
source as unreleased, even if its version constant matches the last release.
The website describes main, including changes not yet released.
Use Node 24 LTS. Whenever the mqlite docs change (and on every release):
cd tools
npm ci
node build.mjs # expects mqlite as the site's sibling checkout
node --test *.test.mjs
npx playwright test --config playwright.config.mjs
node build.mjs --check # compares every generated byte, without writing
node site-audit.mjs /absolute/path/to/mqlite --sdk /absolute/path/to/mqlite-goRun node tools/serve.mjs from the repository root for the same local preview
server used by the browser tests (http://127.0.0.1:4173/; optional port argument).
It uses Node's standard library, binds only to loopback, and does not list
directories or serve hidden paths and files outside the site root.
The browser suite covers desktop pause/replay, keyboard control, reduced motion,
tablet and 390 px transcript layouts, responsive header and quickstart navigation
from 320 px, 200% CSS zoom and narrow-viewport reflow, native More disclosures
without JavaScript, and the rule
that reference pages never download landing-demo assets. Install Chromium once with
npx playwright install chromium when developing locally.
To preview a candidate, pass its absolute checkout path to both build commands.
Before committing, regenerate against the canonical checkout after its docs merge.
--check covers every output in ALL_GENERATED_FILES, including new/missing pages,
metadata, the complete LLM bundle and the vendored highlighter; tests pin that
entire inventory and verify rejection of stale content. It also checks every
advertised route/tool/command count against the source, not just one matching
mention. The three entry points render source/release versions, compatibility
facts and counts from one fact set in both languages. Edit their templates/
sources rather than the generated root files; do not manually repeat current
version numbers. Historical compatibility boundaries remain literal. Local links,
assets and page anchors are verified too. See the maintenance guide
for source-contract review, @latest installation and hourly cross-repository
freshness checks. Scheduled checks cannot deploy the website.
That entry-point check is supplemented by a whole-site index: every public page, locale and asset must have a maintained source and review policy. The Pages package uses this allowlist instead of HTML globs. Literal versions in canonical references, translations, summaries and artwork are classified separately from generated facts. New or changed occurrences, stale production image pins, a new unreviewed stable baseline, or changed default/floor examples fail PR checks. Historical compatibility and benchmark versions are retained rather than blindly replaced. See the maintenance guide for the indexed checklist and audit command. Source contracts cover the embedded console and relevant build/release inputs, and independently check the companion SDK. An old green result does not certify a new source head; human semantic review is still required.
The concepts page displays three SVG illustrations by default: delivery targets,
the message lifecycle and subscription-filter execution. Each image is paired
with the full canonical concepts document, its exact ASCII block and the
reviewed SVG and Chinese text catalog by SHA-256 in
tools/diagrams/manifest.json. A source or artwork change blocks generation until
its semantics, labels and bilingual captions are reviewed together; matching a few words
cannot substitute a stale diagram. The native details disclosure retains the
original English text diagram. Five other explanatory text blocks render as
paired semantic HTML figures or tables, with full-document and exact-block
fingerprints in tools/explanatory-figures.mjs. Their source remains in native
details too. Other code and expression examples stay literal, and the
machine-readable Markdown bundles retain the original diagram source blocks.
Diagrams are local static images. English and Chinese use the same node and arrow geometry; Chinese labels introduce important English terms alongside the Chinese text. The build rejects missing or obsolete labels, unreviewed translation drift, and unreadable font-size overrides. Only the current language's images load. No diagram framework, remote renderer or extra browser script is loaded. Narrow screens scroll within the focusable diagram region; the page itself stays within the viewport. Review all state-transition conditions, especially the final delivery, TTL policy, Cancel admission, and DLQ as a state within the same queue, before updating a source pairing.
CI runs tests and a read-only comparison on Node 24, then packages only the static pages, public assets, machine-readable docs and metadata. Source checkouts, generator dependencies and repository files are excluded from the Pages artifact.
Pull requests validate and package the site without deploying it. A successful
main push (or manual run on main) deploys the checked artifact through the
github-pages environment. Only that job receives pages: write and
id-token: write; repository contents remain read-only. Enable GitHub Pages with
GitHub Actions as its publishing source. The full workflow contract is pinned
in tools/site-workflow.golden.yml and must be deliberately updated when changed.
To inspect the same static artifact locally, use a new output directory:
sh tools/package-site.sh /absolute/path/to/new/site-outputEnglish is the default at /. Every public HTML page has an equivalent under
/zh-CN/, including the landing page, agent guide and all 16 canonical references.
The language link opens the same page and, with JavaScript, preserves the current
section and query. It also works without JavaScript. Locale choice is explicit;
browser settings do not redirect English links. Both locales share the English
section IDs, scripts and styles. They never download a second locale dictionary
or an external font. Identifiers, commands and runnable examples retain their original form.
The three concepts illustrations, landing animation and five explanatory figures
have corresponding English and Chinese text, including accessible captions.
Original English ASCII diagrams remain available in clearly labeled, collapsed
details for source comparison. Browser tests check localized SVG labels against
their canvas and operation/state boxes, including the no-script landing image.
English product documentation in mqlite/docs/ remains the source of truth.
Complete Chinese counterparts live in i18n/zh-CN/docs/. Hand-written page prose,
accessible labels and metadata use the build-time interface.json catalog; the
Chinese machine-readable summary is i18n/zh-CN/llms.txt. The copyable agent instructions are fully translated in agent-prompt.txt;
its protocol literals and rules are checked separately from runnable code.
The public bundles and HTML are generated; do not edit those outputs directly. The seven specialist
references (Turso, retention, benchmarks, conformance, dependencies, MCP and
examples) now have local pages in both languages, as well as bundle entries.
When English changes, review the entire affected Chinese document, not just its heading. Preserve every paragraph, list, table, link target, code example, numeric bound and operational caveat. Prefer precise Chinese, introducing English terms in parentheses where useful. Distinguish message leases from SQL connection leases, authorization from permission levels, durable acknowledgement from unknown outcomes, and measured performance from capacity guarantees.
i18n/zh-CN/manifest.json records SHA-256 hashes for each English source and its
reviewed translation, the interface catalog and both summaries. The manifest also
pins generated-page titles/descriptions and the scripts/templates that contain
paired interface text; changes require reviewing both languages. Update only the
reviewed pairs' hashes after semantic review (for example,
shasum -a 256 ../mqlite/docs/concepts.md i18n/zh-CN/docs/concepts.md). Interface
page source hashes must also match their exact templates/*.html source. The build
rejects unreviewed source or translation drift, missing counterparts, changed
code/identifiers/numbers/links, and different heading, list or table structures.
These checks support human translation review; they cannot establish semantic
accuracy by themselves. Never regenerate fingerprints merely to silence a
failure.
Browser tests cover the explicit language choice, corresponding headings and examples, reciprocal language metadata, keyboard and no-script access, 320 px layouts and shared asset budgets. Packaging includes public HTML and machine docs for both locales; translation sources, catalogs, tools and dependencies stay out of the Pages artifact.
Content rules: distinguish main from released behavior, cite
docs/benchmark.md for measured numbers, and keep the "when NOT to use" section
honest in both languages.
License: MIT © The MQLite Authors.