orz-markdown 1.3.0 → 1.3.2

package/README.md

@@ -1,9 +1,17 @@
 # orz-markdown
 
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.21099237.svg)](https://doi.org/10.5281/zenodo.21099237)
+
 A deeply customized markdown-it parser configured with several official plugins and many custom plugins designed to render interactive objects, embedded rich media, and invisible data. Crafted alongside beautifully optimized CSS themes for an excellent out-of-the-box rendering experience. An agent skill is available for using this markdown parser with AI agents. 
 
 Rendered HTML is intended to live inside a `.markdown-body` container and be paired with one of the bundled themes.
 
+## Citation
+
+If you use or cite the orz-markdown website or editable document family, please cite the archived release:
+
+Yu Wang. (2026). orz-markdown: a Markdown family that travels in one file. Zenodo. https://doi.org/10.5281/zenodo.21099237
+
 ## Installation
 
 Install the package via npm:
@@ -55,7 +63,7 @@ Once the runtime is loaded, selecting rendered content and copying it (Cmd/Ctrl-
 
 It only transforms selections inside an element with class `markdown-body` (wrap your rendered output in one, e.g. `<article class="markdown-body">…</article>`, or mark a container with `data-orz-copy`), and never touches selections inside `<input>`, `<textarea>`, or `contenteditable` regions.
 
-Generated constructs that lose their source after client-side rendering — `mermaid`, `smiles`, `qrcode`, `youtube` — carry a `data-md` attribute that the walker emits verbatim. As a result a copied table of contents yields its heading links (not `{{toc 2,3}}`) and a copied QR code yields `{{qr ...}}` (not its SVG). **Do not strip `data-md` attributes** if you post-process the HTML.
+Generated constructs that lose their source after client-side rendering — `mermaid`, `smiles`, `qrcode`, `youtube`, `chart` — carry a `data-md` attribute that the walker emits verbatim. As a result a copied table of contents yields its heading links (not `{{toc 2,3}}`) and a copied QR code yields `{{qr ...}}` (not its SVG). **Do not strip `data-md` attributes** if you post-process the HTML.
 
 You can also convert a node programmatically:
 
@@ -130,6 +138,14 @@ node_modules/orz-markdown/orz-markdown-skills/SKILL.md
 
 with supporting files under `orz-markdown-skills/references/` and `orz-markdown-skills/assets/`. Point your agent tooling at that directory (e.g. copy or symlink it into your agent's skills folder).
 
+Or hand your agent the skill straight from the CDN — no install needed:
+
+```
+https://cdn.jsdelivr.net/npm/orz-markdown/orz-markdown-skills/SKILL.md
+```
+
+See **[markdown.orz.how/agents.html](https://markdown.orz.how/agents.html)** for every install route (Claude Code, Claude.ai upload, or point-at-URL for any agent).
+
 ## Official Plugins Bundled
 
 This project builds upon `markdown-it` and pre-configures a curated selection of official and popular community plugins.
@@ -159,7 +175,7 @@ We utilize a generalized and uniform `{{plugin_name ...}}` syntax for all custom
 | **Attributes** | N/A | `# Header {{attrs[id="my-id"]}}`| Injects continuous HTML attributes (classes, IDs, config properties) to the immediately preceding element. |
 | **Emoji** | `em` | `{{emoji smile}}` / `{{em tada}}` | Renders the specific text alias directly into the corresponding Unicode emoji natively. |
 | **Table of Content** | N/A | `{{toc}}` or `{{toc 2,3}}` | Autogenerates a Table of Contents based on document headings. Allows specifying bound heading ranges. |
-| **Space** | N/A | `{{space 4}}` | Inserts inline horizontal whitespace entities directly into the text. |
+| **Space** | N/A | `{{space 4}}` | Inserts inline horizontal whitespace — an empty `inline-block` span sized in `rem` (`{{space 4}}` → 4rem wide). |
 | **YouTube** | `yt` | `{{youtube dQw4w9WgXcQ}}` | Embedded block element containing a responsive YouTube video iframe matching the ID. |
 | **Markdown Source**| `md` | `{{md path/to/file.md}}` | Securely embeds the complete content of an external markdown file directly into the parsed structure. |
 | **QR Code** | `qr` | `{{qr https://example.com}}` | Transforms text inline implicitly into an internally generated SVG QR Code natively. |

package/dist/runtime.js

@@ -121,7 +121,7 @@ exports.browserRuntimeScript = String.raw `
   // ---- copy-as-markdown: DOM -> Markdown walker ---------------------------
   // Converts a selected DOM fragment back to Markdown so that copying rendered
   // content yields source, not HTML. Standard constructs are reconstructed from
-  // their tags; generated constructs (math, mermaid, smiles, qr, youtube) carry
+  // their tags; generated constructs (math, mermaid, smiles, qr, youtube, chart) carry
   // a [data-md] breadcrumb that is emitted verbatim. Written without template
   // literals/backticks because this whole file is a String.raw template.
   var BT = String.fromCharCode(96);

package/orz-markdown-skills/SKILL.md

@@ -8,7 +8,7 @@ compatibility:
 
 # orz-markdown
 
-A deeply customized `markdown-it` instance with 10+ plugins, 9 official plugin bundles, and 12 ready-to-use CSS themes. All rendered HTML lives inside `<article class="markdown-body">`.
+A deeply customized `markdown-it` instance with 10+ custom plugins, 10 official plugin bundles, and 12 ready-to-use CSS themes. All rendered HTML lives inside `<article class="markdown-body">`.
 
 ## Rendering (Node.js / ESM)
 
@@ -38,10 +38,10 @@ const html = md.render(resolved, { markdownBasePath: '/local/base/path' });
 
 Every page that displays parser output needs **all five** of these:
 
-1. **Theme stylesheet** — one of the 10 bundled themes, or `assets/minimal.css`
+1. **Theme stylesheet** — one of the 12 bundled themes, or `assets/minimal.css`
 2. **KaTeX CSS** — `https://cdn.jsdelivr.net/npm/katex@0.16.35/dist/katex.min.css`
 3. **Highlight.js CSS** — match light/dark to the chosen theme
-4. **Three CDN scripts** — Highlight.js, Mermaid.js, SmilesDrawer (loaded in body)
+4. **Four CDN scripts** — Highlight.js, Mermaid.js, SmilesDrawer, Chart.js (loaded in body)
 5. **Two inline scripts** — tabs initializer and QR code runtime (also in body)
 
 **Use `assets/template.html`** — all CDN links, scripts, and the `.markdown-body` wrapper are pre-wired. Copy it and replace the `<!-- INSERT RENDERED HTML HERE -->` comment.
@@ -56,6 +56,7 @@ CDN URLs (pinned versions):
 | Highlight.js dark CSS | `.../styles/atom-one-dark.min.css` |
 | Mermaid.js | `https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js` |
 | SmilesDrawer | `https://unpkg.com/smiles-drawer@1.0.10/dist/smiles-drawer.min.js` |
+| Chart.js | `https://cdn.jsdelivr.net/npm/chart.js@4/dist/chart.umd.min.js` |
 
 ### Browser runtime API
 
@@ -71,7 +72,7 @@ document.body.appendChild(script);
 
 The runtime also provides **copy-as-Markdown**: with it loaded, copying a selection inside `.markdown-body` puts Markdown source on the clipboard, not HTML (tables, lists, math, code, etc. are reconstructed). It skips selections inside `<input>`/`<textarea>`/`contenteditable`. Convert a node directly with `window.OrzMarkdownRuntime.elementToMarkdown(node)`.
 
-> **Do not strip `data-md` attributes.** `mermaid`, `smiles`, `qrcode`, and `youtube` output carry a `data-md` breadcrumb so copy recovers their source after client-side rendering (e.g. a copied QR yields `{{qr ...}}`, not its SVG). Preserve these attributes if you post-process the HTML.
+> **Do not strip `data-md` attributes.** `mermaid`, `smiles`, `qrcode`, `youtube`, and `chart` output carry a `data-md` breadcrumb so copy recovers their source after client-side rendering (e.g. a copied QR yields `{{qr ...}}`, not its SVG). Preserve these attributes if you post-process the HTML.
 
 ---
 
@@ -119,7 +120,7 @@ Escape with backslash: `\{{name}}` renders as literal `{{name}}`.
 |---|---|---|
 | **span** | `sp` | `{{sp[red] colored}}` · `{{sp[success] ✓ Done}}` |
 | **emoji** | `em` | `{{emoji wave}}` · `{{em tada}}` |
-| **space** | — | `{{space 4}}` → 4 × `&nbsp;` |
+| **space** | — | `{{space 4}}` → 4rem-wide inline-block spacer |
 | **qrcode** | `qr` | `{{qr https://example.com}}` (click-to-expand SVG) |
 | **youtube** | `yt` | `{{youtube dQw4w9WgXcQ}}` (responsive iframe) |
 | **mermaid** | `mm` | `{{mm\ngraph LR\nA-->B\n}}` |
@@ -178,7 +179,7 @@ Documents may carry stable block IDs on headings: `## Title{{attrs[#blk-abc12345
 |---|---|
 | `references/syntax.md` | Full syntax with examples for every plugin, container, and extended markdown feature |
 | `references/block-ids.md` | Stable block-ID preservation rules — REQUIRED reading before editing documents that use `{{attrs[#blk-...]}}` |
-| `references/themes.md` | Custom theme guide: design tokens, element checklist, 10 design guidelines |
+| `references/themes.md` | Custom theme guide: design tokens, element checklist, 12 design guidelines |
 | `references/css-classes.md` | Every CSS class and HTML element the parser emits — the spec for theme authors |
 | `references/embedding.md` | Host-integration guide for apps that bring their own CSS/shell (slide engines, viewers, editors): the CSS contract + reset gotchas, the JS runtime + diagram drawing, and what copy-as-Markdown needs |
 | `assets/template.html` | Ready-to-use HTML page template with all scripts and CDN links wired up |

package/orz-markdown-skills/assets/template.html

@@ -64,6 +64,26 @@ if (typeof SmilesDrawer !== 'undefined') {
 }
   </script>
 
+  <!-- Chart.js — renders {{chart}} canvases emitted by the parser. -->
+  <script src="https://cdn.jsdelivr.net/npm/chart.js@4/dist/chart.umd.min.js"></script>
+  <script>
+if (typeof Chart !== 'undefined') {
+  document.querySelectorAll('canvas.orz-chart[data-chart]').forEach(function (canvas) {
+    var wrap = document.createElement('div');
+    wrap.style.cssText = 'position:relative;width:100%;max-width:520px;margin:.6em auto';
+    canvas.parentNode.insertBefore(wrap, canvas);
+    wrap.appendChild(canvas);
+    canvas.removeAttribute('width');
+    canvas.removeAttribute('height');
+    try {
+      var config = JSON.parse(canvas.getAttribute('data-chart') || '{}');
+      config.options = Object.assign({ responsive: true, maintainAspectRatio: true, animation: false }, config.options || {});
+      new Chart(canvas, config);
+    } catch (e) {}
+  });
+}
+  </script>
+
   <!-- Tabs component — builds the .tabs-bar and activates .tab panels.
        Must run after the DOM is painted so .tabs elements are found.        -->
   <script>
@@ -184,7 +204,7 @@ if (typeof SmilesDrawer !== 'undefined') {
   // ---- copy-as-markdown: DOM -> Markdown walker ---------------------------
   // Converts a selected DOM fragment back to Markdown so that copying rendered
   // content yields source, not HTML. Standard constructs are reconstructed from
-  // their tags; generated constructs (math, mermaid, smiles, qr, youtube) carry
+  // their tags; generated constructs (math, mermaid, smiles, qr, youtube, chart) carry
   // a [data-md] breadcrumb that is emitted verbatim. Written without template
   // literals/backticks because this whole file is a String.raw template.
   var BT = String.fromCharCode(96);

package/orz-markdown-skills/references/css-classes.md

@@ -193,23 +193,30 @@ span.qrcode { background: #fff; padding: 4px; /* or 6px */ vertical-align: middl
 
 Note: `span.success/info/warning/danger` also have `display: inline-flex; align-items: center; line-height: 1; white-space: nowrap` set by `common.css`. Add `padding`, `border-radius`, `font-size`, and colors in the theme.
 
+### Chart
+
+| Class | Element | Description |
+|---|---|---|
+| `canvas.orz-chart` | `<canvas>` | Carries a Chart.js config as HTML-escaped JSON in `data-chart` (and a `data-md` breadcrumb). The host runtime reads `data-chart` and calls Chart.js. Cap its width. |
+
+```css
+canvas.orz-chart { max-width: 100%; height: auto; }
+```
+
 ### Table of Contents
 
 | Class | Element | Description |
 |---|---|---|
-| `.toc-wrapper` | `<div>` | Outer wrapper (for positioning). |
-| `nav.toc` / `.toc-list` | `<nav>` | The `<ul>` tree of heading links. Reset list bullets in TOC context. |
+| `.toc-list` | `<ul>` | The flat `<ul>` of heading links emitted by `{{toc}}`. Each `<li>` carries an inline `padding-left` for its depth. Reset list bullets. This is the **only** class the parser emits for the TOC. |
 
 ```css
-nav.toc, .toc-list {
-  padding: ...;
-  border: 1px solid var(--border);
-}
-nav.toc ul, .toc-list ul { margin: 0; padding-left: 1.1rem; }
-nav.toc li, .toc-list li { list-style: none; margin-bottom: 0.25rem; }
-nav.toc a, .toc-list a { text-decoration: none; color: var(--link); }
+.toc-list { padding: ...; border: 1px solid var(--border); list-style: none; }
+.toc-list li { list-style: none; margin-bottom: 0.25rem; }
+.toc-list a  { text-decoration: none; color: var(--link); }
 ```
 
+> Note: the parser does **not** emit a `<nav class="toc">` wrapper or a `.toc-wrapper`. `{{toc}}` produces a single `<ul class="toc-list">`. If your host wants a wrapper, add it around the rendered TOC yourself.
+
 ### Test elements (development only)
 
 | Class | Element | Description |

package/orz-markdown-skills/references/embedding.md

@@ -166,14 +166,15 @@ when) all of this holds:
 2. **Content is inside `.markdown-body`** (or an element with `data-orz-copy`).
    The handler ignores selections elsewhere and inside inputs/textareas.
 3. **`data-md` breadcrumbs are preserved.** Generated constructs whose source is
-   otherwise lost — `mermaid`, `smiles`, `qrcode`, `youtube`, `toc`, `chart`,
-   `{{sp}}` (and any plugin that adds one) — carry `data-md` with their original
-   directive. The walker emits it verbatim. **Never strip `data-md`** when you
-   post-process HTML.
+   otherwise lost — `mermaid`, `smiles`, `qrcode`, `youtube`, `chart` (and any
+   plugin that adds one) — carry `data-md` with their original directive. The
+   walker emits it verbatim. **Never strip `data-md`** when you post-process HTML.
 4. **Plugin/container classes are preserved.** Constructs without a `data-md`
-   are recovered *by class*: `<span class="red">` → `{{sp[red] …}}`,
+   are recovered *by class/structure*: `<span class="red">` → `{{sp[red] …}}`,
    `<div class="center">` → `::: center … :::`, nested `cols`/`tabs` get the
-   right fence length. If you rewrite/strip these classes, copy loses the source.
+   right fence length, and a `{{toc}}` is recovered as its rendered list of
+   heading links (not the `{{toc}}` directive). If you rewrite/strip these
+   classes, copy loses the source.
 
 Caveat: a container (`::: center`, `:::: cols`, spoiler, tabs) is recovered only
 when the **selection includes the container element**, not just the text inside

package/orz-markdown-skills/references/syntax.md

@@ -310,10 +310,12 @@ Uses `node-emoji` for name lookup. The emoji text alias (e.g., `wave`, `smile`)
 ### space — Inline horizontal whitespace
 
 ```markdown
-{{space 4}}    →      (4 non-breaking spaces)
-{{space 1}}    →  
+{{space 4}}    → 4rem-wide inline-block spacer
+{{space 1}}    → 1rem-wide inline-block spacer
 ```
 
+The numeric argument is a `rem` width: `{{space 4}}` emits `<span style="display:inline-block;width:4rem"></span>`. Non-positive or non-numeric values render nothing.
+
 ---
 
 ### qrcode / qr — Inline QR code
@@ -381,7 +383,7 @@ Renders `<div class="smiles-render"><canvas data-smiles="...">`. SmilesDrawer.js
 {{toc 1,4}}
 ```
 
-Auto-generates a `<nav class="toc">` from all headings in the document. Optional argument is a comma-separated level range (`min,max`), defaulting to all levels. Must appear after the headings it references in the source (or at the start — the parser makes a pass over the full document).
+Auto-generates a `<ul class="toc-list">` of heading links (each `<li>` indented by depth). Optional argument is a comma-separated level range (`min,max`), defaulting to `1,3`. The placement in the source does not matter — a core rule scans the whole document, so `{{toc}}` works at the top or bottom.
 
 ---
 

package/orz-markdown-skills/references/themes.md

@@ -99,8 +99,8 @@ Follow this section order in every theme file for consistency:
 12. Semantic containers: `.success`, `.info`, `.warning`, `.danger`
 13. Layout utilities: `.left`, `.right`, `.center`
 14. Spoiler, tabs, and columns: `details.spoil`, `.tabs`, `.cols`
-15. TOC and footnotes: `nav.toc`, `.footnotes`
-16. Plugin output: `.youtube-embed`, `.mermaid`, `.smiles-render`, `.qrcode`, span color/badge classes
+15. TOC and footnotes: `.toc-list`, `.footnotes`
+16. Plugin output: `.youtube-embed`, `.mermaid`, `.smiles-render`, `canvas.orz-chart`, `.qrcode`, span color/badge classes
 17. Decorative pseudo-elements and theme-only flourishes
 18. Responsive rules (`@media`)
 19. Print rules (`@media print`)
@@ -165,12 +165,13 @@ Every theme must have CSS rules for all of the following. See `references/css-cl
 - [ ] `.tabs` `.tabs-bar` `.tabs-bar-btn` `.tabs-bar-btn.active` `.tab` `.tab.active`
 - [ ] `.tabs:not([data-js]) .tab` — no-JS fallback: show all panels
 - [ ] `.cols` `.col`
-- [ ] `nav.toc` `.toc-list` — list reset, link styles
+- [ ] `.toc-list` — list reset, link styles (the parser emits only `<ul class="toc-list">`, no `nav.toc` wrapper)
 - [ ] `span.red` `span.yellow` `span.green` `span.blue`
 - [ ] `span.success` `span.info` `span.warning` `span.danger` — inline badge variant
 - [ ] `div.youtube-embed` `div.youtube-embed iframe` — 16:9 responsive wrapper (structural)
 - [ ] `div.mermaid` `div.mermaid svg`
 - [ ] `div.smiles-render` `canvas[data-smiles]`
+- [ ] `canvas.orz-chart` — width-capped (Chart.js draws into it client-side)
 - [ ] `span.qrcode` — **must have `background: #fff`** (SVG is always black-on-white)
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orz-markdown",
-  "version": "1.3.0",
+  "version": "1.3.2",
   "description": "Customized markdown-it parser with official and custom plugins",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/themes/common.css

@@ -10,12 +10,19 @@
 
 .markdown-body img {
   display: block;
-  width: auto;
   max-width: 100%;
   max-height: 100%;
-  height: auto;
   object-fit: contain;
 }
+/* Responsive by default, but explicit dimensions from `![](img =200x100)`
+   (markdown-it-imsize → width/height attributes) must win: only auto-size
+   images that DON'T carry an explicit width/height. */
+.markdown-body img:not([width]) {
+  width: auto;
+}
+.markdown-body img:not([height]) {
+  height: auto;
+}
 
 .markdown-body p > img {
   display: inline;