From 322287da29f71f057492522b0d6a56af05560e37 Mon Sep 17 00:00:00 2001 From: hyper Date: Sat, 12 Sep 2026 23:56:12 +0800 Subject: [PATCH] docs(reference): cover bare dice and tilde fences Add the bare d-form (d20) to the dice notation table, and note that role fences accept backticks or tildes with hyphen-capable attribute keys. Regenerate both reference copies from known.ts and mirror the notes in the skill and markdown docs. --- .agents/skills/tttk-authoring/SKILL.md | 4 +++- .agents/skills/tttk-authoring/reference.md | 5 +++++ .agents/skills/tttk-authoring/yaml-tag.md | 4 ++-- docs/markdown.md | 5 +++++ docs/reference.md | 5 +++++ src/cli/validate/known.ts | 1 + src/cli/validate/reference.ts | 8 ++++++++ 7 files changed, 29 insertions(+), 3 deletions(-) diff --git a/.agents/skills/tttk-authoring/SKILL.md b/.agents/skills/tttk-authoring/SKILL.md index 9661ada..0c0b029 100644 --- a/.agents/skills/tttk-authoring/SKILL.md +++ b/.agents/skills/tttk-authoring/SKILL.md @@ -54,7 +54,9 @@ in `reference.md`. ## Code block roles -Fenced blocks are dispatched by the `role=` attribute in the info string: +Fenced blocks are dispatched by the `role=` attribute in the info string. Both +backtick and tilde (`~~~`) fences work; the closing fence must reuse the opening +marker, and fence attribute keys may contain hyphens (e.g. `data-foo=bar`): | Info string | Behavior | |---|---| diff --git a/.agents/skills/tttk-authoring/reference.md b/.agents/skills/tttk-authoring/reference.md index 899bd76..6654ed9 100644 --- a/.agents/skills/tttk-authoring/reference.md +++ b/.agents/skills/tttk-authoring/reference.md @@ -256,6 +256,10 @@ Renders a clickable span that dispatches a journal command. The `role=` attribute on the info string determines how a fenced block is handled. +Fences may use backticks or tildes (`~~~`); the closing fence must reuse +the opening marker. Fence attribute keys may contain hyphens (e.g. +`data-foo=bar`). + ### `role=spark-table` CSV (or markdown pipe table) rendered as `:md-table`. @@ -339,6 +343,7 @@ Used by `:md-dice`, spark-table headers, and the journal `/roll`: |---|---| | `2d6` | two six-sided dice | | `1d20+5` | d20 plus modifier | +| `d20` | one twenty-sided die (count optional) | | `3d6kh1` | keep highest 1 | | `3d6dl2-1` | drop lowest 2, minus 1 | | `{d4, d8}` | choose one of the listed dice | diff --git a/.agents/skills/tttk-authoring/yaml-tag.md b/.agents/skills/tttk-authoring/yaml-tag.md index a9abfe8..2891c78 100644 --- a/.agents/skills/tttk-authoring/yaml-tag.md +++ b/.agents/skills/tttk-authoring/yaml-tag.md @@ -2,8 +2,8 @@ `` ```yaml role=tag `` renders a custom element from YAML. `tag` names the element, `body` becomes its content, and any other key becomes an attribute. -Fence-line attributes override the YAML body. See `reference.md` for the -element and role catalog. +Fence-line attributes override the YAML body; both backtick and tilde (`~~~`) +fences work. See `reference.md` for the element and role catalog. ````markdown ```yaml role=tag diff --git a/docs/markdown.md b/docs/markdown.md index babddaf..abd527d 100644 --- a/docs/markdown.md +++ b/docs/markdown.md @@ -11,6 +11,10 @@ - [marked-gfm-heading-id](https://github.com/markedjs/marked-gfm-heading-id) - 标题 ID - [marked-directive](https://github.com/fengzilong/marked-directive) - 指令语法 +### 代码块围栏 + +代码块围栏可使用反引号或波浪号（`~~~`）书写；闭合围栏必须与开启围栏使用相同字符，且不短于开启围栏。声明 `role=` 的代码块同理。 + ## 指令语法 通过 `marked-directive` 支持自定义组件插入： @@ -123,6 +127,7 @@ - 点击文本执行掷骰 - 点击骰子图标重置为公式 - `key` 属性将结果记录到 URL 参数中 (`?dice-attack=15`) +- 骰子数量可省略，`d20` 等价于 `1d20` **属性：** diff --git a/docs/reference.md b/docs/reference.md index 899bd76..6654ed9 100644 --- a/docs/reference.md +++ b/docs/reference.md @@ -256,6 +256,10 @@ Renders a clickable span that dispatches a journal command. The `role=` attribute on the info string determines how a fenced block is handled. +Fences may use backticks or tildes (`~~~`); the closing fence must reuse +the opening marker. Fence attribute keys may contain hyphens (e.g. +`data-foo=bar`). + ### `role=spark-table` CSV (or markdown pipe table) rendered as `:md-table`. @@ -339,6 +343,7 @@ Used by `:md-dice`, spark-table headers, and the journal `/roll`: |---|---| | `2d6` | two six-sided dice | | `1d20+5` | d20 plus modifier | +| `d20` | one twenty-sided die (count optional) | | `3d6kh1` | keep highest 1 | | `3d6dl2-1` | drop lowest 2, minus 1 | | `{d4, d8}` | choose one of the listed dice | diff --git a/src/cli/validate/known.ts b/src/cli/validate/known.ts index b2b2e59..78a03a9 100644 --- a/src/cli/validate/known.ts +++ b/src/cli/validate/known.ts @@ -272,6 +272,7 @@ export interface DiceNotation { export const DICE_NOTATION: readonly DiceNotation[] = [ { notation: "2d6", meaning: "two six-sided dice" }, { notation: "1d20+5", meaning: "d20 plus modifier" }, + { notation: "d20", meaning: "one twenty-sided die (count optional)" }, { notation: "3d6kh1", meaning: "keep highest 1" }, { notation: "3d6dl2-1", meaning: "drop lowest 2, minus 1" }, { notation: "{d4, d8}", meaning: "choose one of the listed dice" }, diff --git a/src/cli/validate/reference.ts b/src/cli/validate/reference.ts index f5f65ef..3c09e17 100644 --- a/src/cli/validate/reference.ts +++ b/src/cli/validate/reference.ts @@ -151,6 +151,14 @@ export function renderReference(): string { ); lines.push("handled."); lines.push(""); + lines.push( + "Fences may use backticks or tildes (`~~~`); the closing fence must reuse", + ); + lines.push( + "the opening marker. Fence attribute keys may contain hyphens (e.g.", + ); + lines.push("`data-foo=bar`)."); + lines.push(""); for (const role of ROLE_SPECS) { lines.push(`### \`role=${role.role}\``); lines.push("");