orz-markdown 1.3.0 → 1.3.1

package/README.md

@@ -55,7 +55,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 +130,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 +167,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.1",
   "description": "Customized markdown-it parser with official and custom plugins",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",