orz-markdown 1.0.0 → 1.2.0

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

@@ -0,0 +1,218 @@
+# CSS Class Reference — orz-markdown
+
+Every CSS class and structural HTML element emitted by the parser. Use this as the definitive spec when writing or auditing a theme. All selectors should be scoped under `.markdown-body` in theme files.
+
+---
+
+## Article wrapper
+
+| Selector | Source | Notes |
+|---|---|---|
+| `.markdown-body` | `<article>` wrapping all rendered content | Every theme scopes its styles here |
+
+---
+
+## Standard markdown elements
+
+No plugin-specific classes. Style by tag name scoped under `.markdown-body`.
+
+| Element | Notes |
+|---|---|
+| `h1` – `h6` | Headings. `markdown-it-anchor` adds `id` and injects `<a class="header-anchor">` inside. |
+| `p` | Paragraph. |
+| `a` | Hyperlink. |
+| `strong`, `em` | Bold / italic. |
+| `s`, `del` | Strikethrough. |
+| `mark` | Highlighted text (`==text==` via `markdown-it-mark`). |
+| `ins` | Inserted text (`++text++` via `markdown-it-ins`). |
+| `sub`, `sup` | Subscript / superscript (`~sub~` / `^sup^`). |
+| `code` | Inline code. |
+| `pre > code` | Fenced code block. Highlight.js adds token classes when active. |
+| `blockquote` | Block quote. |
+| `ul`, `ol`, `li` | Lists. |
+| `table`, `thead`, `tbody`, `tr`, `th`, `td` | GFM table. |
+| `hr` | Horizontal rule. |
+| `img` | Image. `markdown-it-imsize` adds `width`/`height` attributes when `=WxH` syntax used. |
+
+---
+
+## markdown-it-anchor
+
+| Class | Element | Description |
+|---|---|---|
+| `.header-anchor` | `<a>` | Permalink prepended inside each heading. Hide by default, show on heading hover. |
+
+---
+
+## markdown-it-task-lists
+
+| Class | Element | Description |
+|---|---|---|
+| `.task-list-item` | `<li>` | List item beginning with `[ ]` or `[x]`. Remove default list-style. |
+| `.task-list-item-checkbox` | `<input type="checkbox">` | Checkbox inside the task item. Usually `pointer-events: none`. |
+
+---
+
+## markdown-it-footnote
+
+| Class | Element | Description |
+|---|---|---|
+| `.footnote-ref` | `<sup><a>` | Inline superscript reference (`[^1]`). |
+| `.footnotes` | `<section>` | Container for all footnotes at page bottom. |
+| `.footnotes-sep` | `<hr>` | Separator between body and footnotes section. |
+| `.footnote-backref` | `<a>` | Back-link from definition to reference. |
+
+---
+
+## KaTeX
+
+| Class | Element | Description |
+|---|---|---|
+| `.katex` | `<span>` | Wrapper for every inline math expression (`$...$`). |
+| `.katex-display` | `<span>` | Wrapper for display block math (`$$...$$`). Add overflow-x for wide equations. |
+| `.katex-error` | `<span>` | Shown when KaTeX cannot parse the expression. Style as a visible error (red, monospace). |
+
+---
+
+## Semantic callouts (`markdown-it-container`)
+
+| Class | Element | Description |
+|---|---|---|
+| `.success` | `<div>` | Green success callout. `:::success ... :::` |
+| `.info` | `<div>` | Blue info callout. `:::info ... :::` |
+| `.warning` | `<div>` | Amber warning callout. `:::warning ... :::` |
+| `.danger` | `<div>` | Red danger callout. `:::danger ... :::` |
+
+Each has `> *:last-child { margin-bottom: 0 }` as a best practice.
+
+---
+
+## Layout containers
+
+| Class | Element | Description |
+|---|---|---|
+| `.left` | `<div>` | Float-left wrapper. `:::left ... :::` Needs mobile unfloat breakpoint. |
+| `.right` | `<div>` | Right-aligned wrapper. `:::right ... :::` |
+| `.center` | `<div>` | Centred wrapper. `:::center ... :::` |
+
+---
+
+## Spoiler
+
+| Selector | Element | Description |
+|---|---|---|
+| `details.spoil` | `<details>` | Collapsible spoiler block. `:::spoil My Title ... :::` |
+| `details.spoil > summary` | `<summary>` | Toggle label. Hide `::webkit-details-marker`. Provide open/close marker via `::before`. |
+| `details.spoil[open] > summary` | `<summary>` | Style when open. Update `::before` content. |
+| `details.spoil > :not(summary)` | any | Body content area. Apply padding here. |
+
+---
+
+## Tabs
+
+| Selector | Element | Description |
+|---|---|---|
+| `.tabs` | `<div>` | Outer wrapper. `:::: tabs ... ::::` |
+| `.tabs[data-js]` | `<div>` | Added by JS after initialisation. Use `.tabs:not([data-js])` for no-JS fallback. |
+| `.tabs-bar` | `<div>` | Tab button bar injected by JS. |
+| `.tabs-bar-btn` | `<button>` | Individual tab button. |
+| `.tabs-bar-btn.active` | `<button>` | Currently selected tab button. |
+| `.tab` | `<div>` | Individual tab panel. **Must be `display: none` by default.** |
+| `.tab.active` | `<div>` | Currently visible panel. **Must be `display: block`.** |
+| `.tabs:not([data-js]) .tab` | `<div>` | No-JS fallback: show all panels. **Must be `display: block`.** |
+
+---
+
+## Columns
+
+| Class | Element | Description |
+|---|---|---|
+| `.cols` | `<div>` | CSS grid wrapper. `:::cols ... :::` Use `grid-template-columns: repeat(auto-fit, minmax(..., 1fr))`. |
+| `.col` | `<div>` | Individual column cell. `:::col ... :::` |
+
+---
+
+## Custom plugins
+
+### YouTube embed
+
+| Class | Element | Description |
+|---|---|---|
+| `.youtube-embed` | `<div>` | 16:9 responsive wrapper. Use padding-bottom trick (`height:0; padding-bottom:56.25%`). |
+
+```css
+div.youtube-embed { position: relative; height: 0; padding-bottom: 56.25%; overflow: hidden; }
+div.youtube-embed iframe { position: absolute; inset: 0; width: 100%; height: 100%; border: 0; }
+```
+
+### Mermaid diagram
+
+| Class | Element | Description |
+|---|---|---|
+| `.mermaid` | `<div>` | Contains raw Mermaid DSL. Mermaid.js replaces it with `<svg>` client-side. |
+
+```css
+div.mermaid { overflow-x: auto; text-align: center; }
+div.mermaid svg { max-width: 100%; height: auto; }
+```
+
+### SMILES chemical structure
+
+| Class | Element | Description |
+|---|---|---|
+| `.smiles-render` | `<div>` | Wrapper around the canvas. Centered by `common.css` structural rules. |
+| `canvas[data-smiles]` | `<canvas>` | Drawing target. Width/height set as HTML attributes. SmilesDrawer draws here client-side. |
+
+The structural flex centering is already in `common.css`. Theme only needs background/border on `.smiles-render` (usually `background: transparent; border: none`).
+
+### QR code
+
+| Class | Element | Description |
+|---|---|---|
+| `.qrcode` | `<span>` | Inline wrapper around the SVG. **Must have `background: #fff; padding: 4px`** so the black SVG is readable on any background. |
+| `.qrcode__icon` | `<span>` | Expand icon shown on hover. Structural rules in `common.css`. |
+| `.qrcode.is-expanded` | `<span>` | Added while expanded. `common.css` hides the source with `visibility: hidden`. |
+| `.qrcode-overlay` | `<span>` (cloned) | Fixed-position fullscreen overlay. All geometry handled by `common.css`. Theme can adjust `background`. |
+
+```css
+span.qrcode { background: #fff; padding: 4px; /* or 6px */ vertical-align: middle; }
+```
+
+### Span (inline color / badge)
+
+| Selector | Description |
+|---|---|
+| `span.red` | Color only — set `color: var(--span-red)` |
+| `span.yellow` | Color only — set `color: var(--span-yellow)` |
+| `span.green` | Color only — set `color: var(--span-green)` |
+| `span.blue` | Color only — set `color: var(--span-blue)` |
+| `span.success` | Badge — background, text color, border matching success palette |
+| `span.info` | Badge — background, text color, border matching info palette |
+| `span.warning` | Badge — background, text color, border matching warning palette |
+| `span.danger` | Badge — background, text color, border matching danger palette |
+
+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.
+
+### 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. |
+
+```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); }
+```
+
+### Test elements (development only)
+
+| Class | Element | Description |
+|---|---|---|
+| `.test-block` | `<div>` | Block debug output. Style as a visually distinct dev-only box. |
+| `.test-inline` | `<span>` | Inline debug output. |

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

