Getting Started

inkwell is a local-first markdown editor for macOS, Windows, and Linux. Your notes are stored as plain .md files in a folder you choose — no sign-up, no cloud, no lock-in.

Install on macOS

1. Download the latest .dmg from the Releases page.
2. Open the disk image and drag inkwell.app to /Applications.
3. On first launch, macOS may show a security prompt — click Open Anyway in System Settings → Privacy & Security.

Install on Windows

1. Download the latest .exe from the Releases page.
2. Run the installer and follow the setup wizard.
3. If Windows SmartScreen shows a warning, click More info → Run anyway.

Install on Linux

1. Download the latest .deb from the Releases page.
2. Install it with sudo apt install ./inkwell_0.8.4_amd64.deb, or double-click it in your file manager if it supports .deb packages.

Open a vault

A vault is any folder on your computer. inkwell stores all notes as .md files inside it, preserving your folder structure exactly.

1. Click Open Vault on the welcome screen.
2. Select a folder (or create a new one).
3. inkwell loads all .md files it finds and shows them in the sidebar.

Create your first note

Press ⌘N or click the + button in the sidebar. Type a title and start writing. Notes are saved automatically — there is no Save button.

Editor

inkwell uses CodeMirror 6 for a fast, distraction-free writing experience with live markdown syntax highlighting.

Normal mode & Markdown mode

Every note opens in Normal mode: a single, distraction-free editor with a live-preview style borrowed from Obsidian and Typora. The raw Markdown delimiters — #, **, ~~, >, list markers, link URLs — are hidden and the text is styled in place, so a heading looks like a heading while you write. Move the cursor onto a line and its delimiters reappear so you can edit them; move away and they hide again.

Click the columns icon in the editor header to put that note into Markdown mode — a split view with the plain Markdown source on the left and a fully rendered, scroll-synced preview on the right. Drag the divider to rebalance the two panes; the ratio is remembered across notes and restarts. The mode is stored per note, so you can leave reference notes in Markdown mode and keep prose in Normal mode.

In both modes, a slim outline rail runs down the right edge — one bar per heading, sized by level. The section at the top of the viewport is highlighted as you scroll, giving you a quick map of a long note.

Slash commands

At the start of a line, type / to open a command menu for inserting block and inline elements without remembering the syntax:

/heading1  /heading2  /heading3
/bullet    /numbered  /todo
/quote     /code      /table
/divider   /highlight /bold  /italic
/video     → embed a YouTube, Vimeo, or Loom link

Type @ anywhere to link another note, and the abbreviation trigger (: by default) to expand snippets — see Note links and Abbreviations below.

Vim mode

Vim keybindings are off by default. Turn them on in Settings → Editor → Vim mode and they apply to every note, in both Normal and Markdown mode. You get modal editing (Esc for normal mode, i/a to insert), motions and operators (dw, ciw, yy, …), / to search, and : commands, with a Vim status line at the bottom of the editor. Notes autosave, so there's no need to :w.

Markdown support

inkwell renders full GitHub Flavored Markdown including tables, task lists, strikethrough, code blocks with syntax highlighting, blockquotes, inline images, and footnotes.

# Heading 1
## Heading 2

**bold**, _italic_, ~~strikethrough~~, ==highlight==

- [x] Done task
- [ ] Open task

| Col A | Col B |
|-------|-------|
| cell  | cell  |

```javascript
const note = "write here"
```

LaTeX math

Mathematical notation is rendered with KaTeX. Wrap inline math in single dollar signs and display math in double dollar signs. For multi-line formulas, use a fenced math (or latex) code block so you never have to escape a $. Math renders live in the preview and is carried through to HTML and PDF exports.

Inline: $E = mc^2$

Display:
$$\int_0^1 x^2 \, dx = \tfrac{1}{3}$$

```math
\frac{\partial \Psi}{\partial t} = \hat{H}\,\Psi
```

Frontmatter

Every note gets automatic YAML frontmatter on creation. You can edit it directly or leave it alone — inkwell uses it to store metadata like tags, pinned state, and timestamps.

