orz-mdhtml — documents

A text twin and a self-editing file

A document is its text twin — notes.md, plain Markdown with a small header at the top — and its self-editing file notes.md.html, one HTML page that reads like a themed website, edits itself in the browser and saves back in place. The file is always built from the text (orz-mdhtml assemble): the exact text rides inside it (byte for byte, line endings kept), everything else is a shell that can be rebuilt, and orz-mdhtml extract gives the text back. Keep the .md in your repository or hand it to an agent; make the .md.html whenever someone needs a file. A relative link to another text ([Week 2](week2.md)) becomes a link to its .md.html in the file.

Published on npm as orz-mdhtml (CLI and Node library) and orz-mdhtml-browser (engine and editor component), always the same version.

In the file: read, edit, save

Keys. Ctrl/⌘ E edit / done · Ctrl/⌘ S save · Ctrl/⌘ Z undo, Shift Ctrl/⌘ Z redo · in the editor Ctrl/⌘ \ cycles split / editor / preview and Esc leaves the text for the toolbar · Ctrl/⌘ P in the editor's preview prints the page (in the read view it is the browser's own print).

A quiet update. A local file checks at most once a day whether a newer release of its engine exists; the pencil then gets a small dot and its list offers Update to x.y.z (in the editor, an "Update available" chip). Update now rebuilds the file from the same text with the new release (its bundle checked by SHA-384) and saves it; nothing changes until you ask. Served pages, framed pages and pages with a host never check.

The header

One {{nyml kind: document}} block at the very top of the text holds the document's metadata and settings. new writes carrier and a uid (the document's id; upgrade, New document and Save as new copy write one too, Save does not — a starter file has none, which is fine); once there is one, leave it as it is.

{{nyml
kind: document
carrier: md
uid: doc-7kq2m9x4p1r8s3t5
title: Cell Biology — Week 3
author: Yu Wang
lang: en
theme: light-academic-1
measure: wide
license: CC-BY-4.0
}}

# Cell Biology — Week 3

One key: value per line (key: | for several lines), no comments (text after a value becomes part of it). Unknown keys are kept; your own tool's keys start with x_<tool>_. A Markdown file with no header is fine too — the tool treats it as a document without a uid; to give it one, run npx orz-mdhtml@1 new with no file name and paste the header it prints at the top.

Twelve themes

The orz-markdown themes, by name and id (orz-mdhtml themes lists them): Orchard light-neat-3 (the default), Neat light-neat-1, Neat 2 light-neat-2, Academic light-academic-1, Academic 2 light-academic-2, Beige beige-decent-1, Beige 2 beige-decent-2, Playful light-playful-1 (a ruled notebook on screen: text on the lines, tables and code pasted on as sheets), Playful 2 light-playful-2, and the dark Dark Elegant dark-elegant-1, Dark Elegant 2 dark-elegant-2 and Nocturne dark-elegant-3.

Create and build with the CLI

Node 20.16 or newer; nothing to install with npx (or npm i -g orz-mdhtml@1):

npx orz-mdhtml@1 new notes.md --title "Field notes"   # a new text twin
# edit notes.md (by hand or with an agent), then:
npx orz-mdhtml@1 notes.md                             # → notes.md.html

Content — title, theme, width, language, metadata — comes only from the text's header; assemble has no content options (--title, --theme are refused with a pointer to the header). Nothing that could hold other work (a file saved in the browser, an edited twin, another document) is overwritten without --force, which keeps a <file>~ backup — unless what it replaces is a known earlier state: what the CLI itself last wrote or read for that pair, or a committed version of the twin in git (a shallow clone knows only its last commit).

For scripts and agents. Every command takes --json: one object on stdout, and on a refusal { "ok": false, "error", "reason", "next" } — reason is a stable code (twin-differs, replaces-mismatch, legacy-file, output-differs, newer-shell, …) and next the one command that resolves it, built from your own arguments and safe to run as it is. assemble, extract (to a file), inspect and upgrade print the sha256 of the text they wrote or read (and every --json result that wrote a text carries it; new prints it only with --json); pass it back as --replaces <sha256> and the file is replaced only while it still holds that text — it works with no cache, no git, in a fresh sandbox. Exit status: 0 done, 1 refused or failed, 2 usage error. Before editing x.md, inspect x.md says whether x.md.html holds work saved in the browser; extract x.md.html -o x.browser.md brings it out for a merge.

Delivery, browsers and limits

Delivery. Files are inline by default: the engine is inside the file (about 1 MB), so it opens without fetching it. --cdn writes a small file for pages you publish on the web; it loads the engine from jsDelivr, https://cdn.jsdelivr.net/npm/orz-mdhtml-browser@<version>/orz-mdhtml.browser.js (the file's own version, e.g. @1.0.2). Either way — an inline file too — the theme stylesheets, KaTeX's and highlight.js's styles, the content libraries (Mermaid, SMILES, Chart.js) and the editor (CodeMirror) load from CDNs: reading styled content and editing need a network connection the first time. A slow or unreachable CDN never holds the page blank: the document shows at once, unstyled, and takes its theme when the stylesheets arrive.

Older files, web apps and agents

npx orz-mdhtml@1 inspect old.md.html
npx orz-mdhtml@1 upgrade old.md.html