hypercross
6d94a99b42
Enrich known.ts with element/role details, inline specs, and dice notation, and render them from reference.ts. Add gen:skill-reference and ~ expansion in --out so the skill copy can be regenerated. The skill's reference.md is now generated; its extra authoring content moved to layout.md, yaml-tag.md, csv.md, and markdown.md.
366 lines
8.6 KiB
Markdown
366 lines
8.6 KiB
Markdown
# tttk syntax reference
|
|
|
|
Generated from `src/cli/validate/known.ts` by `npm run gen:reference`.
|
|
Do not edit by hand.
|
|
|
|
Complete catalog of the custom elements, inline directives, and code block
|
|
roles that `tttk` understands. Everything not listed here is standard GFM
|
|
markdown. Element names are prefixed `md-` and must match exactly.
|
|
|
|
## Contents
|
|
|
|
- [Directive syntax](#directive-syntax)
|
|
- [Custom elements](#custom-elements)
|
|
- [Inline directives](#inline-directives)
|
|
- [Code block roles](#code-block-roles)
|
|
- [Dice notation](#dice-notation)
|
|
- [CSV data files](#csv-data-files)
|
|
|
|
## Directive syntax
|
|
|
|
```text
|
|
:name[content]{key="value" .class #id}
|
|
```
|
|
|
|
| Part | Meaning | Example |
|
|
|---|---|---|
|
|
| `:name` | Registered element name | `:md-dice` |
|
|
| `[content]` | Directive body | `[2d6+d8]` |
|
|
| `{attrs}` | Attributes | `{key="attack"}` |
|
|
| `{.class}` | Shorthand for `class` | `{.text-red-500}` |
|
|
| `{#id}` | Shorthand for `id` | `{#my-dice}` |
|
|
|
|
Container directives:
|
|
|
|
```markdown
|
|
::: container
|
|
Content here, including nested directives.
|
|
:dice[1d20]
|
|
:::
|
|
```
|
|
|
|
Nest with more colons (`::::`, `:::::`).
|
|
|
|
## Custom elements
|
|
|
|
| Directive | Body | Key attributes |
|
|
|---|---|---|
|
|
| `:md-dice` | dice formula | `key` |
|
|
| `:md-table` | CSV path or inline id | `roll`, `remix` |
|
|
| `:md-deck` | CSV path | `size`, `grid`, `layers` |
|
|
| `:md-link` | path, optional #section | — |
|
|
| `:md-embed` | path, optional #section | `headingBase` |
|
|
| `:md-bg` | image path or CSS color | `fit` |
|
|
| `:md-border` | color or border image | `width`, `slice` |
|
|
| `:md-font` | font family | `source`, `weight`, `color` |
|
|
| `:md-pins` | image path | `pins`, `fixed`, `labelStart` |
|
|
| `:md-commander` | command template CSV | `placeholder`, `class`, `height` |
|
|
| `:md-yarn-spinner` | Yarn Spinner file | `start` |
|
|
|
|
### `:md-dice`
|
|
|
|
Clickable dice roller; `key` stores the result in the URL.
|
|
|
|
Clicking the text rolls; clicking the 🎲 resets to the formula. With `key`, the result is stored in the URL as `?dice-<key>=<value>`.
|
|
|
|
- Body: dice formula
|
|
- Attributes: `key`
|
|
|
|
```markdown
|
|
:md-dice[1d20+5]{key="attack"}
|
|
```
|
|
|
|
```markdown
|
|
:md-dice[2d6+3]
|
|
```
|
|
|
|
```markdown
|
|
:md-dice[3d6kh1]
|
|
```
|
|
|
|
### `:md-table`
|
|
|
|
Tab-separated view of a CSV with optional group tabs.
|
|
|
|
`roll` adds a 🎲 random-tab button; `remix` makes `{{prop}}` references pull from a random row. A `group` column in the CSV produces group tabs automatically.
|
|
|
|
- Body: CSV path or inline id
|
|
- Attributes: `roll`, `remix`
|
|
|
|
```markdown
|
|
:md-table[./npcs.csv]
|
|
```
|
|
|
|
```markdown
|
|
:md-table[./encounters.csv]{roll=true}
|
|
```
|
|
|
|
```markdown
|
|
:md-table[./quests.csv]{roll=true remix=true}
|
|
```
|
|
|
|
### `:md-deck`
|
|
|
|
Card layout from a CSV (legacy; prefer `yaml role=tag`).
|
|
|
|
Prefer the `yaml role=tag` form — it is the only form that supports template layers, per-layer alignment, and card backs. The directive form is legacy and only supports the compact `layers` string.
|
|
|
|
- Body: CSV path
|
|
- Attributes: `size`, `grid`, `layers`
|
|
|
|
```markdown
|
|
:md-deck[./cards.csv]{size="63x88" grid="5x5" layers="title:1,1-5,1f8 body:1,5-5,8f3"}
|
|
```
|
|
|
|
### `:md-link`
|
|
|
|
Clickable link that expands the target article inline.
|
|
|
|
- Body: path, optional #section
|
|
|
|
```markdown
|
|
:md-link[./rules.md]
|
|
```
|
|
|
|
```markdown
|
|
:md-link[./rules.md#combat]
|
|
```
|
|
|
|
### `:md-embed`
|
|
|
|
Renders the target article or section inline.
|
|
|
|
`headingBase` shifts the heading levels of the embedded content.
|
|
|
|
- Body: path, optional #section
|
|
- Attributes: `headingBase`
|
|
|
|
```markdown
|
|
:md-embed[./rules.md#combat]{headingBase=1}
|
|
```
|
|
|
|
### `:md-bg`
|
|
|
|
Sets the surrounding article card background.
|
|
|
|
`fit` is one of `cover` (default), `contain`, `fill`, `none`, `scale-down`.
|
|
|
|
- Body: image path or CSS color
|
|
- Attributes: `fit`
|
|
- Body may also be a CSS color (e.g. `#2a1a3a`, `crimson`).
|
|
|
|
```markdown
|
|
:md-bg[./images/dungeon-bg.jpg]{fit="cover"}
|
|
```
|
|
|
|
```markdown
|
|
:md-bg[#2a1a3a]
|
|
```
|
|
|
|
### `:md-border`
|
|
|
|
Applies a border to the article card.
|
|
|
|
Body is a CSS color or a border-image path. Class flags select sides (`t b l r all`), style (`solid dashed dotted double groove ridge inset outset none`), and image repeat (`stretch repeat round space`).
|
|
|
|
- Body: color or border image
|
|
- Attributes: `width`, `slice`
|
|
- Body may also be a CSS color (e.g. `#2a1a3a`, `crimson`).
|
|
|
|
```markdown
|
|
:md-border[crimson]{.b}
|
|
```
|
|
|
|
```markdown
|
|
:md-border[./frame.png]{width="2mm" slice="10" .all.round}
|
|
```
|
|
|
|
### `:md-font`
|
|
|
|
Sets the article font.
|
|
|
|
`source` is `google`, `emfont`, or `local` (default).
|
|
|
|
- Body: font family
|
|
- Attributes: `source`, `weight`, `color`
|
|
|
|
```markdown
|
|
:md-font[Noto Sans SC]{source="google" weight="700" color="#1a1a2e"}
|
|
```
|
|
|
|
### `:md-pins`
|
|
|
|
Numbered markers on an image.
|
|
|
|
`pins` is a space-separated list of `label:x,y` (percent coordinates). `fixed` makes it read-only; otherwise click to add and click a pin to remove. `labelStart` sets the first label (letter or number).
|
|
|
|
- Body: image path
|
|
- Attributes: `pins`, `fixed`, `labelStart`
|
|
|
|
```markdown
|
|
:md-pins[./images/battle-map.png]{pins="A:25,50 B:75,30 C:50,80" fixed}
|
|
```
|
|
|
|
```markdown
|
|
:md-pins[./images/dungeon.png]{labelStart="1"}
|
|
```
|
|
|
|
### `:md-commander`
|
|
|
|
Interactive command history / tracker panel.
|
|
|
|
The body is a CSV of command templates (`command,parameter,label,description,insertedText`).
|
|
|
|
- Body: command template CSV
|
|
- Attributes: `placeholder`, `class`, `height`
|
|
|
|
```markdown
|
|
:md-commander[./commands.csv]{placeholder="输入命令…" height="400px"}
|
|
```
|
|
|
|
### `:md-yarn-spinner`
|
|
|
|
Runs a Yarn Spinner dialogue file.
|
|
|
|
`start` names the entry node (default `start`).
|
|
|
|
- Body: Yarn Spinner file
|
|
- Attributes: `start`
|
|
|
|
```markdown
|
|
:md-yarn-spinner[./story.yarn]{start="start"}
|
|
```
|
|
|
|
## Inline directives
|
|
|
|
### `:[name]`
|
|
|
|
Inserts an icon looked up under `assets/` (searching upward from the file).
|
|
|
|
Default extension is `.png`; `.svg`, `.gif`, `.jpg`, `.jpeg`, and `.webp` are also supported. `label` overlays text, `repeat` duplicates N times, and `join` places a tag name between repeats.
|
|
|
|
- Body: icon name
|
|
- Attributes: `label`, `repeat`, `join`, `class`
|
|
|
|
```markdown
|
|
:[attack] :[shield.svg] :[potion]
|
|
```
|
|
|
|
```markdown
|
|
:[attack]{label=ATK repeat=3 join=br}
|
|
```
|
|
|
|
### `:cmd[command]`
|
|
|
|
Renders a clickable span that dispatches a journal command.
|
|
|
|
- Body: journal command
|
|
- Attributes: `label`
|
|
|
|
```markdown
|
|
:cmd[roll 1d20+5]{label=Roll initiative}
|
|
```
|
|
|
|
```markdown
|
|
:cmd[spark dungeon room-type]{label=Random room}
|
|
```
|
|
|
|
## Code block roles
|
|
|
|
The `role=` attribute on the info string determines how a fenced block is
|
|
handled.
|
|
|
|
### `role=spark-table`
|
|
|
|
CSV (or markdown pipe table) rendered as `:md-table`.
|
|
|
|
The first column header must be a dice formula; each row's first cell is the roll value (a number, or a range like `1-3`). Extra fence attributes are forwarded to the generated `:md-table`, e.g. ` ```csv role=spark-table roll=true `.
|
|
|
|
````markdown
|
|
```csv role=spark-table
|
|
d6,结果
|
|
1,遭遇强盗
|
|
2,平安无事
|
|
```
|
|
````
|
|
|
|
````markdown
|
|
```markdown role=spark-table
|
|
| d6 | 结果 |
|
|
|----|------|
|
|
| 1 | 遭遇强盗 |
|
|
| 2 | 平安无事 |
|
|
```
|
|
````
|
|
|
|
### `role=declare`
|
|
|
|
Reactive variable / tag-modifier definitions.
|
|
|
|
Columns (any order): `tag`, `threshold`, `key`, `expr`. A row with an empty `tag` declares a variable; a row with a `#tag` applies a modifier when that tag is active.
|
|
|
|
````markdown
|
|
```csv role=declare
|
|
tag,threshold,key,expr
|
|
,,$hp,$con*5+$mod_hp
|
|
#warrior,2,$mod_hp,20
|
|
```
|
|
````
|
|
|
|
### `role=file`
|
|
|
|
Stored as inline text content and stripped.
|
|
|
|
Referenced by the derived inline id, e.g. `:md-embed[./text_<hash>]`.
|
|
|
|
````markdown
|
|
```text role=file
|
|
Stored as inline content.
|
|
```
|
|
````
|
|
|
|
### `role=tag`
|
|
|
|
YAML rendered as a custom element.
|
|
|
|
`tag:` names the element, `body:` becomes its content, and any other key becomes an attribute. Fence-line attributes override the YAML body. See `yaml-tag.md`.
|
|
|
|
````markdown
|
|
```yaml role=tag
|
|
tag: md-deck
|
|
body: ./cards.csv
|
|
size: 63x88
|
|
grid: 5x5
|
|
```
|
|
````
|
|
|
|
### No role / unknown role
|
|
|
|
No role → a normal visible code block. Unknown role → warned about and
|
|
stripped.
|
|
|
|
## Dice notation
|
|
|
|
Used by `:md-dice`, spark-table headers, and the journal `/roll`:
|
|
|
|
| Notation | Meaning |
|
|
|---|---|
|
|
| `2d6` | two six-sided dice |
|
|
| `1d20+5` | d20 plus modifier |
|
|
| `3d6kh1` | keep highest 1 |
|
|
| `3d6dl2-1` | drop lowest 2, minus 1 |
|
|
| `{d4, d8}` | choose one of the listed dice |
|
|
|
|
## CSV data files
|
|
|
|
Keep CSV files clean — a header row and data rows. Put deck configuration
|
|
and templates in a `yaml role=tag` block's `data-config`.
|
|
|
|
- `label` — unique row id (number or text).
|
|
- `body` — main content, supports markdown.
|
|
- Any other columns are custom fields.
|
|
- `{{prop}}` in `body` interpolates another column (or front-matter key)
|
|
from the same row; with `{remix}` it pulls from a random row.
|
|
- Wrap values containing `,`, `"`, or newlines in double quotes; escape
|
|
`"` as `""`. Lines beginning with `#` are comments.
|