---
id: note_abc123
title: My Note
created: 2025-01-15T10:30:00.000Z
updated: 2025-06-01T09:14:00.000Z
pinned: false
tags: [writing, ideas]
---

Font & display settings

Open Settings → Editor to adjust the font family (sans-serif, serif, or monospace), font size, and line spacing. Changes apply instantly without restarting.

Abbreviations

Type the trigger character followed by a key to expand it into text as you type, or pick it from the autocomplete dropdown. Five date/time shortcuts are built in:

:today      → 2026-07-17
:tomorrow   → 2026-07-18
:nextweek   → 2026-07-24
:nextmonth  → 2026-08-17
:now        → 14:30

Add your own in Settings → Abbreviations — define a key and the text it expands to, and change the trigger character (default :) to whatever you prefer.

Charts

Turn a data table into a bar, line, area, pie, or donut chart and drop it straight into your note — no formulas, no external tools.

Inserting a chart

Type /chart at the start of a line to open the Insert Chart dialog. Pick a chart type, optionally give it a title, then fill in the data grid: one row per category, one column per series.

• Bar, Line, Area support multiple series — click + Series to add up to 8, and each gets its own column and label.
• Pie and Donut plot a single value per row instead of a series grid.
• Click + Row to add up to 30 categories. Remove a row or series with the trash icon next to it.

Click Insert Chart to write the chart into your note.

How charts are stored

A chart is just a fenced code block tagged chart, holding a small JSON spec — type, labels, and datasets, plus an optional title. It's plain text, so it travels with the note like any other Markdown and merges cleanly in Git or GitHub Sync.

```chart
{
  "type": "bar",
  "title": "Weekly Sales",
  "labels": ["Mon", "Tue", "Wed"],
  "datasets": [{ "label": "Sales", "data": [10, 20, 15] }]
}
```

Editing a chart

A chart renders live in place of the raw code block, in both Normal and Markdown mode. Click it to reopen the same dialog, pre-filled with its current data, and save your changes back into the block. You can also edit the JSON spec directly as text if you prefer.

Charts in exports

Charts render the same way in HTML and PDF exports as they do in the editor — no separate image to manage, and no chart library to install on the reading end.

Canvas

A full drawing canvas lives alongside your notes. Sketch diagrams, flowcharts, and mind maps using a custom HTML5 drawing engine — no third-party libraries, no export needed.

Opening the canvas

Click the Draw icon in the sidebar (or enable it in Settings → General → Canvas). The canvas is shared across your entire vault and saves automatically to .inkwell/canvas.json.

Tools

Shape styling

Select a shape to see its options in the toolbar: stroke colour (12-colour palette), fill toggle, stroke width (thin/medium/thick), and corner radius for rectangles. Text shapes also expose font family, size, bold, and italic controls.

Selection & editing

• Drag corner handles to resize a selected shape.
• Drag the shape itself (or any selected shape in a multi-selection) to move.
• Double-click a text shape to edit its content in an inline input.
• ⌘D duplicates all selected shapes.
• ⌘A selects everything on the canvas.
• Delete or ⌫ removes selected shapes.
• ⌘Z / ⌘⇧Z undo / redo.

Templates

Click the Templates button in the toolbar to load a ready-made diagram. The canvas fits it to the viewport automatically. Available templates:

• Flowchart — Start, two steps, and End with arrows.
• Mind Map — Central topic with six branches.
• Org Chart — CEO with two managers and three reports.
• Sequence Diagram — Two actors with request / response / callback arrows.
• Timeline — Four milestones on a horizontal axis.
• Venn Diagram — Two overlapping labelled sets.

Canvas notes

Click the note icon (top-right of the canvas) or press ⌘/ to open a markdown notes panel. It slides in from the right at half the canvas width — the canvas stays fully interactive while the panel is open. Notes are saved to .inkwell/canvas-notes.md in your vault.

Navigation

