search

nobiot / org-remark

Highlight & annotate text, EWW, Info, and EPUB
https://nobiot.github.io/org-remark/
GNU General Public License v3.0
423 stars 20 forks source link
annotate emacs note-taking org-mode org-roam

readme

+title: README – Org-remark

+options: toc:t creator:nil author:nil broken-links:t

+html: GNU Emacs

+html: GPLv3

+html: GNU ELPA

+html: GNU-devel ELPA

Org-remark lets you highlight and annotate text files, websites, EPUB books and Info documentation with using Org mode.

A user manual is available [[https://nobiot.github.io/org-remark/][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][Installation]] below or the user manual: [[https://nobiot.github.io/org-remark/#Installation][online]] or Info node `(org-remark) Installation'

Getting Started in the user manual will get you started in 5 minutes: [[https://nobiot.github.io/org-remark/#Getting-Started][online]] or or Info node `(org-remark) Getting Started'.

For customization, refer to the customization group org-remark' or user manual: [[https://nobiot.github.io/org-remark/#Customizing][online]] or Info node(org-remark) Customizing'. A [[https://github.com/nobiot/org-remark/tree/main/docs/articles/2023-08-20T184309_C_how-to-set-icons-to-be-svg-images.md][separate online article]] has been written to guide you on how to customize an icon (also part of the user manual. Evaluate (info "(or-gremark) How to Set Org-remark to Use SVG Icons").

An [[https://youtu.be/c8DHrAsFiLc][introductory video]] (8 minutes) and [[https://youtu.be/BTFuS21N00k][V1.1.0 release introduction]] (12 minutes) are available on YouTube.

[[./resources/images/2022-01-22-Title.png]] Figure 1. Left: Org-mode with text enlarged; Right: marginal notes with an inline image. [[https://youtu.be/c8DHrAsFiLc][Introductory video]] (8 minutes) and [[https://youtu.be/BTFuS21N00k][V1.1.0 release introduction]] (12 minutes) are available on YouTube

[[./resources/images/2022-01-22-Context-menu.png]] Figure 2. Mouse context menu with built-in ~context-menu-mode~ available with Emacs version 28 onward

[[./resources/images/2023-08-20-epub-prince-icon.png]] Figure 3. EPUB book ("Prince" by Niccolò Machiavelli via https://www.gutenberg.org/) with icon indicating there are annotations to the highlight: new features with v1.2.0 (2023-08-20). Left: marginal notes file with annotations; Right: an EPUB book file with a highlight and simple ASCII icon.

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:

+BEGIN_SRC elisp

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

+END_SRC

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

+begin_src emacs-lisp

(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))

;; Optional if you would like to highlight EPUB books via nov.el (with-eval-after-load 'nov (org-remark-nov-mode +1))

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

+end_src

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:

+begin_src emacs-lisp

;; 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) (define-key org-remark-mode-map (kbd "C-c n d") #'org-remark-delete))

+end_src

Alternatively, you can use ~use-package~ to set up Org-remark. The example provided below should be equivalent to the setup described above.

+begin_src emacs-lisp

(use-package org-remark :bind (;; :bind keyword also implicitly defers org-remark itself. ;; Keybindings before :map is set for global-map. ("C-c n m" . org-remark-mark) ("C-c n l" . org-remark-mark-line) :map org-remark-mode-map ("C-c n o" . org-remark-open) ("C-c n ]" . org-remark-view-next) ("C-c n [" . org-remark-view-prev) ("C-c n r" . org-remark-remove) ("C-c n d" . org-remark-delete)) ;; Alternative way to enable org-remark-global-tracking-mode' in ;;after-init-hook'. ;; :hook (after-init . org-remark-global-tracking-mode) :init ;; It is recommended that org-remark-global-tracking-mode' be ;; enabled when Emacs initializes. Alternatively, you can put it to ;;after-init-hook' as in the comment above (org-remark-global-tracking-mode +1) :config (use-package org-remark-info :after info :config (org-remark-info-mode +1)) (use-package org-remark-eww :after eww :config (org-remark-eww-mode +1)) (use-package org-remark-nov :after nov :config (org-remark-nov-mode +1)))

+end_src

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 [[http://fsf.org][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" ([[https://orgmode.org/contribute.html#copyright][Org Mode website]]).

Thank you.

New features

Bug fixes

@alan-w-255, Nan Jun Jie (@nanjj), @sgati-bodhi

Documentation (including README, NEWS, CHANGELOG)

@randomwangran, marty hiatt (@mooseyboots), @jsntn

Thank-you to all the comments, issues, and questions on GitHub!

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