Notebook

by Alex
5
4
3
2
1
Score: 55/100

Description

Handwritten notes and PDF annotation for Obsidian, built for stylus and Android tablets. Local-first, open source.

Reviews

No reviews yet.

Stats

1
stars
186
downloads
0
forks
9
days
2
days
2
days
34
total PRs
0
open PRs
0
closed PRs
34
merged PRs
0
total issues
0
open issues
0
closed issues
778
commits

Latest Version

3 days ago

Changelog

Handwritten tasks and a lecture you can follow up from your notes: checkboxes drawn with the pen that tick the tasks in your Markdown notes, a lecture log line in the daily note and an automatic snapshot at the end of each lecture, a gallery of the figures of a lecture, a clean copy of the notes to share, a list of things to look up later, typed text that Obsidian's search can find, and notebooks made from note templates. The notebook format moves to version 17: 0.18 and older open a v17 file read-only and never overwrite it.

Handwritten checklists (#103) and document format 17

  • Handwritten checklists (#103), document format 17. A small square drawn with the pen is offered as a checkbox (a Make checkbox chip next to it; the setting Squares drawn as checkboxes can also make it one at once, or leave it as ink). A checkbox can also be inserted from the Insert sheet. A tap with the pen, a mouse or a finger ticks it (one undo step, refused on a locked page); the tick is drawn above the ink and in exports. The handwriting on the same line to its right is its label: Select with text selects both, and the crop of a task is the box and its line.
  • Send to tasks. Send to tasks… on a selected checkbox adds - [ ] <label> ![[picture]] [[page]] to the daily note, the tasks note or a chosen note (the same code and dialog as Make task, with an optional text), ending in a block id ^nb-… that the plugin wrote. Ticking the checkbox (or undoing, redoing, merging) then ticks that one line of the note and nothing else; if the line is really gone (the note was edited since the link was made and read twice, a minute apart, without it) the checkbox is unlinked with a notice. Unlink task stops the link.
  • Open items. The notebook map has an Open items filter: the pages that still have an unticked checkbox, with the count on the badge.
  • Document format v17. A new page element checkbox (place, size, colour, optional tick, tick time, typed label and task link), one line. The v16 to v17 migration only refuses a checkbox in a v16 file (large v16 files still stage); 0.18 and older open a v17 file read-only and never overwrite it. Read leniently (an invalid detail is dropped and counted), written strictly, repaired from the line scan. Copies of a page or a selection keep the tick but never the task link; notebooks and pages made from or saved as templates are unticked and unlinked. Merging a conflicted copy keeps one checkbox and the later toggle wins.

Clean copy export (#239)

  • Clean copy for exports (#239). The export dialog has a Clean copy switch: the PDF, SVG, PNG and Print leave out the study and working layers — placeholders and the other markers (questions, importance, homework), margin comments (and the PDF comment notes) and collapsed sticky notes together with the ink they hide — so the lecture is ready to share; Also leave out open sticky notes is an option. Boxes, text, pictures, equations, the page header and invisible ink (still governed by Show solutions) are kept. The page model is filtered by the pure cleanPageForExport before drawing; the notebook is never changed, the format is unchanged and an export without the switch is byte-identical to before. Choosing the pages of "this lecture" is still done with Some pages.
  • Figures gallery (#228). Figures… (All actions, the notebook menu and the command palette) opens a grid of every picture placed on the pages (photos, board photos, imported pictures) and every anchored crop that holds a snapshot. A scope switch picks This section (the lecture of the page in view; offered only when some page starts a lecture), Whole notebook or Some pages (typed as 1-3, 5), and kind chips (All / Photos / Crops) show counts. Each card has a page badge; a tap goes to the figure on its page and outlines it for a moment, a long press (or the card's more button, or a right click) offers Copy image, Insert into note… (the 0.18 picture-into-note path, drawn from the figure's place on the page) and Open original. Thumbnails are made lazily from the stored files, only for cards in view, one at a time and only when you are not writing, decoded small and kept in a bounded cache (60). Read-only: it never writes the notebook. No format change. Pure logic in src/model/figures.ts (tests: tests/figures.test.ts), dialog in src/view/figures.ts. Harness: dev/harness/figures-check.ts (doc=figures).

Look up later (#213)

  • Look up later (#213). Look up later… in the selection menu (and the palette) takes a picture of the selection, asks for an optional typed word and appends one line to a Markdown note: - [ ] ![[crop|150]] word — [[Notebook#p3&id=…|Notebook p. 3]] (date). The note is Look up later.md in the notebooks folder by default (setting Look up later note, made on the first entry), the picture width is a setting, and only a line is ever appended: the rest of the note is untouched, typed text is escaped, and the same line is not added twice. The Look up later list… sheet (page sheet, notebook menu, palette) lists this notebook's entries read from the note, with their picture, count and a jump to the page; it is read-only (tick entries off in the note). No format change. Not added as a pen gesture: the gesture system lives in the input files this wave does not touch.

Typed text in search (O19)

  • Companion notes: new setting Include typed text in search (off by default). The companion note also lists, per page, the text of sticky notes, margin comments and replies, equation sources, marker labels and the typed labels of checkboxes (with ☐ / ☑ for the state), with a wikilink back to the page, so Obsidian search finds them. Text is escaped, bounded to 4000 characters per page, and written only inside the generated block. No format change.

Notebooks from note templates (O13)

  • Notebooks from note templates (O13). The public API (now 1.2.0) has api.newNotebook({ name, folder?, template?, content?, open? }), which creates a notebook, optionally from a notebook template, and returns ready-to-paste link and embed Markdown; createNotebook gained the template and templateContent options. A fenced notebook-new block (name="{{title}} sketches", template="Lecture") survives core Templates and Templater and shows a Create notebook card; only a press creates the notebook, and then only that block is replaced by ![[…]], through vault.process with an exact match (no match, or two identical blocks that cannot be told apart: nothing is created). Copy-paste examples for core Templates and Templater in docs/templates.md. No format change. Pure parsing and replacement in src/integration/new-block.ts. Tests: tests/new-block.test.ts.

Lecture snapshots (#222)

  • Automatic snapshot at the end of a lecture (#222). When a lecture ends, the notebook keeps a version of itself named after the course, shown in Restore a previous version as "Lecture hh:mm" with a graduation-cap mark. A lecture ends when lecture mode is left (by you or by the clock), when its class is over, or when the notebook is closed, after you wrote during a timetable class (the same end that writes the lecture log line; switching to another app does not end a lecture, it only saves). The view saves first and the snapshot is made from the file on disk, never from memory; nothing is taken if the save did not finish, if you did not write, or if the notebook holds what its newest snapshot already holds (a fingerprint that ignores the modified time). It goes through the same history folder as every snapshot (<id>/<YYYYMMDD-HHmm>-lecture.snapshot; the course is kept in a small lenient lectures.json beside them, never rewritten if unreadable). Version history has a Lecture snapshots filter when the notebook has any. No format change.
  • Settings (Library). Snapshot at the end of a lecture (on by default: it only does anything for a notebook linked to a timetable class, and the existing interval snapshots are on by default too) and Lecture snapshots to keep (default 20 per notebook). Only this feature's own -lecture snapshots beyond the count move to the trash (through Obsidian's trash path); ordinary snapshots and their Versions to keep count are never touched by it, and it never touches them. Pure logic in src/storage/lecture-snapshot.ts, the list pieces in src/view/history-ui.ts. Tests: tests/lecture-snapshot.test.ts. Harness: dev/harness/snapshot-check.ts (doc=snapshot).

Lecture log (#221)

  • Lecture log in the daily note (#221). With the new setting Lecture log in the daily note on (off by default), when a lecture you wrote in ends (lecture mode left or its class over, or the notebook closed during the class's time slot) one line goes into the daily note of that day: - 10:15–11:45 **Analysis I** · 3 pages · 2 open questions — [[Analysis I#p12&id=…|pp. 12–15]] ^nb-lec-…. The pages run from the lecture page to the one before the next dated page; open questions are the unresolved question markers on them. The line goes under a configurable heading (Lecture log heading, default "## Lectures", added at the end of the note when missing). One line per notebook and class occurrence: it carries a block id the plugin added, and a session that goes on later rewrites exactly that line through vault.process (every other byte of the note stays). It follows the daily-note settings: a missing daily note is made only with Create the daily note if missing; otherwise the line waits in this device's local storage (bounded: 30 lines, 21 days) and is written once the note exists. No format change. Pure logic in src/library/lecture-log-logic.ts, writer in src/library/lecture-log.ts. Tests: tests/lecture-log.test.ts.

Review fixes

  • Lecture log: a session that goes on rewrites only the part of the line the plugin generated (time, course, counts, link). A quote mark, a task box or list marker you put in front of it, and words you added after the link, stay; a copy inside a code fence is never touched; a line you turned into something else is left alone (nothing is rewritten or added).
  • Lecture log: a written line stays in the device's waiting list until a later read of the note, a few seconds on, shows it; a template engine (Templater) that overwrites a brand new daily note after the line was written no longer loses it silently (it is written again, up to 3 times). The vault events that watch the waiting notes are registered once the layout is ready and no longer parse the waiting list on every file.
  • Lecture log: turning Create the daily note if missing on later no longer makes the daily notes of past days (only the class's own day); a course name with %%, <!--, #tag, $…$, == or a trailing backslash can no longer comment out or tag the line; the line's id follows the notebook's document id, so renaming or moving the notebook between two ends of a class rewrites the same line instead of adding a second one.
  • Lecture end: writing up to 10 minutes after a class's time slot still counts for that class (the lecture log and the snapshot are brought up to date). Switching apps during a class makes no lecture end, log call or snapshot; the one end comes when the mode is left, the class is over or the notebook closes.
  • Storage cleanup: lecture snapshots no longer count in the "newest N" window of the ordinary snapshots and are never offered for the trash there; their own Lecture snapshots to keep count governs them. A lecture snapshot that is due while an interval snapshot of the same notebook is running waits instead of being skipped.
  • Restore a previous version: the list opens from the file names and sizes and no longer reads and parses every copy (no page count in the rows); the chosen copy is checked when you restore it.
  • Look up later: the sheet picks the entries of this notebook across the whole shared note before the 500-entry cap and keeps the newest, so a busy shared list no longer hides new entries.
  • Notebooks from note templates: the Create notebook card shows no button inside the Templates or Templater folder (it is the template's own text); once the notebook exists the button never comes back, and a failure to replace the block shows the link instead; the block it replaces is fixed when you press the button, not by a line number that typing above can shift. createNotebook with open no longer fails when only opening the new notebook fails.
  • Companion search text: bare web addresses (https://…, www.…) are broken so they do not become links, and the search text of all pages together is capped at 200,000 characters per note (the cut is said once).
  • Checklists: a long label no longer blocks saving. Sending a checkbox to the tasks with a text of 201 to 300 characters whose 200th character was a space left a label ending in a space, which the writer refused on every save; the label is now trimmed again after it is cut to 200 characters.
  • Checklists: a tick waiting to be written into its task line is no longer lost when you switch app, close the tab or the notebook reloads within the first second: it is noted at once, written when the app is hidden or the notebook closes, kept across a reload, and tried again (4 s, 15 s, 1 min, 5 min) when the write fails.
  • Checklists: a task note that is not in the vault yet (the notebook synced before the note did) or was renamed no longer unlinks the checkbox. The link stays and the tick is retried; a renamed or moved note, or a renamed folder, is followed. Only a note that exists, was edited since the link was made and no longer has the line, twice, unlinks the checkbox (see below).
  • Checklists: Duplicate in the Library gives the copy checkboxes without links to the original's task lines (the ticks stay), so ticking the copy no longer rewrites the original's note.
  • Checklists: moving pages to another notebook (move, split, merge into the trash, restore from the page trash) keeps the links of their checkboxes; only real copies drop them.
  • Checklists: merging an older copy no longer links again a checkbox you unlinked: linking and unlinking are stamped (taskAt, optional, still format 17) and the later decision wins.
  • Checklists: a finger tap on a checkbox is ignored while the pen is down or was just used, so a palm resting on the page between strokes no longer ticks it.
  • Checklists: the pen ticks a checkbox only on the box itself and 3 pt around it (a finger keeps its larger target), so a dot or a colon written right beside the box stays ink.
  • Checklists: the task line is found more safely: copies inside fenced code blocks and the frontmatter are skipped, a task in a callout or quote works, and when two lines carry the same id nothing is changed and a notice says so.
  • Checklists: when two copies disagree about a tick at the same time (or both lack a time), the tick wins, and a copy is not reported as covered while its tick is missing, so Move only no longer sends a tick to the backups.
  • Checklists: the merge summary lists ticked and relinked checkboxes (and resolved markers).
  • Checklists: a task line that is gone is reported only when the checkbox was really unlinked; a refused unlink (locked page, read-only notebook) tells nothing and is tried again.
  • Checklists: the Send to tasks text no longer says ticking the task in the note ticks the checkbox (ticks go from the notebook to the note only).
  • Checklists: in the setting Make it a checkbox, a square is no longer converted while you are still drawing a tick across it; it waits for the stroke and checks again.
  • Checklists: a note path too long to store is refused with a notice when sending a checkbox to the tasks, instead of blocking saves.
  • Checklists: the Open items tooltip follows a changed label.
  • Checklists: an older copy of the note that has not received the task line yet (the notebook synced first) no longer unlinks the checkbox. A line counts as gone only when the note was edited after the link was made and it is read without the line twice, at least a minute apart; otherwise the link stays and the tick is tried again.
  • Checklists: a code block that never closes above the task line (for example one still being typed on another device) no longer makes the line read as deleted.
  • Checklists: a note renamed to a path too long to store keeps the old link, with one notice, instead of making every later save fail.
  • Checklists: following a renamed note is no longer an undo step (Undo does not point the link back to the old name), and it is also followed when the notebook was closed at the time: the renames of notes are remembered on this device for 30 days (a small bounded list, never synced) and consulted when the notebook opens and before a tick finds no note.
  • Checklists: the automatic unlink of a deleted task line is no longer an undo step either, so Undo right after a tick un-ticks it. Both are still saved with the notebook.
  • Checklists: undoing or redoing a move, a move to another page or a margin change of a linked checkbox after its link followed a renamed note (or was dropped) no longer makes a second copy of the checkbox, which stopped every later save of the notebook. The steps in the undo history are told what the upkeep change replaced and keep the link it left. As a backstop, an undo or redo that would leave a notebook the writer refuses (two items with one id, for example) is not done: the notebook stays as it was, the step leaves the undo history and a notice says so; the edit guard now also refuses duplicate ids. Redoing a tick or a resolved marker puts back the very same object, so the steps above it still find it.
  • Checklists: a link that follows a renamed note keeps the time it was made, so a task line deleted from a note edited since the link (and renamed while the notebook was closed) is reported as gone, not as a missing note. The notice about a new path too long to follow is shown once per checkbox in a session, not on every retry.
  • Undo and Redo: a refused redo also clears the redo steps made on top of it; a step that throws is taken back exactly (the step is dropped and the same notice shown, nothing is thrown into the view); a notebook that already failed the check before the step is no longer blamed on the step, so the step is kept.
  • Lecture log: a line is written again after a template engine overwrote the note only within two minutes of the write. Later (after a restart, or when the app was suspended) the line counts as settled, so a line you deleted or moved is not put back, and a confirm never makes a daily note.

README file from

Github

Why Notebook

Features at a glance

The highlights are below; the complete guide, with every setting, is in docs/features.md.

Writing

Ink that feels like paper and stays sharp at any zoom, because every stroke is stored as vector points with pressure.

  • Pen, a highlighter that darkens what is under it instead of covering it, and an eraser for whole strokes, segments or an outlined area.
  • Lasso to move, resize and rotate; shapes that turn clean when you hold still at the end; text boxes, images, a ruler and stamps.
  • Radial menu next to the pen, favourite pens, palm rejection, two- and three-finger taps for undo and redo.
  • Equations typeset with Obsidian's maths engine and function graphs (cartesian, parametric, polar, implicit), both kept as vectors.
  • Papers: blank, ruled, grid, dotted, millimetre, Cornell, music, isometric, hexagonal, planners, and infinite pages.

Study

Tools for lectures and revision, all computed on your device.

  • Markers for gaps, questions, importance and homework (homework becomes Obsidian tasks), with an End of lecture panel.
  • Invisible ink for answers and Redo the exercise: a practice copy with your ink hidden, a peek at the solution and a timer.
  • Pen gestures: circle to select, scribble to delete, "^" to insert space, a star to bookmark.
  • A class timetable that opens the right notebook on a new dated page, and New lecture from slides.
  • A Zettelkasten made from handwriting: cards from a lasso selection or a page, with an inbox to process.

PDF

Annotate slides and papers without losing the clean original.

  • Import a PDF as a notebook, insert PDF pages or a scan (camera, corner detection, document and whiteboard filters).
  • Search the PDF text, a highlighter that snaps to text lines, hide your annotations or dim the page, widen margins to write beside a slide.
  • Open a PDF side by side with your notes, and update to a new version of the slides while your notes stay on their slides.
  • Anchored excerpts: cut a figure onto another page, then tap its badge to jump back to the exact place it came from.
  • Export highlights and text boxes to a Markdown note.

Organisation

Find any page in seconds, even in a big vault.

  • Home dashboard and a library with subject folders, smart collections (To study, Favourites, With PDF, Recent, Exams), tags, pins and an archive.
  • Search across titles, tags and typed text (handwriting is not searched: there is no OCR).
  • Pages panel with thumbnails, drag to reorder, a coloured outline of bookmarks, page tags and a Go to page switcher across notebooks.
  • Export to PDF, SVG, PNG or Markdown with page images; print on desktop.

Obsidian integration

Notebooks behave like part of your vault.

  • Link or embed a single page: [[Physics.notebook#p3]], ![[Physics.notebook#p3]] or a notebook code block; obsidian://notebook links for other apps.
  • Optional companion notes so Obsidian search, the graph, tags and Dataview see your notebooks.
  • Obsidian tags, Obsidian bookmarks to a page, commands for the mobile toolbar, a public API for Templater, QuickAdd and Dataview.
  • A documented file format with a JSON Schema, so other tools can read notebooks.
  • Interface in English and Italian.

Privacy & safety

Your notes are files you own, and the plugin works hard never to lose them.

  • A .notebook file is versioned JSON in your vault; PDFs and images are stored once in _assets. No account, no cloud, no telemetry, no AI.
  • Automatic saving plus an instant save journal that restores the last changes after a crash.
  • Version history, Restore a single page, Repair damaged notebook. Unreadable files are never overwritten and a backup is kept.
  • Sync safety for folder-sync apps: conflicted copies can be merged, an Open on another device banner, and an integrity check that spots stale copies.

Quick start

  1. Install. In Obsidian open Settings → Community plugins → Browse, search for Notebook, then Install and Enable (or open the community page). Prefer the newest build, or a pre-release? Use BRAT.
  2. Create your first notebook. Tap the ribbon icon to open Notebook home, then New notebook. The creation dialog has two tabs: Notebook (cover, name, folder, paper, page size and orientation) and Folder (a subject with its own icon and colour). Choose, then Create.
  3. Write. The pen writes; one finger scrolls and two fingers zoom (turn on Draw with finger in the settings to write with a finger). Click the S Pen side button while the pen hovers, or hold the pen still for a moment, to open the radial menu; hold the button while you write to erase.
  4. S Pen tips. What the side button can and cannot do inside Obsidian on Android, and how to map the pen's remote button to a key, is in S Pen on Android.
  5. Sync. Notebooks are ordinary files: a Google Drive or OneDrive folder-sync app, Syncthing or Obsidian Sync (turn on Other types) all work. Sync the _assets and _backup folders too. Details in the FAQ and in Versions and recovery.

Install with BRAT

BRAT installs the latest GitHub release, pre-releases included, and keeps it updated:

  1. Settings → Community plugins → Browse, search for BRAT (Obsidian42 - BRAT), install and enable it.
  2. Command palette → BRAT: Add a beta plugin for testing → enter https://github.com/Plagemes/Obsidian-Notebook → choose the latest version → Add plugin.
  3. Enable Notebook in Settings → Community plugins.

Manual install (Windows and Android) and debugging on Android are in docs/install.md.

FAQ

Yes. Notebook is free and open source under the MIT licence. There is no paid tier, no account and no ads.

In your vault, as .notebook files (by default in the Notebooks/ folder). PDFs and images live once in Notebooks/_assets/, backups and version snapshots in Notebooks/_backup/. Uninstalling the plugin leaves every file where it is. The format is documented in docs/features.md and docs/architecture.md.

It is designed first for Android tablets with a stylus (S Pen) and also for Windows. It uses no desktop-only code, so it also loads on macOS, Linux and iPad, but those are not a focus and have not been tested. On Android, Obsidian does not pass pen hover to plugins, which limits what the S Pen side button can do (see the next question).

A click while the pen hovers opens the radial menu (or, if you choose, makes the next stroke erase). Holding the button while the nib touches the page erases, and pressing it mid-stroke erases the rest of that stroke. Because Obsidian for Android does not pass hover to plugins, anything that needs hover (a cursor preview, choosing by releasing over an action) cannot work. The full explanation, the timing settings and an optional key-mapping setup are in S Pen on Android.

No. Everything, including the generated art and the statistics, is computed by ordinary code on your device, and nothing is sent anywhere: no account, no server, no telemetry. Syncing is up to you and the tools you already use (Google Drive, OneDrive, Syncthing or Obsidian Sync). Optional AI features are only an idea for much later on the roadmap, after writing and saving are proven stable, and would be local first with any cloud use as an explicit opt-in.

Roadmap

As of 0.21.0 the roadmap has 199 features shipped, 0 in progress and 239 to do (plus 5 deferred and 30 dropped). The live page is rebuilt from docs/roadmap.md on every change, with filters, search and the most requested features.

Contributing

Status: v0.21.0 (document format 19), early development. The automated tests and the browser harness pass, but Notebook has not been verified on Android hardware yet; what is verified, and how to test it, is in docs/testing.md.

Licence

MIT, see LICENSE. Third-party code: perfect-freehand (MIT). PDFs are rendered with the pdf.js that Obsidian provides. No code was copied from the other projects studied in docs/research.md.