README file from
GithubInkling
If you would like to help Inkling by contributing, please fork the repo, or create an issue. For changes created in a fork, if you would like, submit a PR, and we'll get it into an official release on Obsidian! This started as a side project for me, just a guy wanting to only work in his vault. I would love to see the community grow. I had never expected so many people to be interested, but would love to keep development alive. Reach out with changes, and let me know if you want to be added as an official collaborator. - Bluewolf135
Contributers
- Bluewolf135
Handwritten and text annotation for PDFs and Markdown notes in Obsidian, built mobile-first for stylus input.
Inkling exists for one reason: the knowledge stays in the vault. Xodo and GoodNotes are excellent PDF annotators, and if annotating the PDF were the point you should use one of them. The point is that a highlight in a textbook becomes a searchable, linkable Markdown note sitting beside everything else you know — without leaving the app you keep it all in.
Writing on a textbook page
https://github.com/user-attachments/assets/f55a433e-ef7c-4e35-8456-6de9dec51359
Extracting annotations to a note
https://github.com/user-attachments/assets/40446953-9efd-4fca-be6c-e2305961d351
What it does
Annotate PDFs. Pen, highlighter, eraser, shapes, and lasso selection, over any PDF in your vault. Ink is written into the file as real PDF annotations, so it shows up in Obsidian's own reader, in Xodo, in Acrobat — anywhere.
Feels like ink. Every stylus sample is captured, not just the one per frame the browser volunteers; strokes are curve-fitted rather than joined with straight lines; and a pen that reports pressure draws a stroke that tapers with it.
Highlights become notes. Drag the highlighter over text and it snaps to
the lines it swept — and remembers the words it covered. "Extract
annotations to a note" turns those into Markdown, grouped by page, each
entry linking back to [[book.pdf#page=42]] and carrying a block reference
so you can link to one specific highlight.
That works retroactively, on highlights made before you installed this and on highlights made in other PDF software: the match is geometric, so anything with a rectangle over text can have its quote recomputed.
Comments. Tap with the note tool, type, and it commits as a standard PDF sticky note — which means other readers show it too.
Handwritten notes. Create a blank, lined, or dot-grid PDF and write straight into it, adding pages as you fill them.
Ink blocks in Markdown. A ```inkling block is a drawing
surface inside an ordinary note, for a diagram in the middle of a page of
typing. "Insert ink annotation block" leaves a three-line fence in the note
and keeps the strokes in an .ink file beside your other attachments, one
per note, so the note stays readable and small. Where those files go is a
setting.
Getting around. Outline, page jump, find-in-document, per-page zoom (pinch, Ctrl+wheel, or the toolbar), a collapsible toolbar, and dark-mode page inversion that darkens the page without touching the colour of your ink.
Keyboard
Inside the annotate view:
| Key | Action |
|---|---|
s p h e |
Select, pen, highlighter, eraser |
l r o a |
Line, rectangle, oval, arrow |
1–6 |
Preset colours |
[ ] |
Thinner, thicker |
Delete |
Delete selection |
Mod+Z / Mod+Shift+Z |
Undo / redo |
PageUp / PageDown |
Previous / next page |
Mod+= / Mod+- / Mod+0 |
Zoom in / out / reset |
Undo and redo are also palette commands, so you can bind them globally.
Installing
Not in the community catalogue yet. Install with BRAT:
- Install BRAT from Community Plugins.
- Add Beta Plugin, and give it this repository.
- Enable Inkling in Community Plugins.
Or manually: download main.js, manifest.json and styles.css from a
release into <vault>/.obsidian/plugins/inkling/.
Mobile and stylus
Built mobile-first, and tested on a Samsung tablet with an S Pen.
- Palm rejection. Pen and mouse draw; touch scrolls and pinch-zooms.
Touch panning is hand-rolled rather than left to the browser, because
relying on
touch-actionlet a downward pen stroke get taken over mid-draw on real hardware. - Pressure and tilt. Pressure varies stroke width where the stylus reports it.
- No desktop-only APIs. Everything runs on mobile.
Privacy
Inkling makes no network requests. Everything it reads and writes is a file in your vault, through Obsidian's own API. No accounts, no telemetry, nothing sent anywhere.
Obsidian's plugin review lists a few things in the bundle worth explaining:
- Network calls. They are in the bundled PDF library, pdf.js. Most are
not network code at all:
xref.fetchlooks up an object inside the PDF. The real ones download extra fonts, character maps or decoders, and pdf.js makes them only when given a URL to fetch from. Inkling hands it the file's bytes and never sets one. - Base64 (
atob/btoa). An ink block's strokes are compressed and stored in its.inkfile as base64 text, which these encode and decode. They carry drawing data only. pdf.js also uses them for font data. - WebAssembly (
qcms_bg.wasm,openjpeg.wasm). pdf.js's optional colour-management and JPEG 2000 modules. Inkling does not ship them and never tells pdf.js where to find them, so they are never loaded. Without the first, pages use the PDF's plain fallback colours instead of its embedded colour profiles. Without the second, see Limitations. - No dynamic code. The build removes pdf.js's
evalandnew Function, and fails if any come back.
Limitations
Some PDFs open read-only, on purpose. Inkling rewrites a PDF through
pdf-lib, and before it will do that it checks the document two ways: it
compares pdf-lib's reading of the file against pdf.js's, and it looks
for interactive forms and digital signatures. If the two readers disagree,
or the document has a form or a signature, the book renders and its
existing annotations display but drawing is turned off, with a banner
saying why. Filling in a form and saving it through here would lose the
form; re-serializing a signed document invalidates the signature.
Some PDFs are rewritten whole on every save. Most saves append only what changed to the end of the file — a kilobyte or two, however large the book — so sync uploads the change rather than the textbook. A file whose structure Inkling cannot safely append to is rewritten whole instead, and for those it scales how often it saves to the file's size: ten seconds under 5 MB, thirty up to 25 MB, a minute above. Either way, every save is verified against the document it came from before a byte is written.
Extraction is one-directional. Editing an extracted note does not change the PDF.
JPEG 2000 images do not display. A few PDFs, mostly scanned books, store pages or pictures as JPEG 2000. pdf.js decodes those with a WebAssembly module Inkling does not ship, so those images are left blank. The rest of the page, and any ink on it, is unaffected.
Ink blocks render only inside Obsidian, so a note holding one is less portable than one holding an image.
Renaming or moving an .ink file breaks its blocks, for now. The fence
names the file by path, and nothing rewrites it yet, so the blocks show a
read-only "missing" banner and never save over anything. Move the file
back and they return. Renaming or moving the note is fine. Blocks made
by earlier versions, with their strokes inside the note, keep working
exactly as they did.
Development
npm install
npm run dev # watch build
npm test # vitest
npm run lint
npm run build # type-check and production bundle
pdf-lib and pdfjs-dist are pinned to exact versions for reasons
recorded at the top of src/pdfView.ts. Don't bump them without reading
that comment.
Design documents and implementation plans live in docs/superpowers/.
Branches, commit messages and releases are described in
CONTRIBUTING.md.
License
MIT — see LICENSE.