[elpa] externals/org-remark 60cbbc4e99 083/173: Merge dev/0.0.6-revise

[ELPA Syncer]

branch: externals/org-remark
commit 60cbbc4e99604aed232ed3e812d320b93c300eb4
Merge: 6f1a13dbf1 c1adffe077
Author: Noboru Ota <me@nobiot.com>
Commit: Noboru Ota <me@nobiot.com>

    Merge dev/0.0.6-revise
---
 README.org                             | 192 ++++++++---
 org-marginalia-global-tracking.el      | 114 +++++++
 org-marginalia.el                      | 596 ++++++++++++++++-----------------
 resources/images/2021-08-17T220032.png | Bin 0 -> 320137 bytes
 4 files changed, 556 insertions(+), 346 deletions(-)

diff --git a/README.org b/README.org
index 779e19eccb..079c37998b 100644
--- a/README.org
+++ b/README.org
@@ -18,12 +18,33 @@ Refer to the screenshots below for a teaser of  what it can 
do.
 [[./resources/images/2020-12-22T141331-OM-screen-shot-01.png]]
 *Figure 2*. Left: main note with some text highlighted in green; Right: margin 
notes in a marginalia file
 
-[[./resources/images/2020-12-22T141331-OM-screen-shot-02.png]]
-*Figure 3*. It automatically adds the standard Org Mode link to margin notes, 
so it works well with Org-roam's backlinks
+[[./resources/images/2021-08-17T220032.png]]
+*Figure 3*. It can automatically add links with Org-ID from marginal notes 
back to the main file. This works well with Org-roam's backlink (V2)
 
 [[./resources/images/2020-12-22T141331-OM-screen-shot-03.png]]
 *Figure 4*. Main note can be any text files. Left: an ~.el~ file with a 
highlight; Right: marginalia file
 
+* News
+
+** Support for Org ID and Org-roam
+
+As of 0.0.6, seamless workflow with Org-roam has been added by generating ID 
links automatically.
+
+If user option =org-marginalia-use-org-id= is non-nil (default), 
Org-marginalia will create a link back to the source note with using an Org-ID 
link instead of a
+normal file link.
+
+When a new marginalia file is created and =org-marginalia-use-org-id= is
+non-nil, Org-marginalia will add an ID property to the file level. This is 
mainly to support Org-roam's backlink feature for marginalia files.
+
+** Use of Overlays, no longer Text-Properties
+
+This makes easier to add highlighter overlay on top of text regions that 
already have faces (e.g. syntax-highlighted part of source code)
+
+** Removing limitations
+
+- Now turning off minor mode will turn off the highlights
+  It is still recommended to use =org-marginalia-toggle= to temporarily 
hide/show highlights. This is because turning off =org-marginalia-mode= will 
stop tracking of the locations of highlights in the current buffer. **Any** 
(however minor) change will likely result in mismatching the locations of saved 
highlights and the current buffer's text content.
+
 * Contents                                                         :noexport:
 :PROPERTIES:
 :TOC:      :include siblings
