8000 GitHub - meedstrom/org-node: A notetaking system like Roam using Emacs Org-mode
[go: up one dir, main page]
More Web Proxy on the site http://driver.im/
Skip to content

A notetaking system like Roam using Emacs Org-mode

License

Notifications You must be signed in to change notification settings

meedstrom/org-node

Repository files navigation

org-node

Packaging status

News for v3

A lot of code has been spun into a new library https://github.com/meedstrom/org-mem, now a dependency. Reduces codebase by 30%.

Not much new features – mainly a change of plumbing.

Update initfiles when you can. Direct renames:

Old user optionNew user option
org-node-extra-id-dirsorg-mem-watch-dirs
org-node-extra-id-dirs-excludeorg-mem-watch-dirs-exclude
org-node-link-typesorg-mem-seek-link-types
org-node-warn-title-collisionsorg-mem-do-warn-title-collisions

Also enable org-mem-updater-mode. Here’s a new basic-install snippet:

(use-package org-node
  :config
  (setq org-mem-do-sync-with-org-id t)
  (org-mem-updater-mode)
  (org-node-cache-mode))

Node seqs, if you use them, now require turning on explicitly.

(org-node-seq-mode)

For reference, check out the full list of obsoletions near the bottom of file org-node-changes.el.

A silent obsoletion: links are not plists anymore, but plist-get is unhelpfully polite and returns nil when given invalid input. Talk about weak typing! Anyway, use e.g. (org-mem-link-pos LINK) instead of (plist-get LINK :pos). Also, a link is a citation if (org-mem-link-citation-p LINK).

Other changes you may notice:

  • Command org-node-reset (now aliased to org-mem-reset) has become a bit slower, because it scans all subtrees in all files rather than only ID-nodes. Org-node itself does not use that information, but org-mem aims to be useful in a wider domain.
  • Package org-node-fakeroam deprecated
    • New built-in: org-node-roam-accelerator-mode
    • New built-in: org-mem-roamy-db-mode

Background

What’s all this

I like org-roam but found it too slow, so I made quickroam. And that idea spun off into this package, a standalone thing. It may also be easier to pick up than org-roam.

  • 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.

    In pursuit of being “just org-id”, this package has no equivalent setting to org-roam-directory – it just looks up the org-id-locations table.

  • If you were not using org-roam, maybe think of it as somewhat like 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.

What’s a “node”?

My life can be divided into two periods ”before org-roam” and ”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 find and build on my own work, instead of recreating it all the time.

At the core, all the “notetaking packages” (orgrr/zk/zetteldeft/org-roam/denote/howm/minaduki/…) 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.

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 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.

Features

A comparison of three systems that all permit relying on org-id and don’t lock you into the concept of “one-note-per-file”.

Featureorg-roamorg-nodeorg-super-links
Backlinksyesyesyes
Node search and insertyesyes– (suggests org-ql)
Node aliasesyesyes
Node exclusionyeslimitednot applicable
Refileyesyes
Rich backlinks bufferyesyes
Customize how backlinks shownyesyesyes
Reflinksyesyes
Ref searchyesyes (as aliases)not applicable
Org 9.5 @citations as refsyesyesnot applicable
Support org-ref v3yeslimitednot applicable
Support org-ref v2yesnot applicable
Work thru org-roam-captureyesyes?
Work thru org-captureyes?
Daily-nodesyesyes
Node sequencesyes
Show backlinks in same windowyesyes
Cooperate with org-super-linksyesnot applicable
Fix link descriptionsyes
List dead linksyes
Rename file when title changesyes
Warn about duplicate titlesyes
Principled “related-section”yesyes
Untitled notes
org-protocol extensionyes
Support roam: linksyes– (wontfix)
Can have separate note pilesyes– (wontfix)not applicable
Some query-able cacheyesyes
Async cache rebuildyesnot applicable
Time to cache my 3000 nodes2m 48s0m 02snot applicable
Time to save file w/ 400 nodes5–10sinstant?
Time to open minibuffer1–3sinstantnot applicable

Setup

Install

Assuming your package manager knows about MELPA, add this initfile snippet:

(use-package org-node
  :config
  (setq org-mem-do-sync-with-org-id t) ; optional
  (setq org-mem-watch-dirs (list "~/org")) ; optional
  (org-mem-updater-mode)
  (org-node-cache-mode))

