nattoppet 2.1.0 → 4.0.1

package/GUIDE.md

@@ -0,0 +1,732 @@
+# Nattoppet Usage Guide
+
+Nattoppet is a macro-based markup language that compiles to self-contained, minified HTML. You write `.ymd` files using a mix of raw HTML, plain text, and macros. The compiler inlines assets, renders math, and bundles everything into a single file.
+
+This guide covers writing `.ymd` files from the perspective of an end user.
+
+---
+
+## Table of Contents
+
+1. [Quick Start](#quick-start)
+2. [The Core Idea: Macros](#the-core-idea-macros)
+3. [Paragraphs and Indentation](#paragraphs-and-indentation)
+4. [Mixins](#mixins)
+5. [Common Macros](#common-macros)
+6. [Built-in Themes](#built-in-themes)
+   - [vue](#vue--articles-and-blog-posts)
+   - [form](#form--interactive-calculators)
+   - [katex](#katex--math-rendering)
+   - [koa](#koa--long-documents-with-navigation)
+   - [ppt](#ppt--slide-decks)
+   - [tml](#tml--timeline--horizontal-articles)
+7. [Preprocessor Support](#preprocessor-support)
+8. [Scoping and Name Resolution](#scoping-and-name-resolution)
+9. [Traps and Workarounds](#traps-and-workarounds)
+10. [Troubleshooting](#troubleshooting)
+11. [Building and Deploying](#building-and-deploying)
+12. [How It Works Under the Hood](#how-it-works-under-the-hood)
+13. [Summary Cheat Sheet](#summary-cheat-sheet)
+
+---
+
+## Quick Start
+
+### Prerequisites
+
+- [Bun](https://bun.sh) (≥1.0)
+- Clone this repository and run `bun install` in the project root.
+
+### Your first document
+
+A minimal `.ymd` file looks like this:
+
+```ymd
+[mixin] vue
+
+[title]: Hello World
+
+[h2] First Section
+
+  This is a paragraph. It is automatically wrapped in `<p>` tags because it is indented by two spaces.
+
+This line is not indented, so it passes through as raw HTML.
+```
+
+Compile it:
+
+```bash
+bun run nattoppet.ts input.ymd > output.html
+```
+
+Preview with live reload:
+
+```bash
+bun run nattoppet-dev.ts input.ymd
+```
+
+The `--dev` flag disables minification and is useful for debugging. Both compilation modes write to stdout.
+
+---
+
+## The Core Idea: Macros
+
+Everything dynamic in nattoppet is a **macro**. A macro is invoked by writing its name inside square brackets:
+
+```ymd
+[my_macro]
+```
+
+There are two kinds of macros.
+
+### Reference macros: `[name]:`
+
+A reference macro is pure text substitution. When you write `[name]`, the compiler replaces it with the macro's body and interprets the result recursively.
+
+```ymd
+[site_name]: My Blog
+
+Welcome to [site_name]!
+```
+
+Reference macros are defined with a colon (`:`) after the closing bracket. The body extends until the next blank line or the next macro definition, whichever comes first. The body is **trimmed** (leading and trailing whitespace are removed).
+
+```ymd
+[site_name]: My Blog
+[author]: Me
+
+Welcome to [site_name] by [author]!
+```
+
+**Trap**: If you forget a blank line between a macro body and the next macro definition, the second definition terminates the first one immediately:
+
+```ymd
+[#] BAD: [author] is NOT inside [site_name]'s body
+[site_name]: My Blog
+[author]: Me
+```
+
+### Function macros: `[name]=`
+
+A function macro is a snippet of JavaScript that runs at compile time. It is defined with an equals sign (`=`). The last evaluated expression in the block becomes the return value and is spliced into the output.
+
+```ymd
+[upper]=
+const text = this.capture_until('\n')
+text.toUpperCase()
+
+[upper]hello world
+```
+
+Function macros are executed inside a sandboxed context. They have access to the standard library (`read`, `render_markdown`, `render_katex`, etc.) and several special runtime values.
+
+### Special values available inside function macros
+
+| Name | Description |
+|------|-------------|
+| `this.remaining` | The unparsed text that appears **after** the macro invocation. |
+| `this.interpret(str)` | Recursively compile a substring. Definitions visible at the **call site** are available (dynamic scoping). |
+| `this.capture_until(delimiter)` | Consume `this.remaining` up to the first occurrence of `delimiter`, returning the text before it. The delimiter itself is also consumed from `remaining`. |
+| `this.skip(n)` | Skip `n` characters from `this.remaining`. |
+| `this.std_call(has_content?)` | Parse the standard option/argument DSL that many built-in macros use. See below. |
+
+### The `std_call` convention
+
+Most built-in macros use `std_call()` to parse a small DSL after the macro name:
+
+```ymd
+[macro].option1.option2(arg1)(arg2)>>block content<<
+```
+
+`std_call()` returns an object with:
+
+- `opts`: array of dot-prefixed options (e.g. `['option1', 'option2']`).
+- `args`: array of parenthesized or braced arguments (e.g. `['arg1', 'arg2']`).
+- `block`: the content between `>>` and a matching `<<` (or, if `has_content` is true, the rest of the line after a leading space).
+
+Example usage inside a macro definition:
+
+```ymd
+[my_macro]=
+const {opts, args, block} = std_call(true)
+// opts  -> ['center']
+// args  -> ['100px']
+// block -> 'hello'
+
+[my_macro].center(100px) hello
+```
+
+---
+
+## Paragraphs and Indentation
+
+Nattoppet automatically wraps indented prose in `<p>` tags.
+
+- A line that begins with **two spaces** starts a paragraph.
+- Paragraphs are separated by **blank lines** (`\n\n`).
+- Macros inside indented text are expanded normally.
+- Non-indented text passes through unchanged (useful for raw HTML).
+
+```ymd
+  This becomes a paragraph.
+
+  This becomes a second paragraph.
+
+<div>This is raw HTML, not a paragraph.</div>
+```
+
+**Nesting behavior**: If every line in a block is indented, each line can open its own nested `<p>`. This is usually not what you want; keep paragraphs as contiguous indented blocks separated by blank lines.
+
+**Trap**: Mixed indented and non-indented blocks can produce surprising nesting. When in doubt, separate prose from HTML with blank lines.
+
+---
+
+## Mixins
+
+A mixin inlines another file into the current token stream.
+
+```ymd
+[mixin] path/to/file.ymd
+```
+
+**Resolution rules**:
+
+- If the path has an extension, it is used as-is.
+- If the path has no extension and a file with that exact name exists, it is used.
+- Otherwise, `.ymd` is appended (e.g. `[mixin] common` resolves to `common.ymd`).
+- **All mixin paths are resolved relative to the nattoppet installation directory** (where `compiler.ts` lives). Paths starting with `./` are **not** treated specially; they also resolve relative to the compiler root.
+
+### Non-`.ymd` mixins
+
+If you mixin a `.css`, `.js`, or other text file, it is read as raw text and emitted verbatim.
+
+**Trap**: `[mixin]` reads files with UTF-8 encoding. Do **not** use it for binary files (like `.wasm` or images); they will be corrupted. Use `[require]` or `[img]` instead, which read files as buffers.
+
+### `[#slot]` — Content Injection
+
+A mixin can contain a `[#slot]` marker. When the mixin is expanded, the caller's tokens that appear **after** the `[mixin]` directive replace the slot.
+
+```ymd
+[#] -- layout.ymd --
+<!doctype html>
+<title>[title]</title>
+[#slot]
+
+[#] -- page.ymd --
+[mixin] layout.ymd
+
+[title]: My Page
+<h1>Hello</h1>
+```
+
+**Trap**: A mixin may contain **at most one** `[#slot]`. Multiple slots raise a compilation error.
+
+### `common.ymd`
+
+`common.ymd` ships with nattoppet in the project root. Since mixin paths resolve relative to the compiler root, `[mixin] common` finds it automatically. All built-in themes include it, which is why macros like `[require]`, `[img]`, and `[code]` are available in themed documents.
+
+**Trap**: If you write a bare `.ymd` without a theme and want `[require]`, you must add `[mixin] common.ymd` yourself. `[require]` is not a compiler built-in; it is a function macro defined in `common.ymd`.
+
+---
+
+## Common Macros
+
+These macros are available whenever you include `common.ymd` (all built-in themes do this automatically).
+
+### `[require]` — Inline assets intelligently
+
+```ymd
+[require](style.less)
+[require](app.coffee)
+[require](app.js)
+[require](data.json)
+[require](module.wasm)
+[require].my-id(lib/katex.css)
+```
+
+`[require]` detects the file extension and wraps the content appropriately:
+
+| Extension | Output |
+|-----------|--------|
+| `.less` | Compiles to CSS inside `<style>` |
+| `.css` | Inlines inside `<style>` |
+| `.coffee` | Compiles to JS inside `<script>` |
+| `.js` | Inlines inside `<script>` |
+| `.md` | Renders as Markdown HTML |
+| `.wasm` | Inlines as compressed base64 with auto-decompress and `WebAssembly.instantiateStreaming` |
+| `.json` | Inlines as compressed base64 with auto-decompress and `JSON.parse` |
+| other | Raw text |
+
+Options:
+- `.name` sets `id="name"` on the generated `<style>` or `<script>` tag. The entire option string becomes the id.
+
+**WASM/JSON specifics**:
+- The file is compressed with raw deflate and encoded as base64. A small inline script decompresses it via the browser's `DecompressionStream("deflate-raw")`, then instantiates or parses it.
+- The resulting exports/object is exposed on `window.<filename_without_extension>`.
+- `window.wasm_ready` and `window.json_ready` promises coordinate multiple files so you can await them before accessing the data.
+
+### `[img]` — Inline images
+
+```ymd
+[img].center(photo.png)(Alt text)
+```
+
+- Arguments are separate parenthesized groups. Do **not** use commas.
+- First argument is the file path.
+- Second argument is alt text.
+- Options become CSS classes.
+- The image is inlined as a base64 data URI.
+- `.center` wraps the image in a centered `<div>`.
+
+### Headers
+
+```ymd
+[h2] Section Title
+[h3] Subsection Title
+[h4] Sub-subsection Title
+```
+
+These capture the rest of the line, interpret it, and wrap it in the corresponding HTML tag.
+
+### `[quote]` — Blockquote
+
+```ymd
+[quote]>>
+A famous saying.
+<<
+```
+
+Options become CSS classes on the `<blockquote>`.
+
+### `[#]` — Comments
+
+```ymd
+[#] This line is ignored.
+```
+
+`[#]` consumes the rest of the line (or a `>>...<<` block) and produces nothing. It is a regular function macro, not special compiler syntax. It works by evaluating `std_call(true)` for its side effect (consuming input) and returning `''` via the comma operator.
+
+### `[-]` — List items
+
+```ymd
+[-]>>
+First item
+<<
+```
+
+Wraps content in `<li>`. Options become classes.
+
+### `[file]` — Download links
+
+```ymd
+[file](report.pdf)(Download the report)
+```
+
+Creates a download link with the file inlined as a base64 data URI. Arguments are separate parenthesized groups.
+
+### `[code]` — Code blocks
+
+```ymd
+[code].js(console.log('hello'))
+
+[code].js>>
+function greet() {
+    return 'hi'
+}
+<<
+```
+
+- The **language is a dot-option** (e.g. `.js`), not a parenthesized argument.
+- With a single-line argument, wraps in `<code class="language-<option>">`.
+- Without an argument but with a block, wraps in `<pre><code>`.
+
+**Trap**: Writing `[code](js) ...` puts `js` into the code content and loses the actual code. Always use the dot-option form.
+
+### `[link]` — Links
+
+```ymd
+[link](https://example.com)(Click here)
+[link](https://example.com)
+  The link text is captured from the next line if omitted.
+```
+
+Arguments are separate parenthesized groups. Do not use commas.
+
+### `[sup]` — Superscript
+
+```ymd
+[sup](2)  -- produces <sup>2</sup>
+```
+
+### `[eval]` / `[eval*]` — Run JavaScript at compile time
+
+```ymd
+[eval*]>> this.counter = 0 <<
+
+[eval]>> this.counter++ <<
+```
+
+- `[eval]` runs the block and returns the result (inserted into output).
+- `[eval*]` runs the block and discards the result (useful for side effects like initializing state).
+- These macros call `std_call(true)`, so they require either a `>>...<<` block or a space followed by the rest of the line.
+
+**Note**: Both execute in the same sandboxed context as other macros. Variables you set (e.g. `this.index = 0`) persist across macro calls but are scoped to a single compile.
+
+### `[cn]` — CJK text wrapping helper
+
+```ymd
+[cn]>>
+中
+文
+内
+容
+<<
+```
+
+The `[cn]` macro removes **single newlines** between CJK characters and between CJK and adjacent non-whitespace ASCII characters. This lets you write CJK prose with hard line breaks in the source without introducing unwanted spaces in the HTML output. The block content is recursively interpreted first, so macros inside `[cn]` are expanded normally.
+
+**Trap**: Double newlines are preserved as paragraph breaks. Newlines between CJK and whitespace-leading ASCII are also preserved.
+
+---
+
+## Built-in Themes
+
+Themes are mixins that provide a complete page scaffold (doctype, meta tags, styles, scripts). You typically put `[mixin] theme_name` at the top of your file.
+
+### `vue` — Articles and blog posts
+
+```ymd
+[mixin] vue
+
+[title]: My Article
+
+[h2] Introduction
+  Lorem ipsum...
+
+[h3] Subsection
+  More text...
+```
+
+Features:
+- Generates `<!doctype html>`, viewport meta, and a title suffix (`| ylxdzsw's blog`).
+- `[h2]` and `[h3]` are automatically wrapped in anchor tags with ids (`sec0`, `sec1`, ...), enabling deep-linking.
+- Includes `vue.css` and `common.ymd`.
+
+### `form` — Interactive calculators
+
+```ymd
+[mixin] form
+
+[title]: Prime Spiral
+
+[number].n N = 100
+[checkbox].show_diag Show diagonals
+
+[require](main.js)
+```
+
+Features:
+- Generates labeled input fields: `[text]`, `[number]`, `[checkbox]`.
+- Each field takes an optional `.name` option. The inline content block becomes the label text.
+- A **Run** button is automatically appended. When clicked, it gathers inputs into an object and calls `window.run(args)`.
+- The result is displayed in a `<pre>` block.
+- Input values are synced to the URL hash, making state shareable.
+- Includes `form.css`, `form.js`, and `common.ymd`.
+
+**Note**: `N = 100` in the example above is label text, not a default input value. The form theme does not set `value` attributes automatically.
+
+### `katex` — Math rendering
+
+```ymd
+[mixin] katex
+
+[$]E = mc^2$
+
+[$$]>>
+\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
+<<
+```
+
+Features:
+- `[$] ... $` — inline math. Terminates at the first `$`.
+- `[$$]>> ... <<` — display math. Must use the block delimiter for multi-line equations.
+- Includes vendored `katex.css` with all fonts inlined as base64. The output is fully offline-capable.
+- Unicode math symbols (e.g. `α`, `β`, `∫`) and CJK inside `\text{}` work directly in the source.
+
+**Trap**: `[$$]` without the `>>...<<` block form only captures until the end of the line. For any multi-line equation, always use the block form.
+
+**Trap**: `[$]` terminates at the first bare `$`. You cannot use literal `$` characters (e.g. dollar amounts) inside inline math because there is no escaping mechanism.
+
+### `koa` — Long documents with navigation
+
+```ymd
+[mixin] koa
+
+[title]: Documentation
+
+[section] Getting Started
+  Content here...
+
+[section] Advanced Topics
+  More content...
+```
+
+Features:
+- `[section]` creates a new section and auto-populates a hamburger-nav sidebar with a table of contents.
+- Each section gets an id (`sec0`, `sec1`, ...).
+- Includes `koa.css` and `common.ymd`.
+
+**Note**: `[list]` is an internal macro that generates the navigation menu HTML. You do not invoke it directly.
+
+### `ppt` — Slide decks
+
+```ymd
+[mixin] ppt
+
+[title]: My Talk
+
+[section] Slide One
+  - Bullet A
+  - Bullet B
+
+[section].dark Slide Two
+  Dark-themed slide.
+```
+
+Features:
+- `[section]` creates a slide.
+- Options after `[section]` become CSS classes on the slide `<section>`. Only the **first** leading dot is replaced with a space, so `[section].dark.centered` produces `class="scen dark.centered"` rather than two separate classes. Use a single class name or write the classes as one option.
+- Elements inside slides can have animation classes: `.click`, `.delay`, `.sim`, plus timing classes `.short`, `.long`, `.fast`, `.slow`.
+- `[foot]` creates a `<footer>` element.
+- `[span]` creates a vertical spacer `<div>` (takes a length argument).
+- Includes `ppt.css`, `ppt.js`, and `common.ymd`.
+
+### `tml` — Timeline / horizontal articles
+
+```ymd
+[mixin] tml
+
+[title]: Timeline
+
+[article] 2024-01
+  Event description...
+
+[article] 2024-06
+  Another event...
+```
+
+Features:
+- `[article]` wraps each entry in an `<article>` tag.
+- The title becomes an `<h2>` with an auto-generated anchor id.
+- Includes `tml.css`, `tml.js` (enables horizontal wheel scrolling), and `common.ymd`.
+
+---
+
+## Preprocessor Support
+
+`[require]` in `common.ymd` automatically handles several preprocessors:
+
+- **Markdown** (`.md`) — parsed with `marked` and emitted as HTML.
+- **CoffeeScript** (`.coffee`) — compiled to JavaScript with `bare: true`.
+- **Less** (`.less`) — compiled to CSS synchronously.
+
+No additional configuration is needed. Just require the file and the compiler handles the rest.
+
+---
+
+## Scoping and Name Resolution
+
+Understanding how macros find each other is essential for non-trivial documents.
+
+### Forward references
+
+Reference macros (`[name]:`) can be used **before** they are defined:
+
+```ymd
+Before [title] after
+
+[title]: My Title
+```
+
+### Self-reference is forbidden
+
+A reference macro cannot call itself. Doing so produces `definition <name> not found` because the compiler excludes the macro from its own scope to prevent infinite recursion.
+
+### Dynamic scoping for function macros
+
+When a function macro calls `this.interpret(...)`, the substring is evaluated with access to **all macros defined at the call site**, even if those macros were not visible where the function macro itself was defined.
+
+```ymd
+Value: [caller]
+
+[caller]=
+this.interpret('[target]')
+
+[target]: DYNAMIC
+```
+
+This dynamic scoping applies **only** to strings passed to `this.interpret()`. Function macro bodies are JavaScript, not nattoppet markup, so bare `[name]` references inside the JS code itself are not possible.
+
+### Shadowing
+
+If the same name is defined multiple times, the **earliest** definition wins.
+
+```ymd
+[wrapper] after
+
+[wrapper]: [shadow]
+
+[shadow]: FIRST
+
+[shadow]: SECOND
+```
+
+This outputs `FIRST after`; `SECOND` is never used. This is a consequence of forward-reference support: the compiler resolves each macro name when it first encounters it, so the first definition takes precedence. Defining the same name twice is usually a mistake; the second definition is silently ignored.
+
+### Preserving `remaining` across nested calls
+
+`this.interpret` saves and restores `this.remaining`. This makes it safe to call `interpret` inside a function macro without losing your place in the input stream.
+
+---
+
+## Traps and Workarounds
+
+Common pitfalls are listed below. For a quick-reference fix table, see [Troubleshooting](#troubleshooting).
+
+### Square brackets in raw content
+
+Because `[name]` is the macro invocation syntax, raw square brackets in JavaScript, Markdown, or HTML can be mistakenly interpreted as macro calls if the content inside happens to match a defined macro name.
+
+**Workaround**: In practice this is rare because:
+- Inside KaTeX math, the raw string is passed directly to the renderer without macro expansion.
+- Inside `<script>` or `<style>` tags emitted by `[require]`, the content is raw.
+- If you need literal square brackets in prose, define a passthrough macro or write them inside raw HTML tags.
+
+### Array subscripts in inline math
+
+Writing `a[i]` inside a paragraph can trigger macro lookup for `i`. If `i` is not defined, compilation fails with `definition i not found`.
+
+**Workaround**: Use KaTeX math (`[$]a[i][$]`) for mathematical notation containing brackets, or escape the context by wrapping the expression in raw HTML.
+
+### Paragraph nesting with all-indented lines
+
+If every line in a region is indented by two spaces, each line opens a new nested `<p>`. Keep paragraphs as contiguous blocks, using blank lines to separate them.
+
+### Mixin path ambiguity
+
+If you have a file named `foo` (no extension) and also `foo.ymd`, `[mixin] foo` picks the bare file. To force the `.ymd` version, write `[mixin] foo.ymd` explicitly.
+
+### `capture_until` does not include the delimiter
+
+The delimiter passed to `capture_until` is consumed from `remaining` but is **not** included in the returned string. If you need to preserve it, append it manually.
+
+### `[$$]` without space or block
+
+`[$$]` uses `std_call(true)`. If there is **no space** after `[$$]` and no `>>...<<` block (e.g. `[$$]expr`), `std_call` falls through to the default case with no block, and `render_katex(undefined, true)` is called, which will likely throw an error. Always provide either a space and inline content or the `>>...<<` block form.
+
+---
+
+## Troubleshooting
+
+| Symptom | Likely Cause | Fix |
+|---------|--------------|-----|
+| `definition X not found` | You invoked `[X]` but never defined `[X]:` or `[X]=`. | Define the macro, or check for typos. |
+| `definition X not found` inside a self-referential ref | Reference macros cannot reference themselves. | Use a function macro if you need recursion, or restructure. |
+| Multiple `[#slot]` error | A mixin contains more than one slot. | Remove extra slots, or split into multiple mixins. |
+| `mixin not found: X` | The mixin path could not be resolved. | Check the path; remember all mixin paths resolve relative to the compiler root, not the input file. |
+| Math does not render, or renders inline when it should be display | Missing `>>...<<` block delimiters around multi-line `[$$]`. | Use `[$$]>>...<<`. |
+| CJK text has unwanted spaces | Hard line breaks between CJK characters are preserved as spaces by HTML. | Wrap the text in `[cn]>>...<<`. |
+| Paragraphs wrap raw HTML | Indented HTML is treated as prose. | Remove the leading two spaces from HTML lines. |
+| KaTeX fonts not loading | You are not using `[mixin] katex` and instead only included the JS. | Include the `katex` mixin (or manually inline `katex.css`) because the vendored CSS contains base64 fonts. |
+| `less failed to compile synchronously` | The Less compiler returned an error. | Check your `.less` file for syntax errors. |
+| `[code](js)` loses code content | Language must be a dot-option, not a parenthesized argument. | Use `[code].js(...)`. |
+| `[img]` or `[link]` broken | Arguments must be separate parenthesized groups. | Use `[img].center(path)(alt)`, not `[img].center(path, alt)`. |
+
+---
+
+## Building and Deploying
+
+### Native executable bundling
+
+You can turn a `.ymd` file into a desktop application:
+
+```bash
+bun run nattoppet-native.ts init        # create native/ Rust scaffold
+bun run nattoppet-native.ts bundle file.ymd  # compile HTML into native/
+bun run nattoppet-native.ts build file.ymd   # compile HTML and run cargo build --release
+```
+
+The result is a single native binary (Linux/macOS/Windows) that embeds the HTML and renders it with a web-view.
+
+### Project scaffolding
+
+```bash
+bun run nattoppet-init.ts form
+```
+
+This generates a starter `main.ymd`, `main.js`, and optionally Rust/WASM boilerplate plus a GitHub Pages deployment workflow.
+
+---
+
+## How It Works Under the Hood
+
+The nattoppet compiler processes a `.ymd` file in two passes:
+
+1. **Tokenization**: The source is split into a sequence of tokens: raw text chunks (`code`), macro definitions (`ref`/`fn`), mixin directives (`mixin`), and slot markers (`slot`). During this phase, `[mixin] path` files are read and inlined recursively.
+2. **Interpretation**: The token stream is walked left-to-right. Raw text is interpreted (paragraphs and nested macros are expanded); raw asset tokens are emitted as-is.
+
+Function macros are executed via `vm.runInContext` in a sandboxed environment. The completion value of the JavaScript block (the value of the last expression statement) is converted to a string and spliced into the output.
+
+You do not need to understand these internals to use nattoppet, but knowing the two-phase model helps explain why mixins are fully resolved before any macros run.
+
+---
+
+## Summary Cheat Sheet
+
+```ymd
+[#] Structure
+[mixin] theme_name           [#] include a theme
+[mixin] common               [#] include common macros
+[#slot]                      [#] injection point inside a mixin
+
+[#] Macro definitions
+[ref]: text                  [#] reference macro
+[fn]= js_code                [#] function macro
+
+[#] Common macros
+[require](file.ext)          [#] inline asset (auto-detect type)
+[require].id(path)           [#] with element id
+[img].class(path)(alt)       [#] inline image
+[h2] Title                   [#] header
+[quote]>>...<<              [#] blockquote
+[code].lang(code)            [#] inline code
+[code].lang>>...<<          [#] code block
+[link](url)(text)            [#] hyperlink
+[file](path)(text)           [#] download link
+[sup](text)                  [#] superscript
+[#] comment                  [#] comment / ignore
+[-]>>...<<                  [#] list item
+[eval]>> expr <<             [#] compile-time JS (returns value)
+[eval*]>> expr <<            [#] compile-time JS (side effect only)
+[cn]>>...<<                 [#] CJK newline removal
+
+[#] Math
+[$] ... $                    [#] inline math
+[$$]>>...<<                 [#] display math
+
+[#] Form theme
+[text].name Label            [#] text input
+[number].name Label          [#] number input
+[checkbox].name Label        [#] checkbox
+
+[#] Koa theme
+[section] Title              [#] new section + TOC entry
+
+[#] PPT theme
+[section].class Title        [#] new slide
+[foot] text                  [#] footer
+[span](length)               [#] vertical spacer
+
+[#] TML theme
+[article] Title              [#] new timeline article
+```