README – Org-remark

Breaking Changes

• [18 January 2022] Package name change from Org-marginalia to Org-remark. See detail on data conversion. In most cases, no action is required for you.

Introduction

Org-remark lets you highlight and annotate text files and websites with using Org mode [fn:1].

A user manual is available online or Emacs in-system as an Info node `(org-remark)’: (C-h i and find the Org-remark node).

For installation and minimum configuration, refer to Installation below or the user manual: online or Info node `(org-remark) Installation’

Getting Started in the user manual will get you started in 5 minutes: online or or Info node `(org-remark) Getting Started’.

For customization, refer to the customization group `org-remark’ or user manual: online or Info node `(org-remark) Customizing’.

An introductory video (8 minutes) is available on YouTube.

[fn:1]: Feature to highlight and annotate websites is new in the latest GNU-devel ELPA and is planned to be part of v1.1.0.

Features

• Highlight and annotate any text file. The highlights and notes are kepted in an Org file as the plain text database. This lets you easily manage your marginal notes and use the built-in Org fecilities on them – e.g. create a sparse tree based on the category of the notes
• Have the same highlighting and annotating functionality for websites when you use EWW to browse them (new in latest GNU-devel ELPA and is planned to be part of v1.1.0.)
• Create your your own highlighter pens with different colors, type (e.g. underline, squiggle, etc. optionally with Org’s category for search and filter on your highlights and notes)

Screenshots and Videos

Figure 1. Left: Org-mode with text enlarged; Right: marginal notes with an inline image. Introductory video (8 minutes) is available on YouTube

Figure 2. Mouse context menu with built-in context-menu-mode available with Emacs version 28 onward

Figure 3. Main notes can be any text files. Left: marginal notes file; Right: an org-remark.el file with a highlight.

Installation

This package is available on:

• GNU-ELPA (releases only; equivalent to MELPA-Stable)
• GNU-devel ELPA (unreleased development branch; equivalent to MELPA)

GNU ELPA should be already set up in your Emacs by default. If you wish to add GNU-devel ELPA, simply add its URL to package-archives like this:

(add-to-list 'package-archives
             '("gnu-devel" . "https://elpa.gnu.org/devel/") :append)

After installation, we suggest you put the setup below in your configuration.

(org-remark-global-tracking-mode +1)

;; Optional if you would like to highlight websites via eww-mode
(with-eval-after-load 'eww
  (org-remark-eww-mode +1))

Unless you explicitly load org during Emacs initialization, I suggest to defer loading org-remark (thus there is no (require 'org-remark) in the example above). This is because it will also pull in org, which can slow down initialization. You can control the timing of loading org-remark by autoloading some commands in a similar way with the example keybindings below.

Below are example keybindings you might like to consider:

;; Key-bind `org-remark-mark' to global-map so that you can call it
;; globally before the library is loaded.

(define-key global-map (kbd "C-c n m") #'org-remark-mark)

;; The rest of keybidings are done only on loading `org-remark'
(with-eval-after-load 'org-remark
  (define-key org-remark-mode-map (kbd "C-c n o") #'org-remark-open)
  (define-key org-remark-mode-map (kbd "C-c n ]") #'org-remark-view-next)
  (define-key org-remark-mode-map (kbd "C-c n [") #'org-remark-view-prev)
  (define-key org-remark-mode-map (kbd "C-c n r") #'org-remark-remove))

Contributing and Feedback

Create issues, discussion, and/or pull requests in the GitHub repository. All welcome.

Org-remark is available on GNU ELPA and thus copyrighted by the Free Software Foundation (FSF). This means that anyone who is making a substantive code contribution will need to “assign the copyright for your contributions to the FSF so that they can be included in GNU Emacs” (Org Mode website).

Thank you.

Contributors

New features

• echo-text update from the marginal notes to the source buffer by marty hiatt (@mooseyboots)
• Support for websites with eww-mode by Vedang Manerikar (@vedang)

Bug fixes

Nan Jun Jie (@nanjj), @sgati-bodhi

Documentation (including README, NEWS, CHANGELOG)

@randomwangran, marty hiatt (@mooseyboots)

All the comments, issues, and questions on GitHub

@randomwangran, @karthink, @holtzermann17, @shombando, @magthe, @linwaytin, @rtrppl, @ryanprior, @ericsfraga, @darcamo, @zhewy, @QMeqGR, @Vidianos-Giannitsis, @AtomicNess123, @mooseyboots, @ouboub, @dian-yu-luo, @SylvianHemus, @basaran, @Ypot, @oatmealm, @sati-bodhi

License

This work is licensed under a GPLv3 license. For a full copy of the license, refer to LICENSE.

Marginal Notes

This section is created by Org-remark for the source file. It serves as an example to illustrate what Org-remark can do.

defmacro org-remark-create

This macro was inspired by Ov-highlight. It’s by John Kitchin (author of Org-ref). Great UX for markers with hydra. Saves the marker info and comments directly within the Org file as Base64 encoded string. It uses overlays with using ov package.