Scroll (or two-finger swipe) to pan. Pinch or ⌘+scroll to zoom. Hold Space and drag to pan with the hand tool.

Organisation

Folders & notes

The sidebar shows your vault's folder structure. Folders map 1:1 to real directories on disk.

Press ⌘⇧F or use the New Folder button to open the New Folder dialog — it lets you pick the parent folder, or drop the new folder at the library root, rather than only nesting it under the current selection.

Drag notes and folders in the sidebar to reorder, nest, and un-nest them. A drop indicator follows the cursor so you can see exactly where an item will land, and moving a folder relocates its whole subtree on disk.

Double-click any note or folder name (or right-click → Rename) to rename it inline. The file on disk is renamed at the same time.

Pinned notes

Right-click a note and choose Pin to keep it at the top of the sidebar. Pinned notes appear in a dedicated section above the rest of your library.

Search

Press ⌘K to open full-text search across every note in your vault. Results update as you type.

Kanban board

Click the Board icon in the sidebar to open the Kanban view. Create multiple boards, add columns and cards, set due dates, write subtasks, and leave comments on cards. Boards are stored in your vault's .inkwell folder.

Note links

Open the Links panel in the editor toolbar to connect notes to each other. Linked notes appear in a panel below the editor and are tracked bidirectionally. The fastest way to link while writing: type @ and start typing a note's title — inkwell searches your vault and inserts the link for you.

Attachments

Drag files onto the Attachments bar at the bottom of the editor to attach images, PDFs, or documents to a note. Attachments are stored in .inkwell/attachments/ inside your vault. Embed an attachment inline with ![[filename]] syntax.

Trash

Deleted notes are moved to the Trash section at the bottom of the sidebar. They are not removed from disk until you empty the trash — so you can recover them.

Themes

inkwell ships with ten hand-crafted themes. Switch any time from Settings → Themes — the change applies instantly across the editor, sidebar, and code highlighting.

Graphite and Onyx are the newest: a light and a dark pair of minimal, near-grayscale themes in the style of Notion, for when you want the page to disappear entirely.

Custom themes

Open Settings → Themes → New Custom Theme to build your own. The live preview updates instantly as you adjust the background, accent, and text colours. Custom themes are stored in your vault's app data and travel with it.

Syntax highlighting

Code block syntax colours are derived automatically from the active theme's accent colour — you don't need to configure anything.

Export

Click the Share icon in the editor toolbar to open the export dialog. A live preview shows exactly how the output will look.

You can also click Copy to clipboard to paste the rendered Markdown or HTML anywhere.

GitHub Sync

Push any note to a GitHub repository as a .md file, and pull the latest version back in with one click.

Setup

1. Open Settings → GitHub.
2. Enter a Personal Access Token with repo scope (create one at github.com/settings/tokens).
3. inkwell saves the token securely in your system keychain.

Push a note

1. Open the note you want to sync.
2. Click the GitHub icon in the editor toolbar.
3. Choose the repository, branch, and file path.
4. Click Push. inkwell commits the note as a .md file.

Pull a note

In the GitHub sync dialog, click Pull to fetch the latest version of the file from GitHub and overwrite the current note content.

Claude MCP

inkwell ships a native Rust MCP server so Claude can read, write, and search your vault directly — without copy-paste.

How it works

The inkwell-mcp binary is bundled inside the app. It communicates with Claude Desktop (or any MCP-compatible client) over stdio using JSON-RPC 2.0. It reads the active vault path from ~/.inkwell/active-vault, which inkwell writes whenever you open a vault.

Setup

1. Build the MCP server binary (or use the one bundled in the app):
   cd src-tauri && cargo build --release -p inkwell-mcp
2. Add it to your Claude Desktop config at ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "inkwell": {
      "command": "/Applications/inkwell.app/Contents/MacOS/inkwell-mcp"
    }
  }
}

3. Restart Claude Desktop. Open a vault in inkwell. Claude now has access to your notes.

Available tools

Keyboard Shortcuts

Global

Canvas

Editor