Inkswell

by Dan King
5
4
3
2
1
Score: 55/100

Description

Plan, draft, track, revise, and publish longform fiction entirely inside your Obsidian vault using a single host view that organizes Home, Plan, Write, Revise, Publish plus Codex and Track tools.

Reviews

No reviews yet.

Stats

22
stars
7,724
downloads
5
forks
142
days
7
days
7
days
38
total PRs
0
open PRs
3
closed PRs
35
merged PRs
40
total issues
0
open issues
40
closed issues
301
commits

Latest Version

8 days ago

Changelog

Keep your Codex and plan in view while you write. Sidebar companions show this scene's cast, this chapter's beats and synopses, the whole outline, your progress and what's left to revise, in any Obsidian sidebar, following the scene you're writing. Inside Write, the column beside the editor now holds Codex and Plan too, and Ctrl/Cmd-hovering a name shows its Codex card. Write remembers your place in every scene, gets a focus mode, and Inkswell is now ready for other languages, with first drafts in six of them.

Added

  • Keep your Codex, plan and outline beside you while you write. Five new sidebar companions, each opened from its icon on the left rail (right-click → Open in sidebar) or with Open a companion in the sidebar…. They follow the scene you're writing, whether in Write or in a regular tab:
    • Codex lists the characters, places and other entries in this scene (linked ones first, then those named in the text), with a search box for the rest. Click one for its full card; pin the ones you want to Keep at the top.
    • Plan shows this chapter's scenes with their synopses, the beats you've assigned to them, your logline and theme, and your planning note.
    • Scenes is the whole Act › Chapter › Scene outline, for jumping around. Clicking a scene opens it in Write, or in a regular tab if you set Open scenes from the sidebar in in Settings.
    • Track and Revision log (what's left to fix in this scene). Companions only show things; editing still happens in Inkswell. Drag them anywhere and Obsidian keeps your layout. If you drag the whole Inkswell view into a sidebar, it now offers to open a companion there instead. Requested in #77 and #53.
  • Codex and Plan beside the editor, inside Write. The column to the right of the Write editor now has four tabs: Scene, Codex, Plan and Revision log. Codex and Plan show the same thing as their sidebar companions (this scene's cast with a search box; this chapter's scenes, beats and your planning note), so you can keep either next to your prose without opening an Obsidian sidebar. Entries you Keep at the top are shared between the two. Clicking a scene in Plan switches Write to it.
  • Inkswell in six more languages (drafts). Choose 简体中文, Español, Deutsch, Français, Português (Brasil) or 日本語 under the new Settings → Interface language. These are first drafts, machine-translated and marked "(draft — help review)", so Inkswell stays in English unless you pick one. Once a fluent speaker has reviewed a language, Inkswell will follow Obsidian's language for it automatically. Spotted something clumsy? Corrections are very welcome: see Translating Inkswell. Text Inkswell writes into your notes (folder and file names, headings, frontmatter, compiled manuscripts) stays as it is in every language, so a vault reads the same on every device. A few things still assume English: Analysis's readability grade and repeated-phrase checks, smart quotes (always “ ”), and the Word manuscript format, which follows US conventions.
  • Resize or hide the column beside the Write editor. Drag the line between the editor and the column to make it wider or narrower (double-click the line to reset it), or hide the column with the new button at the right of the Write toolbar. Width, hidden or shown, and the tab you left it on are remembered on each device. Five new commands, which you can give hotkeys under Settings → Hotkeys: Show or hide the side panel (Write), and Show Scene details / Codex / Plan / Revision log beside the editor (Write), which also open Write if you're elsewhere. Not on phones, which have no side column.
  • Focus mode in Write. The new arrows button in the Write toolbar hides everything but the editor and the toolbar: the left rail, the project bar, the scene list, the right column and the Next up note. Press it again and it all comes back as you had it. There's a command for it too, Toggle focus mode (Write), so you can give it a hotkey. It works on phones, where it also hides the bottom bar. Focus isn't remembered when you restart Obsidian, so you never open Inkswell to find the navigation gone.
  • Hide the scene list in Write. The button at the left end of the Write toolbar hides the scene list and gives its width to the page (also Show or hide the scene list (Write)). Remembered on each device.
  • Fold the Next up note away. The arrow at the end of the Next up row folds it into a small button in the toolbar. The button shows a dot when there's a note and the note itself when you point at it; click it to bring the row back.
  • A right-click menu in the Write editor. Right-click in your text for Cut, Copy and Paste, bold, italic and strikethrough, Look up in Codex, New Codex entry from selection, Open link at cursor, Split scene here, Move selection to new scene and Log a decision. On phones and tablets the same menu is the ⋯ button in the toolbar.
  • Peek at a Codex entry without leaving the page. In Write, hold Ctrl (Cmd on a Mac) and point at a character's or place's name, or at a link to one, to see its card. In the Scene column, hover or tap a character or location to see the same card (those names used to do nothing when clicked). Look up in Codex does the same from the keyboard or the editor's right-click menu: the name at the cursor, or a quick search. Esc closes the card and your cursor stays put.
  • Open an entry's canvases and files from the Codex. A new Linked files row on each Codex entry lists what its note links to outside the Codex, such as a mood-board canvas, a PDF or a research note. It also lists any canvas that holds the entry's card. Click one to open it. Link a file from the note's text or from any property, like [[Mara moodboard.canvas]]. A link to a canvas or PDF needs its extension: a link Obsidian can't find shows as a dashed chip, and clicking it explains why. The row updates when a linked file is renamed. Requested in #74.
  • Follow links between Codex entries. Click a name in a link field (Relationships, Allies, Participants…) to open that entry in the Codex, or click the arrow beside a single pick such as Owner or Inside. Ctrl/Cmd-click opens the entry's note in a new tab instead.

Changed

  • One name: the Revision log. The list of what's left to revise (the markers you left in your prose plus the decisions you logged) had several names. It is now Revision log everywhere: the tab under Revise (was To-dos), the tab beside the Write editor (was Revision), the sidebar companion, and the phone menu. Logging an entry is Log a decision everywhere (the Write toolbar said Log issue).
  • One command opens it. Open to-dos (Revise) is gone; Open revision log does the same thing. If you had a hotkey on the old command, set it on Open revision log.
  • Log a revision decision now works in Write. The command only showed up in a regular note before. It now also works in the Write editor, and the text you have selected fills in the dialog. Ctrl/Cmd+Shift+L still does it too.
  • The Insert control in Write only inserts. It holds your to-do markers and nothing else. Formatting, splitting a scene, Codex look-up and logging a decision moved to the editor's right-click menu. Find to-dos is gone from the toolbar: the Revision log tab beside the editor already shows that list.
  • New marker words need capital letters. A to-do marker you add under Customize must now use an alphabet with capitals (A–Z, Ä, Ж…). A word in Chinese or Japanese script used to be accepted, but Inkswell could never find it in your text. Existing markers are unaffected.

Fixed

  • Counts read correctly. Word, scene and chapter counts in several places said "1 words" or "1 scenes"; they now use the singular. Counts of a thousand or more get separators everywhere (1,234).
  • Write keeps your place. Leaving Write for the Codex, Plan or anywhere else and coming back used to drop you at the top of the scene with the cursor at the start. Write now reopens each scene where you left it, with the same text on screen, your cursor or selection intact, and the keyboard back in the editor so you can carry on typing (on phones and tablets it waits for a tap, so the keyboard doesn't jump up). The same goes for switching between scenes and back. Jumping to a to-do or a search hit still goes to that spot. Reported in #77.

README file from

Github

Inkswell

A local-first writer's suite for longform fiction in Obsidian. Plan, draft, track, revise, and prepare to publish with Inkswell. My goal is to build the best end-to-end plugin toolkit for writers, especially those working on large series longform projects.

Inkswell — Plan · Write · Track · Revise · Publish, all inside Obsidian

Why Inkswell

  • You can handle nearly the entire writing process just with Inkswell. Inkswell organizes the entire arc of a novel — Plan · Write · Revise · Publish, plus a cross-cutting Codex and Track dashboard — into a single host view. Inkswell can get you from your first story ideas to a finished manuscript, with unique and powerful tools at each stage.
  • Focus on UX with only the features you need. I have noticed a trend in other writing tools to add every possible feature under the sun. For some writers, this may be what they want, but my experience is that those tools often try to do too many things, and it makes it challenging to use them effectively. Inkswell is built with user experience at the forefront - I have made a huge effort to deliver the most vital features for each stage of the writing journey, in order to get the most streamlined workflows possible without being overly opinionated. (I hope!) And when a surface isn't for you, hide it — Settings → Features (or right-click the tab) turns off optional tools like the board, plot grid, beats, or the publishing checklist, losslessly, so the app stays as lean as your workflow.
  • Local-first. No AI. Inkswell makes no network calls, collects no telemetry, and does not generate any text. Your manuscript lives in your vault's frontmatter and the notes you write. Inkswell is built to make it easier for you to write, not do the writing for you.
  • Drop-in for Longform users. I am a long time fan of the Longform plugin, so I made Inkswell compatible with that format. Inkswell reads and writes the same longform frontmatter, so existing projects load with zero migration. Inkswell-only data lives under a separate inkswell key to avoid collisions.

What's inside

Five pipeline phases — Home · Plan · Write · Revise · Publish — plus two cross-cutting tools, Codex and Track, that you reach for at any stage.

Surface What it's for
Home Your books as cover cards on shelves (one per series), a cover-art hero card (logline / theme / word-target progress), a nestable scene tree, multiple drafts per story, ideas inbox + quick capture, and a series dialog for multi-book worlds.
Plan Overview fields, beat sheets (7 templates incl. Save the Cat!), and Structure — the outline tree, a Kanban board, and a plotline × chapter grid, behind one Tree / Board / Grid switcher.
Write A distraction-light Live-Preview editor, writing prompts, fast-drafting inline markers, and timed sprints.
Revise An Audit toolkit, a unified Revision log (draft markers left in prose + logged revision decisions), and manuscript Analysis.
Publish A configurable compile/export pipeline plus a self-publishing checklist and launch planner.
Codex A story bible — characters, locations, worlds, factions, items, events, and concepts — with scene linking and mention auto-detect.
Track Word goals, streaks, a GitHub-style heatmap, lifetime records, a deadline pace calculator, and milestone zones.

Home — organize the whole world

All projects is a set of shelves — one per series, in book order, plus your standalone books — of cover cards showing the book number, scenes and words, progress toward the target, and when you last wrote. Start a book straight into a series from New project, or pick a series (or start one) from any book's menu; a shelf's menu renames the series, reorders its books, or adds another. Click a card to focus on that book: a hero card with cover art, logline, theme, and a progress bar, a strip of the series' other covers, and the nestable scene tree. An ideas inbox with quick capture sits below the shelves — click an idea to edit it, or promote it to a note in your Ideas/ folder from its menu. A story can hold multiple drafts (a first draft, an editor pass…), switchable from the header, each a full independent copy of the manuscript and its planning.

Home: project list, nestable scene tree, and project switcher

Plan — structure before you draft

A three-step flow: Overview (novel-level fields and long-form prose), Beats (7 outline templates incl. Save the Cat!, with scene scaffolding), and Structure — the same scenes seen three ways behind a Tree | Board | Grid switcher: the authoritative Act › Chapter › Scene outline tree, a Kanban board (by status / act / chapter / POV), and a plotline × chapter plot grid.

Plan: Kanban board with colored scene cards grouped by status

Write — draft fast, fix later

A distraction-light, Live-Preview manuscript editor with writing prompts and timed sprints. Five fast-drafting inline markers — for to-dos, research questions, dialogue gaps, missing scenes, and notes — highlight as you type (e.g. [RESEARCH: what did 1920s lamplighters earn?]), so you can mark a gap and keep moving forward. Add your own marker words ([CHECK: …], [TK: …]) under Customize → To-do markers. Find them all later in Revise → Revision log.

Switch Write to Stream to read and edit the whole book as one continuous page, in order: click anywhere to edit that scene in place, jump between chapters, or narrow the page to one chapter, POV, plotline, character or status. Each scene still saves to its own note.

Keep your story beside you while you draft. Hold Ctrl/Cmd and point at a character's or place's name to peek at its Codex card, or open a sidebar companion from the rail (right-click → Open in sidebar): Codex (who and what is in this scene), Plan (this chapter's scenes, synopses and beats, plus your planning note), Scenes (the whole outline), Track, and Revision log. Companions follow the scene you're writing, in Write or in a regular tab.

Write: Live-Preview editor with highlighted draft markers and a running sprint timer

Revise — from draft to book

  • Audit — revision checklists for the whole book, each chapter, each scene, and the prose, a scene-purpose lift-out test, scene-opening variety, a character-arc grid, a side-character roster, and a style-sheet consistency scan.
  • Revision log — everything left to fix in one scene-grouped worklist: every draft marker left in the prose (to-dos, research questions, …), plus your invisible-revision decisions — capture "from now on, assume X" rulings (e.g. "the inn is now called the Gilded Wren") as typed, prioritized entries and keep drafting forward instead of breaking flow to backfill earlier chapters.
  • Analysis — readability, overused words, echoes, and composition mix.

Revise: the Audit toolkit — character-arc grid and revision checklists

Publish — manuscript to market

A configurable compile/export pipeline (Markdown, HTML and Word built in — Word as a standard manuscript with title page and running header; .pdf / .epub via pandoc when installed) with a step editor, chapter grouping, and a pre-export check. Plus a self-publishing Checklist (master checklist + book-metadata worksheet) and a Launch planner — pre-order timeline, budget, cover, marketing, and ARC trackers.

Publish: compile step editor and the self-publishing launch planner

Codex — your story bible

Characters, locations, worlds, factions, items, events, and concepts, each with its own profile and an optional portrait image. Places nest, so a city can sit inside a region inside a world. Every entry automatically lists the scenes that mention it — by name or alias, for any category — so your canon stays consistent as the manuscript grows. Can be scoped for single writing projects, or shared across a series. Pin your main cast in each book so they list first (and come first when you type [[ in Write), and search by name, alias, or a character's Role ("antagonist").

Codex: a character profile in the story bible with linked scenes

Track — view stats, keep pace, achieve goals

Daily / weekly / monthly word goals, habit streaks, a GitHub-style heatmap, lifetime records, a writing-history chart, sprint stats, a deadline pace calculator (required daily words, ahead / on-track / behind), draft-milestone zones, and an optional daily mood. Goals only count writing in your projects — by default just manuscript scenes, with settings toggles to also count planning notes, codex notes, or other project notes. Notes elsewhere in the vault never count.

Track: heatmap, streak, progress rings, and writing-history chart

Privacy & dependencies

  • Local-first. No network calls, no telemetry, no account. Everything is stored in your vault's frontmatter and the plugin's local data.json.
  • No AI. By design — Inkswell is tooling around your writing. It cannot generate any text.
  • Optional pandoc. Markdown, HTML and Word (.docx) export are built in. Exporting to .pdf / .epub (or Word styled by your own reference doc) shells out to a pandoc binary on your machine. It's feature-detected and disabled gracefully when pandoc isn't present.
  • Runs on mobile. Inkswell installs on Obsidian mobile. On tablets and iPad the full suite is available with a responsive layout; on phones it focuses on drafting (a single-column editor with a slide-in scene list), while the planning/reference/publish surfaces point you to a larger screen. The only desktop-only piece is pandoc-based .pdf / .epub export, which disables itself gracefully elsewhere; built-in Word export works everywhere.

Where your data lives — backups & recovery

Everything Inkswell stores is plain text you can inspect, sync, and back up like any other note:

Data Where it lives
Scene prose Ordinary notes in your project's scene folder
Plan data — beats, outline structure, goals, revision log, audit checklists, compile & publishing settings Frontmatter of the project index note (the note named after your project)
Codex entries Ordinary notes with a codex frontmatter key
Plugin settings, writing history, sprints, ideas inbox The plugin's data.json (inside .obsidian/plugins/inkswell/)
Other devices' writing history (opt-in: Sync writing history across devices) One small machine-written note per device under <base folder>/Writing log/, merged on Track

Recovery options, should anything ever go wrong:

  • Obsidian's File Recovery (Settings → File Recovery → View) keeps periodic snapshots of every note that changes — including plugin-written ones. The search is by file name: for plan data (beats, goals, revision log), search for your project's name and look at the index note's snapshots; for prose, search the scene's name.
  • The "Inkswell conflicts" folder: whenever Inkswell must displace a version of your text (resolving an editor/disk conflict, leaving a scene before you've resolved one, or overwriting a file during compile at your request), the displaced version is saved there first — nothing is ever silently discarded.
  • Daily data.json backups: on each load, Inkswell keeps a daily copy of its data.json in .obsidian/plugins/inkswell/backups/ (the last 7 days). To bring back settings only (custom codex types, renamed types, Customize changes, the rail arrangement) without touching your writing history, run the command Restore settings from a backup and pick a day. To restore everything, including writing history: disable Inkswell, copy the backup over data.json, re-enable. If data.json can't be read when Obsidian starts, Inkswell loads the newest backup by itself, keeps the unreadable file as data-unreadable-<date>.json, and shows a notice.

Install

Requirements: Obsidian 1.7.4+ (pandoc optional, for .pdf / .epub).

  • Community plugins: Settings → Community plugins → Browse → search Inkswell → Install → Enable.
  • Manual: download main.js, manifest.json, and styles.css from the latest release into <vault>/.obsidian/plugins/inkswell/, then enable Inkswell in Community plugins.

Open Inkswell from the pen-tip ribbon icon or the "Open Inkswell" command.

Bringing an existing project in

Inkswell works with the notes you already have. Setting up a project only creates one new note, the project's index note; your chapter notes aren't changed. If you sync your vault, set the project up on one device and let sync finish before you open it on another.

From Longform

Nothing to do. Inkswell reads and writes Longform's format, so your projects show up on Home as soon as Inkswell is on.

From a folder of chapter notes

If your book is already in Obsidian as one note per chapter or scene:

  1. Click New project on Home (or run the New project command) and fill it in to match where your book already is:

    • Title: the exact name of the folder that holds your book, for example My Book.
    • Base folder: the folder that contains your book's folder, for example Writing for Writing/My Book/. Clear it if your book's folder is at the top level of your vault.
    • Scene folder: the subfolder your chapter notes are in, for example Chapters. Type / if they sit directly in the book's folder.

    Inkswell adds an index note named after the book (My Book.md) inside the book's folder. If one of your chapters already has exactly that name, rename it first.

  2. On Home, click your book's card. A Scene files out of sync box lists every note in the scene folder as Unindexed. (If you come back to this after restarting Obsidian, the box takes about 10 seconds to appear.)

  3. Click Add as scene on each one in reading order, because each is added to the end. Click Ignore for notes that aren't part of the manuscript, like outlines or scraps.

  4. Fix the order whenever you like by dragging scenes on Home or in Plan → Structure → Tree. If your notes already have a chapter property with a number ("Chapter 12" or "12"), Sort scenes by chapter number… in the book's ⋯ menu puts them in order in one step.

Good to know:

  • Inkswell only picks up notes sitting directly in the scene folder. If your book is split into subfolders (Part 1/, Part 2/), move the notes into one folder first. To keep the parts, give each scene an Act in the Scene inspector.
  • A scene's title is its file name, and renaming a scene in Inkswell renames the note.
  • Words already in your notes don't count as words written today. Only what you write from now on counts toward your goals.

From Scrivener, Word, or Google Docs

Inkswell can't open these files directly, so first turn your manuscript into Markdown:

  • Scrivener: compile to MultiMarkdown (File → Compile).
  • Word: convert it with pandoc: pandoc book.docx -o book.md.
  • Google Docs: File → Download → Markdown (.md).

If you end up with one file per chapter, put them in a folder in your vault and follow the steps above. If you have one big file:

  1. Create a New project, open Write, and click New scene.
  2. Paste your whole manuscript into it.
  3. Put the cursor at the start of chapter two and choose Split scene here… from the Insert menu (or run Split scene at cursor). Name the new scene. Everything from the cursor on moves into it, and it opens.
  4. Repeat at the start of each chapter until you reach the end.

Bringing in your worldbuilding notes

Any note becomes a Codex entry when you add a codex property set to its type: character, location, world, faction, item, event, or concept. An entry without a scope shows up in every book. To tie it to a book or a series, open it in the Codex panel and use Scope → Change….

Try it: the sample vault

examples/sample-vault/ is a complete, openable vault containing a mid-draft novel — The Lamplighter's Archive — wired up to exercise every Inkswell surface: beats, scenes, Codex, a populated Track dashboard, the revision audit, a compile recipe, and the self-publishing planner. Run npm run build:sample, then Open folder as vault on examples/sample-vault. See examples/README.md for details.

Development

npm install
npm run dev      # watch build into main.js
npm run build    # typecheck + production bundle
npm test         # unit tests (vitest)

Copy main.js, manifest.json, and styles.css into <vault>/.obsidian/plugins/inkswell/ to test in a real vault. Architecture, conventions, and the compile/version workflows are documented in AGENTS.md.

AI disclosure

This plugin was developed with the assistance of agentic AI coding tools and practices. I have a mandate at work to learn AI tooling, and I wanted to channel that practice into something useful for a community I love - hopefully this counts as that. Direction, architecture, scope, and review are all handled by me; much of the implementation was AI-assisted under that direction. That said, there is absolutely NO AI-generation in the plugin itself. I used agents to help build it, but the plugin itself has a strict "No AI" policy and no AI or word generation features will ever be added.

License

MIT © Daniel King