npm - orz-mdhtml - Versions diffs - 0.1.0 - Mend

orz-mdhtml 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/README.md +113 -0
package/assets/app.js +555 -0
package/dist/browser-entry.js +34 -0
package/dist/cli.js +158 -0
package/dist/orzmd.browser.js +326 -0
package/dist/template.js +263 -0
package/orz-mdhtml-skills/SKILL.md +90 -0
package/package.json +41 -0

package/dist/template.js ADDED Viewed

@@ -0,0 +1,263 @@
+/**
+ * Builds the self-contained .md.html shell.
+ *
+ * The file is a *document first*: by default it shows the rendered Markdown in
+ * an <iframe> (full theme isolation, true WYSIWYG) with a single small edit
+ * affordance. Clicking it reveals a minimal editor (CodeMirror) beside a live,
+ * incrementally-updated preview. The Markdown source is the single source of
+ * truth, embedded in a <script type="text/markdown">; Save re-serializes the
+ * outer document. Editor libraries are lazy-loaded on first edit so reading
+ * stays lightweight.
+ */
+/** Guard inline <script> content against premature `</script>` termination. */
+function escapeForScript(s) {
+    return s.replace(/<\/(script)/gi, '<\\/$1');
+}
+function escapeHtml(s) {
+    return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+export function buildHtml(opts) {
+    const rendererTag = opts.renderer.mode === 'inline'
+        ? `<script>${escapeForScript(opts.renderer.js)}</script>`
+        : `<script src="${opts.renderer.src}"></script>`;
+    const defaultScheme = opts.themes.find((t) => t.id === opts.defaultTheme)?.scheme ?? 'light';
+    // Everything the app needs to (re)build the iframe + manage themes.
+    const config = {
+        filename: opts.filename,
+        docId: opts.docId,
+        rendererVersion: opts.rendererVersion,
+        versionManifest: opts.versionManifest,
+        defaultTheme: opts.defaultTheme,
+        themes: opts.themes,
+        frame: opts.frame,
+        editorLibs: opts.editorLibs,
+        runtime: opts.runtimeScript,
+    };
+    const themeOptions = opts.themes
+        .map((t) => `<option value="${t.id}"${t.id === opts.defaultTheme ? ' selected' : ''}>${escapeHtml(t.name)}</option>`)
+        .join('');
+    return `<!DOCTYPE html>
+<html lang="en" data-mode="read" data-chrome="${defaultScheme}">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeHtml(opts.title)}</title>
+<meta name="generator" content="orz-mdhtml">
+<style>
+  :root {
+    --chrome-h: 46px;
+    --fab-size: 40px;
+  }
+  [data-chrome="light"] {
+    --c-bg: #ffffff; --c-fg: #1f2328; --c-muted: #6b7280;
+    --c-border: #e6e8eb; --c-hover: #f2f4f6; --c-active: #e8eef7;
+    --c-accent: #2f6feb; --c-shadow: 0 1px 2px rgba(16,24,40,.06), 0 1px 3px rgba(16,24,40,.10);
+    --c-fab-bg: rgba(255,255,255,.92); --c-fab-fg: #374151;
+  }
+  [data-chrome="dark"] {
+    --c-bg: #1b1d21; --c-fg: #e6e8eb; --c-muted: #9aa1ab;
+    --c-border: #2c3036; --c-hover: #24272c; --c-active: #2b3340;
+    --c-accent: #5b8cff; --c-shadow: 0 1px 2px rgba(0,0,0,.4), 0 2px 8px rgba(0,0,0,.35);
+    --c-fab-bg: rgba(33,36,41,.92); --c-fab-fg: #cbd2da;
+  }
+  * { box-sizing: border-box; }
+  html, body { margin: 0; height: 100%; }
+  body {
+    font: 14px/1.5 -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+    background: var(--c-bg); color: var(--c-fg);
+    height: 100vh; overflow: hidden;
+    display: flex; flex-direction: column;
+  }
+  /* ---- toolbar (hidden while reading) ---- */
+  #orz-bar {
+    height: var(--chrome-h); flex: 0 0 var(--chrome-h);
+    display: none; align-items: center; gap: 8px;
+    padding: 0 10px; background: var(--c-bg);
+    border-bottom: 1px solid var(--c-border);
+    -webkit-user-select: none; user-select: none;
+  }
+  html:not([data-mode="read"]) #orz-bar { display: flex; }
+  .bar-spring { flex: 1; }
+  .icon-btn {
+    display: inline-flex; align-items: center; justify-content: center;
+    width: 30px; height: 30px; border: 0; border-radius: 7px;
+    background: transparent; color: var(--c-fg); cursor: pointer;
+    transition: background .12s, color .12s;
+  }
+  .icon-btn:hover { background: var(--c-hover); }
+  .icon-btn svg { width: 17px; height: 17px; display: block; }
+  .icon-btn[aria-pressed="true"] { color: var(--c-accent); background: var(--c-active); }
+  .icon-btn[aria-pressed="false"] { color: var(--c-muted); }
+  .text-btn {
+    display: inline-flex; align-items: center; gap: 6px; height: 30px; padding: 0 11px;
+    border: 1px solid var(--c-border); border-radius: 8px;
+    background: var(--c-bg); color: var(--c-fg); cursor: pointer; font: inherit; font-weight: 500;
+  }
+  .text-btn:hover { background: var(--c-hover); }
+  .text-btn.primary { background: var(--c-accent); border-color: var(--c-accent); color: #fff; }
+  .text-btn.primary:hover { filter: brightness(1.06); }
+  .bar-title {
+    font-weight: 600; color: var(--c-fg); max-width: 38vw;
+    overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
+  }
+  .dirty-dot { width: 7px; height: 7px; border-radius: 50%; background: var(--c-accent);
+    margin-left: 2px; opacity: 0; transition: opacity .15s; }
+  html[data-dirty="1"] .dirty-dot { opacity: 1; }
+  select.theme-pick {
+    height: 30px; padding: 0 26px 0 10px; border: 1px solid var(--c-border); border-radius: 8px;
+    background: var(--c-bg) no-repeat right 8px center; color: var(--c-fg); font: inherit; cursor: pointer;
+    -webkit-appearance: none; appearance: none;
+    background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='12' height='12' viewBox='0 0 24 24' fill='none' stroke='%236b7280' stroke-width='2.5'%3E%3Cpath d='M6 9l6 6 6-6'/%3E%3C/svg%3E");
+  }
+  /* ---- stage: editor pane + preview iframe ---- */
+  #orz-stage { flex: 1; display: flex; min-height: 0; position: relative; }
+  #orz-editor { display: none; min-width: 0; height: 100%; background: var(--c-bg); }
+  #orz-frame { flex: 1; min-width: 0; height: 100%; width: 100%; border: 0; background: #fff; display: block; }
+  html[data-mode="read"]  #orz-editor { display: none; }
+  html[data-mode="read"]  #orz-frame  { flex: 1; }
+  html[data-mode="split"] #orz-editor { display: block; }
+  html[data-mode="split"] #orz-frame  { border-left: 1px solid var(--c-border); }
+  /* CodeMirror fills the editor pane */
+  #orz-editor .CodeMirror { height: 100%; font-family: "SF Mono", "JetBrains Mono", ui-monospace, Menlo, Consolas, monospace; font-size: 13.5px; line-height: 1.6; }
+  #orz-textarea { width: 100%; height: 100%; box-sizing: border-box; border: 0; padding: 16px;
+    resize: none; outline: none; font: 13.5px/1.6 ui-monospace, Menlo, Consolas, monospace;
+    background: var(--c-bg); color: var(--c-fg); }
+  /* Split.js gutter */
+  .gutter { background: var(--c-border); position: relative; }
+  .gutter.gutter-horizontal { cursor: col-resize; width: 8px; }
+  .gutter.gutter-horizontal::after { content: ""; position: absolute; inset: 0 3px;
+    border-radius: 3px; background: transparent; transition: background .12s; }
+  .gutter.gutter-horizontal:hover::after { background: var(--c-accent); }
+  /* ---- floating reader tools (reading mode only) ---- */
+  #orz-reader-tools {
+    position: fixed; right: 18px; bottom: 18px; z-index: 30;
+    display: none; align-items: center; gap: 2px; padding: 4px;
+    border-radius: 24px; border: 1px solid var(--c-border);
+    background: var(--c-fab-bg); color: var(--c-fab-fg);
+    box-shadow: var(--c-shadow); backdrop-filter: blur(8px);
+    opacity: .6; transition: opacity .2s;
+  }
+  #orz-reader-tools:hover { opacity: 1; }
+  html[data-mode="read"] #orz-reader-tools { display: inline-flex; }
+  .rtool {
+    width: 34px; height: 34px; border: 0; border-radius: 50%;
+    background: transparent; color: inherit; cursor: pointer;
+    display: inline-flex; align-items: center; justify-content: center;
+    line-height: 1; transition: background .12s, transform .12s;
+  }
+  .rtool:hover { background: var(--c-hover); }
+  .rtool svg { width: 18px; height: 18px; }
+  .rtool.font { font-weight: 700; font-family: Georgia, "Times New Roman", serif; }
+  .rtool.edit { position: relative; background: var(--c-accent); color: #fff; }
+  .rtool.edit:hover { filter: brightness(1.06); transform: translateY(-1px); }
+  .rtool.edit::after {
+    content: ""; position: absolute; top: 0; right: 0; width: 11px; height: 11px;
+    border-radius: 50%; background: #e5534b; border: 2px solid var(--c-fab-bg);
+    opacity: 0; transition: opacity .15s;
+  }
+  html[data-dirty="1"] #orz-reader-tools { opacity: 1; }
+  html[data-dirty="1"] .rtool.edit::after { opacity: 1; }
+  /* toast */
+  #orz-toast {
+    position: fixed; left: 50%; bottom: 20px; transform: translateX(-50%) translateY(8px);
+    background: #111418; color: #fff; padding: 8px 14px; border-radius: 9px; font-size: 13px;
+    opacity: 0; pointer-events: none; transition: opacity .18s, transform .18s; z-index: 50;
+  }
+  #orz-toast.show { opacity: 1; transform: translateX(-50%) translateY(0); }
+  /* update banner */
+  #orz-update {
+    position: fixed; top: 10px; left: 50%; transform: translateX(-50%); z-index: 40;
+    display: none; align-items: center; gap: 12px;
+    padding: 8px 12px; border-radius: 10px; font-size: 13px;
+    background: var(--c-bg); color: var(--c-fg); border: 1px solid var(--c-border); box-shadow: var(--c-shadow);
+  }
+  #orz-update.show { display: flex; }
+  /* published-page (read-only) save notice */
+  #orz-served-note {
+    position: fixed; top: 10px; left: 50%; transform: translateX(-50%); z-index: 41;
+    display: none; align-items: center; gap: 12px; max-width: min(92vw, 560px);
+    padding: 10px 12px; border-radius: 10px; font-size: 13px; line-height: 1.4;
+    background: var(--c-bg); color: var(--c-fg); border: 1px solid var(--c-border); box-shadow: var(--c-shadow);
+  }
+  #orz-served-note.show { display: flex; }
+  #orz-served-note .note-text { flex: 1; }
+</style>
+</head>
+<body>
+<div id="orz-bar" role="toolbar" aria-label="Editor toolbar">
+  <button class="icon-btn" id="orz-done" title="Done — back to reading" aria-label="Done">
+    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M5 12h14M5 12l6-6M5 12l6 6"/></svg>
+  </button>
+  <span class="bar-title" id="orz-title">${escapeHtml(opts.title)}</span>
+  <span class="dirty-dot" title="Unsaved changes"></span>
+  <span class="bar-spring"></span>
+  <button class="icon-btn" id="orz-sync" title="Sync scrolling" aria-label="Sync scrolling" aria-pressed="true">
+    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M17 1l4 4-4 4"/><path d="M3 11V9a4 4 0 0 1 4-4h14"/><path d="M7 23l-4-4 4-4"/><path d="M21 13v2a4 4 0 0 1-4 4H3"/></svg>
+  </button>
+  <select class="theme-pick" id="orz-theme" title="Theme" aria-label="Theme">${themeOptions}</select>
+  <button class="icon-btn" id="orz-export-bar" title="Download a copy" aria-label="Download a copy">
+    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4"/><path d="M7 10l5 5 5-5"/><path d="M12 15V3"/></svg>
+  </button>
+  <button class="text-btn primary" id="orz-save" title="Save (Cmd/Ctrl+S)">
+    <svg viewBox="0 0 24 24" width="15" height="15" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M19 21H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h11l5 5v11a2 2 0 0 1-2 2z"/><path d="M17 21v-8H7v8M7 3v5h8"/></svg>
+    Save
+  </button>
+</div>
+<div id="orz-stage">
+  <div id="orz-editor"><textarea id="orz-textarea" spellcheck="false"></textarea></div>
+  <iframe id="orz-frame" title="Preview"></iframe>
+</div>
+<div id="orz-reader-tools">
+  <button class="rtool font" id="orz-font-dec" title="Smaller text" aria-label="Decrease text size" style="font-size:13px">A</button>
+  <button class="rtool font" id="orz-font-inc" title="Larger text" aria-label="Increase text size" style="font-size:18px">A</button>
+  <button class="rtool" id="orz-export" title="Download a copy" aria-label="Download a copy">
+    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4"/><path d="M7 10l5 5 5-5"/><path d="M12 15V3"/></svg>
+  </button>
+  <button class="rtool edit" id="orz-fab" title="Edit this document" aria-label="Edit this document">
+    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M12 20h9"/><path d="M16.5 3.5a2.12 2.12 0 0 1 3 3L7 19l-4 1 1-4 12.5-12.5z"/></svg>
+  </button>
+</div>
+<div id="orz-update">
+  <span class="upd-text"></span>
+  <button class="text-btn" id="orz-upd-dismiss">Dismiss</button>
+</div>
+<div id="orz-served-note">
+  <span class="note-text">This is a published page — your edits can't be saved back to the server. You can download a local copy to edit and save.</span>
+  <button class="text-btn primary" id="orz-served-download">Download copy</button>
+  <button class="text-btn" id="orz-served-dismiss">Dismiss</button>
+</div>
+<div id="orz-toast"></div>
+<!-- Embedded markdown source (single source of truth) -->
+<script type="text/markdown" id="orz-src">
+${escapeForScript(opts.source)}
+</script>
+<!-- orz-markdown renderer (parent) -->
+${rendererTag}
+<!-- in-file app config + runtime -->
+<script>window.__ORZ_MDHTML__ = ${escapeForScript(JSON.stringify(config))};</script>
+<script>${escapeForScript(opts.appJs)}</script>
+</body>
+</html>
+`;
+}

package/orz-mdhtml-skills/SKILL.md ADDED Viewed

@@ -0,0 +1,90 @@
+---
+name: orz-mdhtml
+description: Create and use self-contained, editable .md.html documents from Markdown (orz-mdhtml). Use when a user wants a single shareable HTML file that reads like a webpage but can be edited and saved in the browser — e.g. teaching handouts, notes, or published articles.
+---
+# orz-mdhtml — self-contained editable `.md.html`
+`orz-mdhtml` turns a Markdown file into **one `.md.html` file** that:
+- reads like a normal themed webpage (rendered in an isolated `<iframe>`),
+- can be **edited in the browser** (CodeMirror source + live incremental preview),
+- lets readers **switch themes**, **resize text**, **export a local copy**, and
+  **copy rendered content as Markdown source**,
+- **saves itself**: in place on local files (Chromium File System Access API),
+  or as a download elsewhere.
+The Markdown source is embedded in the file as the single source of truth
+(`<script type="text/markdown" id="orz-src">`). Saving re-serializes the whole
+document, so the file reproduces itself.
+## When to use it
+- A user wants a **single shareable file** (email/USB/served page) that is both
+  readable and editable without any app.
+- **Teaching**: a teacher serves a handout as a web page; students download
+  their own copy to annotate.
+- Prefer plain `.md` when the target is a repo/pipeline; prefer orz-markdown's
+  standalone HTML when no editing is needed; use `.md.html` when in-browser
+  editing or reader annotation matters.
+## Generate a file
+Node 18+. From the package (CLI: `orz-mdhtml`, or `npm run gen --` in a clone):
+```bash
+orz-mdhtml <input.md> [options]
+  -o, --out <file>   output path (default: <input>.md.html)
+  --theme <name>     default theme id (default: light-academic-1)
+  --inline           embed the renderer bundle (default; recommended)
+  --cdn              reference the renderer from jsDelivr (needs orz-mdhtml-browser published)
+  --title <text>     document <title>
+```
+Always prefer `--inline` unless `orz-mdhtml-browser` is published to npm.
+Theme ids: `light-academic-1/2`, `light-neat-1/2`, `light-playful-1/2`,
+`beige-decent-1/2`, `dark-elegant-1/2`.
+## Authoring the Markdown
+The source is **orz-markdown** Markdown — standard Markdown plus KaTeX math,
+`{{name body}}` plugins (mermaid, smiles, qrcode, youtube, toc, …), `::: name`
+containers, and `{{attrs[#id .class]}}`. For the full syntax, read the
+orz-markdown skill, shipped at:
+```
+node_modules/orz-markdown/orz-markdown-skills/SKILL.md
+```
+You write only the `.md`; do not hand-write the `.md.html`. To change content,
+edit the `.md` and regenerate (or edit in the browser and Save).
+## What the generated file needs at view time
+"Self-contained" means *one file*, **not** *offline*. The renderer is embedded
+(with `--inline`), but these load from CDN when the file is opened, so **viewing
+requires internet**: theme CSS (jsDelivr `orz-markdown/themes/...`), KaTeX CSS,
+highlight.js, Mermaid, and — only on first edit — CodeMirror, Split.js, morphdom.
+## Deploying / sharing
+- **Distribute the file**: send/host the `.md.html`; readers open it in a browser.
+- **Serve it**: any static host works. When served over http(s), readers can't
+  save back to the server — the file detects this and tells them to **Download a
+  local copy** to edit and save. In-place Save only applies to `file://` copies
+  they own.
+- **Editing/Save** needs a Chromium browser (Chrome/Edge); reading, themes,
+  font size, export, and copy-as-markdown work in all modern browsers.
+## Gotchas for agents
+- Edit the `.md` and regenerate; never restructure the generated HTML by hand —
+  the in-file runtime expects specific element ids (`#orz-src`, `#orz-frame`,
+  `#orz-doc`, etc.).
+- If you post-process the rendered HTML, **preserve `data-md` and
+  `data-src-line` attributes** — they power copy-as-markdown and scroll-sync.
+- The embedded source guards `</script>` as `<\/script>`; read it back via the
+  `#orz-src` element's `textContent` and reverse that escape.
+- Requires `orz-markdown` ≥ 1.2.0 (copy-as-markdown); ≥ 1.2.1 for the
+  whole-table/blockquote copy fix.

package/package.json ADDED Viewed

@@ -0,0 +1,41 @@
+{
+  "name": "orz-mdhtml",
+  "version": "0.1.0",
+  "description": "Generate self-contained, editable .md.html files from Markdown using orz-markdown — preview + edit modes, source-aware copy, in-place save.",
+  "type": "module",
+  "bin": {
+    "orz-mdhtml": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "assets",
+    "orz-mdhtml-skills"
+  ],
+  "scripts": {
+    "build": "tsc && npm run bundle",
+    "bundle": "tsx build/bundle.ts",
+    "gen": "tsx src/cli.ts",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "markdown",
+    "orz-markdown",
+    "self-contained",
+    "html",
+    "editor",
+    "single-file"
+  ],
+  "author": "Yu Wang <yuwang@orz.how>",
+  "license": "MIT",
+  "dependencies": {
+    "orz-markdown": "^1.2.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "esbuild": "^0.21.5",
+    "path-browserify": "^1.0.1",
+    "tsx": "^4.7.0",
+    "typescript": "^5.4.0"
+  }
+}