@@ -32,15 +53,19 @@ Refer to the screenshots below for a teaser of  what it can 
do.
 - [[#installation][Installation]]
 - [[#usage][Usage]]
 - [[#customizing][Customizing]]
-- [[#text-properties-not-overlays][Text-properties, Not Overlays]]
 - [[#known-limitations][Known Limitations]]
 - [[#changelog][Changelog]]
 - [[#credits][Credits]]
 - [[#feedback][Feedback]]
 - [[#license][License]]
 - [[#marginalia-for-org-marginaliael][Marginalia for org-marginalia.el]]
-  - [[#org-marginalia-next][org-marginalia-next]]
-  - [[#org-marginalia-mark][org-marginalia-mark]]
+  - [[#deleted-notes][Deleted Notes]]
+  - [[#deleted-notes-on-jit-lock-register][Deleted Notes on jit-lock-register]]
+  - [[#org-marginalia-load][org-marginalia-load]]
+  - [[#set-buffer-modified-p][set-buffer-modified-p]]
+  - [[#overlay-put][overlay-put]]
+  - [[#make-overlay-beg-end-nil-front-advance][(make-overlay beg end nil 
'FRONT-ADVANCE)]]
+- [[#local-variables][Local Variables]]
 :END:
 
 * Installation
@@ -53,36 +78,68 @@ This package is not available on MELPA. Manual installation 
is required.
 
 Ensure to have Org Mode 9.4 or later (tested on 9.4.2). This package uses 
~org-collect-keywords~, which does not exist in an earlier version.
 
-Store =org-marginalia.el= in your load-path, and put this in your init file:
+Store both of the =.el= files in the repo in your load-path, and put this in 
your init file:
 
 #+BEGIN_SRC emacs-lisp
-(require 'org-marginalia)
+  (add-to-list 'load-path "~/local-repos/org-marginalia/")
+  (require 'org-marginalia-global-tracking)
+  (require 'org-marginalia)
 #+END_SRC
 
-For example, I use this in my init file. Org-marginalia is a local minor mode. 
As I want to activate it automatically for all my text-mode files (Org and 
Markdown), I also put ~org-marginalia-mode 1~ in ~text-mode-hook~ like this 
below.
+By loading =org-marginalia=, it will also pull in Org mode. You might like to 
defer loading of Org as it might take long time. As of version 0.0.6, you can 
do so with loading only =org-marginalia-global-tracking=, which does not load 
=org= automatically.
+
+For example, I use this in my init file. 
 
 #+begin_src emacs-lisp
-(add-hook 'after-init-hook (lambda()
-                             (add-to-list 'load-path 
"~/local-repos/org-marginalia/")
-                             (require 'org-marginalia)
-                             (add-hook 'text-mode-hook #'org-marginalia-mode 
1)))
+  ;; Set `load-path'
+  (add-to-list 'load-path "~/local-repos/org-marginalia")
+
+  ;; Load only `org-marginalia-global-tracking'
+  ;; and turn it on for automatic loading of highlights
+  ;; for the files tracked
+  (load-library "org-marginalia-global-tracking")
+  (org-marginalia-global-tracking-mode 1)
+
+  ;; Set keybindings
+  ;; `org-marginalia-mark' is bound to global-map so that you can call it 
globally
+  ;; before the library is loaded; it has autoload cookie
+  (define-key global-map (kbd "C-c m") #'org-marginalia-mark)
+  ;; The rest of keybidings are done only on loading `org-marginalia'
+  (with-eval-after-load 'org-marginalia
+    (define-key org-marginalia-mode-map (kbd "C-c n o") #'org-marginalia-open)
+    (define-key org-marginalia-mode-map (kbd "C-c n ]") #'org-marginalia-next)
+    (define-key org-marginalia-mode-map (kbd "C-c n [") #'org-marginalia-prev)
+    (define-key org-marginalia-mode-map (kbd "C-c n r") 
#'org-marginalia-remove))
 #+end_src
   
 * Usage
 :PROPERTIES:
 :TOC:      :depth 0
 :END:
-
 ** Commands
+
+- =org-marginalia-global-tracking-mode= ::
+A global minor mode to save and track files that have marginal notes.
+When active, visiting a file being tracked automatically turns on 
=org-marginalia-mode=, which loads highlights previously saved in the 
marginalia file.
+
+The files being tracked are saved in =org-marginalia-tracking-file=, which you 
can customize. The default file is named =.org-marginalia-tracking= in your 
Emacs configuration directory (=user-emacs-directory=).
+
 - =org-marginalia-mode= ::
 Org-marginalia is a local minor mode. Toggle it on/off with using 
=org-marginalia-mode=. On activating, it loads your saved highlights from the 
marginalia file (defined by =org-marginalia-notes-file-path=), and enables 
automatic saving of highlights. The automatic saving is achieved via function 
=org-marginalia-save= added to =after-save-hook=.
 
 - =org-marginalia-mark= ::
-Select a region of text, and call =org-marginalia-mark= to highlight the 
region. It will generate a new ID, and start tracking the location -- so you 
can edit text around the highlighted text. Do not cut, copy and paste as the 
highlight will disappear and it is a bit tricky to recover it. To create a new 
margin note entry in the marginalia file, save the buffer.
+Select a region of text, and call =org-marginalia-mark= to highlight the 
region. It will generate a new ID, and start tracking the location -- so you 
can edit text around the highlighted text. Do not cut, copy and paste as the 
highlight will disappear (you can immediately =undo= to recover the text region 
along the highlights). To create a new marginal note entry in the marginalia 
file, save the buffer.
 
 - =org-marginalia-save= ::
 By default, Org-marginalia automatically creates or updates corresponding 
entries in the marginalia file with location and text of highlights on saving 
the buffer. Nevertheless, you can manually call =org-marginalia-save= to do so 
(automatic process also call this command).
 
+If user option =org-marginalia-use-org-id= is non-nil, Org-marginalia will
+create a link back to the source note with using an Org-ID link instead of a
+normal file link.
+
+When a new marginalia file is created and =org-marginalia-use-org-id= is
+non-nil, Org-marginalia will add an ID property to the file level. This is 
mainly to support Org-roam's backlink feature for marginalia files.
+
 - =org-marginalia-open= ::
 Move your cursor on the highlighted text, and call =org-marginalia-open= to 
open the relevant margin notes in a separate window. Your cursor will move to 
the marginalia buffer narrowed to the relevant margin notes entry. You can edit 
the marginalia buffer as a normal Org buffer. Once you have done editing, you 
may simply save and close the it (kill it or close the window) as per your 
normal workflow. Technically, the marginalia buffer is a cloned indirect buffer 
of the marginalia file. 
 
@@ -165,18 +222,18 @@ I will try to incorporate these into the package when I 
have more time to focus
 - You can customize settings in the =org-marginalia= group.
 - Highlight's face can be changed via =org-marginalia-highlighter=
 - Marginalia file is defined by =org-marginalia-notes-file-path=
-
-* Text-properties, Not Overlays
-
-Technically, Org-marginalia implements the highlighting feature solely with 
text properties, and avoids overlays. This is done in light of oft-mentioned 
performance degradation with the latter.
-
-Personally I have never experienced such performance issues with overlays; 
nevertheless, given that we might have many highlighted text regions in a 
single file, I thought I would take this as an opportunity to take advantage of 
text properties.
+- Your files with marginal notes are saved and tracked in
+  =org-marginalia-tracking-file= (when tracking is turned on via the global
+  minor mode =org-marginalia-global-tracking-mode=)
+- You can use Org-ID to create links from marginal notes back to their main
+  notes when =org-marginalia-use-org-id= is on (default is on). This option 
also enables Org-marginalia to add an ID property when a new marginalia file is 
being created. This is to support seamless workflow with 
[[https://orgroam.com][Org-roam]].
 
 * Known Limitations
 
-- Turning off minor mode does not turn off the highlights :: This should not 
do any harm, but if you are distracted, kill the buffer (not revert) and visit 
it again. Toggling show/hide of highlights is something I would like to add 
later.
-- Copy & pasting loses highlights :: You could manually recover it by 
adjusting the properties in the margin notes file.
-- Undo highlight does not undo it :: Highlight a region of text with 
=org-marginalia-mark= and immediately undo it. The highlight disappears, but it 
is still being tracked with =org-marginalia-highlights=.
+- Copy & pasting loses highlights :: Overlays are not part of the kill; thus 
cannot be yanked.
+  
+- Undo highlight does not undo it :: Overlays are not part of the undo list; 
you cannot undo highlighting. Use =org-marginalia-remove= command instead.
+  
 - Moving source files and marginalia file :: Move your files and marginalia 
file to another directory does not update the source path recorded in the 
marginalia file. It will be confusing. Try not to do this.
 
 * Changelog
@@ -184,8 +241,24 @@ Personally I have never experienced such performance 
issues with overlays; never
 :TOC:      :depth 0
 :END:
 
-** Curent; WIP
-- fix: Add highlighter face def for termianl
+** 0.0.6
+
+Feature:
+- feat: Add =org-marginalia-global-tracking-mode= with a separate .el file
+- feat: Use Org-ID to create a link from the marginal notes back to the main 
file
+  Add Customizable variable =org-marginalia-use-org-id=; default is =t=
+
+Change:
+- chg: Highlights are now overlay; no longer text-properties
+  
+Improvement to existing functions
+- add: Deactivate mark after highlighting
+- add: org-marginalia-remove can take C-u to delete
+
+Fix & Internal Refactor
+- intrnl: Add housekeeping for =org-marginalia-highlights= variable
+- fix: org-id-uuid is not found
+- fix: Add highlighter face def for terminal
 
 ** 0.0.5
 - break: Replace the prefix "om/" in the source code with "org-marginalia"
@@ -242,23 +315,13 @@ This work is licensed under a GPLv3 license. For a full 
copy of the licese, refe
 :END:
 This section is used as a demonstration and a collection of my ideas for this 
package.
 
-** org-marginalia-next
-:PROPERTIES:
-:marginalia-id: 0dba860c
-:marginalia-source-beg: 17029
-:marginalia-source-end: 17048
-:END:
-[[file:~/local-repos/org-marginalia/org-marginalia.el][org-marginalia]]
+** Deleted Notes
 
 I need to think it through.
 Do I want to reveal invisible elments to move, or keep it hidden.
 At the moment, ~om/list-highlights-positions~ has been changed to return 
beginning points of visible ones only -- this can be changed to make it 
opsitonal arg. For example, if I want to list *all*, including the hidden ones, 
do I want to just visible ones?
 
-** org-marginalia-mark
-:PROPERTIES:
-:marginalia-id: b3c8f14e
-:marginalia-source-beg: 9873
-:marginalia-source-end: 9892
+** Deleted Notes on jit-lock-register
 :END:
 [[file:~/local-repos/org-marginalia/org-marginalia.el][org-marginalia]]
 
@@ -295,9 +358,62 @@ jit-lock-register
         (font-lock-unfontify-region beg end))))
 #+end_src
 
+** org-marginalia-load
+:PROPERTIES:
+:marginalia-id: 3ed4316a
+:marginalia-source-beg: 7324
+:marginalia-source-end: 7343
+:END:
+[[file:~/local-repos/org-marginalia/org-marginalia.el][org-marginalia]]
 
 
-* COMMENT Local Variables
+** set-buffer-modified-p
+:PROPERTIES:
+:marginalia-id: 275b8a06
+:marginalia-source-beg: 7203
+:marginalia-source-end: 7224
+:END:
+[[file:~/local-repos/org-marginalia/org-marginalia.el][org-marginalia]]
+
+Adding overlay does not set the buffer modified.
+It's more fluid with save operation.
+You cannot use `undo' to undo highlighter.
+
+** overlay-put
+:PROPERTIES:
+:marginalia-id: 44c310d9
+:marginalia-source-beg: 6461
+:marginalia-source-end: 6472
+:END:
+[[file:~/local-repos/org-marginalia/org-marginalia.el][org-marginalia]]
+
+Do not add the =evaporate t= property for the highlight's overlay. By 
remaining in the buffer, =undo= puts overlays in their original location when 
text regions get killed and subsequently the kill gets undone.
+
+Using overlays instead of text-properties has an advantage of easy composition 
of faces; e.g. when marking on a comment line in =emacs-lisp-mode=, the 
highlighters face won't be composed onto the underlying syntax face for 
comments. Overlay can make it easy to add an additional face to comments and 
other syntactically font-locked regions.
+** (make-overlay beg end nil 'FRONT-ADVANCE)
+:PROPERTIES:
+:marginalia-id: 3ec6b5e6
+:marginalia-source-beg: 6411
+:marginalia-source-end: 6452
+:END:
+[[file:~/local-repos/org-marginalia/org-marginalia.el][org-marginalia]]
+
+It's more intuitive if editing the text both on the beg and end points of the 
highlight overlay does not extend it. Pass FRONT-ADVANCE; keep REAR-ADVANCE as 
default.
+
+#+ref: Manual (elisp)Manging Overlays
+#+begin_quote
+     The arguments FRONT-ADVANCE and REAR-ADVANCE specify the marker
+     insertion type for the start of the overlay and for the end of the
+     overlay, respectively.  *Note Marker Insertion Types::.  If they
+     are both ‘nil’, the default, then the overlay extends to include
+     any text inserted at the beginning, but not text inserted at the
+     end.  If FRONT-ADVANCE is non-‘nil’, text inserted at the beginning
+     of the overlay is excluded from the overlay.  If REAR-ADVANCE is
+     non-‘nil’, text inserted at the end of the overlay is included in
+     the overlay.
+#+end_quote
+
+* Local Variables
 
 # Local Variables:
 # eval: (require 'org-make-toc)
diff --git a/org-marginalia-global-tracking.el 
b/org-marginalia-global-tracking.el
new file mode 100644
index 0000000000..330d7799ed
--- /dev/null
+++ b/org-marginalia-global-tracking.el
@@ -0,0 +1,114 @@
+;;; org-marginalia-global-tracking.el --- Track files with marginal notes -*- 
lexical-binding: t; -*-
+
+;; Copyright (C) 2020 Noboru Ota
+
+;; Author: Noboru Ota <me@nobiot.com>
+;; URL: https://github.com/nobiot/org-marginalia
+;; Version: 0.0.6
+;; Last Modified: 2021-08-18
+;; Package-Requires: ((emacs "27.1") (org "9.4"))
+;; Keywords: org-mode, annotation, writing, note-taking, margin-notes
+
+;; This file is not part of GNU Emacs.
+
+;; This program is free software; you can redistribute it and/or modify
+;; it under the terms of the GNU General Public License as published by
+;; the Free Software Foundation, either version 3 of the License, or
+;; (at your option) any later version.
+
+;; This program is distributed in the hope that it will be useful,
+;; but WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+;; GNU General Public License for more details.
+
+;; You should have received a copy of the GNU General Public License
+;; along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+;;; Commentary:
+;;  This file is part of Org-marginalia
+
+;;; Code:
+
+(declare-function org-marginalia-mode 'org-marginalia)
+
+(defgroup org-marginalia-global-tracking nil
+  "Write margin notes (marginalia) for any text file in a
+separate Org file"
+  :group 'org-marginalia
+  :prefix "org-marginalia-"
+  :link '(url-link :tag "Github" "https://github.com/nobiot/org-marginalia";))
+
+(defcustom org-marginalia-tracking-file
+  (locate-user-emacs-file ".org-marginalia-tracking" nil)
+  "File name where the files `org-marginalia' tracks is saved.
+When `org-marginalia-global-tracking-mode' is active, opening a file
+saved in `org-marginalia-tracking-file' automatically loads highlights."
+  :group 'org-marginalia-global-tracking
+  :type 'file)
+
+(defvar org-marginalia-tracking-file-loaded nil)
+
+(defvar org-marginalia-files-tracked nil)
+
+;;;###autoload
+(define-minor-mode org-marginalia-global-tracking-mode
+  "Global mode. When enabled, check files saved in
+`org-marginalia-tracking-file' and opening them automatically
+activates `org-marginalia-mode' locally for the file opened."
+  :init-value nil
+  :lighter " marginalia-tracking"
+  :global t
+  (cond
+   (org-marginalia-global-tracking-mode
+    ;; Activate
+    (when (and (not org-marginalia-tracking-file-loaded)
+              (file-exists-p org-marginalia-tracking-file))
+      (org-marginalia-tracking-load))
+    (add-hook 'find-file-hook #'org-marginalia-tracking-auto-on)
+    (add-hook 'kill-emacs-hook #'org-marginalia-tracking-save))
+   (t
+    ;; Deactivate
+    (setq org-marginalia-files-tracked nil)
+    (setq org-marginalia-tracking-file-loaded nil)
+    (remove-hook 'find-file-hook #'org-marginalia-tracking-auto-on)
+    (remove-hook 'kill-emacs-hook #'org-marginalia-tracking-save))))
+
+;;;; Private Functions
+
+(defun org-marginalia-tracking-auto-on ()
+  "Activate `org-marginalia-mode' when file is being tracked.
+The files being tracked are loaded on to
+`org-marginalia-files-tracked'.  Refer to
+`org-marginalia-tracking-load'."
+  (when (and org-marginalia-files-tracked
+            (member (abbreviate-file-name (buffer-file-name))
+                    org-marginalia-files-tracked))
+    (unless (featurep 'org-marginalia) (require 'org-marginalia))
+    (org-marginalia-mode +1)))
+
+(defun org-marginalia-tracking-load ()
+  "Load files being tracked from `org-marginalia-tracking-file'.
+It has one filename each line.  The filename is obtrained
+`abbreviated-file-names'.  This function reloads the content of
+the file regardless if it is already done in this Emacs session
+or not."
+  (with-temp-buffer
+    (condition-case nil
+       (progn
+         (insert-file-contents org-marginalia-tracking-file)
+         (setq org-marginalia-files-tracked
+               (split-string (buffer-string) "\n"))
+          (setq org-marginalia-tracking-file-loaded t)))))
+
+(defun org-marginalia-tracking-save ()
+  "Save files being tracked in `org-marginalia-tracking-file'.
+Files with marginal notes are tracked with variable
+`org-marginalia-files-tracked'."
+  (interactive)
+  (when org-marginalia-files-tracked
+    (with-temp-file org-marginalia-tracking-file
+      (insert (mapconcat 'identity org-marginalia-files-tracked "\n")))))
+
+(provide 'org-marginalia-global-tracking)
+
+;;; org-marginalia-global-tracking.el ends here
diff --git a/org-marginalia.el b/org-marginalia.el
index 8706e3e78f..0140da0bed 100644
--- a/org-marginalia.el
+++ b/org-marginalia.el
@@ -1,11 +1,11 @@
-;;; org-marginalia.el --- Highlight text, write margin notes for any text file 
in Org Mode  -*- lexical-binding: t; -*-
+;;; org-marginalia.el --- highlight & annotate       -*- lexical-binding: t; 
-*-
 
 ;; Copyright (C) 2020 Noboru Ota
 
 ;; Author: Noboru Ota <me@nobiot.com>
 ;; URL: https://github.com/nobiot/org-marginalia
-;; Version: 0.0.5
-;; Last Modified: 2021-01-05
+;; Version: 0.0.6
+;; Last Modified: 2021-08-18
 ;; Package-Requires: ((emacs "27.1") (org "9.4"))
 ;; Keywords: org-mode, annotation, writing, note-taking, margin-notes
 
@@ -29,140 +29,7 @@
 ;; This package lets you write margin notes (marginalia) for any text file in
 ;; a separate Org file.
 
-;;;; Installation
-
-;;;;; MELPA
-
-;; This package is not available on MELPA. Manual installation required.
-
-;;;;; Manual
-
-;; Install these required packages:
-
-;; Ensure to have Org Mode 9.4 or later (tested on 9.4).  This package uses
-;; `org-collect-keywords', which does not exist in an earlier version.
-
-;; Then put this file in your load-path, and put this in your init
-;; file:
-;; (require 'org-marginalia)
-
-;;;; Usage
-
-;; - `org-marginalia-mode' ::
-;; Org-marginalia is a local minor mode. Toggle it on/off with using
-;; `org-marginalia-mode'. On activating, it loads your saved highlighters from
-;; the marginalia file, and enables automatic saving of highlighters. The
-;; automatic saving is achieved via function `org-marginalia-save' added to
-;; `after-save-hook'.
-
-;; - `org-marginalia-mark' (C-c n m by default) ::
-;; Select a region of text, and call `org-marginalia-mark' (bound to C-c n m 
by default)
-;; to highlight the region. It will generate a new ID, and start tracking the
-;; location -- so you can edit text around the marked text. Do not copy and
-;; paste as it will disappear and it is a bit tricky to recover the
-;; highlighter. To create a new margin note entry in themarginalia file, save 
the buffer.
-
-;; - `org-marginalia-save' ::
-;; By default, Org-marginalia creates or updates the highlighter's location
-;; and text inside automatically in the marginalia file. You can manually call
-;; `org-marginalia-save' to manually do it (automatic process also call this 
command).
-
-;; - `org-marginalia-open' (C-c o by default) ::
-;; Move your cursor on the highlighted text, and call `org-marginalia-open' to 
open the
-;; relevant margin notes in a separate window. Your cursor should move to the
-;; marginalia buffer narrowed to the relevant margin notes entry. You can edit
-;; the margin notes as a normal Org file. Once you have done editing, you can
-;; simply save and close the buffer (kill or close the window) as per your
-;; normal workflow. Technically, the marginalia buffer is a cloned indirect
-;; buffer of the marginalia file.
-
-;; - `org-marginalia-load' ::
-;; This command open the marginalia file and load the saved highlights onto
-;; current buffer. If there is no margin notes for it, it will output a
-;; message in the echo. Highlights tracked locally by this packages cannot
-;; persist when you kill the buffer, or quit Emacs. When you re-launch Emacs,
-;; ensure to turn on `org-marginalia-mode' to load the highlights. Load is
-;; automatically done when you activate the minor mode.
-
-;; - `org-marginalia-remove' ::
-;; This command removes the highlight at point. It will remove the highlight,
-;; and remove the properties from the marginalia, but will keep the headline
-;; and notes in tact.
-;;
-;; You can pass a universal argument with
-;; \\[universal-argument] (ARG). If this is the case, the command
-;; additionally deletes the entire heading subtree, along with the
-;; notes you have written, for the highlight."
-
-
-;; - `org-marginalia-next' (C-c n ] by default) ::
-;; Move to the next highlight if any. If there is none below the cursor, and
-;; there is a highlight above, loop back to the top one.
-
-;; If the point has moved to the next highlight, this function enables
-;; transient map with `set-transient-map'. You don't have to press the
-;; keybinding prefix again to move further to the next. That is, you can do a
-;; key sequence like this (assuming `org-marginalia-next' is bound to C-c n):
-
-;;   C-c n ] ] ] ]
-
-;; If you have the same prefix for `org-marginalia-prev', you can combine it 
in the
-;; sequence like so:
-
-;;  C-c n ] ] [ [
-;;  This lets your cursor back to where you started (next next prev prev)
-
-;; - `org-marginalia-prev' (C-c n [ by default) :: Move to the previous 
highlight if any.
-;; If there is none above the cursor, and there is a highlight below, loop
-;; back to the bottom one. This function enables transient map. See 
`org-marginalia-next'
-;; for detail.
-
-;; - `org-marginalia-toggle' ::
-;; Toggle showing/hiding of highlighters in current buffer. It only affects
-;; the display of the highlighters. When hidden, highlights' locations are
-;; still kept tracked; thus, upon buffer-save the correct locations are still
-;; recorded in the marginalia file.
-
-;;;; Customizing
-
-;; - Highlighter face can be changed via `org-marginalia-highlighter'
-;; - Marginalia file is defined with `org-marginalia-notes-file-path'
-
-;;;; Known Limitations
-
-;; - Turning off minor mode does not turn off the highlighters
-;;   This should not do any harm, but if you are distracted, kill the buffer
-;;   (not revert) and visit it again. Toggling show/hide of highlighters is
-;;   something I - would like to add later.
-
-;; - Copy & pasting loses highlights
-;;   You could mqanually recover it by adjusting the properties in the
-;;   marginalia file.
-
-;;;; Credits
-
-;; To create this package, I was inspired by the following packages. I did not
-;; copy any part of them, but borrowed some ideas from them -- e.g. saving the
-;; margin notes in a separate file.
-
-;; - [[https://github.com/jkitchin/ov-highlight][ov-highlight]]
-;;   John Kitchin's (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.
-
-;; - [[https://github.com/bastibe/annotate.el][Annotate.el]]
-;;   Bastian Bechtold's (author of Org-journal). Unique display of annotations
-;;   right next to (or on top of) the text. It seems to be designed for very
-;;   short annotations, and perhaps for code review (programming practice); I
-;;   have seen recent issues reported when used with variable-pitch fonts
-;;   (prose).
-
-;; - 
[[https://github.com/tkf/org-mode/blob/master/contrib/lisp/org-annotate-file.el][Org-annotate-file]]
-;;   Part of Org's contrib library. It seems to be designed to annotate a
-;;   whole file in a separate Org file, rather than specific text items
-
-;; - [[https://github.com/IdoMagal/ipa.el][InPlaceAnnotations (ipa-mode)]]
-;;   It looks similar to Annotate.el above
+;; Refer to README.org and docstring of variables and functions.
 
 ;;; Code:
 
@@ -170,6 +37,7 @@
 
 (require 'org)
 (require 'org-id)
+(require 'org-marginalia-global-tracking)
 (declare-function org-collect-keywords 'org)
 
 ;;;; Customization
@@ -195,17 +63,22 @@ separate Org file"
   "Specify the file path for the marginalia.org file.
 The default is \"./marginalia.org\", thus one marginalia file per directory.
 Ensure that it is an Org file."
-  :type 'string
+  :type 'file
+  :group 'org-marginalia)
+
+(defcustom org-marginalia-use-org-id t
+  "Define if Org-marginalia use Org-ID to link back to the main note."
+  :type 'boolean
   :group 'org-marginalia)
 
 ;;;; Variables
 
+(defvar-local org-marginalia-loaded nil)
+
 (defvar-local org-marginalia-highlights '()
   "Keep track of all the highlights.
-It is a local variable, and is a list of multiple highlights.
-Each highlight is an alist of this structure:
-
-   (id beg-marker . end-marker)
+It is a local variable and is a list of multiple highlights.
+Each element is an overlay representing a highlighted text region.
 
 On save-buffer each highlight will be persisted in the marginalia file
 (defined by `org-marginalia-notes-file-path').")
@@ -225,18 +98,33 @@ It is meant to exist only one of these in each Emacs 
session.")
 ;;;###autoload
 (define-minor-mode org-marginalia-mode
     "Highlight text, write margin notes for any text file in Org Mode.
+This is a local minor-mode.
+
+On activation, it loads your saved highlights from the marginalia
+file and enables automatic saving of highlights.
 
-This command toggles Org-marginalia local minor mode. On
-activation, it loads your saved highlights from the marginalia
-file, and enables automatic saving of highlights.
+The automatic saving is achieved via function
+`org-marginalia-save' added to `after-save-hook'.
 
-The automatic saving is achieved via function `org-marginalia-save' added
-to `after-save-hook'.
+On deactivation, it removes all the overlays and stops tracking
+the highlights in this buffer by setting variable
+`org-marginalia-highlights' to nil. Be careful of behavior, if
+you still wish to retain the locations of highlights.
 
-Interactively with no argument, this command toggles the mode. A
-positive prefix argument enables the mode, any other prefix
-argument disables it. From Lisp, argument omitted or nil enables
-the mode, `toggle' toggles the state.
+It is recommended to use `org-marginalia-toggle' if you wish to
+temporarily hide highlights in the current buffer. It keeps
+`org-marginalia-highlights' unchanged.
+
+While the tracking of highlights is stopped,
+editing the buffer will likely result in mismatch between the
+saved highlights' locations and the current buffer's text
+content.
+
+Highlights tracked by variable `org-marginalia-highlights' cannot
+persist when you kill the buffer or quit Emacs. When you
+re-launch Emacs and visit the same file, ensure to turn on
+`org-marginalia-mode' to load the highlights from the marginalia
+file. `org-marginalia-global-tracking-mode' can automate this.
 
 \\{org-marginalia-mode-map}"
     :init-value nil
@@ -248,46 +136,119 @@ the mode, `toggle' toggles the state.
      (org-marginalia-mode
       ;; Activate
       (org-marginalia-load)
-      (add-hook 'after-save-hook #'org-marginalia-save nil t))
+      (add-hook 'after-save-hook #'org-marginalia-save nil t)
+      (add-hook 'kill-buffer-hook #'org-marginalia-tracking-save nil t))
      (t
       ;; Deactivate
-      (remove-hook 'after-save-hook #'org-marginalia-save t))))
+      (when org-marginalia-highlights
+       (dolist (highlight org-marginalia-highlights)
+         (delete-overlay highlight)))
+      (setq org-marginalia-highlights nil)
+      (setq org-marginalia-loaded nil)
+      (org-marginalia-tracking-save)
+      (remove-hook 'after-save-hook #'org-marginalia-save t)
+      (remove-hook 'kill-buffer-hook #'org-marginalia-tracking-save t))))
 
 ;;;###autoload
 (defun org-marginalia-mark (beg end &optional id)
   "Highlight the selected region (BEG and END).
 When used interactively. it will generate a new ID, always
 assuming it is a new highlighted text region, and start tracking
-the higlight's location, so that you can edit the text around.
+the highlight's location, so that you can edit the text around.
 
-It will not create a marginalia entry yet. Call `org-marginalia-save' to
-create a new entry (it is automatic with `after-save-hook').
+It will not create a marginalia entry yet. Save the current
+buffer or call `org-marginalia-save' to create a new entry (it is
+automatic with `after-save-hook').
 
 When this function is called from Elisp, ID can be optionally
 passed. If so, no new ID gets generated.
 
-Every highlighted texts in the local buffer is tracked by
-`org-marginalia-highlights' local variable. The highlght is sorted by the
-beginning point in the ascending; this is useful for `org-marginalia-next'
-and `org-marginalia-prev'."
+Every highlighted text region in the current buffer is tracked by
+local variable `org-marginalia-highlights'. The highlights are
+sorted in the ascending order; this is a property of the variable
+used for `org-marginalia-next' and `org-marginalia-prev'."
   (interactive "r")
+  ;; Ensure to turn on the local minor mode
+  (unless org-marginalia-mode (org-marginalia-mode +1))
   ;; UUID is too long; does not have to be the full length
   (when (not id) (setq id (substring (org-id-uuid) 0 8)))
   ;; Add highlight to the text
   (org-with-wide-buffer
-   (add-text-properties beg end '(font-lock-face org-marginalia-highlighter))
-   (add-text-properties beg end (list 'org-marginalia-id id)))
-  ;; Keep track in a local variable It's alist; don't forget the dot
-  ;;   (beg . end)
-  ;; The dot "." is imporant to make the car/cdr "getter" interface clean.
-  ;; Also, `set-marker-insertion-type' to set the type t is necessary to move
-  ;; the cursor in sync with the font-lock-face property of the text property.
-  (push (cons id
-          (cons (org-marginalia-make-highlight-marker beg) 
(org-marginalia-make-highlight-marker end)))
-        org-marginalia-highlights)
+   (let ((ov (make-overlay beg end nil 'FRONT-ADVANCE)))
+     (overlay-put ov 'face 'org-marginalia-highlighter)
+     (overlay-put ov 'org-marginalia-id id)
+     ;; Keep track it in a local variable. It's a list overlays, guranteed to
+     ;; contain only marginalia overlays as opposed to the one returned by
+     ;; `overlay-lists'
+
+     ;; TODO Do we need to consider this for overlay?
+     ;; `set-marker-insertion-type' to
+     ;; set the type t is necessary to move the cursor in sync with the
+     ;; font-lock-face property of the text property.
+     (push ov org-marginalia-highlights)
+     ;; Adding overlay does not set the buffer modified.
+     ;; It's more fluid with save operation.
+     ;; You cannot use `undo' to undo highlighter.
+     (deactivate-mark)
+     (unless (buffer-modified-p) (set-buffer-modified-p t))))
+  (org-marginalia-housekeep)
   (org-marginalia-sort-highlights-list))
 
 ;;;###autoload
+(defun org-marginalia-load ()
+  "Open the marginalia file and load the saved highlights onto current buffer.
+If there is no margin notes for it, it will output a message in
+the echo.
+
+Highlights tracked locally by variable
+`org-marginalia-highlights' cannot persist when you kill the
+buffer or quit Emacs. When you re-launch Emacs, ensure to turn on
+`org-marginalia-mode' to load the highlights.
+`org-marginalia-global-tracking-mode' can automate this."
+  (interactive)
+  ;; Open the marginalia file
+  ;; Read all the positions
+  (unless org-marginalia-mode (org-marginalia-mode +1))
+  (unless org-marginalia-loaded
+    (when-let* ((filename (buffer-file-name))
+               (margin-buf (find-file-noselect org-marginalia-notes-file-path))
+               (source-path (abbreviate-file-name filename)))
+      ;; Get hilights: each highlighlight is stored as an alist
+      ;; (id beg . end)
+      ;; TODO check if there is any relevant notes for the current file
+      (let ((highlights '()))
+       (with-current-buffer margin-buf
+          (org-with-wide-buffer
+           (let ((heading (org-find-property
+                          org-marginalia-prop-source-file source-path)))
+             (if (not heading)
+                (message "No marginalia written for %s." source-path)
+               (goto-char (org-find-property
+                          org-marginalia-prop-source-file source-path))
+               ;; Narrow to only subtree for a single file
+               ;; `org-find-property' ensures that it is the beginning of H1
+               (org-narrow-to-subtree)
+               ;; It's important that the headline levels are fixed
+               ;; H1: File
+               ;; H2: Higlighted region (each one has a dedicated H2 subtree)
+               (while (not (org-next-visible-heading 1))
+                (when-let ((id (org-entry-get (point) "marginalia-id"))
+                            (beg (string-to-number
+                                 (org-entry-get (point)
+                                                "marginalia-source-beg")))
+                            (end (string-to-number
+                                 (org-entry-get (point)
+                                                "marginalia-source-end"))))
+                   (push (cons id (cons beg end)) highlights)))))))
+       ;; Back to the current buffer
+       ;; Look highilights and add highlights to the current buffer
+       (dolist (highlight highlights)
+          (let ((id (car highlight))
+               (beg (car (cdr highlight)))
+               (end (cdr (cdr highlight))))
+            (org-marginalia-mark beg end id)))))
+    (setq org-marginalia-loaded t)))
+
 (defun org-marginalia-save ()
   "Save all the highlights tracked in current buffer to marginalia file.
 The marginalia file is defined in `org-marginalia-notes-file-path' variable.
@@ -297,18 +258,25 @@ achieved via `after-save-hook' (added via 
`org-marginalia-mode' when you
 activate the minor mode).
 
 `org-marginalia-highlights' is the local variable that tracks every highlight
-in the current buffer. Each highlight is represented by this data structure:
+in the current buffer. Each highlight is represented by an overlay."
 
-   (id beg-marker . end-marker)"
   (interactive)
   (let* ((filename (buffer-file-name))
          (source-path (abbreviate-file-name filename))
-         (title (or (car (cdr (assoc "TITLE" (org-collect-keywords 
'("TITLE")))))
-                    (file-name-sans-extension (file-name-nondirectory 
(buffer-file-name))))))
-    (dolist (highlight org-marginalia-highlights)
-      (org-marginalia-save-single-highlight highlight title source-path))))
+         (title (or (cadr (assoc "TITLE" (org-collect-keywords '("TITLE"))))
+                    (file-name-sans-extension
+                    (file-name-nondirectory (buffer-file-name))))))
+    (org-marginalia-housekeep)
+    (org-marginalia-sort-highlights-list)
+    (dolist (h org-marginalia-highlights)
+      (let ((orgid (and org-marginalia-use-org-id
+                       (org-entry-get (overlay-start h) "ID" 'INHERIT))))
+       (org-marginalia-save-single-highlight h title source-path orgid)))
+    ;; Tracking
+    (when org-marginalia-files-tracked
+      (add-to-list 'org-marginalia-files-tracked
+                  (abbreviate-file-name (buffer-file-name))))))
 
-;;;###autoload
 (defun org-marginalia-open (point)
   "Open the margin notes at POINT, narrowed to the relevant headline.
 It creates a cloned indirect buffer of the marginalia file
@@ -323,7 +291,8 @@ tracking it."
     (kill-buffer org-marginalia-last-notes-buffer))
   (when-let ((id (get-char-property point 'org-marginalia-id))
              (ibuf (make-indirect-buffer
-                   (find-file-noselect org-marginalia-notes-file-path) 
"*marginalia*" 'clone)))
+                    (find-file-noselect org-marginalia-notes-file-path)
+                   "*marginalia*" 'clone)))
     (setq org-marginalia-last-notes-buffer ibuf)
     (org-switch-to-buffer-other-window ibuf)
     (widen)(goto-char (point-min))
@@ -331,101 +300,48 @@ tracking it."
       (goto-char (org-find-property org-marginalia-prop-id id))
       (org-narrow-to-subtree))))
 
-;;;###autoload
-(defun org-marginalia-load ()
-  "Open the marginalia file and load the saved highlights onto current buffer.
-If there is no margin notes for it, it will output a message in
-the echo.
-
-Highlights tracked locally by this packages cannot persist when
-you kill the buffer, or quit Emacs. When you re-launch Emacs,
-ensure to turn on `org-marginalia-mode' to load the highlights.
-Load is automatically done when you activate the minor mode."
-  (interactive)
-  ;; Open the marginalia file
-  ;; Read all the positions
-  (when-let* ((filename (buffer-file-name))
-              (margin-buf (find-file-noselect org-marginalia-notes-file-path))
-              (source-path (abbreviate-file-name filename)))
-    ;; Get hilights: each highlighlight is stored as an alist
-    ;; (id beg . end)
-    ;; TODO check if there is any relevant notes for the current file
-    (let ((highlights '()))
-      (with-current-buffer margin-buf
-        (org-with-wide-buffer
-         (let ((heading (org-find-property org-marginalia-prop-source-file 
source-path)))
-           (if (not heading) (message "No marginalia written for %s." 
source-path)
-             (goto-char (org-find-property org-marginalia-prop-source-file 
source-path))
-             ;; Narrow to only subtree for a single file
-             ;; `org-find-property' ensures that it is the beginning of H1
-             (org-narrow-to-subtree)
-             ;; It's important that the headline levels are fixed
-             ;; H1: File
-             ;; H2: Higlighted region (each one has a dedicated H2 subtree)
-             (while (not (org-next-visible-heading 1))
-               (when-let ((id (car (org--property-local-values "marginalia-id" 
nil)))
-                          (beg (string-to-number (car 
(org--property-local-values "marginalia-source-beg" nil))))
-                          (end (string-to-number (car 
(org--property-local-values "marginalia-source-end" nil)))))
-                 (push (cons id (cons beg end)) highlights)))))))
-      ;; Back to the current buffer
-      ;; Look highilights and add highlights to the current buffer
-      (dolist (highlight highlights)
-        (let ((id (car highlight))
-              (beg (car (cdr highlight)))
-              (end (cdr (cdr highlight))))
-          (org-marginalia-mark beg end id))))))
-
-;;;###autoload
 (defun org-marginalia-remove (point &optional arg)
   "Remove the highlight at POINT.
-It will remove the highlight, and remove the properties from the
-marginalia, but will keep the headline and notes.
-
-You can pass a universal argument with
-\\[universal-argument] (ARG). If this is the case, the command
-additionally deletes the entire heading subtree, along with the
-notes you have written, for the highlight."
+It will remove the highlight and the properties from the
+marginalia, but will keep the headline and notes. This is to
+ensure to keep any notes you might have written intact.
+
+You can let this command delete the entire heading subtree, along
+with the notes you have written, for the highlight by pass a
+universal argument with \\[universal-argument] (ARG). If you have
+done so by error, you could still `undo' it in the marginalia
+buffer"
   (interactive "d\nP")
-  (when-let* ((id (get-char-property point 'org-marginalia-id))
-              (mks (cdr (assoc id org-marginalia-highlights))))
-    ;; Remove the highlight text prop and id
-    (remove-list-of-text-properties (marker-position (car mks))
-                                   (marker-position (cdr mks))
-                                   '(org-marginalia-id font-lock-face))
-    ;; Remove the element in the variable org-marginalia-highlights
-    (setq org-marginalia-highlights (assoc-delete-all id 
org-marginalia-highlights))
+  ;; TODO There may be multple overlays
+  (when-let* ((id (get-char-property point 'org-marginalia-id)))
+    ;; Remove the highlight overlay and id
+    (dolist (ov (overlays-at (point)))
+      ;; Remove the element in the variable org-marginalia-highlights
+      (when (overlay-get ov 'org-marginalia-id)
+       (delete ov org-marginalia-highlights)
+       (delete-overlay ov)))
     (org-marginalia-sort-highlights-list)
     ;; Update the marginalia note file accordingly
-    (with-current-buffer (find-file-noselect org-marginalia-notes-file-path)
-      (org-with-wide-buffer
-       (when-let ((id-headline (org-find-property org-marginalia-prop-id id)))
-         (goto-char id-headline)
-        (org-narrow-to-subtree)
-         (org-delete-property org-marginalia-prop-id)
-         (org-delete-property org-marginalia-prop-source-beg)
-         (org-delete-property org-marginalia-prop-source-end)
-         (when arg
-           ;; TODO I would love to add the y-n prompt if there is any notes 
written
-           (delete-region (point-min)(point-max))
-           (message "Deleted the marginal notes.")))))
+    (org-marginalia-remove-marginalia id arg)
     t))
 
 (defun org-marginalia-next ()
-  "Look at the current point, and move to the next highlight, if any.
-If there is none below the point, but there is a highlight in the
+  "Look at the current point and move to the next highlight, if any.
+If there is none below the point but there is a highlight in the
 buffer, go back to the first one.
 
-If the point has moved to the next highlight, this function
-enables transient map with `set-transient-map'. You don't have to
-press the keybinding prefix again to move further to the next.
-That is, you can do a key sequence like this:
+After the point has moved to the next highlight, this command
+lets you move further by re-entering only the last letter like
+this example:
+
+   C-n \] \] \] \] \] \(assuming this command is bound to C-n\)
 
-   `\\[org-marginalia-next]' \] \] \] \]
+This is achieved by transient map with `set-transient-map'.
 
 If you have the same prefix for `org-marginalia-prev', you can combine it in
 the sequence like so:
 
-   `\\[org-marginalia-next]' \] \] \[ \["
+   C-n \] \] \] \[ \["
   (interactive)
   (if (not org-marginalia-highlights)
       (progn (message "No highlights present in this buffer.") nil)
@@ -448,17 +364,18 @@ the sequence like so:
 If there is none above the point, but there is a highlight in the
 buffer, go back to the last one.
 
-If the point has moved to the previous highlight, this function
-enables transient map with `set-transient-map'. You don't have to
-press the keybinding prefix again to move further to the next.
-That is, you can do a key sequence like this:
+After the point has moved to the previous highlight, this command
+lets you move further by re-entering only the last letter like
+this example:
+
+   C-n \[ \[ \[ \[ \[ \(assuming this command is bound to C-n \[\)
 
-   `\\[org-marginalia-prev]' \[ \[ \[ \[
+This is achieved by transient map with `set-transient-map'.
 
 If you have the same prefix for `org-marginalia-next', you can combine it in
 the sequence like so:
 
-   `\\[org-marginalia-prev]' \] \] \[ \["
+   C-n \] \] \] \[ \["
   (interactive)
   (if (not org-marginalia-highlights)
       (progn (message "No highlights present in this buffer.") nil)
@@ -478,15 +395,15 @@ the sequence like so:
 
 (defun org-marginalia-toggle ()
   "Toggle showing/hiding of highlighters in current buffer.
-It only affects the display of the highlighters. The locations
-are still kept tracked; thus, upon buffer-save the correct
-locations are still recorded in the marginalia file."
+It only affects the display of the highlighters. Their locations
+are still kept tracked; upon buffer-save the correct locations
+are still recorded in the marginalia file."
   (interactive)
   (when-let ((highlights org-marginalia-highlights))
     ;; Check the first highlight in the buffer
     ;; If it's hidden, all hidden. Show them.
     ;; If not, all shown. Hide them.
-    (if-let* ((beg (car (cdr (nth 0 highlights))))
+    (if-let* ((beg (overlay-start (nth 0 highlights)))
               (hidden-p (get-char-property beg 'org-marginalia-hidden)))
         (org-marginalia-show)
       (org-marginalia-hide))
@@ -496,22 +413,36 @@ locations are still recorded in the marginalia file."
 
 ;;;;; Private
 
-(defun org-marginalia-save-single-highlight (highlight title source-path)
+(defun org-marginalia-save-single-highlight (highlight title source-path orgid)
   "Save a single HIGHLIGHT in the marginalia file with properties.
 The marginalia file is specified by SOURCE-PATH. If headline with
 the same ID already exists, update it based on the new highlight
 position and highlighted text as TITLE. If it is a new highlight,
-creat a new headline at the end of the buffer."
-  (let* ((pos (cdr highlight))
-         (beg (marker-position (car pos)))
-         (end (marker-position (cdr pos)))
+create a new headline at the end of the buffer.
+
+ORGID can be passed to this function. If user option
+`org-marginalia-use-org-id' is non-nil, this function will create
+a link back to the source via an Org-ID link instead of the
+normal file link.
+
+When a new marginalia file is created and
+`org-marginalia-use-org-id' is non-nil, this function adds ID
+property to the file level. This is mainly to support Org-roam's
+backlink feature for marginalia files."
+  (let* ((beg (overlay-start highlight))
+         (end (overlay-end highlight))
+        (id (overlay-get highlight 'org-marginalia-id))
          ;;`org-with-wide-buffer is a macro that should work for non-Org file'
          (text (org-with-wide-buffer (buffer-substring-no-properties beg 
end))))
     ;; TODO Want to add a check if save is applicable here.
     (with-current-buffer (find-file-noselect org-marginalia-notes-file-path)
+      ;; If it is a new empty marginalia file
+      (when (and (org-marginalia-empty-buffer-p) org-marginalia-use-org-id)
+       (org-id-get-create))
       (org-with-wide-buffer
-       (let ((file-headline (org-find-property org-marginalia-prop-source-file 
source-path))
-             (id-headline (org-find-property org-marginalia-prop-id (car 
highlight))))
+       (let ((file-headline (org-find-property
+                            org-marginalia-prop-source-file source-path))
+             (id-headline (org-find-property org-marginalia-prop-id id)))
          (unless file-headline
            ;; If file-headline does not exist, create one at the bottom
            (goto-char (point-max))
@@ -523,10 +454,13 @@ creat a new headline at the end of the buffer."
                 (goto-char id-headline)
                 ;; Update the existing headline and position properties
                 (org-edit-headline text)
-                (org-set-property org-marginalia-prop-source-beg 
(number-to-string beg))
-                (org-set-property org-marginalia-prop-source-end 
(number-to-string end)))
+                (org-set-property org-marginalia-prop-source-beg
+                                 (number-to-string beg))
+                (org-set-property org-marginalia-prop-source-end
+                                 (number-to-string end)))
                (t ;; No headline with the ID property. Create one
-                (when-let ((p (org-find-property 
org-marginalia-prop-source-file source-path)))
+                (when-let ((p (org-find-property
+                              org-marginalia-prop-source-file source-path)))
                   (goto-char p))
                 (org-narrow-to-subtree)
                 (goto-char (point-max))
@@ -535,27 +469,22 @@ creat a new headline at the end of the buffer."
                 ;; Create a headline
                 ;; Add a properties
                 (insert (concat "** " text "\n"))
-                (org-set-property org-marginalia-prop-id (car highlight))
-                (org-set-property org-marginalia-prop-source-beg 
(number-to-string beg))
-                (org-set-property org-marginalia-prop-source-end 
(number-to-string end))
-                (insert (concat "[[file:" source-path "]" "[" title "]]"))))))
+                (org-set-property org-marginalia-prop-id id)
+                (org-set-property org-marginalia-prop-source-beg
+                                 (number-to-string beg))
+                (org-set-property org-marginalia-prop-source-end
+                                 (number-to-string end))
+               (if (and org-marginalia-use-org-id orgid)
+                   (insert (concat "[[id:" orgid "]" "[" title "]]"))
+                 (insert (concat "[[file:" source-path "]" "[" title 
"]]")))))))
       (when (buffer-modified-p) (save-buffer) t))))
 
-(defun org-marginalia-make-highlight-marker (point)
-  "Return marker of the insertion-type t for POINT.
-The insertion-type is important in order for the highlight
-position (beg and end points) in sync with the highlighted text
-properties."
-  (let ((marker (set-marker (make-marker) point)))
-    (set-marker-insertion-type marker t)
-    marker))
-
 (defun org-marginalia-list-highlights-positions (&optional reverse)
   "Return list of beg points of highlights in this buffer.
 By default, the list is in ascending order.
 If REVERSE is non-nil, return list in the descending order.
 
-It also checks if the position is visible or not. Returns only
+It also checks if the position is visible or not. Return only
 visible ones.
 
 If none, return nil."
@@ -563,7 +492,7 @@ If none, return nil."
     (let ((list org-marginalia-highlights))
       (setq list (mapcar
                   (lambda (h)
-                    (let ((p (marker-position (car (cdr h)))))
+                    (let ((p (overlay-start h)))
                       ;; Checking if the p is visible or not
                       (if (or
                            (> p (point-max))
@@ -584,7 +513,10 @@ Instead of receiving it as an arg, it assumes its 
existence. It
 also distructively updates `org-marginalia-highlights'.
 It returns t when sorting is done."
   (when org-marginalia-highlights
-    (setq org-marginalia-highlights (seq-sort-by (lambda (s) (car (cdr s))) 
#'< org-marginalia-highlights))
+    (setq org-marginalia-highlights
+         (seq-sort-by (lambda (ov) (overlay-start ov))
+                      #'<
+                      org-marginalia-highlights))
     t))
 
 (defun org-marginalia-find-next-highlight ()
@@ -609,30 +541,79 @@ Look through `org-marginalia-highlights' list (in 
descending order)."
   "Hide highlighters.
 It will remove the font-lock-face of all the highlights, and add
 'org-marginalia-hidden property with value 't. It does not check the current
-hidden state, thus not interactive. Use `org-marginalia-toggle-display'
+hidden state, thus not interactive. Use `org-marginalia-toggle'
 command to manually toggle the show/hide state."
   (when-let ((highlights org-marginalia-highlights))
     (dolist (highlight highlights)
-      (let ((beg (car (cdr highlight)))
-            (end (cdr (cdr highlight))))
-        (remove-list-of-text-properties beg end '(font-lock-face))
-        (add-text-properties beg end (list 'org-marginalia-hidden t))))
+        (overlay-put highlight 'face nil)
+        (overlay-put highlight 'org-marginalia-hidden t))
     t))
 
 (defun org-marginalia-show ()
-  "Show highlighters.
+  "Show highlights.
 It adds the font-lock-face to all the highlighted text regions.
 It does not check the current hidden state, thus not interactive.
-Use `org-marginalia-toggle-display' command to manually toggle the show/hide
-state."
+Use `org-marginalia-toggle' command to manually toggle the
+show/hide state."
   (when-let ((highlights org-marginalia-highlights))
     (dolist (highlight highlights)
-      (let ((beg (car (cdr highlight)))
-            (end (cdr (cdr highlight))))
-        (remove-list-of-text-properties beg end '(org-marginalia-hidden))
-        (add-text-properties beg end '(font-lock-face 
org-marginalia-highlighter))))
+        (overlay-put highlight 'org-marginalia-hidden nil)
+        (overlay-put highlight 'face 'org-marginalia-highlighter))
     t))
 
+(defun org-marginalia-remove-marginalia (id &optional delete-notes)
+  "Remove marginalia entry for the ID for the current buffer.
+By default, it deletes only the properties of the entry keeping
+the headline intact. You can pass DELETE-NOTES and delete the all
+notes of the entry."
+  (with-current-buffer (find-file-noselect org-marginalia-notes-file-path)
+      (org-with-wide-buffer
+       (when-let ((id-headline (org-find-property org-marginalia-prop-id id)))
+         (goto-char id-headline)
+        (org-narrow-to-subtree)
+         (org-delete-property org-marginalia-prop-id)
+         (org-delete-property org-marginalia-prop-source-beg)
+         (org-delete-property org-marginalia-prop-source-end)
+         (when delete-notes
+           ;; TODO I would love to add the y-n prompt if there is any notes 
written
+           (delete-region (point-min)(point-max))
+           (message "Deleted the marginal notes."))
+        (when (buffer-modified-p) (save-buffer))))
+      t))
+
+(defun org-marginalia-housekeep ()
+  "Housekeep the internal variable `org-marginalia-highlights'.
+This is a private function; housekeep is automatically done on
+save.
+
+Case 1. Both start and end of an overlay are identical
+
+        This should not happen when you manually mark a text
+        region. A typical cause of this case is when you delete a
+        region that contains a highlight overlay.
+
+Case 2. The overlay points to no buffer
+
+        This case happens when overlay is deleted by
+        `overlay-delete' but the variable not cleared."
+  (dolist (ov org-marginalia-highlights)
+    ;; Both start and end of an overlay are indentical; this should not happen
+    ;; when you manually mark a text region. A typical cause of this case is
+    ;; when you delete a region that contains a highlight overlay.
+    (when (and (overlay-buffer ov)
+              (= (overlay-start ov) (overlay-end ov)))
+      (org-marginalia-remove-marginalia (overlay-get ov 'org-marginalia-id))
+      (delete-overlay ov))
+    (unless (overlay-buffer ov)
+      (setq org-marginalia-highlights (delete ov org-marginalia-highlights))))
+  t)
+
+(defun org-marginalia-empty-buffer-p ()
+  "Return non-nil when the current buffer is empty."
+  (save-excursion
+    (goto-char (point-max))
+    (= 1 (point))))
+
 ;;;; Footer
 
 (provide 'org-marginalia)
@@ -641,9 +622,8 @@ state."
 
 ;; Local Variables:
 ;; coding: utf-8
-;; fill-column: 78
+;; fill-column: 80
 ;; require-final-newline: t
 ;; sentence-end-double-space: nil
 ;; eval: (setq-local org-marginalia-notes-file-path "README.org")
-;; eval: (if (find-library "org-marginalia")(progn (require 
'org-marginalia)(org-marginalia-mode 1)))
 ;; End:
diff --git a/resources/images/2021-08-17T220032.png 
b/resources/images/2021-08-17T220032.png
new file mode 100644
index 0000000000..181a45269c
Binary files /dev/null and b/resources/images/2021-08-17T220032.png differ