floorianmb/prism-viz

Interactive charts, diagrams, dashboards and formulas right inside your notes.
Offline, in your vault's theme, safely sandboxed – and built so Claude Code and Codex can render, check and fix what they write. Now as a community plugin! Here: https://community.obsidian.md/plugins/prism-viz

Install · Quickstart · With AI agents · Features · Privacy · Example vault

_{A dashboard built from a plain Markdown table in the same note. Edit the table and the charts follow.}

No-code charts: a YAML spec pointing at a table	Explorable explanations: a slider in one block drives a chart in another
Scenes: prism.canvas + prism.animate, paused off screen	Your vault as data: prism.notes() over frontmatter
Mermaid: [[links]] in nodes open the note	Formulas: KaTeX, offline, with mhchem
Scrollytelling: the chart follows the section you are reading	Tasks across the vault: prism.notes({ include: ["tasks"] })
Live API data (opt-in): prism.http.json, sent by Obsidian, no CORS	Charts from web APIs: cached in prism.state, every loading state handled
Web pages (opt-in): ```viz web as a desktop webview, works for sites that refuse framing	…or as an iframe: mode: iframe, also on mobile

_{All of these are in the example vault, together with variants, a link graph, the page monitor, a Bases chart and an HTML widget. Screenshots are real renders in Obsidian's default dark theme.}

• 🤖 Built for agents. Your agent writes a ```viz block, renders the note from the command line and gets back errors with note line numbers plus a PNG snapshot. It fixes the block until the render is clean, with no copy-pasting screenshots back and forth. A ready-made skill teaches Claude Code and Codex how to do it.
• 📒 Your notes are the data. Chart a Markdown table, the frontmatter of every note, your tasks, links and backlinks, or a CSV in your vault. Edit the note and the chart follows. Widgets can write back too: check off tasks, fill in a habit tracker, set a property.
• 🎨 Looks like it belongs. Blocks pick up your theme's colors and fonts, switch live between light and dark, size themselves and show up in PDF exports.
• 🔒 Safe by default. Every block runs in a sandboxed iframe with a strict CSP and no network access. Chart.js, D3, Mermaid, three.js and KaTeX are bundled, so everything works offline.

From the community plugins (recommended)

1. Open Settings → Community plugins → Browse and search for Prism.
2. Select Install, then Enable.
3. https://community.obsidian.md/plugins/prism-viz

With BRAT (for beta versions)

1. Install and enable BRAT from the community plugins.
2. Run BRAT: Add a beta plugin for testing and enter floorianmb/prism-viz.
3. Enable Prism under Settings → Community plugins.

Manually

1. Download main.js, manifest.json and styles.css from the latest release.
2. Put them into <your vault>/.obsidian/plugins/prism-viz/.
3. Reload Obsidian and enable Prism.

Just looking? Open the examples/ folder as a vault. It has a note for every feature.

Put a table in a note and add a chart below it. No code needed:

| Month | Notes | Tasks done |
| ----- | ----: | ---------: |
| Jan   |    34 |         21 |
| Feb   |    41 |         29 |
| Mar   |    57 |         38 |
^stats

```viz chart title="My vault in Q1"
type: bar
source: ^stats
x: Month
```

Change a number in the table and the chart updates. Want more? A ```viz block takes any HTML, SVG and JavaScript, with the bundled libraries and a prism API for your notes:

```viz chart title="Notes by type"
<canvas id="c"></canvas>
<script>
prism.notes().then(notes => {
  const counts = {};
  for (const n of notes) { const t = n.frontmatter.type ?? "(none)"; counts[t] = (counts[t] || 0) + 1; }
  new Chart(c, { type: "bar", data: { labels: Object.keys(counts), datasets: [{ data: Object.values(counts) }] },
                 options: { plugins: { legend: { display: false } } } });
});
</script>
```

Or start from a template: Prism: Insert starter (dashboard, architecture diagram, timeline, chart from frontmatter, chart from a table, formula).

1. Install the skill. Prism opens a page with the install command for your vault after you install or update it; open it again any time with Prism: Install agent skill. On macOS/Linux the command is:

   d="$(mktemp -d)" && git clone --depth 1 https://github.com/floorianmb/prism-viz.git "$d" && node "$d/scripts/install-skill.mjs" --vault '/path/to/your/vault' && rm -rf "$d"

   It copies skill/ to ~/.claude/skills/prism and ~/.codex/skills/prism (wherever those folders exist) and puts the render script into the vault's plugin folder (the community plugin download only contains main.js, manifest.json and styles.css). From a clone: npm run install-skill -- --vault '/path/to/your/vault'. For other agents, run Prism: Generate agent rules as well. It writes PRISM.md and a snippet for your CLAUDE.md / AGENTS.md.

2. Ask for a visualization, e.g. "Add a dashboard of my reading list to Books.md".

3. The agent closes the loop on its own:

   node .obsidian/plugins/prism-viz/scripts/prism-render.mjs "Books.md"

   The note renders invisibly in the running Obsidian app. The command prints JSON with every error (note line, origin, message) and the paths of the PNG snapshots, and exits with 0 = ok, 1 = block errors, 2 = render failed, 3 = Obsidian not reachable. The agent fixes the block, looks at the snapshot and renders again until the result is clean.

If something breaks while you are reading, use Copy prompt for agent in the block's menu or error panel. It copies the location, the errors, the source and the render command, ready to paste.

The complete API is documented in skill/reference.md.

Default height, maximum auto height, theme sync, lazy rendering, error log, errors in the editor, blocks may edit their note, snapshots, data folders, network allowlist and online access.

Prism works offline and does not connect to the internet unless you turn that on yourself.

• No network by default. Chart.js, D3, Mermaid, three.js, KaTeX and html-to-image are bundled in main.js. Nothing is downloaded at runtime, and the plugin never installs or updates code on its own.
• No telemetry, no account, no ads. Prism has no server of its own and sends no usage data anywhere.
• Opt-in network access. Only these settings, all empty or off by default, let blocks reach the network. Which remote services are contacted depends entirely on the URLs and domains you put into your notes and settings:
  • Network allowlist: blocks may load scripts, styles, images and fonts from, and send requests to, the domains you list here.
  • Online access → API requests: blocks may call web APIs with prism.http through Obsidian's requestUrl, to show live data. By default nothing is sent until you click Run requests below the block. The click approves only the hosts the bar names; a request to any other host asks again. See docs/online-access.md.
  • Online access → Web pages: ```viz web blocks and <iframe>s may show web pages inside a note.