@@ -0,0 +1,439 @@
+# Syntax Reference — orz-markdown
+
+Complete syntax reference for all features. Covers standard markdown, official plugin extensions, containers, and all custom `{{...}}` plugins.
+
+---
+
+## Standard Markdown (CommonMark)
+
+```markdown
+# H1  ## H2  ### H3  #### H4  ##### H5  ###### H6
+
+**bold**    *italic*    ***bold italic***
+`inline code`
+[link text](https://url.com)
+[link with title](https://url.com "Title")
+![alt text](image.png)
+![alt text](image.png =400x200)    ← image sizing (markdown-it-imsize)
+
+> blockquote
+> > nested blockquote
+
+- unordered item
+* also unordered
+1. ordered item
+2. second item
+
+---   (horizontal rule — also *** or ___)
+
+    indented code block
+
+```language
+fenced code block
+```
+```
+
+---
+
+## Extended Syntax (Official Plugins)
+
+### Highlighting, Insert, Delete — `markdown-it-mark`, `markdown-it-ins`
+
+```markdown
+==highlighted text==        → <mark>
+++inserted text++           → <ins>
+~~deleted text~~            → <s> (also ~~strikethrough~~)
+```
+
+### Sub / Superscript — `markdown-it-sub`, `markdown-it-sup`
+
+```markdown
+H~2~O                       → H₂O  (subscript)
+E = mc^2^                   → E = mc² (superscript)
+```
+
+### Task Lists — `markdown-it-task-lists`
+
+```markdown
+- [x] Completed task
+- [ ] Uncompleted task
+- [x] Another done item
+```
+
+Renders `<li class="task-list-item">` with `<input type="checkbox" class="task-list-item-checkbox">`.
+
+### Footnotes — `markdown-it-footnote`
+
+```markdown
+Here is a footnote reference[^1] and another[^note].
+
+[^1]: First footnote text.
+[^note]: Named footnote text.
+```
+
+### KaTeX Math — `@traptitech/markdown-it-katex`
+
+```markdown
+Inline math: $E = mc^2$
+
+Display (block) math:
+$$
+\int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}
+$$
+
+mhchem chemistry (built-in extension):
+$\ce{H2O}$
+$\ce{Fe^{2+} + 2e- -> Fe}$
+```
+
+Requires KaTeX CSS in the page head: `https://cdn.jsdelivr.net/npm/katex@0.16.35/dist/katex.min.css`
+
+### Heading Anchors — `markdown-it-anchor`
+
+Every heading automatically gets an `id` attribute and a `<a class="header-anchor">` permalink prepended inside it. No special syntax — it's automatic.
+
+---
+
+## Containers — `::: name ... :::`
+
+All containers use fenced colon syntax: `::: name` — **the space between `:::` and the name is required** (`:::name` without a space does not parse). Nesting is supported: the outer container must use more fence-colons than the inner (e.g. `::::` outer, `:::` inner).
+
+### Semantic callouts
+
+```markdown
+::: success
+**Success!** The operation completed without errors.
+:::
+
+::: info
+**Note:** Here is some important information.
+:::
+
+::: warning
+**Warning:** This action cannot be undone.
+:::
+
+::: danger
+**Error:** Authentication failed.
+:::
+```
+
+Renders `<div class="success|info|warning|danger">`. In themes, the first `**bold**` in the first paragraph is styled with the callout's accent color.
+
+### Layout containers
+
+```markdown
+::: left
+Floats left. Text following in the source wraps on the right side.
+:::
+
+::: left 30%
+Optional width argument sets both max-width and width.
+Accepts any CSS length: %, px, em, rem, vw.
+:::
+
+::: right
+Floats right.
+:::
+
+::: center
+Centers horizontally (max 42rem).
+:::
+```
+
+Width argument is only supported on `left`. `right` and `center` have no argument.
+
+### Spoiler (collapsible)
+
+```markdown
+::: spoil Click to reveal
+Hidden content shown when the summary is clicked.
+
+Can contain any markdown content.
+:::
+```
+
+The text after `::: spoil` becomes the `<summary>` label. Renders `<details class="spoil">`.
+
+### Tabs
+
+```markdown
+:::: tabs
+::: tab JavaScript
+```js
+console.log("Hello");
+```
+:::
+::: tab Python
+```python
+print("Hello")
+```
+:::
+::::
+```
+
+Outer fence uses four colons `::::`. Inner tab panes use three `:::`. The text after `::: tab` is the button label (set as `data-label` attribute). JavaScript initializes the tab bar — without JS all panels fall back to block display.
+
+### Columns
+
+```markdown
+:::: cols
+::: col
+Equal-width column one.
+:::
+::: col
+Equal-width column two.
+:::
+::::
+```
+
+Without arguments, all `col` children share equal width. Pass space-separated values to set column widths:
+
+- **Plain numbers** → become `fr` units: `:::: cols 1 2` → `grid-template-columns: 1fr 2fr`
+- **CSS lengths** → pass through as-is: `:::: cols 30% 70%` → `grid-template-columns: 30% 70%`
+- Both forms can be mixed: `:::: cols 1fr 200px 2fr`
+
+```markdown
+:::: cols 1 2 1
+::: col
+One quarter.
+:::
+::: col
+Two quarters.
+:::
+::: col
+One quarter.
+:::
+::::
+```
+
+The number of values should match the number of `col` children, but mismatches are handled by CSS grid rules.
+
+### Nesting containers
+
+Each nesting level requires an additional colon. The outermost container uses the most colons; each layer inside uses one fewer:
+
+```markdown
+:::: info
+Outer info box.
+
+::: warning
+Nested warning inside the info box.
+:::
+
+Back to info content.
+::::
+```
+
+Three levels deep:
+
+```markdown
+::::: outer-class
+:::: cols
+::: col
+Column A content.
+:::
+::: col
+Column B content.
+:::
+::::
+:::::
+```
+
+### Arbitrary class name
+
+Any `::: name` that is not a reserved keyword becomes `<div class="name">`:
+
+```markdown
+::: my-card
+Content inside a div with class="my-card".
+:::
+
+::: highlight-box
+Use your own CSS to style arbitrary containers.
+:::
+```
+
+---
+
+## Custom Plugins — `{{name[args] body}}`
+
+The unified plugin dispatch syntax. Both block and inline forms are supported.
+
+**Inline:** `{{name[args] body}}`
+**Block (multi-line):**
+```
+{{name[args]
+body content
+spanning lines
+}}
+```
+
+**Aliases:** most plugins have a short alias (e.g., `sp` = `span`, `yt` = `youtube`).
+**Escaping:** `\{{name}}` renders as literal `{{name}}`.
+
+---
+
+### span / sp — Inline colored or styled text
+
+```markdown
+{{sp[red] red text}}
+{{sp[yellow] amber text}}
+{{sp[green] green text}}
+{{sp[blue] blue text}}
+
+{{sp[success] ✓ Done}}
+{{sp[info] ℹ Note}}
+{{sp[warning] ⚠ Caution}}
+{{sp[danger] ✗ Error}}
+
+{{span[my-custom-class] any class name works}}
+```
+
+The first argument (inside `[...]`) is used verbatim as the `class` attribute on a `<span>`. Built-in color classes: `red`, `yellow`, `green`, `blue`. Built-in badge classes: `success`, `info`, `warning`, `danger`. Any custom class name works — style it yourself in your theme.
+
+---
+
+### emoji / em — Unicode emoji from name
+
+```markdown
+{{emoji wave}}       → 👋
+{{em smile}}         → 😊
+{{emoji tada}}       → 🎉
+{{em rocket}}        → 🚀
+```
+
+Uses `node-emoji` for name lookup. The emoji text alias (e.g., `wave`, `smile`) is resolved to the Unicode character at render time — no client-side library needed.
+
+---
+
+### space — Inline horizontal whitespace
+
+```markdown
+{{space 4}}    → &nbsp;&nbsp;&nbsp;&nbsp; (4 non-breaking spaces)
+{{space 1}}    → &nbsp;
+```
+
+---
+
+### qrcode / qr — Inline QR code
+
+```markdown
+{{qr https://example.com}}
+{{qrcode mailto:hello@example.com}}
+```
+
+Renders an inline SVG QR code inside `<span class="qrcode">`. The inline version is small; clicking it expands to a fullscreen overlay (requires the QR runtime script in the page). Requires a white background on the span — themes must set `background: #fff` on `.qrcode` so the SVG is readable on dark backgrounds.
+
+---
+
+### youtube / yt — Responsive YouTube embed
+
+```markdown
+{{youtube dQw4w9WgXcQ}}
+{{yt https://youtu.be/dQw4w9WgXcQ}}
+```
+
+Accepts a bare video ID or a full YouTube URL. Renders a `<div class="youtube-embed">` with a 16:9 padding-bottom responsive iframe wrapper. Iframes are never shown in print.
+
+---
+
+### mermaid / mm — Diagram (client-side rendered)
+
+```markdown
+{{mermaid
+graph LR
+  A[Start] --> B{Decision}
+  B -->|Yes| C[Result]
+  B -->|No|  D[Other]
+}}
+
+{{mm
+sequenceDiagram
+  Alice->>Bob: Hello Bob
+  Bob-->>Alice: Hi Alice
+}}
+```
+
+Renders `<div class="mermaid">` containing the raw DSL text. Mermaid.js runs client-side and replaces the div with an SVG. Requires `mermaid.min.js` in the page. Supports all Mermaid diagram types: `graph`, `sequenceDiagram`, `flowchart`, `classDiagram`, `gantt`, `pie`, etc.
+
+---
+
+### smiles / sm — Chemical structure (client-side rendered)
+
+```markdown
+{{smiles CCO}}
+{{sm C1=CC=CC=C1}}
+{{smiles
+[Cu+2].[O-]S(=O)(=O)[O-]
+}}
+```
+
+Renders `<div class="smiles-render"><canvas data-smiles="...">`. SmilesDrawer.js draws into the canvas element client-side. Requires `smiles-drawer.min.js` in the page. Pass SMILES notation strings — any valid SMILES formula works.
+
+---
+
+### toc — Table of contents
+
+```markdown
+{{toc}}
+{{toc 2,3}}
+{{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).
+
+---
+
+### attrs — Inject HTML attributes
+
+```markdown
+# My Section {{attrs[id="hero"]}}
+# Another {{attrs[class="featured" data-x="y"]}}
+
+A paragraph. {{attrs[style="color:red"]}}
+```
+
+Injects any HTML attributes onto the immediately preceding token (heading, paragraph, etc.). Accepts any valid HTML attribute syntax inside `[...]`.
+
+---
+
+### markdown / md — Embed external file
+
+```markdown
+{{md ./path/to/other.md}}
+{{markdown ../shared/footer.md}}
+```
+
+Reads and inlines the content of a local markdown file at render time. Path is resolved relative to `markdownBasePath` (passed as the second argument to `md.render(source, { markdownBasePath })`). For remote URL includes, pre-process with `prepareSources()` first.
+
+---
+
+### yaml / yml — Invisible YAML metadata block
+
+```markdown
+{{yaml
+title: My Document
+author: Alice
+tags: [markdown, tutorial]
+created: 2025-01-01
+}}
+```
+
+Emits `<script type="application/yaml">` with the raw YAML text. Invisible to the user. Accessible via JavaScript: `document.querySelector('script[type="application/yaml"]').textContent`.
+
+---
+
+### nyml — Invisible parsed metadata block
+
+```markdown
+{{nyml
+title: My Document
+count: 42
+items:
+  - alpha
+  - beta
+}}
+```
+
+Parsed using the NYML key-value syntax and emitted as `<script type="application/json">`. Invisible to the user. Accessible via: `JSON.parse(document.querySelector('script[type="application/json"]').textContent)`.