Scribe of Lagash - Visualization

An Obsidian plugin that helps writers visualize their chapters and scenes. It is the first plugin in the Scribe of Lagash series, a set of independent, focused tools for planning and writing stories in Obsidian.

This plugin doesn't own your prose: chapters and scenes are just regular notes in your vault. Point the plugin at the folder that holds a story and it recognises chapters and scenes from their titles ("Chapter 1", "Scene II", "Prologue", …); a little scribe-note-* frontmatter is optional and only needed to override the title or add detail. The only file the plugin ever writes is a per-story StoryLines file that stores the story's default view.

Current features

• StoryLines view — the story's default view (ribbon icon / "Open StoryLines" command). Horizontal, colored lines for a story, with each chapter/scene as a card sitting on a line. Pick "Create lines" the first time to seed a "Main line", then drag cards between lines or along the shared column grid — columns line up across every line by reading order, and you can leave deliberate gaps between cards. Dropping a card onto an occupied column nudges the others right. When a Story Outline is set up, an **Align cards to Story Outline ** toolbar button snaps every card — real or planned — back to the outline's reading order and onto the line its row names. Add / rename / recolour / reorder / delete lines from the line headers. Changes save to the StoryLines file (StoryLines.md) automatically; Mod+Z undoes.
• Story Outline file (optional) — name a file under Story Outline file name in settings and click Create; it's written as an empty Markdown table (Act / Chapter / Scene / Line / Synopsis). The .md extension is optional — Outline and Outline.md both create (SL) Outline.md. Fill it in to plan the story before the notes exist: rows with no matching note appear as dashed placeholder cards on the StoryLines view, and clicking one creates the note (title, Synopsis, frontmatter) on that line. Once a note exists its Synopsis shows on the card; a row that disagrees with the real note/folder gets a ⚠ marker — the files always win. See docs/feature-plans/outline-file-plan.md.

Planned next: a chronological view ordering chapters/scenes by their scribe-note-date, and a matrix view grouping them by character, place, or situation. See docs/feature-plans/line-view-plan.md.

Setting up a story

In the plugin settings, add the vault-relative folder that holds your story's notes under Story folder. The plugin scans that folder and classifies each note by its title:

Leave Story folder empty to scan the whole vault instead.

Recognised title words

The Title language setting picks which language's words the plugin looks for at the start of a note's title. The number may be digits or a roman numeral (IV), an optional . can follow the keyword, and matching is case-insensitive. English (en) and Spanish (es) ship today:

So with Title language set to Español, Cap. 3 — La caída is chapter 3 and Escena II is scene 2. Adding a language is one more pattern table in src/data/titleParser.ts — nothing else changes.

Story structure

A note's place in the manuscript comes from where it sits in folders, not from frontmatter. Any of these layouts works — but pick one per story:

A scene's chapter is simply its containing folder — there is no parent key. Prologue.md / Epilogue.md / Interlude.md can go anywhere; having no number, they sort after the numbered notes in the same folder.

Don't mix "chapter as a file" and "chapter as a folder" in the same story. If you do, every file-chapter sorts before any folder-chapter's scenes. Pick one style and convert the whole story to it.

Manuscript order is then: folder path first (all of Act I/… before Act II/…; a numbered folder sorts by its number, so Chapter 2/ comes before Chapter 10/), then the number in the title, then the title text. Sub-folders also show as a breadcrumb under each card — a note at My Story/Act I/Chapter I/Scene 1.md (story folder My Story) shows "Scene 1" with "Act I - Chapter I" underneath.

Planning ahead with the Story Outline file

Set Story Outline file name in settings (the .md is optional — Outline and Outline.md both mean (SL) Outline.md) and click Create. The plugin writes one (SL) <name>.md per story folder with an empty table and a column guide, and never touches it again.

When you plan a story in the Story Outline file table before writing the notes, fill the columns that match your layout:

Numbers may be digits or roman numerals, optionally followed by free text — e.g. a Chapter cell of 1 - The beginning plans Chapter 1 - The beginning.md, the same as if you'd typed that title directly. The Act / Chapter / Scene words and folder names follow the Title language setting. Line is a line name or id from the StoryLines file; Synopsis shows on the card and becomes the note body when you create it. A row with neither a Chapter nor a Scene value is ignored, and un-numbered units (Prologue, …) can't be planned here — create those notes directly. The Story Outline file created for you repeats this guide below the table.

Optional frontmatter

None of this is required — it only adds detail the cards can show:

---
scribe-note-date: 1901-03-04       # in-story date, any free-form string
scribe-note-characters: [Alice, Bob]
scribe-note-places: [Riverside Tavern]
scribe-note-status: draft
---

Development

npm install
npm run dev    # watch build, outputs main.js
npm run build  # type-check + production build
npm test       # unit tests (Node's built-in runner; no test framework dependency)

Supply-chain safety

• Every dependency in package.json is pinned to an exact version — no ^/~ ranges and no latest. .npmrc sets save-exact=true so future npm install <pkg> additions stay pinned by default.
• .npmrc also sets ignore-scripts=true, so npm install/npm ci never runs a dependency's preinstall/install/postinstall script automatically. The only dependency that ships one is esbuild, and its script just optimizes linking its already-installed platform binary — the build works fine without it. On the rare platform where it doesn't (e.g. an environment without a matching prebuilt @esbuild/* package), run npm run rebuild:esbuild to explicitly and visibly opt that one script back in for that single command.

To try the plugin in a vault, copy (or symlink) manifest.json, main.js, and styles.css into <vault>/.obsidian/plugins/scribe-of-lagash-visualization/, then enable it from Obsidian's Community Plugins settings.

Contributing

Found a bug, or have a feature request? Open one on the GitHub Issues page — there's a template for each.

Contributions are welcome — see CONTRIBUTING.md for dev setup, code conventions, and the PR process. This project follows a Code of Conduct.

Found a security issue? See SECURITY.md instead of opening a public issue.

See CHANGELOG.md for release history.

License

MIT.