• Code in your notes. A ```viz block runs the HTML and JavaScript written in the note, in a sandboxed iframe (scripts only, strict CSP, no direct access to Obsidian or your vault, and no network beyond what you allow above). Only use blocks from sources you trust, as with any code you run.
• Files. The plugin only works inside your vault. It reads data files from the folders you list under Data folders (read-only) and writes to .prism/ (error log, render results, snapshots), plus files you create on purpose (exports, baked images, PRISM.md from Generate agent rules). A block changes its own note only through prism.edit and only after you clicked Allow edits for it (Settings → Prism → Blocks may edit their note turns this off). Only the install script for the agent skill (scripts/install-skill.mjs) writes outside a vault (~/.claude/skills, ~/.codex/skills), and only when you run it yourself in a terminal; the plugin just shows the command.
• Vault index. To answer prism.notes() (names, tags, frontmatter, links, tasks), to list data files and to find blocks for the gallery and command-line renders, Prism goes through the file list of your vault. That metadata only goes to blocks in your own notes and never leaves Obsidian.
• Clipboard. Prism writes to the clipboard only when you pick a copy action (copy as PNG, copy source or errors, copy prompt, embed link after an export). It never reads the clipboard, and blocks have no clipboard access.
• Local storage. Measured block heights and the crash guard use Obsidian's per-vault local storage; block state is saved in the plugin's data.json.
• Desktop only. The page monitor reads CPU and memory figures of Obsidian's own processes through Electron. These stay on your machine.

npm install
npm run build   # type-check, bundle the libraries and main.js, generate skill/reference.md
npm run dev     # watch mode

The runtime files are manifest.json, main.js and styles.css. Pushing a tag that matches the manifest version (e.g. 0.3.0) builds them and publishes a GitHub release.

Releasing. manifest.json holds the version; the build takes prism.version and the version in PRISM.md from it. For a release:

1. Set the version in manifest.json and package.json, run npm install (updates package-lock.json) and add "<version>": "<minAppVersion>" to versions.json.
2. Add a ## <version> – <date> section to CHANGELOG.md; the release notes are taken from it.
3. Run npm run check-version. It fails when any of these files disagree; CI and the release workflow run it too.
4. Commit, then push a tag named exactly like the version.

main.ts                   plugin: code block processor, commands, notes query, exports, snapshots
src/frame.ts              one rendered block: iframe lifecycle, message bridge, toolbar, errors, watchdogs
src/document.ts           srcdoc builder (CSP, theme, base CSS, libraries) and line map
src/runtime/prelude.ts    iframe runtime (window.prism), bundled to a string at build time
src/runtime/chartSpec.ts  declarative chart spec → Chart.js config
src/runtime/table.ts      interactive table for ```viz table / prism.table
src/noteInfo.ts           note tables, headings and tasks for prism.note() / prism.notes({ include })
src/basesView.ts          "Prism chart" view for Obsidian Bases
src/loopGuard.ts          infinite-loop instrumentation (acorn)
src/theme.ts              Obsidian theme → CSS variables
src/errorLog.ts           .prism/errors.json
src/htmlFile.ts           .html view and embeds
src/data.ts               data file path resolution and allowlist
src/perf/                 page monitor: block stats, Electron process metrics
src/online/               opt-in network access: settings + consent, prism.http, ```viz web blocks
scripts/prism-render.mjs  CLI for agents (render a note, print JSON)
scripts/build-skill.mjs   skill/reference.md from src/agentRules.ts (part of npm run build)
scripts/install-skill.mjs installs skill/ for Codex and Claude Code (+ prism-render.mjs into --vault)
examples/                 example vault with a note per feature
docs/pinch-zoom.md        how pinch zoom works (host transform, gesture messages, clamping)
docs/block-state.md       how prism.state is keyed and moves along when blocks are inserted or removed
docs/online-access.md     online access settings, per-host approval of requests, limits
docs/note-edits.md        prism.edit: API, approval, how edits are applied
docs/frontmatter-charts.md  source: notes and aggregate in declarative charts and tables
docs/editor-errors.md     error marks in the editor
docs/bake.md              baked images for Publish, GitHub and other apps
src/noteEdit.ts           prism.edit: task/cell/row edits on note text, approval bar
src/editorErrors.ts       CodeMirror decorations for block errors
src/bake.ts               baked image lines and relative links
scripts/check-version.mjs checks that manifest, package, versions.json and changelog agree

• errors.json reflects the last render, either when a block was visible in Obsidian or via obsidian://prism?render=…. The render command needs the desktop app (it launches Obsidian if it is not running).
• ![[file.html]] embeds use Obsidian's internal embed registry. If it is unavailable, embeds fall back to Reading view only.
• PNG export and snapshots use html-to-image. WebGL canvases need preserveDrawingBuffer: true, and export needs the block to be visible.

MIT, see LICENSE. Third-party licenses: THIRD_PARTY_LICENSES.txt.