README file from
GithubDice Table
Roll a random result set from Markdown dice tables and save it with one click.
Dice Table is a lightweight randomizer for Obsidian. You write "dice tables" as ordinary Markdown notes; the plugin reads them, rolls one random entry per section, and — if you like the result — saves it as a new note or exports it as a PNG/JPG image.
Engine and data are fully separated. The plugin knows nothing about any specific table. It only understands three things:
#(H1) — the dice name##(H2) — a pool (one thing to roll)-— a face (one possible result)
Any Markdown file that follows this shape is a dice table. Write 5 pools and you roll 5 items; write 20 and you roll 20. No per-table configuration needed.
Features
- Roll everything at once — one click rolls every pool in the selected table.
- Re-roll a single pool — each result row has a small re-roll button that re-rolls only that pool.
- Multi-select pools — write
## Loot ×3to roll 3 non-repeating entries from one pool. Also accepts*3,x3,X3. Append重复,repeatorr(no space) to allow repeats, e.g.## Loot ×3repeat. - Weights —
- Rare sword ^5makes a face five times as likely (weights 1:5:10 land on 6.25% / 31.25% / 62.5%). - Referenced pools stay out of results (setting) — by default a pool referenced by
->or{bank}only acts as a source and does not get its own row; turn on "Show referenced pools" to show it too (a name then has exactly one value per roll). - References & nesting —
## Character ×3 -> Attributesrolls N characters from one attribute definition (define once, reuse everywhere);- Magic item -> Raritykeeps rolling after a hit. Cross-document targets use Obsidian links: wiki links[[folder/file#dice]](shortest / vault / relative paths) and Markdown links[text](folder/file.md)both work; a plain name (no brackets) is looked up in the current document only — cross-document references always use link forms. Unresolved references are reported with a notice, never silently ignored. - Random subset of pools — write
# Scene card ×3on the H1 line and each roll draws 3 random pools (append重复/repeatto allow the same pool twice). - Random number pools —
## Strength 1~100rolls a random integer (endpoints included);## Weight 0.1~9.9 小数2位rolls decimals;## Luck ×5 1~100rolls 5 at once (no repeats by default — add重复/repeatto allow them). Negative ranges work:-10~10. - Word banks & sentence templates — write
{color}inside a face and it fills with a random word from the same-named pool. Any ordinary pool is a word bank (weights apply);{[[file#pool]]}reaches other files; the same placeholder rolls once per roll, so{name} picks up {name}'s swordis one person. - Sticky toolbar — roll, switch tables and save sit in one row pinned to the top, however long the results get; a "more actions" menu (copy / write to note / open the table file / change the table folder, two-way synced with settings) keeps the rest one click away.
- Persisted roll history — the last 20 rolls survive restarting Obsidian and can be loaded back into the result area.
- Open the table file — "Open file" in the more-actions menu opens the current table's Markdown file for quick edits.
- Multiple dice per file — a file may contain several H1 dice; pick one from a dropdown.
- Auto-refresh — new, renamed or deleted table files in the dice folder are picked up automatically, and changing the dice folder itself takes effect without reloading the plugin.
- Save with one click — results are saved using your own naming template, e.g.
{H1}_{YYYYMMDD-HHmm}. Variables:{H1},{H2},{H2:2},{YYYY},{MM},{DD},{HH},{mm},{ss},{WW}and combos like{YYYYMMDD-HHmm}. Illegal filename characters are replaced automatically; name collisions get a numeric suffix. - Image export — set the save format to PNG or JPG and the result is rendered as a clean 2x result card. Colors follow your theme at export time (dark mode exports a dark card).
- Follows your theme — the UI and the default card style use Obsidian's theme variables, so light/dark and custom themes just work.
- Open where you want — the dice view can open in a main tab or in the sidebar (configurable in settings).
- Built-in user manual — the full manual ships inside the plugin: open Settings → Dice Table → User manual and read it without leaving Obsidian (Chinese and English, following your Obsidian language).
Installation
- Open Settings → Community plugins in Obsidian.
- Search for Dice Table and install it, or install manually from a release (copy
main.js,manifest.json,styles.cssinto<vault>/.obsidian/plugins/dice-table/). - Enable the plugin.
Usage
-
Open settings and point Dice folder at a folder containing your dice tables (a folder picker suggests existing folders; new paths are created automatically when saving).
-
Set Save folder and, optionally, the naming template and save format (Markdown / PNG / JPG).
-
Click the dice icon in the left ribbon. Pick a table, roll, re-roll single pools as you like.
-
Happy with the result? Hit Save — the file (or image) lands in your save folder with your naming template.
-
Need the full documentation? Settings → Dice Table → User manual opens the complete manual (table syntax, multi-select, weights, naming templates, saving, view and settings reference).
Dice table example
# Archaeology Site
## Terrain
- Sunken temple
- Wind-carved cliffs
## Loot ×2
- Bronze idol
- Cracked amphora
Network access
None. Dice Table makes no network requests and collects no data.
中文说明
骰子桌(Dice Table) 是一个 Obsidian 随机结果插件:把骰子写成普通 Markdown 笔记(H1=骰子名,H2=要摇的项,横杠条目=可摇的面),插件从每个项里随机抽一条组成一组结果,满意就一键保存为笔记或导出 PNG/JPG 图片。引擎与数据彻底分离:插件不认识任何具体骰子,只认 H1/H2/横杠结构;表里有几个 H2 就摇几项。支持单项重摇、×N 多选(## 战利品 ×3,默认不重复,×3重复/×3repeat 允许重复)、面权重 ^N(- 稀有剑 ^5)、嵌套与引用(## 角色 ×3 -> 属性集 属性集单点定义、改一处全局生效;跨文档用链接语法:[[文件夹/文件#骰子名]] 双链(最短链/库内路径/绝对/相对)或 [显示](文件夹/文件.md) Markdown 链接;裸名只在当前文档内查找,引用不上会提示)、随机子集池(# 场景卡 ×3 每摇随机 3 个池,×3重复 可重复)、随机数字池(## 力量 1~100 整数、## 体重 0.1~9.9 小数2位 小数、## 幸运 ×5 1~100 一次摇 5 个且默认不重复)、词库占位符(面里写 {颜色},摇骰时从同名池摇一个词填进句子——任何普通池都是词库、权重照常生效,跨文档用 {[[文件#池]]},同一次摇骰内同名占位符只摇一次)、摇骰历史持久化(最近 20 组重启后仍在)、顶部引用项默认不在结果里重复占行(设置里可切换显示)、吸顶工具栏(摇骰/换表/一键保存,更多操作菜单=复制、写入笔记、打开当前骰子文件、修改骰子路径并与设置页双向同步)、一个文件多个骰子、自定义命名模板(如 {H1}_{YYYYMMDD-HHmm})、导出图片时自动固化当前主题色。插件不发起任何网络请求。