Skip to content

About

MQLite website and documentation

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

18 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

mqlitehq.github.io

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.

Layout

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

Syncing with the code (the anti-rot rule)

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-go

Run 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.

Publishing

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-output

English and Simplified Chinese

English 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.

About

MQLite website and documentation

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages