Org-noter, by Gonçalo Santos, was inspired by the now-orphaned Interleave
package, by Sebastian Christ. In Sebastian’s words (with minor edits):
In the past, textbooks were sometimes published as interleaved editions. That meant, each page was followed by a blank page and ambitious students/scholars had the ability to take their notes directly in their copy of the textbook. Newton and Kant were prominent representatives of this technique. [find reference]
Nowadays, textbooks (or lecture materials) come in PDF format. Although almost every PDF Reader has the ability to add some notes to the PDF itself, it is not as powerful as it could be. This is what this Emacs minor mode tries to accomplish. It presents your PDF side by side with an Org Mode buffer of your notes, narrowed down to just those passages that are relevant to this particular page in the document viewer.
Org-noter’s purpose is to let you create notes that are kept in sync when you
scroll through the document, but that are external to it - the notes
themselves live in an Org-mode file. As such, this leverages the power of
Org-mode (the notes may have outlines, latex fragments, babel, etc…) while
acting like notes that are made inside the document. Also, taking notes is
very simple: just press i and annotate away!
Org-noter is compatible with DocView, PDF Tools, Nov.el, and DJVU-image-mode. These modes make it possible to annotate PDF, EPUB, Microsoft Office, DVI, PS, OpenDocument, and DJVU formatted files. Note that PDF support is our prime goal. Other format have been supported by other contributors, but we need code contributions from users of other formats to maintain/progress usability with those formats.
- clone this repo to a local directory
- add to your init file:
(add-to-list 'load-path "<path-to-org-noter>") (require 'org-noter)
(use-package org-noter
:load-path "<path-to-org-noter>"
:ensure t
:demand t)In plain straight.el syntax
(straight-use-package 'org-noter)(straight-use-package 'use-package)
(setq straight-use-package-by-default t)
(use-package org-noter)Alternate form cribbed from dmitrym0#3
(use-package org-noter
:straight
(:repo "org-noter/org-noter"
:host github
:type git
:files ("*.el" "modules/*.el")))(add-to-list 'package-archives '("melpa" . "https://melpa.org/packages/"))
(package-refresh-contents)
(package-install 'org-noter)- Easy to use annotation interface
- Just press
iin the document buffer and annotate away! - Keep your notes in sync with the document
- When you take a note by pressing
i, it saves the location where you took it so it is able to show you the notes while you scroll, automatically! - Easy navigation
- You may navigate your document as usual, seeing the notes buffer scroll and show you the respective notes; however, you may also navigate by notes, only seeing annotated pages/chapters.
- Isolated interface
- Each session has its own frame and the document and notes buffers are indirect buffers to the original ones. Killing any of these things will terminate your annotation session.
- Simultaneous sessions
- You may open as many annotation sessions as you wish, at the same time! The root heading of each document will be made read-only to prevent you from deleting a heading from an open session.
- Resume annotating from where you left
- When
org-noter-auto-save-last-locationis non-nil, it will save the last location you visited and pick it up when you start another session! You may also set this per-document, read more here. - Keep your notes organized
- You may arrange your notes however you want! You can create groups and nest notes (and even nest documents inside other documents)!
- Annotate
org-attach‘ed files - If you have any attached files, it will let you choose one as the document to annotate.
org-noter-enable-update-renames- Optional feature to update document paths when renaming or moving document files or notes files. This allows you to change your mind later about the names and locations of your document files and notes files without having to manually update all the links.
org-noter-toggle-notes-window-location(M-T)- Toggle between horizontal and vertical document/notes layout.
org-noter-start-from-dired(Suggested keybinding:M-s n)- Start
sessions directly from
dired. Opens all marked files or the file at point if none are marked.
new (PDFs only with the pdftools package)
- 2D precise notes
- (Ahmed Shariff) Location tooltip appears at start of selected text or point of click.
- Multicolumn ordering of precise notes
- With the
COLUMN_EDGESproperty, you can specify the number of columns in a multicolumn document (or pages thereof). Precise notes are ordered vertically within columns. UseM-x org-noter-pdf-set-columnsto interactively setCOLUMN_EDGESfor the current heading. The property is inheritable, so it can be set at the page, chapter/section, or document level. See docs/HOWTO.org for more details. - Highlighting of selected text
- Default behavior (on/off) is
user-customizable via
org-noter-highlight-selected-text. Non-default behavior is activated with aC-uprefix to the note insertion command. - Customizable tooltip arrow colors
org-noter-arrow-foreground-color(default orange-red) andorg-noter-arrow-foreground-color(default white) are both user customizable.
[TODO: make/link to screencast]
If you want to give it a try without much trouble:
- Open an Org file where you want the notes to go.
- Create a root heading to hold the notes.
- Run
M-x org-noterinside the Org file. On the first run, it will ask you for the path of the document and save it in a property. By default, it will also let you annotate an attached file (org-attach documentation).
This will open a new dedicated frame where you can use the keybindings described here.
More generally, there are two modes of operation. You may run
M-x org-noter:
- Inside a heading in an Org notes file
- This will associate that heading with a document and open a session with it. This mode is the one described in the example above.
- In a document
- Run
M-x org-noterwhen viewing a document (eg. PDF, epub…).This will try to find the respective notes file automatically. It will search in all parent folders and some specific folders set by you. See
org-noter-default-notes-file-namesandorg-noter-notes-search-pathfor more information.
There is, of course, more information in the docstrings of each command.
See docs/CUSTOMIZATIONS.org for examples of user & maintainer customizations to this package.
There are two kinds of customizations you may do:
- Global settings, affecting every session
- Document-specific settings, which override the global settings
The global settings are changed with either the customization interface from Emacs or directly in your
init file. To find which settings are available, you may use the customization interface or you may just
read org-noter.el.
The best way to set document-specific settings is by using the utility commands provided (list below). In order to use them, you need an open session. The commands may change the settings for that session only (not surviving restarts), or for every session with that document.
List of utility commands (check the docstrings to learn how to make the changes permanent, or revert to the default):
- You may set a start location for this document, by using
org-noter-set-start-location. - To automatically resume from where you left, use
org-noter-set-auto-save-last-location. - With
org-noter-set-notes-window-behavior, you may change when the notes window pops up. - With
org-noter-set-notes-window-location, you may change where the notes window pops up. org-noter-set-doc-split-fractionwill ask you for the fraction of the frame that the document window occupies when split.org-noter-set-hide-otherwill toggle whether or not it should hide headings not related to the executed action.org-noter-set-closest-tipping-pointwill set the closest note tipping point. Also check the docstring of the variableorg-noter-closest-tipping-pointin order to better understand the tipping point.- org-roam integration: run
(org-noter-enable-org-roam-integration)after loading org-noter.
| Key | Description | Where? |
i | Insert note | Document buffer |
C-i, TAB | Insert note, toggle no-questions | Document buffer |
M-i | Insert precise note | Document buffer |
C-M-i | Insert precise note, toggle no-questions | Document buffer |
q | Kill session | Document buffer |
M-p | Sync previous page/chapter | Document and notes buffer |
M-. | Sync current page/chapter | Document and notes buffer |
M-n | Sync next page/chapter | Document and notes buffer |
C-M-p | Sync previous notes | Document and notes buffer |
C-M-. | Sync selected notes | Document and notes buffer |
C-M-n | Sync next notes | Document and notes buffer |
You can use the usual keybindings to navigate the document
(n, p, SPC, …).
There are two types of sync commands:
- To sync a page/chapter, means it will find the [previous|current|next] page/chapter and show the corresponding notes for that page/chapter; as such, it will always pop up the notes buffer, if it does not exist. This type of command is in relation to the current page/chapter in the document.
- To sync the notes, means it will find the [previous|current|next] notes and go to the corresponding location on the document. So, you need to have the notes window open, because this type of commands is in relation to the selected notes (ie, where the cursor is).
When using PDF Tools, the command org-noter-create-skeleton imports the PDF outline or
annotations (or both!) as notes, and it may be used, for example, as a starting point.
You may also want to check the docstrings of the functions associated with the keybindings, because there is some extra functionality in some.
- more consistent use of selected text in title or body
- more consistent primary default title (short-selected-text)
- more consistent secondary default title (“Notes for page <location>”)
- avoids having different notes with the same heading
Previously, repeated TAB’s give multiple notes. Now, new notes in the same location with the same title are not made, but selected text is added to the note body. Precise notes are excepted from this rule.
- long text-selections are enclosed in #+BEGIN_QUOTE…#+END_QUOTE
- short text-selections are enclosed in “…” (LaTeX style) when they are not used as the title of the note.
- short/long text-selections are differentiated by the custom variable
org-noter-max-short-selected-text-length(default: 80 char)Previously, long selections were those with more than 3 lines.
insert-note i | precise note M-i | no-questions C-i, TAB | |
|---|---|---|---|
| title prompt? | Y | Y | N |
| default title 1 | prior note by location | selected-text | N/A |
| default title 2 | “Notes for page #” | “Notes for page # x y” | “Notes for page #” |
| new note | with new title | always | always |
| body | selected-text on existing note | selected-text (> 3 lines) | none |
| insert-note | precise note | insert, no-questions | precise, no-questions | |
|---|---|---|---|---|
| title prompt? | Y | Y | N | N |
| default title 1 | short-selected-text | short-selected-text | short-selected-text | short-selected-text |
| default title 2 | “Notes for page #” | “Notes for page # x y” | “Notes for page #” | “Notes for page # x y” |
| new note | with new title | always | with new title | always |
| body | selected-text (not title) | selected-text (not title) | selected-text (not title) | selected-text (not title) |
| highlight selection | user setting/toggle | user setting/toggle | user setting/toggle | user setting/toggle |
- Sebastian Christ
- Author of the
interleavepackage, inspiration fororg-noter - Gonçalo Santos
- Author of
org-noter - Ahmed Shariff
- Contributor of 2-D precise notes
- Charlie Gordon
- Contributor of DJVU support and document-type modularization