Obsidian Stats logoObsidian Stats

Chartdown

by Nossimonov
5
4
3
2
1
Score: 50/100
Install Code

Description

Obsidian plugin: render Chartdown map blocks (battlemaps, hex charts, region maps) as SVG in your notes

Reviews

No reviews yet.

Stats

0
stars
194
downloads
0
forks
12
days
8
days
8
days
2
total PRs
0
open PRs
0
closed PRs
2
merged PRs
0
total issues
0
open issues
0
closed issues
34
commits

Latest Version

0.4.0
9 days ago

Changelog

[0.4.0] — 2026-08-08

You can get closer to a map

Ctrl/⌘ + scroll over a map zooms about the cursor; drag to pan; the toolbar gains + / − / Fit. A bare scroll still scrolls the note past the map, rather than trapping it.

This is the first release where zooming is worth doing. Narrowing the view used to magnify the linework along with the land, so a closer look gave you a bigger picture and nothing else — the coastline over a narrow channel drew 2px at ×4 and 32px at ×64. The ink now holds the width it had when the map was fitted, so the geometry grows and the drawing stays crisp. Your position survives a re-render, so editing a .cd file does not throw you back to the whole map while you are checking a number you zoomed in for.

A secret door stays secret

hidden was honoured on an ordinary line and dropped on a structure detail, so this drew the door on the players' map:

building cellar : A1..B2
  door : at B2.s hidden

Written one indentation further out it was withheld correctly. Nothing reported the difference. If you keep secrets in a note you hand to your table, this is the release to be on.

The renderer underneath is Chartdown 0.6.0

The plugin versions on its own lane, and this jump to 0.4.0 marks the minor version behind it. Most of what you will notice comes from there: an ambient light: no longer washes over the map's own title and coordinates, a lamp on one level no longer lights the floor above it, and a theme's ink : fill= now reaches the title, compass, scale bar and coordinate letters instead of stopping at the map.

Chartdown 0.6.0 also refuses four things it used to accept in silence — a bare archetype word, a structure detail the slot cannot take, an address form nothing consumes, and an unchecked hex ledger line. A document that rendered before may now report an error in your note. In every case the map you were getting was not the map you asked for; the Chartdown 0.6.0 notes say what each one was.

Built from Nossimonov/Chartdown@main.

See all version on GitHub

README file from

Github

Chartdown for Obsidian

Write TTRPG maps as plain text in your notes; see them as maps. Chartdown is a Markdown-inspired language for battlemaps, hex charts, and region maps — this plugin renders every ```chartdown fence in place, entirely on your machine.

```chartdown
# Ambush at Redford Crossing
map: battlemap
grid: square 20x15
scale: 5ft
[terrain]
river redford "The Redford" : path A9 F9 K9 P10 T10 width=2
road tollroad "Old Toll Road" : path K1 K15
ford : on redford on tollroad difficult
[tokens]
goblins g1 g2 : C12 E13
ogre "Gruk" : G9 size=2 hidden
party start : J14..L15
```

What you get

  • Maps in your prep notes — versionable, diffable, no graphical editor. Edit the fence, reopen the note, the map follows.
  • GM/player split, fail-closed — hidden tokens, [gm] notes, and triggers render only in GM view. Each map has a toolbar toggle; the settings tab sets the default.
  • Export SVG — one click writes the map (in the current view) next to the note and reveals it in your system file explorer.
  • Export UVTT — one .dd2vtt per map level, with walls, doors, windows, and lights mapped for VTT import (Foundry, Roll20 via importers, Arkenforge, …) and the map image rasterized in-app. Note: .dd2vtt files are hidden in Obsidian's own file explorer (unknown extension) — they're real files in your vault folder, and the export reveals them.
  • .cd files open to their map — keep a map as its own file, not only as a fence inside a note. Opening one shows the rendered map with the same toolbar; a Source button swaps to the text, and edits save in place. Exports take the file's own name, so sunless-hollow.cd writes sunless-hollow.svg beside it. While this plugin is enabled it claims the .cd extension for the vault; disable it and those files go back to being unopenable, since nothing else knows what they are.
  • Multi-level battlemaps, themes, light and sight — the full Chartdown language.

Try the language first in the playground — no install, runs in your browser.

Long source? Fold it with a callout

A detailed map is a long fence, and a long fence disrupts the read. Wrap it in a collapsed callout — the - after the type is what starts it folded:

> [!note]- Map source (Chartdown)
> ```chartdown
> # Garl's Estate
> map: battlemap
> grid: square 30x22
> …
> ```

The map renders when you expand it, toolbar and all.

Not <details>. You will see that idiom recommended for GitHub, where it folds properly — but Obsidian does not parse a fence inside a raw HTML block, so the map never renders and you get the source as text (Chartdown#225). A callout is the one that works in both, which matters if the same file is read here and on GitHub.

Co-write your maps with an AI assistant

Chartdown is plain text, which means any LLM you already use can write it with you: describe the scene in prose ("the estate has a treasury, a ballroom, slave cells below…"), get a ```chartdown fence back, paste it in your note, and it renders. The plugin ships no AI, no API keys, and makes no network calls — you bring the assistant; you just have to teach it the language once per conversation:

  • Chat assistants (ChatGPT, Claude, …): give it the single-file language reference — https://nossimonov.github.io/Chartdown/llms-full.txt — by pasting it into the chat (or just the link, for assistants that browse). Then describe your scene, or paste an existing map and describe the changes; ask it to reply with one ```chartdown block.

  • Tool-using agents (Claude Code and other MCP clients): the @chartdown/mcp server hands the agent the whole loop — the spec, fail-loud validation, and PNG rendering, so it can check its own work before you see it:

    claude mcp add chartdown -- npx -y @chartdown/mcp

Each map's toolbar closes the round trip: Copy Chartdown puts the map's source on your clipboard, opening with a comment that points at the language reference — so wherever you paste it, an LLM chat included, the reader knows what it's looking at and where the spec lives. Paste Chartdown brings the reply back: it accepts a bare document or a ```chartdown fence straight from the chat, validates it, and only then replaces the map in your note — an invalid paste changes nothing and tells you the offending line. (The paste button grays out while the clipboard is empty; the check looks only at clipboard format metadata, never the content — your clipboard is read exactly once, on an explicit paste click.)

Manual installation

Until the plugin is in the community store: download main.js, manifest.json, and styles.css from the latest release, place them in <your vault>/.obsidian/plugins/chartdown/, then enable Chartdown under Settings → Community plugins. (Or point BRAT at Nossimonov/obsidian-chartdown.)

Development

Development happens in the Chartdown monorepo (packages/obsidian), which is where the tests and issue tracker live — please file issues and PRs there. This repository carries the store-facing artifact: src/ and styles.css are synced verbatim from the monorepo by the release workflow (every release commit pins the exact source it was built from), and release assets carry build-provenance attestations. The plugin imports @chartdown/core and @chartdown/render-svg, published from the same monorepo.

License

MIT. The Chartdown language specification is CC-BY-4.0.

Sponsors