Getting Started

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

Install

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.

Open a vault

A vault is any folder on your Mac. 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.

Split view

Click the split-view icon in the toolbar (or press ⌘⇧P) to open a rendered preview alongside the editor. The preview updates live as you type. Click the icon again to return to the focused editor.

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"
```

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.

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. Create folders with the + button next to any folder, or drag notes between folders to reorganise. Folders map 1:1 to real directories 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.

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 eight hand-crafted themes. Switch any time from Settings → Themes.

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