If you’re coming here from org-roam, try this instead:

(use-package org-node
  :config
  (setq org-node-creation-fn #'org-node-new-via-roam-capture)
  (setq org-node-slug-fn #'org-node-slugify-like-roam-default)
  (setq org-node-datestamp-format "%Y%m%d%H%M%S-")
  (setq org-mem-do-sync-with-org-id t)
  (setq org-mem-watch-dirs
        (list "~/org-roam/")) ;; Your org-roam-directory here
  (org-mem-updater-mode)
  (org-node-cache-mode)
  (org-node-roam-accelerator-mode))

An update broke things?

See How to rollback at the end of this readme.

Can’t find any nodes?

See Manage org-id-locations.

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.

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

To browse config options, type M-x customize-group RET org-node.

Final tip: there’s 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!

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, that’s exactly what it is. Imagine seeing that, all the time. The following sections outline two general ways to do so.

Backlink solution 1: displayed in a separate window

Option 1A: Reuse the org-roam buffer

You can use the org-roam buffer without the rest of org-roam. Enable:

(org-node-roam-accelerator-mode)

Option 2A: Use the org-node-context buffer

Org-node ships a complete rewrite of the org-roam buffer.

Add to initfiles:

(org-node-context-follow-mode) ;; optional behavior

;; Example keybindings
(keymap-set org-mode-map "M-s M-t" #'org-node-context-toggle)
;; if your window mgmt style is constantly lose all windows
(keymap-set global-map "M-s M-r" #'org-node-context-raise)

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.

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

Option 2A: Automatic :BACKLINKS: property

Add to i 8000 nitfiles:

(setq org-node-backlink-do-drawers nil)
(org-node-backlink-mode)

For a first-time run, type M-x org-node-backlink-mass-update-props. (Don’t worry if you change your mind; undo with M-x org-node-backlink-mass-delete-props.)

NOTE 1: To be clear, this mode never generates new IDs. That’s your own business. This only adds/edits :BACKLINKS: properties.

That means not all links create a backlink, only links located in an entry that has or inherits an ID. After all, there must be something to link back to.

NOTE 2: People who prefer to hard-wrap text, instead of enabling visual-line-mode or similar, may prefer Option 2B.

Option 2B: Automatic :BACKLINKS:...:END: drawer

Same as Option 2A, but uses a multiline drawer.

For a first-time run, type M-x org-node-backlink-mass-update-drawers. (Don’t worry if you change your mind; undo with M-x org-node-mass-delete-drawers.)

Then add to initfiles:

(org-node-backlink-mode)

Option 2C: Semi-automatic :BACKLINKS:...:END: drawer

If you were previously using org-super-links, you can continue letting it manage its drawers, and leave org-node out of the matter.

Just add to initfiles:

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

You may find these tools useful:

  • 1. You can list any dead forward-links to fix them manually:

    M-x org-node-list-dead-links

  • 2. You can add all missing backlinks in bulk:

    M-x org-node-backlink-mass-update-drawers

The second command may be useful as a starting point if you’re new to org-super-links, pre-populating the notes you already have.

However, when you have pre-existing drawers… 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 may re-sort your backlinks and re-format their appearance into something you don’t want; double-check the following options:

  • org-node-backlink-drawer-sorter
  • org-node-backlink-drawer-formatter

Finally, lines that contain no Org link such as [[id:1234][Title]] are deleted, which would mean destroying any other info within. Same if a backlink is stale and no longer valid.

Misc

Manage org-id-locations

Ever run into “ID not found” situations? Here’s an extra way to feed data to org-id, as I find clumsy the built-in options.

(setq org-mem-do-sync-with-org-id t)
(setq org-mem-watch-dirs ;; Configure me
      '("~/org/"
        "~/Syncthing/"
        "/mnt/stuff/"))

Do a M-x org-mem-reset and see if it can find your notes now.

Undoing an org-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 a line in org-roam-id.el that causes org-id to preferentially look up the org-roam DB instead of org-id’s own table!

Either revert that with the following snippet, or simply delete the DB (often located at “~/.emacs.d/org-roam.db”).

;; Undo an org-roam override
(with-eval-after-load 'org-roam-id
  (org-link-set-parameters
   ;; This was default value at least from Org 9.1 to 9.7+
   "id" :follow #'org-id-open :store #'org-id-store-link-maybe))

Org-capture

You may have heard that org-roam has a set of meta-capture templates: the 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.

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

The secret sauce is (function org-node-capture-target):

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

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

(setq org-node-creation-fn #'org-capture)

That last optional functionality may be confusing if I describe it – better you give it a spin and see if you like.

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 anything tagged “project” or perhaps anything that has a TODO state. Here’s a way to exclude both, plus anything with a :ROAM_EXCLUDE: property:

(setq org-node-filter-fn
      (lambda (node)
        (not
         (or (org-mem-entry-todo-state node)
             (member "project" (org-mem-entry-tags node))
             (org-mem-entry-property "ROAM_EXCLUDE" node)))))

Or you could go with a whitelist approach, to show only nodes from a certain directory we’ll call “my-personal-wiki”:

(setq org-node-filter-fn
      (lambda (node)
        (and (string-search "/my-personal-wiki/" (org-mem-entry-file node))
             (not (org-mem-entry-property "ROAM_EXCLUDE" node)))))

(NB: if you don’t know what ROAM_EXCLUDE is, feel free to omit that rule)

Limitation: 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 :ROAM_EXCLUDE: t at the top won’t do it, because unlike in org-roam, child ID nodes of an excluded node are not excluded! The option org-node-filter-fn applies 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.

It works well for me to filter out any file or directory that happens to contain “archive” in the name:

(setq org-node-filter-fn
      (lambda (node)
        (not (string-search "archive" (org-mem-file node)))))

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

(setq org-node-filter-fn
      (lambda (node)
        (not (member "hide_node" (org-mem-tags node)))))

Completion-at-point

To complete words at point into known node titles:

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

Customize appearance

(Analogue to org-roam-node-display-template)

To customize how the nodes look in the minibuffer, configure org-node-affixation-fn:

M-x customize-variable RET org-node-affixation-fn

A related option is org-node-alter-candidates, which lets you match against the annotations as well as the title:

(setq org-node-alter-candidates t)

Grep

If you have Ripgrep installed on the computer, and Consult installed on Emacs, you can use this command to grep across all your Org files at any time.

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

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

  1. Use org-node-grep and type :math:
  2. Use embark-export (from package Embark)
  3. Use wgrep-change-to-wgrep-mode (from package wgrep)
  4. Do a query-replace (M-%) to replace all :math: with :Math:
  5. Type C-c C-c to apply the changes

Let org-open-at-point detect refs

(For background, see What are ROAM_REFS? at the end of this README.)

Say there’s a link to a web URL, and you’ve forgotten you also have a node listing that exact URL in its 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:

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

Limitation: TRAMP

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

The best way to change this is to file an issue to show you care :-)

Limitation: Encryption

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

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… there’s a workaround. Assuming you leave org-node-affixation-fn at its default setting, adding this to initfiles tends to do the trick:

(setq org-no
5D32
de-alter-candidates t)

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. Some people make this trick part of their workflow.

NB: for users of 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. (#62)

Limitation: Org-ref

Org-node supports the Org 9.5 @citations, but not fully the aftermarket org-ref &citations that emulate LaTeX look-and-feel.

What works is bracketed Org-ref v3 citations that start with “cite”, e.g. [[citep:...]], [[citealt:...]], [[citeauthor:...]], since org-mem-parser.el is able to pick them up for free.

What doesn’t work is e.g. [[bibentry:...]] since it doesn’t start with “cite”, nor plain citep:... since it is not wrapped in brackets.

If you need more of Org-ref, you have at least two options:

  • Use org-roam - see discussions on boosting its performance here and here
  • Contribute to org-mem, see function org-mem-parser--collect-links-until.

Toolbox

Basic commands:

  • org-node-find
  • org-node-insert-link
  • org-node-insert-transclusion
  • org-node-insert-transclusion-as-subtree
  • org-node-visit-random
  • org-node-refile
  • org-node-context-raise
  • org-node-context-toggle
  • org-node-seq-dispatch
    • Browse node series – see README
  • org-node-extract-subtree
    • A bizarro counterpart to org-roam-extract-subtree. Export the subtree at point into a file-level node, leave a link in the outline parent of where the subtree was, and show the new file as current buffer.
  • org-node-nodeify-entry
    • (Trivial) Give an ID to the subtree at point, and run the hook org-node-creation-hook
  • org-node-insert-heading
    • (Trivial) Shortcut for org-insert-heading + org-node-nodeify-entry
  • org-node-grep
    • (Requires consult) Grep across all known Org files.

Rarer commands:

  • org-node-rewrite-links-ask
    • Look for link descriptions that got out of sync with the corresponding node title, then prompt at each link to update it
  • org-node-rename-file-by-title
    • Auto-rename the file based on the current #+title or first heading
      • Can be run manually or placed on after-save-hook! When run as a hook, it is conservative, doing nothing until you configure org-node-renames-allowed-dirs.
      • Please note that if your filenames have datestamp prefixes, like org-roam’s default behavior of making filenames such as 20240831143302-node_title.org, it is important to get 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.

  • org-node-list-dead-links
    • List links where the destination ID could not be found
  • org-node-lint-all-files
    • Can help you fix a broken setup: it runs org-lint on all known files and generates a report of Org syntax problems, for you to correct manually.

      Org-node assumes all files have valid syntax, but many of the reported problems are survivable.

  • org-node-list-reflinks
    • List all links that aren’t id: links. Also includes citations, even though they are technically not links.
  • org-node-list-feedback-arcs
  • org-node-rename-asset-and-rewrite-links
    • Interactively rename an asset such as an image file and try to update all Org links to them. Requires wgrep.
      • NOTE: It prompts you for a certain root directory, and then only looks for links in there, 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, then those links won’t be updated. Or if you choose ~/org/some-subdir as the root directory, then links in ~/org/file.org will not update. So choose ~/org as the root even if you are renaming something in a subdir.

Rarer commands for org-node-backlink-mode:

  • org-node-backlink-mass-update-drawers
  • org-node-backlink-mass-update-props
  • org-node-backlink-mass-delete-drawers
  • org-node-backlink-mass-delete-props
  • org-node-backlink-fix-buffer

Experimental: Node sequences

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

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

and configure org-node-seq-defs. See wiki for premade examples.

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 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…

Appendix

Appendix I: Rosetta stone

API cheatsheet between org-roam and org-node.

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

Appendix II: How to rollback

Instructions to downgrade to an older version, let’s say 1.6.2.

With Quelpa:

(use-package org-node
  :quelpa (org-node :fetcher github :repo "meedstrom/org-node"
                    :branch "v1.6"))

With vc-use-package on Emacs 29:

(use-package org-node
  :vc (:fetcher github :repo "meedstrom/org-node"
       :branch "v1.6"))

With built-in :vc on Emacs 30+ (but note default value of use-package-vc-prefer-newest means you never update, since it is not aware of Git tags):

(use-package org-node
  :vc (:url "https://github.com/meedstrom/org-node"
       :branch "v1.6"))

With Elpaca as follows. Note that recipe changes only take effect after you do M-x elpaca-delete and it re-clones – the idea is that Elpaca users will prefer to do it manually.

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

…Elpaca can also target an exact version tag. Package manager of the future, it is:

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

With Straight:

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

Appendix III: Random tips

Org-roam shipped the optional (require 'org-roam-export), a patch to fix id: links in HTML export.

Good news, upstream fixed the root of the issue in 5e9953fa0! Update Org to 9.7+, then set this.

(setq org-html-prefer-user-labels t)

Appendix IV: What are ROAM_REFS?

Here’s the start of one of my note files. Note the :ROAM_REFS: line.

: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.

...

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

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

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

Org-roam calls such backlinks reflinks. In my view, adding a new word for such a similar concept just increases the air of mystery. That’s why in org-node’s context buffer, they’re just called “ref backlinks” – as opposed to “ID backlinks”.

What’s it actually used for?

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

Citations

As a special case, citation keys such as “@ioannidis2005” also work in ROAM_REFS, corresponding to Org citations like [cite:@ioannidis2005].

About

A notetaking system like Roam using Emacs Org-mode

Resources

License

Stars

Watchers

Forks

Contributors 3

  •  
  •  
  •  
0