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
@end ifnottex

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

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

Background

* What's all this::
* What's a "node"?::
* Features::

Setup

* Install::
* Quick start::

Install

* An update broke things?::

Backlinks

* What are backlinks?::
* Backlink solution 1 Borrow org-roam's backlink buffer::
* Backlink solution 2 Print inside the file::

Backlink solution 2: Print inside the file

* Option 2A Let org-node manage a @samp{BACKLINKS} property::
* Option 2B Let org-super-links manage a @samp{BACKLINKS...END} drawer: Option 2B Let org-super-links manage a @samp{BACKLINKSEND} drawer. 

Misc

* Manage org-id-locations::
* Exclude uninteresting nodes::
* Org-capture::
* Completion-at-point::
* FAQ Any analogue to @samp{org-roam-node-display-template}?::
* Grep::
* Let org-open-at-point detect refs::
* Limitation TRAMP::
* Limitation Encryption::
* Limitation Unique titles::
* Limitation Org-ref::
* Toolbox::
* Experimental Node sequences::

Manage org-id-locations

* Undoing a Roam hack::

Exclude uninteresting nodes

* Limitation @samp{ROAM_EXCLUDE}::

Experimental: Node sequences

* What are "node seqs"?::
* Future::

Appendix

* Appendix I Rosetta stone::
* Appendix II How to rollback::

Appendix II: How to rollback

* Match fakeroam version::
* What version is installed?::

@end detailmenu
@end menu

@node Background
@chapter Background

@menu
* What's all this::
* What's a "node"?::
* Features::
@end menu

@node What's all this
@section What's all this

