To install this package, run in Emacs:
M-x package-install RET org-remark RET
Org-remark lets you highlight and annotate any text file with using Org mode.
A user manual is available online or Emacs in-system as an Info node `(org-remark)': (
C-h i and find the
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.
This package is available on:
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 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).
This work is licensed under a GPLv3 license. For a full copy of the license, refer to LICENSE.
Current - fix: "Wrong type argument: stringp, nil" on highlightintg in scratch Version 1.0.3 - fix #23: "Wrong type argument: stringp, nil" on org export - fix:#22: highlights not found when marginalia does not show all Version 1.0.2 - Update README, user manual, and doc strings in source Version 1.0.1 - Update user manual Version 1.0.0 - chg: align with GNU convention: path -> file name Regarding user option `org-remark-notes-file-path`, the GNU convention is to call this a "file name" rather than a "path"; "path" is only used for lists of directories as in `load-path` (pointed out by Stefan Monnier; thank you). To align with the GNU convention, the following changes are done. Users should not have to change their existing customization as the old names are aliased to the new ones. User option: - org-remark-notes-file-path -> org-remark-notes-file-name - org-remark-source-path-function -> 'org-remark-source-file-name Function: - org-remark-notes-file-path-function -> org-remark-notes-file-name-function Private Function: - org-remark-notes-get-file-path -> org-remark-notes-get-file-name `org-remark-notes-file-path`, `org-remark-source-path-function`, and `org-remark-notes-file-path-function` are used by existing customization, thus both explicitly made obsolete and aliased to the new file-name equivalents. - fix: Relative file name of the source file in the notes file The relative file name of the source was not relative from the marginal notes file but from the source file itself -- this should be relative from the marginal notes. - chg: `org-remark-global-tracking-mode' has been simplified. This is not expected to break the user's workflow or configuration -- simply removing a superfluous feature. .org-remark-tracking file is no longer necessary and can be safely deleted from the user's Emacs configuraiton directory if present. Automatic activation of `org-remark-mode' is done by looking the presence of a marginal notes file for current buffer open. `org-remark-global-tracking-mode' itself is still relevant and recommended to be setup as was previously in the user manual. - add: Option to use relative links from the marginal notes back to the source Adding user option org-remark-source-path-function. The default is file-relative-name. - add: Adding a new option to org-remark-notes-file-path to use a function Its default function is org-remark-notes-file-path-function. It returns a file name like this: "FILE-notes.org" by adding "-notes.org" as a suffix to the file name without the extension. Version 0.2.0 - add: org-remark-delete - rm: Adding Org-ID automatically to file level when file is empty Version 0.1.0 * Features & additions - docs: comprehensive user manual (online - Info to be added on ELPA release) - feat: org-remark-create macro to let users create their own custom pens - feat: minor-mode menu for menu-bar-mode This works as mouse context-menu for the new context-menu-mode (>= Emacs 28) - add: browse-next/prev: move and display next/prev marginal notes at the same time - add: view/open to display side-window by default (user option) - add: org-remark-link property in marginal notes file with ::line-number search option - feat: org-remark-legacy-convert as a separate feature This is for automatically converting legacy Org-marginalia file to Org-remark. - feat: Legacy data facility with org-remark-tracking * Changes - chg: `remove' (and delete) only removes one highlight at a time instead of remove all at point - chg: Save marginal notes on `mark' instead of wainting for `save' ... ...