Orz markdown

Skill wangyu16/orz-claude-plugin/skills/orz-markdown

Install

npx -y skills add wangyu16/orz-claude-plugin --skill orz-markdown

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

3 things to look at

21 days oldThe repository was created 21 days ago. New is not bad, but a brand new repository carrying a familiar-sounding name is the shape a typosquat arrives in, and there has been no time for anyone else to find a problem with it.
no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
0 stars0 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

orz-markdown usage skill. Use this skill whenever you need to render markdown with this parser, write markdown that uses {{...}} custom plugin syntax (mermaid, chart, qrcode, youtube, smiles, toc, span, emoji, attrs, space, yaml, nyml, or their aliases mm/qr/yt/sm/sp/em), use :::container syntax (success/info/warning/danger/spoil/tabs/tab/cols/col/left/right/center), set up a complete HTML page to display parser output, choose or import one of the 12 bundled CSS themes, or create a custom theme stylesheet. Also invoke when asked about .markdown-body class, prepareSources, browser runtime scripts for QR codes or tabs, or any KaTeX math syntax in this project. ALWAYS invoke before editing documents whose headings carry stable block IDs ({{attrs[#blk-...]}}).

SKILL.md

10.8 KB, ~2.7k tokens by cl100k_base, as published. Nobody here has run it

orz-markdown

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)

import md from 'orz-markdown';

const html = md.render(markdownSource);
const page = `<article class="markdown-body">${html}</article>`;

Parser is configured with html: true — raw HTML in source is emitted verbatim. Sanitize untrusted content before rendering to avoid XSS.

Remote URL includes

If the source contains {{markdown https://...}}:

import md, { prepareSources } from 'orz-markdown';

const resolved = await prepareSources(markdownSource);
const html = md.render(resolved, { markdownBasePath: '/local/base/path' });

prepareSources(src, opts?) (≥ 1.5.0) accepts options for safe server-side use: allowedHosts (only resolve includes from these hosts — an SSRF guard when the source is host-authored), fetcher (inject the transport; defaults to global fetch), and maxDepth (recursion for nested includes, default 3). Nested includes resolve with an ancestor-chain cycle guard. No options preserves the prior behavior.

HTML Page Requirements

Every page that displays parser output needs all five of these:

Theme stylesheet — one of the 12 bundled themes, or assets/minimal.css
KaTeX CSS — https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.css
Highlight.js CSS — match light/dark to the chosen theme
Four CDN scripts — Highlight.js, Mermaid.js, SmilesDrawer, Chart.js (loaded in body)
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  comment.

Mounting output in an <iframe> (viewer / editor / slide or page engine)? Call getPreviewFrameAssets() from orz-markdown/preview-frame — it returns the pinned CDN URLs, the runtime, headLinks(scheme) / bodyScripts() strings, and a window.__orzEnhance() that does all of items 3–5 (highlight code, draw mermaid/SMILES/charts, init tabs + QR). One call instead of re-deriving the wiring. See references/embedding.md.

CDN URLs (pinned versions):

Library	URL
Highlight.js JS	`https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/highlight.min.js`
Highlight.js light CSS	`.../styles/github.min.css` (same base URL)
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/[email protected]/dist/smiles-drawer.min.js`
Chart.js	`https://cdn.jsdelivr.net/npm/chart.js@4/dist/chart.umd.min.js`

Browser runtime API

For programmatic control after mounting HTML dynamically:

import { getBrowserRuntimeScript } from 'orz-markdown/runtime';
const script = document.createElement('script');
script.textContent = getBrowserRuntimeScript();
document.body.appendChild(script);
// or call directly: window.OrzMarkdownRuntime.init(rootElement)

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, 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.

Portable document metadata

The single-file, self-editing family shares DocMeta from orz-markdown/doc-meta: title, author, description, license (spdx, name, url), source, date, and keywords. In mdhtml and paged source, authors may provide a {{nyml kind: meta ...}} block. The builder consumes that block and emits standard <head> metadata plus a machine-readable #orz-meta JSON island; those emitted records survive later in-browser saves and framework updates. Host-injected metadata wins field by field. Slides use deck title: and author: as their source metadata and accept the same host override.

Use extractDocMeta, mergeDocMeta, renderDocMetaHead, renderDocMetaIsland, and parseDocMetaIsland from orz-markdown/doc-meta; do not create a second metadata grammar in a host app.

Themes

Twelve bundled themes — each auto-imports common.css (structural rules for tables, images, QR overlays, print).

File	Style	Scheme
`dark-elegant-1.css`	Cinzel headings · scholarly serif	Dark
`dark-elegant-2.css`	Dark elegant variant	Dark
`dark-elegant-3.css`	Lora · VS Code-dark, colourful headings "Nocturne"	Dark
`light-neat-1.css`	Figtree · clean modern sans	Light
`light-neat-2.css`	Light neat variant	Light
`light-neat-3.css`	Bricolage · calm green "Orchard"	Light
`beige-decent-1.css`	Warm beige · print-like prose	Light
`beige-decent-2.css`	Beige decent variant	Light
`light-academic-1.css`	Alegreya · justified scholarly prose	Light
`light-academic-2.css`	Light academic variant	Light
`light-playful-1.css`	Casual · personal blog	Light
`light-playful-2.css`	Light playful variant	Light

// With bundler:
import 'orz-markdown/themes/light-neat-1.css';

// Plain HTML:
// <link rel="stylesheet" href="node_modules/orz-markdown/themes/light-neat-1.css">

For custom themes start from assets/minimal.css (structural only, no decoration) and add your visual layer. See references/themes.md for the design token pattern, element checklist, and design guidelines. See references/css-classes.md for the full list of every CSS class the parser emits. Building a host app that supplies its own CSS and page shell (a slide engine, viewer, or editor)? Read references/embedding.md — it gathers the CSS contract, the JS runtime + diagram-drawing duties, and the copy-as-Markdown requirements into one checklist (and the non-obvious gotchas, like a host CSS reset stripping bold/sub/sup).

Plugin Syntax — Quick Reference

For complete examples and all options, read references/syntax.md.

Custom plugins — `{{name[args] body}}`

Single-line: {{name[args] body}} — Multi-line: {{name[args]\nbody\n}} — both close with }}. Escape with backslash: \{{name}} renders as literal {{name}}.

Plugin	Alias	Quick example
span	`sp`	`{{sp[red] colored}}` · `{{sp[success] ✓ Done}}`
emoji	`em`	`{{emoji wave}}` · `{{em tada}}`
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}}`
smiles	`sm`	`{{smiles C1=CC=CC=C1}}` (chemical structure)
chart	—	`{{chart\ntype: bar\nlabels: A, B\ndata: 1, 2\n}}` (Chart.js bar/line/pie/doughnut)
toc	—	`{{toc}}` or `{{toc 2,3}}` (heading levels)
attrs	—	`# Title{{attrs[id="hero"]}}`
markdown	`md`, `md-include`	`{{md ./path/to/file.md}}`
yaml	`yml`	`{{yaml\nkey: val\n}}` (invisible metadata)
nyml	—	`{{nyml\nkey: val\n}}` (parsed to JSON)

Containers — `::: name ... :::`

Space between ::: and name is required. Nesting uses more colons on the outer level.

::: success          ::: info         ::: warning      ::: danger
::: left             ::: right        ::: center
::: left 30%         (optional CSS width arg — only on `left`)
::: spoil My Title   ::: my-class-name   (arbitrary class)

:::: tabs            (outer: 4 colons)
::: tab Label One    (inner: 3 colons)
:::
::: tab Label Two
:::
::::

:::: cols            (equal-width columns)
:::: cols 1 2 1      (ratio: numbers → fr units, or any CSS length)
::: col
:::
::::

:::: outer           (nesting: outer uses more colons than inner)
::: inner
:::
::::

Stable Block IDs — editing rules

Documents may carry stable block IDs on headings: ## Title{{attrs[#blk-abc12345]}} (canonical form: no space before the marker). These IDs are the block's permanent identity for the host application.

The non-negotiables: IDs are immutable — when editing or rewriting a section, preserve its {{attrs[#blk-...]}} marker exactly, even if you rewrite the heading text completely. Never reuse, invent, regenerate, or duplicate an ID, and never convert to or from Pandoc {#id} syntax (unsupported; corrupts the heading).

Before any edit to a document containing {{attrs[#blk-...]}}, read references/block-ids.md — it has the full rules and a pre-save checklist.

Reference Files

File	When to read
`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, 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
`assets/minimal.css`	Structural-only stylesheet — starting point for custom themes