Ink Graph

See and edit the structure of your ink story inside Obsidian. Ink Graph draws knots, stitches, choices, diverts, tunnels and threads as a map, shows where every variable is read and written, warns about loops that would hang the story, and lets you change the story by working on the map. Every action is written back to your .ink text, so nothing else stores your story.

Features

• A map of the story. Knots with their stitches grouped inside, and every link between them: choices, diverts, tunnels, threads and function calls. Several choices between the same two knots share one line.
• Variables at a glance. Click a variable to light up the places that write it (orange) and read it (blue).
• Loop warnings. A cycle with no choice in it hangs the player. Ink Graph marks such cycles in red; a dashed outline means the loop is conditional and may be fine (a counter, for example).
• Edit on the map. Create knots and stitches, drag a link between two nodes (or out to empty space to create the node it leads to), rename, delete. Every edit is checked by recompiling the story first and is refused if it would add an error.
• Details on demand. Select a link to see its kind, its condition and every place it is written, with the source line.
• Your layout is yours. Positions are saved next to the story (main.graph.json), so they travel with it in git.

Works alongside Ink Player and Ink Language. Ink Graph does not register the .ink extension itself.

Getting started

Open any .ink file and run the command Open story graph (or click the network icon in the left ribbon, "Open ink graph"). The story root is found by following INCLUDEs upwards, so the graph covers every file the story includes.

Editing safely

• Dropping a link on empty canvas opens one small dialog for the new node's name and the kind of link. Esc, a click outside, the X or Cancel closes it without changing anything, and nothing opens if you let go outside the graph view. The node and its link are one change: a single undo takes back both.
• Rename updates every reference ink resolves to the node, across files: diverts, knot.stitch paths and read counts like {knot > 1}. Prose and comments are left alone.
• The placeholder -> END that a new knot or stitch starts with gives way to the first link you draw from it: a divert or a choice takes its place (a tunnel goes before it, since the story still ends there). Later links just add lines. An -> END that belongs to a choice's branch, or is not the node's last line, is never touched.
• From the (start) block a link becomes a line above the first knot. If the story already starts with a divert, that divert is named in the message: anything added after it would never run, so change that line instead.
• Delete a node removes its lines up to the next header (a knot goes with its stitches). Diverts and choices that led to it are redirected to -> END. Tunnels, threads, function calls, read counts and divert variables cannot be redirected, so the delete is refused and lists those places; click one to open it.
• Delete a link removes a choice as a whole when the link is its only exit. A divert among other content goes alone, together with an { condition: } or - else: wrapper that would be left empty.
• Anything bigger than one line is shown as a diff first. A one-line delete happens at once and can be undone.

Loops without choices

Settings

Installation

From the community plugin list (once it is accepted): Settings → Community plugins → Browse → search for Ink Graph.

Manually: download main.js, manifest.json and styles.css from the latest release into <your vault>/.obsidian/plugins/ink-graph/, then enable the plugin.

Known limits

• The graph is rebuilt on the main thread (debounced), so very large stories may feel slow while you type.
• An unclosed { can swallow the lines after it while you are typing, so parts of the graph briefly disappear.
• Function calls and diverts through a variable (-> x) are shown but cannot be deleted from the graph.
• Delete and Backspace have no touch equivalent; use the menu or the panel buttons on a phone.

Development

This repository is a monorepo (the plugin lives in apps/obsidian-ink-graph, the story parser and editor core in packages/ink-core). See docs/DEVELOPMENT.md.

License

MIT