Export and host

Export a complete catalogue

npx mokly export --out .context/mokly-site

Export compiles in memory, then packages the complete catalogue: one shell page per entry at view/<path>/index.html, the generated views and documents under static/mokly-generated/, referenced authored assets under static/ and Git comparisons. --out is required and is resolved beside the config, not beside your working directory; an absolute path must stay inside the repository root.

--base overrides the configured base ref for that run. The branch point must be present in the checkout. Mokly reads a complete verified v9 inventory from that commit or runs the commit’s own baseline recipe when output is absent or incomplete. Check out full history in CI. Export never fetches history for you. A base built by an earlier Mokly version makes Changes unavailable; export prints the reason and still packages the current catalogue. Other invalid comparison inputs fail the export.

Deploy it

Serve the directory’s contents at the root of an HTTP(S) origin, with correct MIME types and directory indexes. No Mokly process, Git checkout, source tree or rewrite rule is needed there: a host that serves view/<path>/index.html for /view/<path>/ serves every entry, and hosts that drop index.html or the trailing slash still open the same page. Give the catalogue an origin of its own: it resolves every address from that root, so keep it off a path prefix and reach it over HTTP(S) rather than from a local folder.

Configure revalidation for the shell and mutable assets, serve comparison files with Cache-Control: no-store and X-Content-Type-Options: nosniff, and deploy atomically so a reader never meets a mixture of two builds. The artifact includes a 404.html your host can use as its error document.

What a reader gets

The whole catalogue: navigation, search, tags, viewport and scheme controls, use-case flows, whole-document pages and Markdown documents, the details inspector and the comparisons. Comparisons load only once a reader selects one. A refresh reads the same exported generation; deploy a new export to publish new results.

Re-exporting

Each export has its own content-derived deployment identity, so a reader with an old tab reloads fully when the deployed catalogue changes. A re-export replaces only the output it owns and restores the previous site if installing the new one fails and recovery is safe. Choose a destination that is missing or empty and outside your source, generated, dependency and comparison directories.

Exported paths are relative, slash-separated, well-formed Unicode without control characters, backslashes, colons, empty segments, . or .., and at most 1,024 UTF-8 bytes. A refusal prints the escaped path so invisible characters can be found. Before deleting a destination created by an earlier Mokly release, move out any files you added yourself.