HandNote is an Obsidian community plugin for handwritten notes, made
first for the iPad and Apple Pencil (a finger, a mouse or a pen tablet work too). Write in notebook
pages, select with a lasso, convert handwriting to editable text on your device, write directly on
your Markdown notes, and annotate PDF, Word, PowerPoint and Excel files by hand. Every page is a plain
.handnote file in your vault. Free and open source (MIT).
Install from the Obsidian community directory · Releases · FAQ · 中文说明 · 中文教程
handnote-main-en-github.mp4
iPad clips: real Apple Pencil recordings of HandNote 0.8.1. Desktop clips: the released 0.8.1 files, with the handwriting played back by a script (marked in the video). A longer tour with the 0.9 document import and a voice-over is on YouTube.
Pressure-sensitive fountain pen, pencil, highlighter, dashed strokes and a laser pointer. The ink is smoothed without lagging behind the pen, ends in a pointed stroke when you flick, widens when you tilt the Apple Pencil and stays exactly where you wrote it when you lift the pen; zoom in up to 2400 %. Calibrate the pressure from your own writing in one tap. The shape pen turns casual strokes into lines, arrows, curves, rectangles, ellipses (also tilted), triangles and regular polygons, and a nearly straight highlighter stroke becomes a straight line. Pages come in A4, A5, A3 or Letter with blank, ruled, grid or dotted paper.
Draw a loop around handwriting and choose Convert → Text. The ink is replaced in place by editable text (Chinese and English), in one undo step, with candidates for uncertain characters and a Restore ink button. Recognition runs on your device: the runtime is built into the plugin, and the text models are downloaded once, when you ask (details).
Import document… (command palette or the editor menu), or right-click a file in the file list → Annotate in HandNote. Every page of the document becomes a HandNote page of the same size, and you write on it like on any other page.
- PDF — rendered by the PDF engine that comes with Obsidian.
- Word (.docx, and older .doc) — headings, styles, lists, tables, pictures and landscape sections, laid out into fixed pages.
- PowerPoint (.pptx) — one page per slide: backgrounds, shapes, text, pictures, groups, tables.
- Excel (.xlsx) — printed on A4 pages like OneNote, cells at their real size, number formats, fills, borders and merged cells. Formulas show the value saved in the file; HandNote does not recalculate.
The original file is kept unmodified in your vault (folder HandNote imports by default) and the
note stores only a reference plus your ink. Macros never run, nothing is uploaded. What a file
contains that HandNote cannot show (charts, animations, footnotes…) is listed when you import it.
New in 0.12.1: tap the HandNote pen icon at the top right of any Markdown note and write on it with the same pens, highlighter, shape pen, eraser, lasso, text boxes, images and shapes as in a HandNote note, right inside Obsidian's editor. The note stays editable: the Apple Pencil only writes, and a finger tap on the text lets you type there. Pan into the margins and zoom from 50 % to 800 % with the text laid out sharp at every size.
Annotations follow the text: ink, text boxes and images move with their line when you add or delete
lines above, and a highlight follows the words it covers. They are saved in a separate file under
HandNote annotations/, so your .md file is never changed; an annotation whose line cannot
be found stays where it was and is never deleted. The ink shows in the editing view, not in reading
view, and there is no PNG / PDF export of annotated Markdown notes yet
(details).
Convert → Math opens a LaTeX editor with a live preview: type the formula, then insert it next
to your handwriting or replace the ink. Formulas stay editable objects you can move, resize and copy
as Markdown ($$…$$). Handwritten-math recognition is available through MyScript with your own
keys; this plugin has no on-device math recognition.
Many pages per note, reordered in the page sidebar; bookmark the pages you need often and list only those. Text boxes, images, shapes with connectors and editable formulas sit on the page with your ink; the lasso moves, resizes, rotates, recolours and groups any of them. Long-press the page with a finger (right-click on desktop) to paste, add a text box or insert an image right there.
Next to notes with pages, HandNote makes infinite whiteboards (ribbon icon → Infinite whiteboard): one canvas without edges, dotted by default, zoom out to 10 %. A note with pages can be turned into a whiteboard in one step (undo brings it back): its pages become page frames, laid out from left to right with their paper, imported documents and ink, and the lasso moves a whole frame. Export the whole board or the current view as an image, or embed it in Markdown.
A hand tool (H) that only moves the page, a command for every tool and page action (give them hotkeys in Settings → Hotkeys), go to page by tapping the page counter, a contents tab for PDFs with bookmarks, and pull past the last page to add a new one.
Every note is a .handnote file in your vault, synced by whatever you already use. Embed a page in
any Markdown note with ![[Lecture 3.handnote]]. No account, no server of its own. Saving is
careful: it checks the file was not changed by sync first, keeps a recovery journal and backups,
and opens damaged or newer-format files read-only.
- In Obsidian: Settings → Community plugins → Browse, search for HandNote, then Install and Enable. (Or open the directory page and press Add to Obsidian.)
- Create a note: the New handwritten note command, or right-click a folder → New HandNote.
- Write. Pick the lasso, circle a few words, press Convert → Text. The first time, HandNote offers to download the text model (size shown first); Chinese also works with the built-in offline engine, without any download.
Manual install: copy main.js, manifest.json and styles.css from the
latest release into
<vault>/.obsidian/plugins/handnote/ and enable HandNote. The SHA-256 of each file is in the
release notes, and releases carry GitHub build-provenance attestations.
| Platform | Status |
|---|---|
| iPad (Obsidian for iPadOS) with Apple Pencil | Primary target: pressure, tilt, palm rejection, finger pan / pinch, two-finger undo |
| Windows / macOS / Linux | Mouse, pen tablet, touch screen, keyboard shortcuts |
| iPhone / Android | Should work (no desktop-only APIs are used) but is not tested |
Requires Obsidian 1.11.4 or newer. On-device recognition on iPad / iPhone needs iPadOS / iOS 16.4 or newer.
- Is HandNote an Obsidian plugin? Yes: a community plugin listed in Obsidian's official
directory (id
handnote). It is made independently, not by the Obsidian team. - Does it work on the iPad with an Apple Pencil? Yes, that is the main target: pressure, palm rejection, finger gestures for pan, zoom and undo.
- Can it convert handwriting to text? Yes, Chinese and English, on your device, after a one-time model download (15.8 MB / 7.5 MB). A built-in offline engine also reads neat Chinese.
- Can I annotate documents? Yes, since 0.9.0: PDF, Word (.docx, .doc), PowerPoint (.pptx) and Excel (.xlsx). The original file is not changed and nothing is uploaded.
- Can I write on my Markdown notes? Yes, since 0.12.1: by hand, in Obsidian's own editor. The
.mdfile is not changed; the ink is saved beside it inHandNote annotations/. - Is there an infinite canvas? Yes, since 0.11.0: infinite whiteboards, and any note with pages can be turned into one.
- Is there on-device handwritten-math recognition? No. Type formulas as LaTeX with a live preview, or use MyScript with your own keys.
- Is it free? Yes, MIT-licensed, with no account, subscription or telemetry. Optional cloud services use your own keys.
Gestures and shortcuts
| Action | Pencil / pen | Finger | Mouse / keyboard |
|---|---|---|---|
| Write | draw | — (unless "finger drawing" is on) | drag |
| Pan / zoom | hand tool; desktop pen tablet: Space + drag, or a pen button set to middle click | one-finger drag / pinch | hand tool (H), space + drag, Ctrl + wheel |
| Undo / redo | — | two- / three-finger tap | Ctrl+Z / Ctrl+Shift+Z |
| Edit a text | tap it (lasso or text tool) | tap it | click it (lasso or text tool) |
| Pen ⇄ eraser | — | double-tap with one finger | 1 / E |
| Paste / add here | — | long-press the page | right-click, Ctrl+V |
Settings → HandNote → Recognition and AI → Local recognition. The recognition runtime (ONNX Runtime Web 1.24.2, MIT) is built into the plugin; it is never downloaded and starts only when you convert. The recognition models are not built in: each one is downloaded separately, and only when you ask.
| Pack | Size | Downloaded from (first mirror that answers) | Used for | Licence |
|---|---|---|---|---|
| Chinese text — PaddleOCR PP-OCRv5 mobile rec (ONNX) + dictionary | 15.8 MB | PaddleOCR's official download (Baidu, paddle-model-ecology.bj.bcebos.com), Hugging Face PaddlePaddle/PP-OCRv5_mobile_rec_onnx (or hf-mirror.com); dictionary from the PaddleOCR GitHub repository (or its jsDelivr copy) |
Chinese and mixed lines | Apache-2.0 (model card) |
| English text — PaddleOCR en_PP-OCRv5 mobile rec (ONNX) + dictionary | 7.5 MB | as above (en_PP-OCRv5_mobile_rec_onnx) |
English lines | Apache-2.0 (model card) |
| Hand font — Excalifont + Xiaolai (optional) | up to 12.1 MB, loaded per character | Excalidraw's npm package / repository (npmmirror, jsDelivr, GitHub, Fastly) | hand-lettered look for converted text | SIL OFL 1.1 |
- When: only after you press a pack's Download button in Local recognition, or accept the offer shown when you convert without the model. The size is shown first. Nothing is downloaded at startup, on install, on update or in the background.
- Checked: every file has a fixed size and SHA-256 in the plugin; a file that does not match is discarded. There is no automatic model update: new models only come with a new plugin version, and you still press the button.
- Stored: in this device's app storage (IndexedDB, per device). Never in your vault, never synced. Uninstalling HandNote does not delete them; delete them in Local recognition first.
- Uploaded: nothing. The download requests are plain file requests (short HEAD requests first to find a mirror that answers). Your notes and your handwriting never leave the device for local recognition.
- Offline: after the download, recognition works without a connection. Without the models, writing and everything else still works; Convert → Text can use the built-in offline Chinese engine.
- Blocked mirrors: Import files accepts the same files from disk (same hash check). Run self-test shows what works on this device and which mirrors answer.
Nothing is sent anywhere unless you set it up yourself:
- MyScript (Settings → HandNote → Recognition): your own MyScript keys. The strokes of a selection are sent to MyScript after a confirmation, for text or math. MyScript's terms and pricing apply.
- AI providers (Settings → HandNote → AI): OpenAI, Anthropic, Google Gemini, DeepSeek, Alibaba Cloud Qwen, or any OpenAI-compatible endpoint, with your own key — to turn a sketch into a mind map or a flowchart, or read text from a picture. A picture of the selection is sent after a confirmation. The provider's pricing applies.
Keys are kept in Obsidian's secret storage, never in settings files or notes.
No telemetry, no analytics, no account, no server of its own. Every network request — service, purpose, data sent, cost, offline behaviour — is listed in PRIVACY.md.
- No on-device math recognition. Type formulas as LaTeX, or use MyScript with your own keys. Notes with formulas made by any HandNote version open and edit normally.
- Recognition is trained on general handwriting: unusual or very small writing, or several scripts in one line, are read less reliably. Uncertain results come with candidates, and the ink is kept until you choose.
- A note made with a newer HandNote opens read-only in an older one. Update HandNote on every device that edits the same notes.
- Imported Word / PowerPoint / Excel files are re-laid out by HandNote, not by Microsoft Office:
page breaks and fonts can differ slightly, and charts, SmartArt, animations, headers / footers and
footnotes are not shown. Older .ppt / .xls must be saved as .pptx / .xlsx or PDF first. Office
files get a small
.handnote-layout.jsonbeside them — let your sync tool sync it. - Notes with imported pages use file format 6: HandNote 0.8.x opens them read-only. Whiteboards and the curve shapes added in 0.11 use format 7: HandNote 0.10 and older open them read-only.
- Handwriting written with 0.11 or newer also stores the drawn ink, so those notes are about 1.6–1.9 times larger than before.
- Ink on Markdown notes shows only in the editing view (not in reading view or embeds), cannot be exported as PNG / PDF yet, and its lasso has no Convert / AI. Ink follows its line, not the shape of the sentence; on a device with another font or width its horizontal position can differ.
- Phone layouts are not optimised.
main.jsis about 6.5 MB because the recognition runtime is built in. Obsidian Sync's Standard plan does not sync files over 5 MB, so with that plan install HandNote on each device from Community plugins (your notes sync as usual).
More answers: FAQ.md.
Bugs and ideas: GitHub issues (please do not attach private notes or keys). Security problems: SECURITY.md.
HandNote's own code: MIT. Parts made by others keep their own licences and are not
covered by HandNote's licence: ONNX Runtime Web inside main.js (MIT, © Microsoft Corporation),
the Chinese stroke data inside main.js (Arphic Public License, vendor/hanzi-mmah/), and the
optional downloads (Apache-2.0, SIL OFL 1.1). Details and licence texts:
THIRD_PARTY_NOTICES.md.
HandNote is an independent community plugin. It is not made by, affiliated with or endorsed by Obsidian, MyScript, Goodnotes, Xmind, Excalidraw or Microsoft. Screenshots: Obsidian desktop with HandNote 0.8.1 in a demo vault (the import screenshot: HandNote 0.9.0); the handwriting in them is played back by a script.





