mirror of
https://github.com/org-roam/org-roam
synced 2025-08-01 12:17:21 -05:00
(docs): update docs (#229)
This commit is contained in:
Jethro Kuan
GitHub
@ -57,7 +57,7 @@ For more detailed installation instructions (including instructions for
|
||||
Spacemacs users), please see [the installation
|
||||
documentation](https://org-roam.readthedocs.io/en/develop/installation/).
|
||||
|
||||
## Knowledge Bases using Org-Roam
|
||||
## Knowledge Bases using Org-roam
|
||||
|
||||
- [Jethro Kuan](https://braindump.jethro.dev/)
|
||||
([Source](https://github.com/jethrokuan/braindump/tree/master/org))
|
||||
|
||||
@ -1,12 +1,12 @@
|
||||
The bulk of Org-roam's functionality is built on top of vanilla
|
||||
Org-mode features. However, to support additional functionality,
|
||||
Org-roam adds several Org-roam-specific keywords. This functionality
|
||||
is not crucial to effective use of Org-roam.
|
||||
Org-mode. However, to support additional functionality, Org-roam adds
|
||||
several Org-roam-specific keywords. These functionality are not
|
||||
crucial to effective use of Org-roam.
|
||||
|
||||
## File Aliases
|
||||
|
||||
Suppose you want a note to be referred to by different names (e.g.
|
||||
"World War 2", "WWII"). You may specify such aliases using the file
|
||||
"World War 2", "WWII"). You may specify such aliases using the
|
||||
`#+ROAM_ALIAS` attribute:
|
||||
|
||||
```org
|
||||
@ -14,3 +14,27 @@ Suppose you want a note to be referred to by different names (e.g.
|
||||
#+ROAM_ALIAS: "WWII" "World War II"
|
||||
```
|
||||
|
||||
|
||||
## File Refs
|
||||
|
||||
Refs are unique identifiers for files. Each note can only have 1 ref.
|
||||
For example, a note for a website may contain a ref:
|
||||
|
||||
```org
|
||||
#+TITLE: Google
|
||||
#+ROAM_KEY: https://www.google.com/
|
||||
```
|
||||
|
||||
These keys come in useful for when taking website notes, using the
|
||||
`roam-ref` protocol (see [Roam Protocol](roam_protocol.md)).
|
||||
|
||||
Alternatively, add a ref for notes for a specific paper, using its
|
||||
[org-ref](https://github.com/jkitchin/org-ref) citation key:
|
||||
|
||||
```org
|
||||
#+TITLE: Neural Ordinary Differential Equations
|
||||
#+ROAM_KEY: cite:chen18_neural_ordin_differ_equat
|
||||
```
|
||||
|
||||
In future, the backlinks buffer will also show notes with that
|
||||
citation key.
|
||||
|
||||
@ -1,7 +1,7 @@
|
||||
---
|
||||
title: "Comparing Org-Roam With Other Packages"
|
||||
metaTitle: "Comparing Org-Roam With Other Packages"
|
||||
metaDescription: "Comparing Org-Roam With Other Packages"
|
||||
title: "Comparing Org-roam With Other Packages"
|
||||
metaTitle: "Comparing Org-roam With Other Packages"
|
||||
metaDescription: "Comparing Org-roam With Other Packages"
|
||||
---
|
||||
|
||||
# Org-brain
|
||||
|
||||
@ -1,19 +1,13 @@
|
||||
To ensure that Org-roam remains manageable, the number of
|
||||
configuration options is deliberately kept small. However, we have
|
||||
attempted to accommodate as many usage styles as possible.
|
||||
|
||||
In this section, we'll go over the main customization options
|
||||
available to Org-Roam. This section is *crucial*. We need to exploit
|
||||
the flexibility of Emacs, and mould our tools exactly to our liking.
|
||||
The number of configuration options is deliberately kept small, to
|
||||
keep the Org-roam codebase manageable. However, we attempt to
|
||||
accommodate as many usage styles as possible.
|
||||
|
||||
All of Org-roam's customization options can be viewed via `M-x
|
||||
customize-group org-roam`.
|
||||
|
||||
## Setting the Org-roam Directory
|
||||
|
||||
Perhaps the single most important variable to set is
|
||||
`org-roam-directory`. Set `org-roam-directory` to the folder
|
||||
containing all your Org files:
|
||||
Set `org-roam-directory` to the folder containing all your Org files:
|
||||
|
||||
```emacs-lisp
|
||||
(setq org-roam-directory "/path/to/org/")
|
||||
@ -24,22 +18,21 @@ considered part of the Org-roam ecosystem.
|
||||
|
||||
### Having More Than One Org-roam Directory
|
||||
|
||||
Emacs supports customizing variables by directory, so that all files
|
||||
in a directory and subdirectories will have the same custom
|
||||
settings. It does this by checking for a file named `.dir-locals.el`
|
||||
in that directory. This file can override the `org-roam-directory`
|
||||
variable and all files within that directory will be treated as
|
||||
their own separate set of Org-roam files.
|
||||
Emacs supports directory-local variables, allowing the value of
|
||||
`org-roam-directory` to be different in different directories. It does
|
||||
this by checking for a file named `.dir-locals.el`.
|
||||
|
||||
Here is an example `.dir-locals.el` file that would be placed in a
|
||||
second Org-roam directory.
|
||||
To add support for multiple directories, override the
|
||||
`org-roam-directory` variable using directory-local variables. This is
|
||||
what `.dir-locals.el` may contain:
|
||||
|
||||
```emacs-lisp
|
||||
((nil . ((org-roam-directory . "/path/to/here/"))))
|
||||
```
|
||||
|
||||
Remember to run `org-roam-build-cache` from a file within that
|
||||
directory, at least once.
|
||||
All files within that directory will be treated as their own separate
|
||||
set of Org-roam files. Remember to run `org-roam-build-cache` from a
|
||||
file within that directory, at least once.
|
||||
|
||||
## Org-roam Buffer
|
||||
|
||||
@ -59,14 +52,13 @@ frame width. For example:
|
||||
```
|
||||
|
||||
Will result in the Org-roam buffer taking up 40% of the screen width.
|
||||
I have found this to be a good number.
|
||||
|
||||
## Org-roam Links
|
||||
|
||||
By default, links are inserted with the title as the link description.
|
||||
This can make them hard to distinguish from external links. If you
|
||||
wish, you may choose add special indicators for Org-roam links by
|
||||
tweaking `org-roam-link-title-format`, for example:
|
||||
This can make them hard to distinguish from external links. You may
|
||||
choose add special indicators for Org-roam links by tweaking
|
||||
`org-roam-link-title-format`, for example:
|
||||
|
||||
```emacs-lisp
|
||||
(setq org-roam-link-title-format "R:%s")
|
||||
@ -78,90 +70,20 @@ simply style the link differently, by customizing `org-roam-link-face`
|
||||
|
||||
## Org-roam Files
|
||||
|
||||
These customization options revolve around the Org files created and
|
||||
managed by Org-roam.
|
||||
|
||||
### Automatically Creating Files Using Timestamp
|
||||
|
||||
A common hassle is ensuring that files are uniquely named within the
|
||||
Org-roam directory. Org-roam's default workflow utilizes the title of
|
||||
Org files in all of its main commands (`org-roam-insert`,
|
||||
`org-roam-find-file`). Hence, having any unique file name is a decent
|
||||
option, and the default workflow uses the timestamp as the filename.
|
||||
|
||||
Org-roam provides templating functionality via `org-roam-templates`.
|
||||
`org-roam-templates` maps a template string key to a template. Each
|
||||
template consists of two parts: (1) a function that takes the title,
|
||||
and generates a filename. (2) the template content. The templated
|
||||
content accepts two special fields: `${title}` and `${slug}`, which
|
||||
are substituted with the title and slug respectively. Org-roam ships
|
||||
with the default template, which inserts the title of the note.
|
||||
|
||||
Here's an example of customizing templates:
|
||||
|
||||
```emacs-lisp
|
||||
(defun jethro/org-roam-title-private (title)
|
||||
(let ((timestamp (format-time-string "%Y%m%d%H%M%S" (current-time)))
|
||||
(slug (org-roam--title-to-slug title)))
|
||||
(format "private-%s_%s" timestamp slug)))
|
||||
|
||||
(setq org-roam-templates
|
||||
(list (list "default" (list :file #'org-roam--file-name-timestamp-title
|
||||
:content "#+SETUPFILE:./hugo_setup.org
|
||||
#+HUGO_SECTION: zettels
|
||||
#+HUGO_SLUG: ${slug}
|
||||
#+TITLE: ${title}"))
|
||||
(list "private" (list :file #'jethro/org-roam-title-private
|
||||
:content "#+TITLE: ${title}"))))
|
||||
```
|
||||
|
||||
Here, I define a file-name function `jethro/org-roam-title-private`,
|
||||
which forms titles like `private-20200202000000-note_name`. The
|
||||
content string is simply the title. For the default template, I have
|
||||
extended it to include more boilerplate content for publishing
|
||||
purposes.
|
||||
|
||||
If you wish to be prompted to change the file name on creation, set
|
||||
`org-roam-filename-noconfirm` to `nil`:
|
||||
|
||||
```emacs-lisp
|
||||
(setq org-roam-filename-noconfirm nil)
|
||||
```
|
||||
|
||||
It is then the user's responsibility to ensure that the file names are
|
||||
unique.
|
||||
|
||||
If you prefer just the title slug as the filename (with no timestamp),
|
||||
you can use the following template:
|
||||
|
||||
```emacs-lisp
|
||||
(defun my-org-roam-no-timestamp-in-title (title)
|
||||
(let ((slug (org-roam--title-to-slug title)))
|
||||
(format "%s" slug)))
|
||||
|
||||
(setq org-roam-templates
|
||||
(list (list "default" (list :file #'my-org-roam-no-timestamp-in-title
|
||||
:content "#+TITLE: ${title}"))))
|
||||
```
|
||||
|
||||
### Autopopulating Titles
|
||||
|
||||
The default workflow uses the title of the Org file in several
|
||||
commands. The title is specified via the `#+TITLE:` attribute,
|
||||
typically near the top of the file. The option
|
||||
`org-roam-autopopulate-title` defaults to `t`. When true, the title
|
||||
attribute is automatically inserted into the files created via
|
||||
Org-roam commands. Setting it to `nil` will disable this behaviour.
|
||||
Org-roam files are created and prefilled using Org-roam's templating
|
||||
system. The templating system is customizable, and the system is
|
||||
described in detail in the [Org-roam Template](templating.md) page.
|
||||
|
||||
### Encryption
|
||||
|
||||
Encryption (via GPG) can be enabled for all new files by setting
|
||||
`org-roam-encrypt-files` to `t`. When enabled, new files are created
|
||||
with the .org.gpg extension and decryption are handled automatically
|
||||
by EasyPG. Note that this causes Emacs to ask for password when the
|
||||
cache is built (if you have an encrypted file in `org-roam-directory`)
|
||||
as well as each time a new file is created. It might be a good idea to
|
||||
cache the password in order to make this more managable.
|
||||
with the `.org.gpg` extension and decryption are handled automatically
|
||||
by EasyPG.
|
||||
|
||||
Note that Emacs will prompt for a password for encrypted files during
|
||||
cache updates if it requires reading the encrypted file. To reduce the
|
||||
number of password prompts, you may wish to cache the password.
|
||||
|
||||
## Org-roam Graph Viewer
|
||||
|
||||
@ -170,13 +92,13 @@ Org-roam generates an SVG image using
|
||||
[Graph Setup](graph_setup.md) page.
|
||||
|
||||
Org-roam tries its best to locate the Graphviz executable from your
|
||||
PATH, but if it fails to do so, you may set it manually:
|
||||
`PATH`, but if it fails to do so, you may set it manually:
|
||||
|
||||
```
|
||||
(setq org-roam-graphviz-executable "/path/to/dot")
|
||||
```
|
||||
|
||||
Org-roam also attempts to use Firefox (located on PATH) to view the
|
||||
Org-roam also attempts to use Firefox (located on `PATH`) to view the
|
||||
SVG, you may choose to set it to any compatible program:
|
||||
|
||||
```
|
||||
|
||||
@ -117,6 +117,12 @@ within Org-mode.
|
||||
[Org-ref][org-ref] does citation and bibliography management in
|
||||
Org-mode, and a great tool for scientific notes.
|
||||
|
||||
### Spaced Repetition
|
||||
|
||||
[Org-fc][org-fc] is a spaced repetition system that scales well with a
|
||||
large number of files. Other alternatives include
|
||||
[org-drill][org-drill], and [pamparam][pamparam].
|
||||
|
||||
[deft]: https://jblevins.org/projects/deft/
|
||||
[notdeft]: https://github.com/hasu/notdeft
|
||||
[org-download]: https://github.com/abo-abo/org-download
|
||||
@ -124,3 +130,6 @@ Org-mode, and a great tool for scientific notes.
|
||||
[org-noter]: https://github.com/weirdNox/org-noter
|
||||
[interleave]: https://github.com/rudolfochrist/interleave
|
||||
[org-ref]: https://github.com/jkitchin/org-ref
|
||||
[org-fc]: https://github.com/l3kn/org-fc/
|
||||
[org-drill]: https://orgmode.org/worg/org-contrib/org-drill.html
|
||||
[pamparam]: https://github.com/abo-abo/pamparam
|
||||
|
||||
66
doc/index.md
66
doc/index.md
@ -1,40 +1,62 @@
|
||||
![org-roam][org-roam-intro-image]
|
||||
|
||||
## What is Org-Roam?
|
||||
## What is Org-roam?
|
||||
|
||||
Org-roam is a rudimentary [Roam][roamresearch] replica built around
|
||||
the all-powerful [Org-mode][org].
|
||||
Org-roam is a [Roam][roamresearch] replica built around the
|
||||
all-powerful [Org-mode][org].
|
||||
|
||||
Like Roam, Org-roam offers a powerful and effortless non-hierarchical
|
||||
note-taking approach. With Org-roam, notes flow naturally, making
|
||||
note-taking fun and easy. To understand more about Roam, I recommend
|
||||
the following links:
|
||||
Org-roam is a solution for effortless non-hierarchical note-taking,
|
||||
building upon Org-mode. This solution is heavily inspired by [Roam
|
||||
Research][roamresearch]. With Org-roam, notes flow naturally, making
|
||||
note-taking fun and easy. Org-roam should also work as a plug-and-play
|
||||
solution for anyone already using Org-mode for their personal wiki.
|
||||
|
||||
- [Building a second brain in
|
||||
Roam](https://reddit.com/r/RoamResearch/comments/eho7de/building_a_second_brain_in_roamand_why_you_might)
|
||||
- [Roam: Why I Love It and How I Use
|
||||
It](https://www.nateliason.com/blog/roam)
|
||||
To understand more about Roam, a collection of links are available in
|
||||
[the appendix](notetaking_workflow.md).
|
||||
|
||||
The goal of the project is to implement core features of Roam around
|
||||
Org-mode, and eventually introduce features enabled by the Emacs
|
||||
ecosystem.
|
||||
Org-roam aims to implement the core features of Roam, leveraging the
|
||||
mature ecosystem around Org-mode where possible. Eventually, we hope
|
||||
to further introduce features enabled by the Emacs ecosystem.
|
||||
|
||||
## Why build Org-Roam?
|
||||
## Why use Org-roam?
|
||||
|
||||
With Org-roam, you:
|
||||
##### Private and Secure
|
||||
|
||||
1. Never have to leave Emacs.
|
||||
2. Can leverage all the powerful features of Org-mode: LaTeX, tables,
|
||||
and the whole to-do ecosystem (org-agenda etc.)
|
||||
3. Be in full control your second brain, and access it offline. Never
|
||||
share your data with anyone
|
||||
Edit your personal wiki completely offline, entirely in your control.
|
||||
Encrypt your notes with GPG.
|
||||
|
||||
##### Longevity
|
||||
|
||||
Unlike web solutions like Roam research, the notes are first and
|
||||
foremost plain Org-mode files -- Org-roam simply builds up an
|
||||
auxilliary database to give the personal wiki superpowers. Having your
|
||||
notes in plain-text is crucial for the longevity of your wiki. Never
|
||||
have to worry about proprietary web solutions being taken down. Edit
|
||||
your plain-text notes in notepad if all other editors cease to exist.
|
||||
|
||||
##### Free and Open-source
|
||||
|
||||
Org-roam is free and open-source, which means that if you feel unhappy
|
||||
with any part of Org-roam, you may choose to extend Org-roam, or open
|
||||
a PR.
|
||||
|
||||
##### Leverage the Org-mode Ecosystem
|
||||
|
||||
Over the years, Emacs and Org-mode has developed into a mature system
|
||||
for plain-text organization. Building upon Org-mode already puts
|
||||
Org-roam light-years ahead of many other solutions.
|
||||
|
||||
Emacs is also a fantastic interface for editing text, and we can
|
||||
inherit many of the powerful text-navigation and editing packages
|
||||
available to Emacs.
|
||||
|
||||
There are several packages that are similar to Org-roam, see the
|
||||
[Comparison](comparison.md) page for a detailed comparison.
|
||||
|
||||
## Project Status
|
||||
|
||||
As of February 2020, it is in a very early stage of development.
|
||||
As of March 2020, most of the core functionality and interfaces have
|
||||
stabilized, and a stable release is near.
|
||||
|
||||
[org-roam-intro-image]: images/org-roam-intro.png
|
||||
[roamresearch]: https://www.roamresearch.com/
|
||||
|
||||
@ -3,7 +3,7 @@
|
||||
The recommended method is using [use-package][use-package] and
|
||||
[straight][straight], or a similar package manager.
|
||||
|
||||
```
|
||||
```emacs-lisp
|
||||
(use-package org-roam
|
||||
:hook
|
||||
(after-init . org-roam-mode)
|
||||
@ -13,6 +13,7 @@ The recommended method is using [use-package][use-package] and
|
||||
:bind (:map org-roam-mode-map
|
||||
(("C-c n l" . org-roam)
|
||||
("C-c n f" . org-roam-find-file)
|
||||
("C-c n b" . org-roam-switch-to-buffer)
|
||||
("C-c n g" . org-roam-show-graph))
|
||||
:map org-mode-map
|
||||
(("C-c n i" . org-roam-insert))))
|
||||
@ -25,39 +26,48 @@ directory and add it to your load path:
|
||||
git clone https://github.com/jethrokuan/org-roam/ ~/.emacs.d/elisp/org-roam
|
||||
```
|
||||
|
||||
```
|
||||
```emacs-lisp
|
||||
(use-package org-roam
|
||||
:load-path "elisp/"
|
||||
:hook
|
||||
(after-init . org-roam-mode)
|
||||
:straight (:host github :repo "jethrokuan/org-roam" :branch "develop")
|
||||
:custom
|
||||
(org-roam-directory "/path/to/org-files/")
|
||||
:bind (:map org-roam-mode-map
|
||||
:load-path "elisp/"
|
||||
:hook
|
||||
(after-init . org-roam-mode)
|
||||
:straight (:host github :repo "jethrokuan/org-roam" :branch "develop")
|
||||
:custom
|
||||
(org-roam-directory "/path/to/org-files/")
|
||||
:bind (:map org-roam-mode-map
|
||||
(("C-c n l" . org-roam)
|
||||
("C-c n f" . org-roam-find-file)
|
||||
("C-c n b" . org-roam-switch-to-buffer)
|
||||
("C-c n g" . org-roam-show-graph))
|
||||
:map org-mode-map
|
||||
(("C-c n i" . org-roam-insert))))
|
||||
```
|
||||
|
||||
Or without use-package:
|
||||
Or without `use-package`:
|
||||
|
||||
```
|
||||
```emacs-lisp
|
||||
(add-to-list 'load-path "./elisp")
|
||||
(require 'org-roam)
|
||||
(define-key 'org-roam-mode-map (kbd "C-c n l") #'org-roam)
|
||||
(define-key 'org-roam-mode-map (kbd "C-c n f") #'org-roam-find-file)
|
||||
(define-key 'org-roam-mode-map (kbd "C-c n b") #'org-roam-switch-to-buffer)
|
||||
(define-key 'org-roam-mode-map (kbd "C-c n g") #'org-roam-switch-to-buffer)
|
||||
(define-key 'org-mode-map (kbd "C-c n i") #'org-roam-insert)
|
||||
(org-roam-mode +1)
|
||||
```
|
||||
|
||||
There are a number of important configuration options, that greatly
|
||||
affect the Roam workflow. Do look through them at the
|
||||
[Configuration](configuration.md) page.
|
||||
The [Configuration](configuration.md) page details some of the common
|
||||
configuration options available.
|
||||
|
||||
[use-package]: https://github.com/jwiegley/use-package
|
||||
[straight]: https://github.com/raxod502/straight.el
|
||||
|
||||
## Spacemacs
|
||||
If you are using Spacemacs, you can easily install org-roam by creating a simple layer that wraps org-roam. Paste the following into a new file `/.emacs.d/private/org-roam/packages.el`.
|
||||
```
|
||||
If you are using Spacemacs, install org-roam by creating a simple
|
||||
layer that wraps Org-roam. Paste the following into a new file
|
||||
`~/.emacs.d/private/org-roam/packages.el`.
|
||||
|
||||
```emacs-lisp
|
||||
(defconst org-roam-packages
|
||||
'((org-roam :location
|
||||
(recipe :fetcher github :repo "jethrokuan/org-roam" :branch "develop"))))
|
||||
@ -87,13 +97,16 @@ If you are using Spacemacs, you can easily install org-roam by creating a simple
|
||||
"rg" 'org-roam-show-graph))))
|
||||
```
|
||||
|
||||
Next, append `org-roam` to the `dotspacemacs-configuration-layers` list in your `.spacemacs` configuration file. Reload (`SPC f e R`) or restart Emacs to load `org-roam`. It's functions are available under the prefix `SPC a r` and `, r` when visiting an org-mode buffer.
|
||||
Next, append `org-roam` to the `dotspacemacs-configuration-layers`
|
||||
list in your `.spacemacs` configuration file. Reload (`SPC f e R`) or
|
||||
restart Emacs to load `org-roam`. It's functions are available under
|
||||
the prefix `SPC a r` and `, r` when visiting an org-mode buffer.
|
||||
|
||||
## Doom Emacs
|
||||
|
||||
If you are using [Doom Emacs](https://github.com/hlissner/doom-emacs), configure packages as explained in the [getting started](https://github.com/hlissner/doom-emacs/blob/develop/docs/getting_started.org#configuring-packages) guide.
|
||||
|
||||
Declare org-roam as a package in your `~/.doom.d/packages.el`:
|
||||
Declare Org-roam as a package in your `~/.doom.d/packages.el`:
|
||||
|
||||
```elisp
|
||||
;; ~/.doom.d/packages.el
|
||||
@ -102,7 +115,7 @@ Declare org-roam as a package in your `~/.doom.d/packages.el`:
|
||||
:recipe (:host github :repo "jethrokuan/org-roam" :branch "develop"))
|
||||
```
|
||||
|
||||
Subsequently, in your `~/.doom.d/config.el` file, configure org-roam:
|
||||
Subsequently, in your `~/.doom.d/config.el` file, configure Org-roam:
|
||||
|
||||
```elisp
|
||||
;; ~/.doom.d/config.el
|
||||
|
||||
@ -8,6 +8,9 @@
|
||||
- [Roam: Why I Love It and How I Use It][5]
|
||||
- [Adam Keesling's Twitter Thread][6]
|
||||
|
||||
## Threads
|
||||
- [Ask HN: How to Take Good Notes][8]
|
||||
|
||||
## What to Do With Your Notes
|
||||
- [How to Use Roam to Outline a New Article in Under 20 Minutes][2]
|
||||
|
||||
@ -18,3 +21,4 @@
|
||||
[5]: https://www.nateliason.com/blog/roam
|
||||
[6]: https://twitter.com/adam_keesling/status/1196864424725774336?s=20
|
||||
[7]: https://blog.jethro.dev/posts/how_to_take_smart_notes_org/
|
||||
[8]: https://news.ycombinator.com/item?id=22473209
|
||||
|
||||
@ -1,7 +1,7 @@
|
||||
## What is Roam protocol?
|
||||
|
||||
Org-roam defines two protocols that help boost productivity, by
|
||||
extending `org-protocol`: the `roam-file` and `roam-ref` protocol.
|
||||
Org-roam extending `org-protocol` with 2 protocols: the `roam-file`
|
||||
and `roam-ref` protocol.
|
||||
|
||||
## The `roam-file` protocol
|
||||
|
||||
@ -30,22 +30,22 @@ where `template` is the template key for a template in
|
||||
`org-roam-ref-capture-templates`. More documentation on the templating
|
||||
system can be found [here](templating.md).
|
||||
|
||||
These templates should contain a `#+ROAM_KEY: {ref}` in it.
|
||||
These templates should contain a `#+ROAM_KEY: ${ref}` in it.
|
||||
|
||||
## Org-protocol Setup
|
||||
## Setting up Org-roam protocol
|
||||
|
||||
The instructions for setting up org-protocol can be found
|
||||
[here][org-protocol-inst], but they are reproduced below.
|
||||
|
||||
Across all platforms, to enable `org-roam-protocol`, you have to add
|
||||
the following to your init file:
|
||||
To enable org-roam's protocol extensions, you have to add the
|
||||
following to your init file:
|
||||
|
||||
```emacs-lisp
|
||||
(require 'org-roam-protocol)
|
||||
```
|
||||
|
||||
We also need to create a desktop application for emacsclient. The
|
||||
instructions for various platforms are shown below:
|
||||
The instructions for setting up `org-protocol` can be found
|
||||
[here][org-protocol-inst], but they are reproduced below.
|
||||
|
||||
We will also need to create a desktop application for `emacsclient`.
|
||||
The instructions for various platforms are shown below:
|
||||
|
||||
## Linux
|
||||
|
||||
|
||||
64
doc/tour.md
64
doc/tour.md
@ -1,67 +1,65 @@
|
||||
Org-roam was built to support a workflow that was not possible with
|
||||
vanilla Org-mode. This flow is modelled after the [Zettelkasten
|
||||
method][zettelkasten], and many of [Roam Research][roam]'s workflows.
|
||||
Understanding this flow is crucial! Org-roam doesn't auto-magically
|
||||
make your note-taking better -- it's changing the note-taking workflow
|
||||
that does.
|
||||
It is crucial to understand that Org-roam does not auto-magically make
|
||||
note-taking better -- it's changing the note-taking workflow that
|
||||
does.
|
||||
|
||||
To understand more the methods and madness, the [Note-Taking
|
||||
Workflow][appendix:ntw] page contains a page of useful references.
|
||||
I've also written [a post][jethro-blog-post] about how I use Org-roam.
|
||||
To understand more about the methods and madness, the [Note-Taking
|
||||
Workflow][appendix:ntw] page contains a page of useful references. The
|
||||
author has also written [a post][jethro-blog-post] about how he uses
|
||||
Org-roam.
|
||||
|
||||
Without further ado, let's begin!
|
||||
## Activating Org-roam
|
||||
|
||||
## Building the Cache
|
||||
Org-roam's entry point is the global minor `org-roam-mode`. This sets
|
||||
up Emacs with several hooks, for keeping the org-roam cache
|
||||
consistently updated, as well as showing the backlinks buffer.
|
||||
|
||||
The cache is a sqlite database named `org-roam.db`, which resides at
|
||||
the root of your `org-roam-directory`. To begin, we need to do a first
|
||||
build of this cache. To do so, run `M-x org-roam-build-cache`. This
|
||||
may take a while the first time, but is generally instantaneous in
|
||||
subsequent runs.
|
||||
the root of the `org-roam-directory`. Activating `org-roam-mode`
|
||||
builds the cache, which may take a while the first time, but is
|
||||
generally instantaneous in subsequent runs. To build the cache
|
||||
manually again, run `M-x org-roam-build-cache`.
|
||||
|
||||
## Finding a Note
|
||||
|
||||
`org-roam-find-file` shows you the list of notes you currently have in
|
||||
Org-roam. Selecting the title will bring you to the corresponding
|
||||
note. Entering a title of a note that does not yet exist will create a
|
||||
new note with that title.
|
||||
`org-roam-find-file` shows the list of titles for notes that reside in
|
||||
`org-roam-directory`. Selecting a note title will bring you to the
|
||||
corresponding note. Entering a title of a note that does not yet exist
|
||||
will create a new note with that title.
|
||||
|
||||
|
||||
|
||||
## Inserting Links
|
||||
|
||||
Within your Org-roam notes, you are encouraged to liberally insert
|
||||
links to existing (or new) Org-roam notes with `org-roam-insert`.
|
||||
Entering a non-existent title will also create a new note with that
|
||||
title.
|
||||
`org-roam-insert` insert links to existing (or new) notes. Entering a
|
||||
non-existent title will also create a new note with that title.
|
||||
|
||||
|
||||
|
||||
It is crucial for good usage of Org-roam to insert links liberally
|
||||
where you want the notes to resurface!
|
||||
Good usage of Org-roam requires liberally linking files. This allows
|
||||
the build-up of a dense knowledge graph.
|
||||
|
||||
## The Org-roam Buffer
|
||||
|
||||
All of Org-roam's operations are designed such that the built cache is
|
||||
a consistent view of the inter-connectivity between your notes. The
|
||||
Org-roam buffer shows backlinks: i.e. the files that link to the
|
||||
currently viewed file, along with some surrounding context. The
|
||||
Org-roam buffer will always show the backlinks for the current
|
||||
Org-roam file in view.
|
||||
The Org-roam buffer is often displayed in the side window. It shows
|
||||
backlinks for the currently active Org-roam note, along with some
|
||||
surrounding context.
|
||||
|
||||
|
||||
|
||||
## Exporting the Graph
|
||||
|
||||
It's also possible to export the links as a graph, using graphviz. The
|
||||
generated graph is navigable in Emacs, but requires some additional
|
||||
setup, which I describe in the [Graph Appendix][appendix:graph-setup]
|
||||
page.
|
||||
Org-roam also uses Graphviz to generate a graph, with notes as nodes,
|
||||
and links between them as edges. The generated graph can be used to
|
||||
navigate to the files, but this requires some additional setup
|
||||
described in the [Roam Protocol][appendix:roam-protocol] page.
|
||||
|
||||
|
||||
|
||||
[zettelkasten]: https://zettelkasten.de/
|
||||
[appendix:ntw]: notetaking_workflow.md
|
||||
[appendix:graph-setup]: graph_setup.md
|
||||
[appendix:roam-protocol]: roam_protocol.md
|
||||
[roam]: https://www.roamresearch.com/
|
||||
[jethro-blog-post]: https://blog.jethro.dev/posts/how_to_take_smart_notes_org/
|
||||
|
||||
@ -1,14 +1,14 @@
|
||||
site_name: "Org-Roam: Roam + Org-Mode = ♥"
|
||||
site_name: "Org-roam"
|
||||
repo_url: https://github.com/jethrokuan/org-roam/
|
||||
edit_uri: edit/master/doc/
|
||||
copyright: "Copyright (C) 2020 Jethro Kuan and contributors"
|
||||
docs_dir: doc
|
||||
nav:
|
||||
- Home: index.md
|
||||
- A Tour of Org-Roam: tour.md
|
||||
- A Tour of Org-roam: tour.md
|
||||
- Installation: installation.md
|
||||
- Configuration: configuration.md
|
||||
- Anatomy of a Roam file: anatomy.md
|
||||
- Anatomy of an Org-roam file: anatomy.md
|
||||
- The Templating System: templating.md
|
||||
- Ecosystem: ecosystem.md
|
||||
- Similar Packages: comparison.md
|
||||
|
||||
@ -25,6 +25,11 @@
|
||||
;; We extend org-protocol, adding custom Org-roam handlers. The setup
|
||||
;; instructions for `org-protocol' can be found in org-protocol.el.
|
||||
;;
|
||||
;; We define 2 protocols:
|
||||
;;
|
||||
;; 1. "roam-file": This protocol simply opens the file given by the FILE key
|
||||
;; 2. "roam-ref": This protocol creates or opens a note with the given REF
|
||||
;;
|
||||
;;; Code:
|
||||
|
||||
(require 'org-protocol)
|
||||
@ -39,15 +44,14 @@
|
||||
:file-name "${slug}"
|
||||
:head "#+TITLE: ${title}
|
||||
#+ROAM_KEY: ${ref}\n"
|
||||
:unnarrowed t)))
|
||||
:unnarrowed t))
|
||||
"The Org-roam templates used during a capture from the roam-ref protocol.
|
||||
Details on how to specify for the template is given in `org-roam-capture-templates'.")
|
||||
|
||||
(defun org-roam-protocol-open-ref (info)
|
||||
"Process an org-protocol://roam-ref?ref= style url with INFO.
|
||||
|
||||
The sub-protocol used to reach this function is set in
|
||||
`org-protocol-protocol-alist'.
|
||||
|
||||
This function decodes a ref.
|
||||
It opens or creates a note with the given ref.
|
||||
|
||||
javascript:location.href = \\='org-protocol://roam-ref?template=r&ref=\\='+ \\
|
||||
encodeURIComponent(location.href) + \\='&title=\\=' \\
|
||||
|
||||
53
org-roam.el
53
org-roam.el
@ -59,7 +59,7 @@
|
||||
:link '(url-link :tag "Online Manual" "https://org-roam.readthedocs.io/"))
|
||||
|
||||
(defgroup org-roam-faces nil
|
||||
"Faces used by Org-Roam."
|
||||
"Faces used by Org-roam."
|
||||
:group 'org-roam
|
||||
:group 'faces)
|
||||
|
||||
@ -574,7 +574,8 @@ specified via the #+ROAM_ALIAS property."
|
||||
;;;; Org-roam capture
|
||||
(defun org-roam--new-file-path (id)
|
||||
"The file path for a new Org-roam file, with identifier ID.
|
||||
If ABSOLUTE, return an absolute file-path. Else, return a relative file-path."
|
||||
If ABSOLUTE, return an absolute file-path. Else, return a
|
||||
relative file-path."
|
||||
(let ((absolute-file-path (file-truename
|
||||
(expand-file-name
|
||||
(if org-roam-encrypt-files
|
||||
@ -587,7 +588,7 @@ If ABSOLUTE, return an absolute file-path. Else, return a relative file-path."
|
||||
"The default file name format for org-roam templates.")
|
||||
|
||||
(defvar org-roam--capture-header-default "#+TITLE: ${title}\n"
|
||||
"The default file name format for org-roam templates.")
|
||||
"The default capture header for org-roam templates.")
|
||||
|
||||
(defvar org-roam--capture-file-path nil
|
||||
"The file path for the Org-roam capture. This variable is set
|
||||
@ -599,11 +600,17 @@ template. This variable is populated dynamically, and is only
|
||||
non-nil during the org-roam capture process.")
|
||||
|
||||
(defvar org-roam--capture-context nil
|
||||
"A cons cell containing the context (search term) to get the
|
||||
exact point in a file. This variable is populated dynamically,
|
||||
and is only active during an org-roam capture process.
|
||||
"A symbol, that reflects the context for obtaining the exact point in a file.
|
||||
This variable is populated dynamically, and is only active during
|
||||
an org-roam capture process.
|
||||
|
||||
E.g. ('title . \"New Title\")")
|
||||
The `title' context is used in `org-roam-insert' and
|
||||
`org-roam-find-file', where the capture process is triggered upon
|
||||
trying to create a new file without that `title'.
|
||||
|
||||
The `ref' context is used by `org-roam-protocol', where the
|
||||
capture process is triggered upon trying to find or create a new
|
||||
note with the given `ref'.")
|
||||
|
||||
(defvar org-roam-capture-templates
|
||||
'(("d" "default" plain (function org-roam--capture-get-point)
|
||||
@ -611,10 +618,30 @@ E.g. ('title . \"New Title\")")
|
||||
:file-name "%<%Y%m%d%H%M%S>-${slug}"
|
||||
:head "#+TITLE: ${title}\n"
|
||||
:unnarrowed t))
|
||||
"Capture templates for org-roam.")
|
||||
"Capture templates for Org-roam. The capture templates are an extension of
|
||||
`org-capture-templates', and the documentation there also applies.
|
||||
|
||||
`org-capture-templates' are extended in 3 ways:
|
||||
|
||||
1. Template expansion capabilities are extended with additional custom syntax.
|
||||
See `org-roam--fill-template' for more details.
|
||||
2. The `:file-name' key is added, which expands to the file-name of the note
|
||||
if it creates a new file. This file-name is relative to `org-roam-directory',
|
||||
and is without the file-extension.
|
||||
3. The `:head' key is added, which contains the template that is inserted on
|
||||
initial creation (added only once). This is where insertion of any note
|
||||
metadata should go.")
|
||||
|
||||
(defun org-roam--fill-template (str &optional info)
|
||||
"Return a file name from template STR."
|
||||
"Expands the template STR, returning the string.
|
||||
This is an extension of org-capture's template expansion.
|
||||
|
||||
First, it expands ${var} occurences in STR, using the INFO alist.
|
||||
If there is a ${var} with no matching var in the alist, the value
|
||||
of var is prompted for via completing-read.
|
||||
|
||||
Next, it expands the remaining template string using
|
||||
`org-capture-fill-template'."
|
||||
(-> str
|
||||
(s-format (lambda (key)
|
||||
(or (s--aget info key)
|
||||
@ -647,7 +674,10 @@ If the search is via title, it is assumed that the file does not
|
||||
yet exist, and org-roam will attempt to create new file.
|
||||
|
||||
If the search is via ref, it is matched against the Org-roam database.
|
||||
If there is no file with that ref, a file with that ref is created."
|
||||
If there is no file with that ref, a file with that ref is created.
|
||||
|
||||
This function is used solely in Org-roam's capture templates: see
|
||||
`org-roam-capture-templates'."
|
||||
(pcase org-roam--capture-context
|
||||
('title
|
||||
(let ((file-path (org-roam--capture-new-file)))
|
||||
@ -726,6 +756,7 @@ If PREFIX, downcase the title before insertion."
|
||||
|
||||
(defun org-roam--capture-advance-point ()
|
||||
"Advances the point if it is updated.
|
||||
|
||||
We need this function because typically org-capture prevents the
|
||||
point from being advanced, whereas when a link is inserted, the
|
||||
point moves some characters forward. This is added as a hook to
|
||||
@ -1115,7 +1146,7 @@ it.
|
||||
When called from Lisp, enable `org-roam-mode' if ARG is omitted,
|
||||
nil, or positive. If ARG is `toggle', toggle `org-roam-mode'.
|
||||
Otherwise, behave as if called interactively."
|
||||
:lighter " Org-Roam"
|
||||
:lighter " Org-roam"
|
||||
:keymap org-roam-mode-map
|
||||
:group 'org-roam
|
||||
:require 'org-roam
|
||||
|
||||
Reference in New Issue
Block a user