org-node.texi

\input texinfo    @c -*- texinfo -*-
@c %**start of header
@setfilename org-node.info
@settitle org-node
@documentencoding UTF-8
@documentlanguage en
@c %**end of header

@dircategory Emacs
@direntry
* Org-Node: (org-node). Link org-id entries into a network.
@end direntry

@finalout
@titlepage
@title org-node
@author Martin Edström
@end titlepage

@ifnottex
@node Top
@top org-node

This is the instruction manual for org-node.  The @uref{https://github.com/meedstrom/org-node, README} is separate@comma{} but you should not need it anymore.

@end ifnottex

@menu
* Setup::
* Backlinks::
* Misc::
* Appendix::

@detailmenu
--- The Detailed Node Listing ---

Setup

* Installation::
* Quick start::

Installation

* An update broke things?::

Backlinks

* Backlink solution 1 displayed in a separate window::
* Backlink solution 2 printed inside the file::

Misc

* Org-capture::
* Exclude uninteresting nodes::
* Missing completions?::
* Completion-at-point::
* Customize appearance::
* Sort completions::
* Grep::
* Let org-open-at-point detect refs::
* Limitation TRAMP::
* Limitation Unique titles::
* Limitation Org-ref::
* Toolbox::
* Experimental Node sequences::

Sort completions

* Bonus Lining up properties::

Experimental: Node sequences

* What are node seqs?::

Appendix

* Appendix I Rosetta stone::
* Appendix II How to rollback::
* Appendix III Random tips::
* Appendix IV What are @samp{ROAM_REFS}?::

Appendix III: Random tips

* Fix export to HTML::

Appendix IV: What are @samp{ROAM_REFS}?

* What's it actually used for?::
* Citations::

@end detailmenu
@end menu

@node Setup
@chapter Setup

@menu
* Installation::
* Quick start::
@end menu

@node Installation
@section Installation

Assuming your package manager gets recipes from @uref{https://melpa.org/#/getting-started, MELPA}@comma{} add the following initfile snippet.

@lisp
(use-package org-mem
  :config
  (org-mem-updater-mode))

(use-package org-node
  :init
  ;; Optional key bindings
  ;; Tip: Try changing these to just "M-o"!
  (keymap-global-set "M-o n" org-node-global-prefix-map)
  (with-eval-after-load 'org
    (keymap-set org-mode-map "M-o n" org-node-org-prefix-map))
  :config
  (org-node-cache-mode))
@end lisp

If you're coming here from @strong{org-roam}@comma{} try this instead:

@lisp
(use-package org-mem
  :config
  (setq org-mem-watch-dirs
        (list "~/org/")) ;; Your org-roam-directory here
  (org-mem-updater-mode))

(use-package org-node
  :init
  ;; Optional key bindings
  ;; Tip: Try changing these to just "M-o"!
  (keymap-global-set "M-o n" org-node-global-prefix-map)
  (with-eval-after-load 'org
    (keymap-set org-mode-map "M-o n" org-node-org-prefix-map))
  :config
  (org-node-cache-mode)
  (org-node-roam-accelerator-mode)
  (setq org-node-creation-fn #'org-node-new-via-roam-capture)
  (setq org-node-file-slug-fn #'org-node-slugify-like-roam-default)
  (setq org-node-file-timestamp-format "%Y%m%d%H%M%S-"))
@end lisp

@menu
* An update broke things?::
@end menu

@node An update broke things?
@subsection An update broke things?

See at the end of this readme: @ref{Appendix II How to rollback, , How to rollback}

@node Quick start
@section Quick start

If you're new to these concepts@comma{} fear not.  The main things for day-to-day operation are two commands:

@itemize
@item
@samp{org-node-find} (@code{M-o n f})
@itemize
@item
Tip: Consider binding a short key like @code{M-o f}
@end itemize
@item
@samp{org-node-insert-link} (@code{M-o n i})
@itemize
@item
Tip: Consider binding a short key like @code{M-o i}
@end itemize
@end itemize

Tip: There's @strong{no separate command} for creating a new node!  Reuse one of the commands above@comma{} and type the name of a node that doesn't exist.  Try it and see what happens!

To see a list of all commands@comma{} enter an Org buffer and type @code{M-o n <f1>}.

To browse config options@comma{} type @code{M-x customize-group RET org-node RET} (or @code{M-o n x o}).

@node Backlinks
@chapter Backlinks

Backlinks are the butter on the bread that is your notes.  If you've ever seen a "What links here" section on some webpage@comma{} that's exactly what it is.

You do not have to create backlinks yourself@comma{} they are autogenerated.  The following sections outline two basic ways this can work.

@menu
* Backlink solution 1 displayed in a separate window::
* Backlink solution 2 printed inside the file::
@end menu

@node Backlink solution 1 displayed in a separate window
@section Backlink solution 1: displayed in a separate window

@table @asis
@item Solution 1A: Reuse the org-roam buffer
You can use the org-roam buffer without the rest of org-roam!  Enable the following mode.

Then to learn how to invoke the buffer@comma{} see their documentation at @ref{The Org-roam Buffer,,,org-roam,} or @uref{https://www.orgroam.com/manual.html#The-Org_002droam-Buffer, online website}.

@lisp
(org-node-roam-accelerator-mode)
@end lisp
@end table


@table @asis
@item Solution 1B: Use the org-node-context buffer
Org-node ships a rewrite of the org-roam buffer@comma{} in the included extension org-node-context.el.

Try the command @samp{org-node-context-dwim} (@code{M-o n b}).

If you like it@comma{} consider binding it to an easily typed key@comma{} such as @samp{M-o M-b}.  Or you can let it keep itself updated@comma{} reflecting where point is at all times@comma{} by enabling this mode:

@lisp
;; Tip: if you're like org-node's author and constantly lose your window
;; configuration@comma{} the Emacs 30 command `toggle-window-dedicated' (C-x w d)
;; can help@comma{} or simply invoking `org-node-context-dwim' a lot.
;; The latter strategy tends to make this mode superfluous.
(org-node-context-follow-mode)
@end lisp
@end table

@node Backlink solution 2 printed inside the file
@section Backlink solution 2: printed inside the file

I rarely have the screen space to display a backlink buffer.  Because it needs my active involvement to keep visible@comma{} I go long periods seeing no backlinks.

A complementary solution@comma{} which can also stand alone@comma{} is to have the backlinks @emph{written into} the file@comma{} on an Org property line or in a drawer.

To be clear@comma{} this solution never generates new IDs (and neither would Solution 1).  That's your own business.  This only adds/edits @samp{:BACKLINKS:} properties or drawers.

@quotation
[!NOTE]
A difference between org-node-context (solution 1) and org-node-backlink-mode (solution 2) is that the latter only shows backlinks corresponding to links where the original site @emph{already has or inherits some ID}.  The former additionally shows backlinks to places that have no ID at all (since v3.14).

@end quotation

@table @asis
@item Solution 2A: Automatic @samp{:BACKLINKS:} property line
Add to initfiles:

@lisp
(setq org-node-backlink-do-drawers nil)
(org-node-backlink-mode)
@end lisp

For a first-time run@comma{} type @code{M-x org-node-backlink-mass-update-props}.  (Don't worry if you change your mind; undo with @code{M-x org-node-backlink-mass-delete-props}.)
@end table


@table @asis
@item Solution 2B: Automatic @samp{:BACKLINKS:...:END:} drawer
Same as Solution 2A@comma{} but uses a multiline drawer.

Add to initfiles:

@lisp
(setq org-node-backlink-do-drawers t)
(org-node-backlink-mode)
@end lisp

For a first-time run@comma{} type @code{M-x org-node-backlink-mass-update-drawers}.  (Don't worry if you change your mind; undo with @code{M-x org-node-mass-delete-drawers}.)
@end table


@table @asis
@item Solution 2C: Semi-automatic @samp{:BACKLINKS:...:END:} drawer
If you were previously using @uref{https://github.com/toshism/org-super-links, org-super-links}@comma{} you can continue letting it manage its drawers@comma{} and leave org-node out of the matter.

Do not enable `org-node-backlink-mode` at all@comma{} just add to initfiles:

@lisp
(add-hook 'org-node-insert-link-hook
          #'org-super-links-convert-link-to-super)
@end lisp

You may find these tools useful:

@itemize
@item
1. You can list any dead forward-links to fix them manually:

@code{M-x org-node-list-dead-links}

@item
2. You can add all missing backlinks in bulk:

@code{M-x org-node-backlink-mass-update-drawers}
@end itemize

The second command may be useful as a starting point if you're new to org-super-links@comma{} pre-populating the notes you already have.

However@comma{} when you have pre-existing drawers@dots{} @strong{make a full backup} before trying it!

Org-node has a different usage in mind than org-super-links.  You may be accustomed to having old manually formatted and sorted drawers.

Running aforementioned command @strong{may re-sort your backlinks and re-format their appearance into something you don't want}; double-check the following options:

@itemize
@item
@samp{org-node-backlink-drawer-sorter}
@item
@samp{org-node-backlink-drawer-formatter}
@end itemize

Finally@comma{} lines that contain no Org link such as @samp{[[id:1234][Title]]} are @strong{deleted}@comma{} which would mean @strong{destroying any other info within.}  Same if a backlink is stale and no longer valid.
@end table

@node Misc
@chapter Misc

@menu
* Org-capture::
* Exclude uninteresting nodes::
* Missing completions?::
* Completion-at-point::
* Customize appearance::
* Sort completions::
* Grep::
* Let org-open-at-point detect refs::
* Limitation TRAMP::
* Limitation Unique titles::
* Limitation Org-ref::
* Toolbox::
* Experimental Node sequences::
@end menu

@node Org-capture
@section Org-capture

You may have heard that org-roam has a set of meta-capture templates: the @samp{org-roam-capture-templates}.

People who understand the magic of capture templates@comma{} they may take this in stride.  Me@comma{} I never felt confident using a second-order abstraction over an already leaky abstraction.

Can we just use vanilla org-capture?  That'd be less scary.  The answer is yes!

The secret sauce is @samp{(function org-node-capture-target)}.  Examples:

@lisp
(setq org-capture-templates
      '(("e" "Capture entry into ID node"
         entry (function org-node-capture-target) "* %?")

        ("p" "Capture plain text into ID node"
         plain (function org-node-capture-target) nil
         :empty-lines-after 1)

        ("j" "Jump to ID node"
         plain (function org-node-capture-target) nil
         :prepend t
         :immediate-finish t
         :jump-to-captured t)

        ;; Sometimes handy after `org-node-insert-link'@comma{} to
        ;; make a stub you plan to fill in later@comma{} without
        ;; leaving the current buffer for now
        ("q" "Make quick stub ID node"
         plain (function org-node-capture-target) nil
         :immediate-finish t)))
@end lisp

With that done@comma{} you can optionally configure the everyday commands @samp{org-node-find} & @samp{org-node-insert-link} to outsource to org-capture when they try to create new nodes:

@lisp
(setq org-node-creation-fn #'org-capture)
@end lisp

That last optional functionality may only confuse you more if I try to describe it in words -- better you give it a spin and see if you like.

For deeper hacking@comma{} see @uref{https://github.com/meedstrom/org-node/wiki/Capture, wiki}.

@node Exclude uninteresting nodes
@section Exclude uninteresting nodes

One user had over a thousand project-nodes@comma{} but only just began to do a knowledge base@comma{} and wished to avoid seeing the project nodes.

This could work by---for example---excluding anything with the Org tag @samp{:project:} or perhaps anything that has a TODO state.  Here's a way to exclude both:

@lisp
(setq org-node-filter-fn
      (lambda (node)
        (not (or (member "project" (org-mem-tags node))
                 (org-mem-todo-state node)))))
@end lisp

Or you could go with a whitelist approach@comma{} to show only nodes from a certain directory we'll call "my-personal-wiki":

@lisp
(setq org-node-filter-fn
      (lambda (node)
        (string-search "/my-personal-wiki/" (org-mem-file node))))
@end lisp

@node Missing completions?
@section Missing completions?

Since @uref{https://github.com/meedstrom/org-mem, org-mem} only looks at saved files on disk@comma{} new notes only "appear" after save.  So it can make for a smoother experience to enable @samp{auto-save-visited-mode}.

That is also the usage that I test most -- I've had the following config for years:

@lisp
(setq auto-save-visited-interval 2)
(auto-save-visited-mode)
@end lisp

FWIW@comma{} org-node used to try to be smarter and also cache notes in unsaved buffers@comma{} but that quickly became difficult to reason about@comma{} especially wrt. deciding whether to update a backlink or not.

@node Completion-at-point
@section Completion-at-point

A global minor mode to complete words at point into known node titles:

@lisp
(org-node-complete-at-point-mode)
(setq org-roam-completion-everywhere nil) ;; Stop org-roam equivalent.
@end lisp

@node Customize appearance
@section Customize appearance

(Analogue to @samp{org-roam-node-display-template}@comma{} for those of you who know what that is)

To customize how the nodes look in the minibuffer@comma{} configure @samp{org-node-affixation-fn}:

@example
M-x customize-variable RET org-node-affixation-fn
@end example

A related option is @samp{org-node-alter-candidates}@comma{} which lets you match against the annotations as well as the title if set to t:

@lisp
(setq org-node-alter-candidates t)
@end lisp

@node Sort completions
@section Sort completions

A useful way to sort completions is to base it on a @samp{:TIME_MODIFIED:} property under each of your ID-nodes.

First@comma{} of course@comma{} a few nodes must have such a property.  Start generating them by adding this hook:

@lisp
(setq org-node-property-mtime "TIME_MODIFIED")
(add-hook 'org-node-modification-hook
          #'org-node-update-mtime-property)
@end lisp

Then to start actually sorting nodes by their @samp{:TIME_MODIFIED:} values:

@lisp
(setq org-node-display-sort-fn
      #'org-node-sort-by-mtime-property)
@end lisp

@menu
* Bonus Lining up properties::
@end menu

@node Bonus Lining up properties
@subsection Bonus: Lining up properties

I want to see @samp{:TIME_CREATED:} right above @samp{:TIME_MODIFIED:}.

So I re-sort the entire properties drawer on save:

@lisp
(add-hook 'org-node-modification-hook
          (defun my-sort-properties ()
            (org-back-to-heading-or-point-min)
            (re-search-forward org-property-drawer-re (org-entry-end-position))
            (let ((end (pos-bol))
                  (beg (progn (goto-char (match-beginning 0))
                              (forward-line 1)
                              (point))))
              (sort-lines nil beg end)))
          50)
;; The above is so the following properties will come in predictable order.
(setq org-node-property-crtime "TIME_CREATED")
(setq org-node-property-mtime "TIME_MODIFIED")
@end lisp

@node Grep
@section Grep

If you have Ripgrep installed on the computer@comma{} and @uref{https://github.com/minad/consult, Consult} installed on Emacs@comma{} you can use this command to grep across all your Org files at any time.

@itemize
@item
@samp{org-node-grep} (@code{M-o n g})
@end itemize

This can be a power-tool for mass edits.  Say you want to rename some Org tag @samp{:math:} to @samp{:Math:} absolutely everywhere.  Then you could follow a procedure such as:

@enumerate
@item
Use @samp{org-node-grep} and type @samp{:math:}
@item
Use @samp{embark-export} (from package @uref{https://github.com/oantolin/embark, Embark})
@item
Use @samp{wgrep-change-to-wgrep-mode} (from package @uref{https://github.com/mhayashi1120/Emacs-wgrep, wgrep})
@item
Do a query-replace (@code{M-%}) to replace all @samp{:math:} with @samp{:Math:}
@item
Type @code{C-c C-c} to apply the changes
@end enumerate

@node Let org-open-at-point detect refs
@section Let org-open-at-point detect refs

(For background@comma{} see @ref{Appendix IV What are @samp{ROAM_REFS}?, , What are ROAM@math{_REFS}?} at the end of this README@.)

Say there's a link to a web URL@comma{} and you've forgotten you also have a node listing that exact URL in its @samp{ROAM_REFS} property.

Wouldn't it be nice if@comma{} clicking on that link@comma{} you automatically visit that node first instead of being sent to the web?  Here you go:

@lisp
(add-hook 'org-open-at-point-functions
          #'org-node-try-visit-ref-node)
@end lisp

@node Limitation TRAMP
@section Limitation: TRAMP

Working with files over TRAMP is unsupported@comma{} because org-mem works in parallel subprocesses which do not inherit your TRAMP setup.

The best way to change this is to @uref{https://github.com/meedstrom/org-mem/issues, file an issue} to show you care :-)

@node Limitation Unique titles
@section Limitation: Unique titles

If two ID-nodes exist with the same title@comma{} one of them disappears from minibuffer completions.

That's just the nature of completion.  Much can be said for embracing the uniqueness constraint@comma{} and org-node will print messages about collisions.

Anyway@dots{} there's a workaround.  Assuming you leave @samp{org-node-affixation-fn} at its default setting@comma{} adding this to initfiles tends to do the trick:

@lisp
(setq org-node-alter-candidates t)
@end lisp

This lets you match against the node outline path and not only the title@comma{} which resolves most conflicts given that the most likely source of conflict is subheadings in disparate files@comma{} that happen to be named the same.

NB: for users of @samp{org-node-complete-at-point-mode}@comma{} this workaround won't help those completions.  With some luck you'll link to the wrong one of two homonymous nodes@comma{} but it's worth being aware. (@uref{https://github.com/meedstrom/org-node/issues/62, #62})

@node Limitation Org-ref
@section Limitation: Org-ref

Org-node supports the Org 9.5 @@citations@comma{} but not fully the aftermarket @uref{https://github.com/jkitchin/org-ref, org-ref} &citations that emulate @LaTeX{} look-and-feel.

What works is bracketed Org-ref v3 citations that start with "cite"@comma{} e.g. @samp{[[citep:...]]}@comma{} @samp{[[citealt:...]]}@comma{} @samp{[[citeauthor:...]]}@comma{} since org-mem-parser.el is able to pick them up for free.

What doesn't work is e.g. @samp{[[bibentry:...]]} since it doesn't start with "cite"@comma{} nor plain @samp{citep:...} since it is not wrapped in brackets.

If you need more of Org-ref@comma{} you have at least two options:

@itemize
@item
Use org-roam - see discussions on boosting its performance @uref{https://org-roam.discourse.group/t/rewriting-org-roam-node-list-for-speed-it-is-not-sqlite/3475/92, here} and @uref{https://org-roam.discourse.group/t/improving-performance-of-node-find-et-al/3326/33, here}

@item
Contribute to @uref{https://github.com/meedstrom/org-mem, org-mem}@comma{} see function @samp{org-mem-parser--scan-text-until}.
@end itemize

@node Toolbox
@section Toolbox

(Note that you can view this same list of commands in Emacs.  Assuming that @samp{M-o n} was where you bound @samp{org-node-org-prefix-map}@comma{} type @samp{M-o n <f1>}.)

Basic commands:

@itemize
@item
@samp{org-node-find}
@item
@samp{org-node-insert-link}
@item
@samp{org-node-insert-into-related}
@item
@samp{org-node-insert-transclusion}
@item
@samp{org-node-insert-transclusion-as-subtree}
@item
@samp{org-node-visit-random}
@item
@samp{org-node-context-dwim}
@item
@samp{org-node-set-tags}
@item
@samp{org-node-add-alias}
@item
@samp{org-node-add-ref}
@item
@samp{org-node-refile}
@itemize
@item
Does two technically different things: either move a subtree into some node it prompts you for@comma{} or if you press RET with no input@comma{} extract the subtree into a new file (similarly to @samp{org-roam-extract-subtree})
@end itemize
@item
@samp{org-node-seq-dispatch}
@itemize
@item
Browse node series -- see README
@end itemize
@item
@samp{org-node-nodeify-entry}
@itemize
@item
Give an ID to the entry at point@comma{} and run the hook @samp{org-node-creation-hook}
@end itemize
@item
@samp{org-node-grep}
@itemize
@item
(Requires @uref{https://github.com/minad/consult, consult}) Grep across all known Org files.
@end itemize
@item
@samp{org-node-card-view}
@itemize
@item
Try it and@comma{} uh@comma{} see.
@end itemize
@end itemize

Rarer commands:

@itemize
@item
@samp{org-node-rewrite-links-ask}
@itemize
@item
Look for link descriptions that got out of sync with the corresponding node title@comma{} then prompt at each link to update it
@end itemize

@item
@samp{org-node-rename-file-by-title}
@itemize
@item
Auto-rename the file based on the current @samp{#+title} or first heading
@itemize
@item
Can be run manually or placed on @samp{after-save-hook}!  When run as a hook@comma{} it is conservative@comma{} doing nothing until you configure @samp{org-node-renames-allowed-dirs}.
@item
@strong{Please note} that if your filenames have datestamp prefixes@comma{} like org-roam's default behavior of making filenames such as @samp{20240831143302-node_title.org}@comma{} it is important to get @samp{org-node-file-timestamp-format} right or it @strong{may clobber a pre-existing datestamp}.

A message is printed about the rename@comma{} but it's easy to miss.
@end itemize
@end itemize

@item
@samp{org-node-list-dead-links}
@itemize
@item
List links where the destination ID could not be found
@end itemize

@item
@samp{org-node-lint-all-files}
@itemize
@item
Can help you fix a broken setup: it runs org-lint on all known files and generates a report of Org syntax problems@comma{} for you to correct manually.

Org-node @uref{https://github.com/meedstrom/org-node/issues/8#issuecomment-2101316447, assumes all files have valid syntax}@comma{} but many of the reported problems are survivable.
@end itemize

@item
@samp{org-node-list-reflinks}
@itemize
@item
List all links that aren't @samp{id:} links.  Also includes citations@comma{} even though they are technically not links.
@end itemize

@item
@samp{org-node-list-feedback-arcs}
@itemize
@item
(Requires GNU R@comma{} with R packages stringr@comma{} readr and igraph)

Explore @uref{https://en.wikipedia.org/wiki/Feedback_arc_set, feedback arcs} in your ID link network.  Can work as a sort of @uref{https://edstrom.dev/zvjjm/slipbox-workflow#ttqyc, occasional QA routine}.
@end itemize

@item
@samp{org-node-rename-asset-and-rewrite-links}
@itemize
@item
Interactively rename an asset such as an image file and try to update all Org links to them.  Requires @uref{https://github.com/mhayashi1120/Emacs-wgrep, wgrep}.
@itemize
@item
NOTE: It prompts you for a certain root directory@comma{} and then only looks for links in there@comma{} and in sub and sub-subdirectories and so on -- but won't find a link elsewhere.

Like if you have Org files under /mnt linking to assets in /home@comma{} then those links won't be updated.  Or if you choose ~/org/some-subdir as the root directory@comma{} then links in ~/org/file.org will not update.  So choose ~/org as the root even if you are renaming something in a subdir.
@end itemize
@end itemize
@end itemize

Rarer commands for org-node-backlink-mode:

@itemize
@item
@samp{org-node-backlink-mass-update-drawers}
@item
@samp{org-node-backlink-mass-update-props}
@item
@samp{org-node-backlink-mass-delete-drawers}
@item
@samp{org-node-backlink-mass-delete-props}
@item
@samp{org-node-backlink-fix-buffer}
@end itemize

@node Experimental Node sequences
@section Experimental: Node sequences

Do you already know about "daily-notes"?  Then get started as follows:

@enumerate
@item
Configure variable @samp{org-node-seq-defs}; see @uref{https://github.com/meedstrom/org-node/wiki/Configuring-node-sequences, wiki} for premade examples
@item
Enable @samp{(org-node-seq-mode)}
@item
Try the command @samp{org-node-seq-dispatch} (@code{M-o n s})
@itemize
@item
Tip: Consider binding a shorter key @code{M-o s}
@end itemize
@end enumerate

@menu
* What are node seqs?::
@end menu

@node What are node seqs?
@subsection What are node seqs?

It's easiest to explain node sequences if we use "daily-notes" (aka "dailies") as an example.

Org-roam's idea of a "daily-note" is the same as an @uref{https://github.com/bastibe/org-journal, org-journal} entry: a file/entry where the title is just today's date.

You don't need software for that basic idea@comma{} only to make it extra convenient to navigate them and jump back and forth in the series.

Thus@comma{} fundamentally@comma{} any "journal" or "dailies" software are just operating on a sorted series to navigate through.  A node sequence.  You could have sequences for@comma{} let's say@comma{} historical events@comma{} Star Trek episodes@comma{} your school curriculum@dots{}

@node Appendix
@chapter Appendix

@menu
* Appendix I Rosetta stone::
* Appendix II How to rollback::
* Appendix III Random tips::
* Appendix IV What are @samp{ROAM_REFS}?::
@end menu

@node Appendix I Rosetta stone
@section Appendix I: Rosetta stone

API cheatsheet between org-roam and org-node.

@multitable {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
@headitem Action
@tab org-roam
@tab org-node
@item Get ID near point
@tab @samp{(org-roam-id-at-point)}
@tab @samp{(org-entry-get-with-inheritance "ID")}
@item Get node at point
@tab @samp{(org-roam-node-at-point)}
@tab @samp{(org-node-at-point)}
@item Prompt user to pick a node
@tab @samp{(org-roam-node-read)}
@tab @samp{(org-node-read)}
@item Get node by ID
@tab 
@tab @samp{(org-mem-entry-by-id ID)}
@item Get list of files
@tab @samp{(org-roam-list-files)}
@tab @samp{(org-mem-all-files)}
@item Get backlink objects
@tab @samp{(org-roam-backlinks-get NODE)}
@tab @samp{(org-mem-id-links-to-entry NODE)}
@item Get reflink objects
@tab @samp{(org-roam-reflinks-get NODE)}
@tab @samp{(org-mem-roam-reflinks-to-entry NODE)}
@item Get title
@tab @samp{(org-roam-node-title NODE)}
@tab @samp{(org-mem-entry-title NODE)}
@item Get title of file where NODE is
@tab @samp{(org-roam-node-file-title NODE)}
@tab @samp{(org-mem-file-title NODE)}
@item Get title @emph{or} name of file where NODE is
@tab 
@tab @samp{(org-mem-file-title-or-basename NODE)}
@item Get full path to file where NODE is
@tab @samp{(org-roam-node-file NODE)}
@tab @samp{(org-mem-entry-file NODE)}
@item Get ID
@tab @samp{(org-roam-node-id NODE)}
@tab @samp{(org-mem-entry-id NODE)}
@item Get tags
@tab @samp{(org-roam-node-tags NODE)}
@tab @samp{(org-mem-entry-tags NODE)}
@item Get tags (local only)
@tab 
@tab @samp{(org-mem-entry-tags-local NODE)}
@item Get tags (inherited only)
@tab 
@tab @samp{(org-mem-entry-tags-inherited NODE)}
@item Get outline level
@tab @samp{(org-roam-node-level NODE)}
@tab @samp{(org-mem-entry-level NODE)}
@item Get char position
@tab @samp{(org-roam-node-point NODE)}
@tab @samp{(org-mem-entry-pos node)}
@item Get line number
@tab 
@tab @samp{(org-mem-entry-lnum NODE)}
@item Get properties
@tab @samp{(org-roam-node-properties NODE)}
@tab @samp{(org-mem-entry-properties NODE)}
@item Get subtree TODO state
@tab @samp{(org-roam-node-todo NODE)}
@tab @samp{(org-mem-entry-todo-state NODE)}
@item Get subtree SCHEDULED
@tab @samp{(org-roam-node-scheduled NODE)}
@tab @samp{(org-mem-entry-scheduled NODE)}
@item Get subtree DEADLINE
@tab @samp{(org-roam-node-deadline NODE)}
@tab @samp{(org-mem-entry-deadline NODE)}
@item Get subtree CLOSED
@tab 
@tab @samp{(org-mem-entry-closed NODE)}
@item Get subtree priority
@tab @samp{(org-roam-node-priority NODE)}
@tab @samp{(org-mem-entry-priority NODE)}
@item Get outline-path
@tab @samp{(org-roam-node-olp NODE)}
@tab @samp{(org-mem-entry-olpath NODE)}
@item Get @samp{ROAM_REFS}
@tab @samp{(org-roam-node-refs NODE)}
@tab @samp{(org-mem-entry-roam-refs NODE)}
@item Get @samp{ROAM_ALIASES}
@tab @samp{(org-roam-node-aliases NODE)}
@tab @samp{(org-mem-entry-roam-aliases NODE)}
@item Get @samp{ROAM_EXCLUDE}
@tab 
@tab @samp{(org-mem-entry-property "ROAM_EXCLUDE" NODE)}
@item Ensure fresh data
@tab @samp{(org-roam-db-sync)}
@tab @samp{(org-node-cache-ensure t t)}
@end multitable

@node Appendix II How to rollback
@section Appendix II: How to rollback

Instructions to downgrade to @uref{https://github.com/meedstrom/org-node/tags, an older version}@comma{} let's say 1.6.2.

With @uref{https://github.com/quelpa/quelpa, Quelpa}:
@lisp
(use-package org-node
  :quelpa (org-node :fetcher github :repo "meedstrom/org-node"
                    :branch "v1.6"))
@end lisp

With @uref{https://github.com/slotThe/vc-use-package, vc-use-package} on Emacs 29:
@lisp
(use-package org-node
  :vc ( :fetcher github :repo "meedstrom/org-node"
        :branch "v1.6"))
@end lisp

With built-in @samp{:vc} on Emacs 30+ (but note default value of @samp{use-package-vc-prefer-newest} means you never update@comma{} since it is not aware of Git tags):
@lisp
(use-package org-node
  :vc ( :url "https://github.com/meedstrom/org-node"
        :branch "v1.6"))
@end lisp

With @uref{https://github.com/progfolio/elpaca, Elpaca} as follows.  Note that recipe changes only take effect after you do @samp{M-x elpaca-delete} and it re-clones -- the idea is that Elpaca users will prefer to do it manually with @code{M-x elpaca-visit} and using Magit to switch branch.

@lisp
(use-package org-node
  :ensure ( :fetcher github :repo "meedstrom/org-node"
            :branch "v1.6"))
@end lisp

@dots{}Elpaca can also target an exact version tag!  Package manager of the future@comma{} it is:

@lisp
(use-package org-node
  :ensure ( :fetcher github :repo "meedstrom/org-node"
            :tag "1.6.2"))
@end lisp

With @uref{https://github.com/radian-software/straight.el, Straight}:

@lisp
(use-package org-node
  :straight (org-node :type git :host github :repo "meedstrom/org-node"
                      :branch "v1.6"))
@end lisp

@node Appendix III Random tips
@section Appendix III: Random tips

@menu
* Fix export to HTML::
@end menu

@node Fix export to HTML
@subsection Fix export to HTML

Org-roam shipped the optional @samp{(require 'org-roam-export)}@comma{} a patch to fix @samp{id:} links in HTML export.

Good news@comma{} upstream fixed the root of the issue in 5e9953fa0!  Update Org to 9.7+ (comes with Emacs 30)@comma{} then set this.

@example
(setq org-html-prefer-user-labels t)
@end example

@node Appendix IV What are @samp{ROAM_REFS}?
@section Appendix IV: What are @samp{ROAM_REFS}?

Here's the start of one of my note files.  Note the @samp{:ROAM_REFS:} line.

@example
:PROPERTIES:
:CREATED:  [2023-09-11 Mon 12:00]
:ID:       3bf9opc0tik0
:ROAM_REFS: https://www.greaterwrong.com/s/pFatcKW3JJhTSxqAF https://mindingourway.com/guilt/
:END:
#+filetags: :pub:
#+options: toc:t
#+title: Replacing Guilt

Takeaways from Nate Soares' excellent "Replacing Guilt" series.

...
@end example

An explanation: think of them as like IDs.  While org-node is built around the ID property because it acts as a singular identifier@comma{} the concept can be generalized.

In another universe@comma{} @samp{ROAM_REFS} might have been called @samp{EXTRA_IDS} because in many ways it is just a list of additional IDs for the same node.

For performance reasons@comma{} not just any string of text is accepted -- it must have valid links per Org syntax@comma{} such as @samp{[[https://gnu.org][GNU Website]]} or @samp{https://gnu.org}.  That is because the @uref{https://github.com/meedstrom/org-mem, org-mem} library searches for links anyway in all body text@comma{} making it cheap to see after-the-fact where else this same "extra ID" may have been mentioned@comma{} and generate a backlink!

Org-roam calls such backlinks @emph{reflinks}.  In my view@comma{} adding a new word for such a similar concept just increases the air of mystery.  That's why in org-node's context buffer@comma{} they're just called "ref backlinks" -- as opposed to "ID backlinks".

@menu
* What's it actually used for?::
* Citations::
@end menu

@node What's it actually used for?
@subsection What's it actually used for?

People often use it to write notes about a specific web-page or PDF file@comma{} and call it a ref-node for that resource.

@node Citations
@subsection Citations

As a special case@comma{} citation keys such as "@@ioannidis2005" also work in @samp{ROAM_REFS}@comma{} corresponding to Org citations like @samp{[cite:@@ioannidis2005]}.

@bye