[This notice written on 18 January 2022]
Happy 2022!
I have changed the name of the project and package to ”Org-remark” from Org-marginalia.
If you are using Org-marginalia now, there are breaking changes. This package includes the feature that automatically converts the old Org-marginalia data into the new Org-remark data. Add org-remark-convert-legacy feature like this:
(require 'org-remark-convert-legacy)This feature is designed to work automatically and transparently to you, meaning you should not have to do anything, as long as you did not customize org-marginala-notes-file-path. If you did, you also need to customize org-remark-notes-file-path. You can also manually do data conversion if you wish. For more detail, refer to the docstring of function org-remark-convert-legacy-data.
Org-remark lets you highlight and annotate any text file with using Org mode.
A user manual is available online (Info node will be available when Org-remark is added to ELPA/MELPA) 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-transclusion’ or user manual: online or Info node `(org-remark) Customizing’.
An introductory video (8 minutes) is available on YouTube.
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.
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.
(require 'org-remark-global-tracking)
(org-remark-global-tracking-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))Create issues, discussion, and/or pull requests in the GitHub repository. All welcome.
Org-remark is planned to be submitted to 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.
This work is licensed under a GPLv3 license. For a full copy of the license, refer to LICENSE.
This section is created by Org-remark for the source file. It serves as an example to illustrate what Org-remark can do.
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.