I like @uref{https://github.com/org-roam/org-roam, org-roam} but found it too slow, so I made @uref{https://github.com/meedstrom/quickroam, quickroam}.  And that idea spun off into this package, a standalone thing.  It may also be easier to pick up than org-roam.

@itemize
@item
@strong{If you were using org-roam}, there is nothing to migrate.  You can use both packages.  It's the same on-disk format: "notes" are identified by their org-id.

With optional shims, you can even @strong{skip syncing the org-roam DB} and continue using its rich backlinks buffer!

In pursuit of being "just org-id", this package has no equivalent setting to @samp{org-roam-directory} -- it just looks up the @samp{org-id-locations} table.

@item
@strong{If you were not using org-roam}, maybe think of it as somewhat like @uref{https://github.com/alphapapa/org-recent-headings, org-recent-headings} tooled-up to the extent that you won't need other methods of browsing, as long as you give IDs to all objects of interest.

If you were the sort of person to prefer ID-links over file links or any other type of link, you're in the right place!  Now you can rely on IDs, and---if you want---stop worrying about filenames, directories and subtree hierarchies.  As long as you've assigned an ID to a heading or file, you can find it later.
@end itemize

@node What's a "node"?
@section What's a "node"?

My life can be divided into two periods "@strong{before org-roam}" and "@strong{after org-roam}".  I crossed a kind of gap once I got a good way to link between my notes.  It's odd to remember when I just relied on browsing subtrees and filesystem directories -- what a strange way to work!

I used to lose track of things I had written, under some forgotten heading in a forgotten file in a forgotten directory.  The org-roam method let me @strong{find and build on} my own work, instead of @uref{https://en.wikipedia.org/wiki/Cryptomnesia, recreating it all the time}.

At the core, all the "notetaking packages" (@uref{https://github.com/rtrppl/orgrr, orgrr}/@uref{https://github.com/localauthor/zk, zk}/@uref{https://github.com/EFLS/zetteldeft, zetteldeft}/@uref{https://github.com/org-roam/org-roam, org-roam}/@uref{https://github.com/protesilaos/denote, denote}/@uref{https://github.com/kaorahi/howm, howm}/@uref{https://github.com/kisaragi-hiu/minaduki, minaduki}/@dots{}) try to help you with this: make it easy to link between notes and explore them.

Right off the bat, that imposes two requirements: a method to search for notes, since you can't link to something you can't search for, and a design-choice about what kinds of things should turn up as search hits.  What's a "note"?

Just searching for Org files is too coarse.  Just searching for any subtree anywhere brings in too much clutter.

@strong{Here's what org-roam invented.}  It turns out that if you limit the search-hits to just those files and subtrees you've deigned to assign an org-id -- which roughly maps to @emph{everything you've ever thought it was worth linking to} -- it filters out the noise excellently.

Once a subtree has an ID you can link to, it's a "node" because it has joined the wider graph, the network of linked nodes.  I wish the English language had more distinct sounds for the words "node" and "note", but to clarify, I'll say "ID-node" when the distinction matters.

@node Features
@section Features

A comparison of three similar systems, which permit relying on org-id and don't lock you into concept of "one-note-per-file".

@multitable {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} {aaaaaaaa} {aaaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
@headitem Feature
@tab org-roam
@tab org-node
@tab @uref{https://github.com/toshism/org-super-links, org-super-links}
@item Backlinks
@tab yes
@tab yes
@tab yes
@item Node search and insert
@tab yes
@tab yes
@tab -- (suggests @uref{https://github.com/alphapapa/org-ql, org-ql})
@item Node aliases
@tab yes
@tab yes
@tab --
@item Node exclusion
@tab yes
@tab limited
@tab not applicable
@item Refile
@tab yes
@tab yes
@tab --
@item Rich backlinks buffer
@tab yes
@tab yes (org-roam's)
@tab --
@item Customize how backlinks shown
@tab yes
@tab yes (org-roam's)
@tab yes
@item Reflinks
@tab yes
@tab yes (as backlinks)
@tab --
@item Ref search
@tab yes
@tab yes (as aliases)
@tab not applicable
@item Org 9.5 @@citations as refs
@tab yes
@tab yes
@tab not applicable
@item Support org-ref v3
@tab yes
@tab limited
@tab not applicable
@item Support org-ref v2
@tab yes
@tab --
@tab not applicable
@item Work thru org-roam-capture
@tab yes
@tab yes
@tab ?
@item Work thru org-capture
@tab --
@tab yes
@tab ?
@item Daily-nodes
@tab yes
@tab yes
@tab --
@item Node sequences
@tab --
@tab yes
@tab --
@item Show backlinks in same window
@tab --
@tab yes
@tab yes
@item Cooperate with org-super-links
@tab --
@tab yes
@tab not applicable
@item Fix link descriptions
@tab --
@tab yes
@tab --
@item List dead links
@tab --
@tab yes
@tab --
@item Rename file when title changes
@tab --
@tab yes
@tab --
@item Warn about duplicate titles
@tab --
@tab yes
@tab --
@item Principled "related-section"
@tab --
@tab --
@tab yes
@item Untitled notes
@tab --
@tab --
@tab --
@item Support @samp{roam:} links
@tab yes
@tab -- (WONTFIX)
@tab not applicable
@item Can have separate note piles
@tab yes
@tab -- (WONTFIX)
@tab not applicable
@item Some query-able cache
@tab EmacSQL
@tab hash tables
@tab --
@item Async cache rebuild
@tab --
@tab yes
@tab not applicable
@item @strong{Time to cache my 3000 nodes}
@tab @strong{2m 48s}
@tab @strong{0m 01s}
@tab not applicable
@item @strong{Time to save file w/ 400 nodes}
@tab @strong{5--10s}
@tab @strong{instant}
@tab ?
@item @strong{Time to open minibuffer}
@tab @strong{1--3s}
@tab @strong{instant}
@tab not applicable
@end multitable

@node Setup
@chapter Setup

@menu
* Install::
* Quick start::
@end menu

@node Install
@section Install

Assuming your package manager knows about @uref{https://melpa.org/#/getting-started, MELPA}, add this initfile snippet:

@lisp
(use-package org-node
  :after org
  :config (org-node-cache-mode))
@end lisp

If you use org-roam, you probably want the following module as well.  Check its README to make org-node @uref{https://github.com/meedstrom/org-node-fakeroam, work with org-roam side-by-side}!

@lisp
(use-package org-node-fakeroam
  :defer)
@end lisp

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

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

You can rollback to a version that used to work.  See @uref{https://github.com/meedstrom/org-node#appendix-ii-how-to-rollback, How to rollback} at the end of this readme.

As of v1.8, part of the code was spun out to a new library (@uref{https://github.com/meedstrom/el-job/, el-job}) -- you may have to update your package repositories via commands @samp{package-refresh-contents}, @samp{elpaca-update-menus} or equivalent.

@node Quick start
@section Quick start

If you're new to these concepts, fear not.  The main things for day-to-day operation are two verbs: "find" and "insert".

Pick some short keys and try them out.

@lisp
(keymap-set global-map "M-s M-f" #'org-node-find)
(keymap-set org-mode-map "M-s M-i" #'org-node-insert-link)
@end lisp

To browse config options, type @samp{M-x customize-group RET org-node RET}.

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

@node Backlinks
@chapter Backlinks

@menu
* What are backlinks?::
* Backlink solution 1 Borrow org-roam's backlink buffer::
* Backlink solution 2 Print inside the file::
@end menu

@node What are backlinks?
@section What are backlinks?

Backlinks are the butter on the bread of your notes.  If you've ever seen a "What links here" section on some webpage, that's exactly what it is.  Imagine seeing that, all the time.  The following sections outline two general ways to do so.

@node Backlink solution 1 Borrow org-roam's backlink buffer
@section Backlink solution 1: Borrow org-roam's backlink buffer

As a Roam user, you can keep using @samp{M-x org-roam-buffer-toggle}.

TIP: If it has been slow, or saving files has been slow, @uref{https://github.com/meedstrom/org-node-fakeroam, org-node-fakeroam} gives you ways to speed it up.

TIP: If you have not done so yet, I recommend binding some short key sequences.  I spent many months waffling on where to bind them, so here's an example:

@lisp
;; Either this...
(keymap-set org-mode-map "M-s M-r" #'org-roam-buffer-toggle)
(keymap-set global-map "M-s M-d" #'org-roam-buffer-display-dedicated)

;; ...or just this for a different behavior
(keymap-set global-map "M-s M-r" #'org-node-fakeroam-show-buffer)
@end lisp

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

I rarely have the screen space to display a backlink buffer.  Because it needs my active involvement to keep visible, I go long periods seeing no backlinks.  This solution can be a great complement (or even stand alone).

@menu
* Option 2A Let org-node manage a @samp{BACKLINKS} property::
* Option 2B Let org-super-links manage a @samp{BACKLINKS...END} drawer: Option 2B Let org-super-links manage a @samp{BACKLINKSEND} drawer. 
@end menu

@node Option 2A Let org-node manage a @samp{BACKLINKS} property
@subsection Option 2A: Let org-node manage a @samp{:BACKLINKS:} property

For a first-time run, type @samp{M-x org-node-backlink-fix-all-files}.  (Don't worry if you change your mind; undo with @samp{M-x org-node-backlink-regret}.)

Then enable the following global mode, which keeps these properties updated.

@lisp
(org-node-backlink-mode)
@end lisp

NOTE 1: To be clear, this never generates new IDs.  That's your own business.  This only adds/edits :BACKLINKS: properties, and no backlink will appear that correspond to a link if the context for that link has no ID among any outline ancestor.

NOTE 2: By default, the setting @samp{org-node-backlink-aggressive} is nil, so that stale backlinks are not cleaned until you carry out some edits under an affected heading and then save the file, which fixes that heading's :BACKLINKS: property.  If you'd like it to be more proactive, set t:

@lisp
(setq org-node-backlink-aggressive t)
@end lisp

NOTE 3:  People who prefer to hard-wrap text instead of enabling @samp{visual-line-mode} or similar may not find this way of displaying backlinks very scalable, since Org places properties on a single logical line, that may run off the edge of the screen.

@node Option 2B Let org-super-links manage a @samp{BACKLINKSEND} drawer
@subsection Option 2B: Let org-super-links manage a @samp{:BACKLINKS:...:END:} drawer

I @emph{think} the following should work. Totally untested, let me know!

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

Bad news: this is currently directed towards people who used @uref{https://github.com/toshism/org-super-links, org-super-links} from the beginning, or people who are just now starting to assign IDs, as there is not yet a command to add new BACKLINKS drawers in bulk to preexisting nodes. (@uref{https://github.com/toshism/org-super-links/issues/93, org-super-links#93})

@node Misc
@chapter Misc

@menu
* Manage org-id-locations::
* Exclude uninteresting nodes::
* Org-capture::
* Completion-at-point::
* FAQ Any analogue to @samp{org-roam-node-display-template}?::
* Grep::
* Let org-open-at-point detect refs::
* Limitation TRAMP::
* Limitation Encryption::
* Limitation Unique titles::
* Limitation Org-ref::
* Toolbox::
* Experimental Node sequences::
@end menu

@node Manage org-id-locations
@section Manage org-id-locations

Ever run into "ID not found" situations?  Org-node gives you an extra way to feed data to org-id, as @uref{http://edstrom.dev/wjwrl/taking-ownership-of-org-id, I find clumsy the built-in options}.

Example setting:

@lisp
(setq org-node-extra-id-dirs
      '("~/org/"
        "~/Syncthing/"
        "/mnt/stuff/"))
@end lisp

Do a @samp{M-x org-node-reset} and see if it can find your notes now.

@menu
* Undoing a Roam hack::
@end menu

@node Undoing a Roam hack
@subsection Undoing a Roam hack

If you have org-roam loaded, but no longer update the DB, opening a link can sometimes send you to an outdated file path due to @uref{https://github.com/org-roam/org-roam/blob/2a630476b3d49d7106f582e7f62b515c62430714/org-roam-id.el#L91, a line in org-roam-id.el} that causes org-id to @emph{preferentially} look up the org-roam DB instead of org-id's own table!

Either revert that with the following snippet, or if @uref{https://github.com/meedstrom/org-node-fakeroam, Fakeroam} can cover your needs, simply delete the Roam DB (at "~/.emacs.d/org-roam.db").

@lisp
;; Undo a Roam override
(with-eval-after-load 'org-roam-id
  ;; Restore default for Org 9.1 through 9.7+
  (org-link-set-parameters
   "id" :follow #'org-id-open :store #'org-id-store-link-maybe))
@end lisp

@node Exclude uninteresting nodes
@section Exclude uninteresting nodes

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

This could work by, for example, excluding a "project" tag and excluding any note that has a TODO state:

@lisp
(setq org-node-filter-fn
      (lambda (node)
        (not
         (or (org-node-get-todo node)
             (member "project"
                     (org-node-get-tags-with-inheritance node))
             (assoc "ROAM_EXCLUDE" (org-node-get-properties node))))))
@end lisp

Or you could go with a whitelist approach, to see only nodes from a certain directory we'll call "my-wiki":

@lisp
(setq org-node-filter-fn
      (lambda (node)
        (and (string-search "/my-wiki/" (org-node-get-file-path node))
             (not (assoc "ROAM_EXCLUDE" (org-node-get-properties node))))))
@end lisp

(NB: if you don't know what @samp{ROAM_EXCLUDE} is, feel free to omit that clause)

@menu
* Limitation @samp{ROAM_EXCLUDE}::
@end menu

@node Limitation @samp{ROAM_EXCLUDE}
@subsection Limitation: @samp{ROAM_EXCLUDE}

Let's say you have a big archive file, fulla IDs, and you want all the nodes within out of sight.

Putting a @samp{:ROAM_EXCLUDE: t} at the top won't do it, because unlike in org-roam, @strong{child ID nodes of an excluded node are not excluded!}  The @samp{org-node-filter-fn} applies its ruleset to each node in isolation.

However, nodes in isolation do still have inherited tags.  So you can exploit that, or the outline path or file name.

Really, filename!  Even though a big selling point of IDs is that you avoid depending on filenames, it's pragmatic to let up on principles sometimes :-)  It works well for me to filter out any file or directory that happens to contain "archive" in the name:

@lisp
(setq org-node-filter-fn
      (lambda (node)
        (not (string-search "archive" (org-node-get-file-path node)))))
@end lisp

Or put something like @samp{#+filetags: :hide_node:} at the top of each file, and set:

@lisp
(setq org-node-filter-fn
      (lambda (node)
        (not (member "hide_node"
                     (org-node-get-tags-with-inheritance node))))))
@end lisp

@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, they may take this in stride.  Me, I never felt confident using a second-order abstraction over an already leaky abstraction I didn't fully understand.

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)}:

@lisp
(setq org-capture-templates
      '(("i" "Capture 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
         :jump-to-captured t
         :immediate-finish t)

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

With that done, 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 be confusing if I describe it -- better you try and see if you like.

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

To complete words at point into known node titles:

@lisp
(org-node-complete-at-point-mode)
(setq org-roam-completion-everywhere nil) ;; Prevent Roam's variant
@end lisp

@node FAQ Any analogue to @samp{org-roam-node-display-template}?
@section FAQ: Any analogue to @samp{org-roam-node-display-template}?

Want to customize how the nodes look in the minibuffer?

Configure @samp{org-node-affixation-fn}:

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


A related variable is @samp{org-node-alter-candidates}.  Read its docstring.

@node Grep
@section Grep

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

@lisp
(keymap-set global-map "M-s M-g" #'org-node-grep)
@end lisp

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

Say there's a link to a web URL, 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, clicking on that link, 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 for now.  Org-node tries to be very fast, often nulling @samp{file-name-handler-alist}, which TRAMP needs.

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

@node Limitation Encryption
@section Limitation: Encryption

Encrypted nodes probably won't be found.  As with TRAMP, file an issue.

@node Limitation Unique titles
@section Limitation: Unique titles

If two ID-nodes exist with the same title, one of them disappears from minibuffer completions.

That's just the nature of completion.  Much can be said for embracing the uniqueness constraint, 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, 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, which resolves most conflicts given that the most likely source of conflict is subheadings in disparate files, that happen to be named the same.  @uref{https://fosstodon.org/@@nickanderson/112249581810196258, Some people} make this trick part of their workflow.

NB: for users of @samp{org-node-complete-at-point-mode}, this workaround won't help those completions.  With some luck you'll rarely insert the wrong link, 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, but not fully the aftermarket @uref{https://github.com/jkitchin/org-ref, org-ref} &citations that emulate @LaTeX{} look-and-feel, because it would double the time taken by @samp{M-x org-node-reset}.

What works is bracketed Org-ref v3 citations that start with "cite", e.g. @samp{[[citep:...]]}, @samp{[[citealt:...]]}, @samp{[[citeauthor:...]]}, since org-node-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", nor plain @samp{citep:...} since it is not wrapped in brackets.

If you need more of Org-ref, 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
Get your elbows dirty and try to revive the archived branch @uref{https://github.com/meedstrom/org-node/branches, "orgref"}, see @uref{https://github.com/meedstrom/org-node/commit/90b0e503ac75428a5d3ca6a4c8c51b5e075064d3, relevant commit}.
@end itemize

@node Toolbox
@section Toolbox

Basic commands:

@itemize
@item
@samp{org-node-find}
@item
@samp{org-node-insert-link}
@item
@samp{org-node-insert-transclusion}
@item
@samp{org-node-insert-transclusion-as-subtree}
@item
@samp{org-node-visit-random}
@item
@samp{org-node-refile}
@item
@samp{org-node-seq-dispatch}
@itemize
@item
Browse node series -- see README
@end itemize
@item
@samp{org-node-extract-subtree}
@itemize
@item
A bizarro counterpart to @samp{org-roam-extract-subtree}.  Export the subtree at point into a file-level node, @strong{leave a link in the outline parent of where the subtree was}, and show the new file as current buffer.
@end itemize
@item
@samp{org-node-nodeify-entry}
@itemize
@item
(Trivial) Give an ID to the subtree at point, and run the hook @samp{org-node-creation-hook}
@end itemize
@item
@samp{org-node-insert-heading}
@itemize
@item
(Trivial) Shortcut for @samp{org-insert-heading} + @samp{org-node-nodeify-entry}
@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-fakeroam-show-buffer}
@itemize
@item
A different way to invoke the Roam buffer: display the buffer @emph{or} refresh it if it was already visible.  And a plot twist, if it was not visible, do not refresh until the second invocation.
@end itemize
@end itemize

Rarer commands:

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

Org-node @uref{https://github.com/meedstrom/org-node/issues/8#issuecomment-2101316447, assumes all files have valid syntax}, though many of the problems reported by org-lint are survivable.
@end itemize
@item
@samp{org-node-rewrite-links-ask}
@itemize
@item
Look for link descriptions that got out of sync with the corresponding node title, 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
Also works as an after-save-hook!  Does nothing as such until you configure @samp{org-node-renames-allowed-dirs}.
@item
Please note that if your filenames have datestamp prefixes, it is important to get @samp{org-node-datestamp-format} right or it may clobber a pre-existing datestamp.  A message is printed about the rename, 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-list-reflinks}
@itemize
@item
List citations and non-ID links
@itemize
@item
Can be interesting for seeing which links have an associated node and which don't (usually, most don't)
@end itemize
@end itemize
@item
@samp{org-node-backlink-fix-all-files}
@itemize
@item
Update @samp{BACKLINKS} property in all nodes
@end itemize
@item
@samp{org-node-list-feedback-arcs}
@itemize
@item
(Requires GNU R, with R packages stringr, readr and igraph)

Explore @uref{https://en.wikipedia.org/wiki/Feedback_arc_set, feedback arcs} in your ID link network.  Can be 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: For now, it only looks for links inside the root directory that it prompts you for, and sub and sub-subdirectories and so on -- but won't find a link outside that root directory.

Like if you have Org files under /mnt linking to assets in /home, those links won't be updated.  Neither if you choose ~/org/subdir as the root directory will links in ~/org/file.org be updated.
@end itemize
@end itemize
@end itemize

@node Experimental Node sequences
@section Experimental: Node sequences

Do you already know about "daily-notes"?  Then get started with a keybinding such as:

@lisp
(keymap-set global-map "M-s s" #'org-node-seq-dispatch)
@end lisp

and configure @samp{org-node-seq-defs}.  See @uref{https://github.com/meedstrom/org-node/wiki/Configuring-series, wiki}.

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

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

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

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, only to make it extra convenient to navigate them and jump back and forth in the series.

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

Currently, defining a new node seq requires writing 5 lambdas, but once you get the hang of it, you can often reuse those lambdas.

@node Future
@subsection Future

A future version will likely bring convenient wrappers that let you define a node seq in 1-2 lines.

It's also possible we just redesign this completely.  Input welcome.  How would you like to define a node sequence?  Where should the information be stored?

@node Appendix
@chapter Appendix

@menu
* Appendix I Rosetta stone::
* Appendix II How to rollback::
@end menu

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

API cheatsheet between org-roam and org-node.

@multitable {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
@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 Get list of files
@tab @samp{(org-roam-list-files)}
@tab @samp{(org-node-list-files)}
@item Prompt user to pick a node
@tab @samp{(org-roam-node-read)}
@tab @samp{(org-node-read)}
@item Get backlink objects
@tab @samp{(org-roam-backlinks-get NODE)}
@tab @samp{(org-node-get-id-links-to NODE)}
@item Get reflink objects
@tab @samp{(org-roam-reflinks-get NODE)}
@tab @samp{(org-node-get-reflinks-to NODE)}
@item Get title
@tab @samp{(org-roam-node-title NODE)}
@tab @samp{(org-node-get-title NODE)}
@item Get title of file where NODE is
@tab @samp{(org-roam-node-file-title NODE)}
@tab @samp{(org-node-get-file-title NODE)}
@item Get title @emph{or} name of file where NODE is
@tab 
@tab @samp{(org-node-get-file-title-or-basename NODE)}
@item Get name of file where NODE is
@tab @samp{(org-roam-node-file NODE)}
@tab @samp{(org-node-get-file-path NODE)}
@item Get ID
@tab @samp{(org-roam-node-id NODE)}
@tab @samp{(org-node-get-id NODE)}
@item Get tags
@tab @samp{(org-roam-node-tags NODE)}
@tab @samp{(org-node-get-tags-with-inheritance NODE)}
@item Get local tags
@tab 
@tab @samp{(org-node-get-tags-local NODE)}
@item Get outline level
@tab @samp{(org-roam-node-level NODE)}
@tab @samp{(org-node-get-level NODE)}
@item Get whether this is a subtree
@tab @samp{(=< 0 (org-roam-node-level NODE))}
@tab @samp{(org-node-get-is-subtree NODE)}
@item Get char position
@tab @samp{(org-roam-node-point NODE)}
@tab @samp{(org-node-get-pos NODE)}
@item Get properties
@tab @samp{(org-roam-node-properties NODE)}
@tab @samp{(org-node-get-properties NODE)}, only includes explicit properties
@item Get subtree TODO state
@tab @samp{(org-roam-node-todo NODE)}
@tab @samp{(org-node-get-todo NODE)}
@item Get subtree SCHEDULED
@tab @samp{(org-roam-node-scheduled NODE)}
@tab @samp{(org-node-get-scheduled NODE)}
@item Get subtree DEADLINE
@tab @samp{(org-roam-node-deadline NODE)}
@tab @samp{(org-node-get-deadline NODE)}
@item Get subtree priority
@tab @samp{(org-roam-node-priority NODE)}
@tab @samp{(org-node-get-priority NODE)}
@item Get outline-path
@tab @samp{(org-roam-node-olp NODE)}
@tab @samp{(org-node-get-olp NODE)}
@item Get @samp{ROAM_REFS}
@tab @samp{(org-roam-node-refs NODE)}
@tab @samp{(org-node-get-refs NODE)}
@item Get @samp{ROAM_ALIASES}
@tab @samp{(org-roam-node-aliases NODE)}
@tab @samp{(org-node-get-aliases NODE)}
@item Get @samp{ROAM_EXCLUDE}
@tab 
@tab @samp{(assoc "ROAM_EXCLUDE" (org-node-get-properties 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}, 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+:
@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 inside the cloned repo.

@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, 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

@menu
* Match fakeroam version::
* What version is installed?::
@end menu

@node Match fakeroam version
@subsection Match fakeroam version

The extension @uref{https://github.com/meedstrom/org-node-fakeroam, org-node-fakeroam} has been tightly coupled with contemporary versions of org-node, but hopefully it will warn about any version mismatch at load-time.

Just in case, the release history:
@itemize
@item
2024-10-05: org-node v1.5 and org-node-fakeroam v1.3
@item
2024-10-24: org-node v1.6 and org-node-fakeroam v1.4
@item
2024-10-27: org-node v1.7 and org-node-fakeroam v1.5
@item
2024-11-14: org-node v1.8
@item
2024-11-18: org-node v1.9 and org-node-fakeroam v1.6
@item
2024-12-29: org-node-fakeroam v1.7
@end itemize

@node What version is installed?
@subsection What version is installed?

This info depends on your package manager.  I do not embed version in the source code.

@itemize
@item
With Elpaca
@itemize
@item
@samp{M-x elpaca-info RET org-node RET}
@end itemize
@item
With Straight and Borg:
@itemize
@item
go to @samp{M-x find-library RET org-node RET}
@item
then run the Git command @code{git log --tags --pretty="%ci %d"}
@end itemize
@item
With the built-in package.el
@itemize
@item
unfortunately@dots{} MELPA does not make it easy (their version numbering is @uref{https://github.com/melpa/melpa/issues/2955#issuecomment-1874169295, planned to improve}).  For now, cross-correlate with the date.
@end itemize
@end itemize

@bye