(feat): move fuzzy links to roam: links (#1105)

This commit is contained in:
Jethro Kuan
2020-09-23 17:58:18 +08:00
committed by GitHub
parent da6af3a468
commit ae32c465de
8 changed files with 539 additions and 384 deletions

View File

@ -544,10 +544,46 @@ The Org-roam buffer displays backlinks for the currently active Org-roam note.
The ~no-delete-window~ parameter for the org-roam buffer. Setting it to ~'t~ prevents the window from being deleted when calling ~delete-other-windows~.
** Org-roam Links
** Org-roam Files
Org-roam links are regular ~file:~ links in Org-mode. By default, links are
inserted with the title as the link description with ~org-roam-insert~.
Org-roam files are created and prefilled using Org-roam's templating
system. The templating system is customizable (see [[*The Templating System][The Templating System]]).
* Inserting Links
The preferred mode of linking is via ~file~ links to files, and ~id~ links for
headlines. This maintains the strongest compatibility with Org-mode, ensuring
that the links still function without Org-roam, and work well exporting to other
backends.
~file~ links can be inserted via ~org-roam-insert~. Links to headlines can be
inserted by navigating to the desired headline and calling ~org-store-link~.
This will create an ID for the headline if it does not already exist, and
populate the Org-roam database. The link can then be inserted via
~org-insert-link~.
An alternative mode of insertion is using Org-roam's ~roam~ links. Org-roam
registers this link type, and interprets the path as follows:
- ~[[roam:title]]~ :: links to an Org-roam file with title or alias "title"
- ~[[roam:*headline]]~ :: links to the headline "headline" in the current Org-roam file
- ~[[roam:title*headline]]~ :: links to the headline "headline" in the Org-roam file with title or alias "title"
~roam~ links support auto-completion via ~completion-at-point~: simply call
~completion-at-point~ within a roam link. Users of ~company-mode~ may want to
prepend ~company-capf~ to the beginning of variable ~company-backends~.
To easily insert ~roam~ links, one may wish to use a package like [[https://github.com/emacsorphanage/key-chord/][key-chord]]. In the following example, typing "[[" will insert a stub ~roam~ link:
#+BEGIN_SRC emacs-lisp
(key-chord-define org-mode-map "[[" #'my/insert-roam-link)
(defun my/insert-roam-link ()
"Inserts an Org-roam link."
(interactive)
(insert "[[roam:]]")
(backward-char 2))
#+END_SRC
- User Option: org-roam-link-title-format
@ -557,10 +593,18 @@ inserted with the title as the link description with ~org-roam-insert~.
If your version of Org is at least ~9.2~, consider styling the link differently,
by customizing the ~org-roam-link~, and ~org-roam-link-current~ faces.
** Org-roam Files
- User Option: org-roam-completion-ignore-case
Org-roam files are created and prefilled using Org-roam's templating
system. The templating system is customizable (see [[*The Templating System][The Templating System]]).
When non-nil, the ~roam~ link completions are ignore case. For example,
calling ~completion-at-point~ within ~[[roam:fo]]~ will present a completion
for a file with title "Foo". Defaults to ~t~.
- User Option: org-roam-link-auto-replace
When non-nil, ~roam~ links will be replaced with ~file~ or ~id~ links when
they are navigated to, and on file save, when a match is found. This is
desirable to maintain compatibility with vanilla Org, but resolved links are
harder to edit. Defaults to ~t~.
* Navigating Around

View File

@ -72,6 +72,7 @@ General Public License for more details.
* Anatomy of an Org-roam File::
* The Templating System::
* Concepts and Configuration::
* Inserting Links::
* Navigating Around::
* Encryption::
* Graphing::
@ -108,7 +109,6 @@ Concepts and Configuration
* Directories and Files::
* The Org-roam Buffer::
* Org-roam Links::
* Org-roam Files::
Navigating Around
@ -294,9 +294,9 @@ To use Melpa:
@end itemize
@lisp
(require 'package)
(add-to-list 'package-archives
'("melpa" . "http://melpa.org/packages/") t)
(require 'package)
(add-to-list 'package-archives
'("melpa" . "http://melpa.org/packages/") t)
@end lisp
@itemize
@ -305,9 +305,9 @@ To use Melpa-Stable:
@end itemize
@lisp
(require 'package)
(add-to-list 'package-archives
'("melpa-stable" . "http://stable.melpa.org/packages/") t)
(require 'package)
(add-to-list 'package-archives
'("melpa-stable" . "http://stable.melpa.org/packages/") t)
@end lisp
Org-roam also depends on a recent version of Org, which can be obtained in Org's
@ -321,14 +321,14 @@ Once you have added your preferred archive, you need to update the
local package list using:
@example
M-x package-refresh-contents RET
M-x package-refresh-contents RET
@end example
Once you have done that, you can install Org-roam and its dependencies
using:
@example
M-x package-install RET org-roam RET
M-x package-install RET org-roam RET
@end example
Now see @ref{Post-Installation Tasks}.
@ -340,7 +340,7 @@ Users of Debian 11 or later or Ubuntu 20.10 or later can simply install Org-roam
using Apt:
@example
apt-get install elpa-org-roam
apt-get install elpa-org-roam
@end example
Org-roam will then be autoloaded into Emacs.
@ -356,7 +356,7 @@ Org-roam uses @code{emacsql-sqlite3}, which requires @code{sqlite3} to be locate
operating system. You can verify that this is the case by executing:
@lisp
(executable-find "sqlite3")
(executable-find "sqlite3")
@end lisp
If you have @code{sqlite3} installed, and @code{executable-find} still reports @code{nil}, then
@ -365,7 +365,7 @@ variable @code{exec-path}. You may rectify this by manually adding the path with
your Emacs configuration:
@lisp
(add-to-list 'exec-path "path/to/sqlite3")
(add-to-list 'exec-path "path/to/sqlite3")
@end lisp
@node Getting Started
@ -478,10 +478,10 @@ The aliases are space-delimited, and can be multi-worded using quotes
Take for example the following org file:
@example
#+title: World War 2
#+roam_alias: "WWII" "World War II"
#+title: World War 2
#+roam_alias: "WWII" "World War II"
* Headline
* Headline
@end example
@multitable {aaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaa}
@ -552,8 +552,8 @@ Refs are unique identifiers for files. Each note can only have 1 ref.
For example, a note for a website may contain a ref:
@example
#+title: Google
#+roam_key: https://www.google.com/
#+title: Google
#+roam_key: https://www.google.com/
@end example
These keys come in useful for when taking website notes, using the
@ -563,8 +563,8 @@ Alternatively, add a ref for notes for a specific paper, using its
@uref{https://github.com/jkitchin/org-ref, org-ref} citation key:
@example
#+title: Neural Ordinary Differential Equations
#+roam_key: cite:chen18_neural_ordin_differ_equat
#+title: Neural Ordinary Differential Equations
#+roam_key: cite:chen18_neural_ordin_differ_equat
@end example
The backlinks buffer will show any cites of this key: e.g.
@ -617,11 +617,11 @@ To demonstrate the additions made to org-capture templates. Here, we walkthrough
the default template, reproduced below.
@lisp
("d" "default" plain (function org-roam--capture-get-point)
"%?"
:file-name "%<%Y%m%d%H%M%S>-$@{slug@}"
:head "#+title: $@{title@}\n"
:unnarrowed t)
("d" "default" plain (function org-roam--capture-get-point)
"%?"
:file-name "%<%Y%m%d%H%M%S>-$@{slug@}"
:head "#+title: $@{title@}\n"
:unnarrowed t)
@end lisp
@enumerate
@ -687,11 +687,11 @@ advantage of org-mode's @code{%(EXP)} template expansion to call @code{format-ti
directly to provide its third argument to specify UTC@.
@lisp
("d" "default" plain (function org-roam--capture-get-point)
"%?"
:file-name "%(format-time-string \"%Y-%m-%d--%H-%M-%SZ--$@{slug@}\" (current-time) t)"
:head "#+title: $@{title@}\n"
:unnarrowed t)
("d" "default" plain (function org-roam--capture-get-point)
"%?"
:file-name "%(format-time-string \"%Y-%m-%d--%H-%M-%SZ--$@{slug@}\" (current-time) t)"
:head "#+title: $@{title@}\n"
:unnarrowed t)
@end lisp
@node Concepts and Configuration
@ -707,7 +707,6 @@ All of Org-roam's customization options can be viewed via
@menu
* Directories and Files::
* The Org-roam Buffer::
* Org-roam Links::
* Org-roam Files::
@end menu
@ -773,11 +772,53 @@ User Option: org-roam-buffer-no-delete-other-windows
The @code{no-delete-window} parameter for the org-roam buffer. Setting it to @code{'t} prevents the window from being deleted when calling @code{delete-other-windows}.
@end itemize
@node Org-roam Links
@section Org-roam Links
@node Org-roam Files
@section Org-roam Files
Org-roam links are regular @code{file:} links in Org-mode. By default, links are
inserted with the title as the link description with @code{org-roam-insert}.
Org-roam files are created and prefilled using Org-roam's templating
system. The templating system is customizable (see @ref{The Templating System}).
@node Inserting Links
@chapter Inserting Links
The preferred mode of linking is via @code{file} links to files, and @code{id} links for
headlines. This maintains the strongest compatibility with Org-mode, ensuring
that the links still function without Org-roam, and work well exporting to other
backends.
@code{file} links can be inserted via @code{org-roam-insert}. Links to headlines can be
inserted by navigating to the desired headline and calling @code{org-store-link}.
This will create an ID for the headline if it does not already exist, and
populate the Org-roam database. The link can then be inserted via
@code{org-insert-link}.
An alternative mode of insertion is using Org-roam's @code{roam} links. Org-roam
registers this link type, and interprets the path as follows:
@table @asis
@item @code{[[roam:title]]}
links to an Org-roam file with title or alias ``title''
@item @code{[[roam:*headline]]}
links to the headline ``headline'' in the current Org-roam file
@item @code{[[roam:title*headline]]}
links to the headline ``headline'' in the Org-roam file with title or alias ``title''
@end table
@code{roam} links support auto-completion via @code{completion-at-point}: simply call
@code{completion-at-point} within a roam link. Users of @code{company-mode} may want to
prepend @code{company-capf} to the beginning of variable @code{company-backends}.
To easily insert @code{roam} links, one may wish to use a package like @uref{https://github.com/emacsorphanage/key-chord/, key-chord}. In the following example, typing ``[['' will insert a stub @code{roam} link:
@lisp
(key-chord-define org-mode-map "[[" #'my/insert-roam-link)
(defun my/insert-roam-link ()
"Inserts an Org-roam link."
(interactive)
(insert "[[roam:]]")
(backward-char 2))
@end lisp
@itemize
@item
@ -788,14 +829,23 @@ special indicators for Org-roam links. Defaults to @code{"%s"}.
If your version of Org is at least @code{9.2}, consider styling the link differently,
by customizing the @code{org-roam-link}, and @code{org-roam-link-current} faces.
@item
User Option: org-roam-completion-ignore-case
When non-nil, the @code{roam} link completions are ignore case. For example,
calling @code{completion-at-point} within @code{[[roam:fo]]} will present a completion
for a file with title ``Foo''. Defaults to @code{t}.
@item
User Option: org-roam-link-auto-replace
When non-nil, @code{roam} links will be replaced with @code{file} or @code{id} links when
they are navigated to, and on file save, when a match is found. This is
desirable to maintain compatibility with vanilla Org, but resolved links are
harder to edit. Defaults to @code{t}.
@end itemize
@node Org-roam Files
@section Org-roam Files
Org-roam files are created and prefilled using Org-roam's templating
system. The templating system is customizable (see @ref{The Templating System}).
@node Navigating Around
@chapter Navigating Around
@ -906,10 +956,10 @@ a function accepting a single argument: the graph file path.
If you are using WSL2 and would like to open the graph in Windows, you can use the second option to set the browser and network file path:
@lisp
(setq org-roam-graph-viewer
(lambda (file)
(let ((org-roam-graph-viewer "/mnt/c/Program Files/Mozilla Firefox/firefox.exe"))
(org-roam-graph--open (concat "file://///wsl$/Ubuntu" file)))))
(setq org-roam-graph-viewer
(lambda (file)
(let ((org-roam-graph-viewer "/mnt/c/Program Files/Mozilla Firefox/firefox.exe"))
(org-roam-graph--open (concat "file://///wsl$/Ubuntu" file)))))
@end lisp
@end itemize
@ -968,7 +1018,7 @@ are excluded.
@end itemize
@example
(setq org-roam-graph-exclude-matcher '("private" "dailies"))
(setq org-roam-graph-exclude-matcher '("private" "dailies"))
@end example
This setting excludes all files whose path contain ``private'' or ``dailies''.
@ -981,7 +1031,7 @@ its interactive commands. The default setting uses Emacs' standard
@code{completing-read} mechanism.
@lisp
(setq org-roam-completion-system 'default)
(setq org-roam-completion-system 'default)
@end lisp
If you have installed Helm or Ivy, and have their modes enabled, under the
@ -991,7 +1041,7 @@ In the rare scenario where you use Ivy globally, but prefer @uref{https://emacs-
commands, set:
@lisp
(setq org-roam-completion-system 'helm)
(setq org-roam-completion-system 'helm)
@end lisp
Other options include @code{'ido}, and @code{'ivy}.
@ -1184,7 +1234,7 @@ or as a keybinding in @code{qutebrowser} in , using the @code{config.py} file (s
@uref{https://github.com/qutebrowser/qutebrowser/blob/master/doc/help/configuring.asciidoc, Configuring qutebrowser}):
@example
config.bind("<Ctrl-r>", "open javascript:location.href='org-protocol://roam-ref?template=r&ref='+encodeURIComponent(location.href)+'&title='+encodeURIComponent(document.title)")
config.bind("<Ctrl-r>", "open javascript:location.href='org-protocol://roam-ref?template=r&ref='+encodeURIComponent(location.href)+'&title='+encodeURIComponent(document.title)")
@end example
where @code{template} is the template key for a template in
@ -1255,7 +1305,7 @@ operations. To reduce the number of garbage collection processes, one may set
@code{org-roam-db-gc-threshold} to a high value (such as @code{most-positive-fixnum}):
@lisp
(setq org-roam-db-gc-threshold most-positive-fixnum)
(setq org-roam-db-gc-threshold most-positive-fixnum)
@end lisp
@node Appendix
@ -1319,9 +1369,9 @@ operations. To reduce the number of garbage collection processes, one may set
@code{winner-mode} can be used as a simple version of browser history for Org-roam. Each click through org-roam links (from both Org files and the backlinks buffer) causes changes in window configuration, which can be undone and redone using @code{winner-mode}. To use @code{winner-mode}, simply enable it, and bind the appropriate interactive functions:
@lisp
(winner-mode +1)
(define-key winner-mode-map (kbd "<M-left>") #'winner-undo)
(define-key winner-mode-map (kbd "<M-right>") #'winner-redo)
(winner-mode +1)
(define-key winner-mode-map (kbd "<M-left>") #'winner-undo)
(define-key winner-mode-map (kbd "<M-right>") #'winner-redo)
@end lisp
@ -1343,15 +1393,15 @@ versions of a tracked Org-roam note.
@uref{https://jblevins.org/projects/deft/, Deft} provides a nice interface for browsing and filtering org-roam notes.
@lisp
(use-package deft
:after org
:bind
("C-c n d" . deft)
:custom
(deft-recursive t)
(deft-use-filter-string-for-filename t)
(deft-default-extension "org")
(deft-directory "/path/to/org-roam-files/"))
(use-package deft
:after org
:bind
("C-c n d" . deft)
:custom
(deft-recursive t)
(deft-use-filter-string-for-filename t)
(deft-default-extension "org")
(deft-directory "/path/to/org-roam-files/"))
@end lisp
If the title of the Org file is not the first line, you might not get
@ -1360,29 +1410,29 @@ functionality. Here I'm using
@uref{https://github.com/raxod502/el-patch, el-patch}:
@lisp
(use-package el-patch
:straight (:host github
:repo "raxod502/el-patch"
:branch "develop"))
(use-package el-patch
:straight (:host github
:repo "raxod502/el-patch"
:branch "develop"))
(eval-when-compile
(require 'el-patch))
(eval-when-compile
(require 'el-patch))
(use-package deft
;; same as above...
:config/el-patch
(defun deft-parse-title (file contents)
"Parse the given FILE and CONTENTS and determine the title.
If `deft-use-filename-as-title' is nil, the title is taken to
be the first non-empty line of the FILE. Else the base name of the FILE is
used as title."
(el-patch-swap (if deft-use-filename-as-title
(deft-base-filename file)
(let ((begin (string-match "^.+$" contents)))
(if begin
(funcall deft-parse-title-function
(substring contents begin (match-end 0))))))
(org-roam--get-title-or-slug file))))
(use-package deft
;; same as above...
:config/el-patch
(defun deft-parse-title (file contents)
"Parse the given FILE and CONTENTS and determine the title.
If `deft-use-filename-as-title' is nil, the title is taken to
be the first non-empty line of the FILE. Else the base name of the FILE is
used as title."
(el-patch-swap (if deft-use-filename-as-title
(deft-base-filename file)
(let ((begin (string-match "^.+$" contents)))
(if begin
(funcall deft-parse-title-function
(substring contents begin (match-end 0))))))
(org-roam--get-title-or-slug file))))
@end lisp
The Deft interface can slow down quickly when the number of files get
@ -1398,14 +1448,14 @@ provides better journaling capabilities, and a nice calendar interface
to see all dated entries.
@lisp
(use-package org-journal
:bind
("C-c n j" . org-journal-new-entry)
:custom
(org-journal-date-prefix "#+title: ")
(org-journal-file-format "%Y-%m-%d.org")
(org-journal-dir "/path/to/org-roam-files/")
(org-journal-date-format "%A, %d %B %Y"))
(use-package org-journal
:bind
("C-c n j" . org-journal-new-entry)
:custom
(org-journal-date-prefix "#+title: ")
(org-journal-file-format "%Y-%m-%d.org")
(org-journal-dir "/path/to/org-roam-files/")
(org-journal-date-format "%A, %d %B %Y"))
@end lisp
@node Note-taking Add-ons
@ -1432,12 +1482,12 @@ These are some plugins that make note-taking in Org-mode more enjoyable.
@end float
@lisp
(use-package org-download
:after org
:bind
(:map org-mode-map
(("s-Y" . org-download-screenshot)
("s-y" . org-download-yank))))
(use-package org-download
:after org
:bind
(:map org-mode-map
(("s-Y" . org-download-screenshot)
("s-y" . org-download-yank))))
@end lisp
@node mathpixel
@ -1451,12 +1501,12 @@ These are some plugins that make note-taking in Org-mode more enjoyable.
@end float
@lisp
(use-package mathpix.el
:straight (:host github :repo "jethrokuan/mathpix.el")
:custom ((mathpix-app-id "app-id")
(mathpix-app-key "app-key"))
:bind
("C-x m" . mathpix-screenshot))
(use-package mathpix.el
:straight (:host github :repo "jethrokuan/mathpix.el")
:custom ((mathpix-app-id "app-id")
(mathpix-app-key "app-key"))
:bind
("C-x m" . mathpix-screenshot))
@end lisp
@node Org-noter / Interleave
@ -1503,8 +1553,8 @@ variable using directory-local variables. This is what @code{.dir-locals.el} may
contain:
@lisp
((nil . ((org-roam-directory . ".")
(org-roam-db-location . "./org-roam.db"))))
((nil . ((org-roam-directory . ".")
(org-roam-db-location . "./org-roam.db"))))
@end lisp
All files within that directory will be treated as their own separate