mirror of
https://github.com/org-roam/org-roam
synced 2025-08-01 12:17:21 -05:00
(ci): remove old docs, add landing page (#619)
This commit is contained in:
Jethro Kuan
GitHub
1
.gitignore
vendored
1
.gitignore
vendored
@ -13,3 +13,4 @@
|
|||||||
/doc/mimetype
|
/doc/mimetype
|
||||||
/doc/stats/
|
/doc/stats/
|
||||||
/config.mk
|
/config.mk
|
||||||
|
/doc/manual/
|
||||||
|
|||||||
@ -29,6 +29,7 @@ dir: org-roam.info
|
|||||||
html-dir:
|
html-dir:
|
||||||
@printf "Generating org-roam/*.html\n"
|
@printf "Generating org-roam/*.html\n"
|
||||||
@$(MAKEINFO) --html org-roam.texi
|
@$(MAKEINFO) --html org-roam.texi
|
||||||
|
mv org-roam manual
|
||||||
|
|
||||||
%.pdf: %.texi
|
%.pdf: %.texi
|
||||||
@printf "Generating $@\n"
|
@printf "Generating $@\n"
|
||||||
|
|||||||
@ -1,41 +0,0 @@
|
|||||||
The bulk of Org-roam's functionality is built on top of vanilla
|
|
||||||
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
|
|
||||||
`#+ROAM_ALIAS` attribute:
|
|
||||||
|
|
||||||
```org
|
|
||||||
#+TITLE: World War 2
|
|
||||||
#+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
|
|
||||||
```
|
|
||||||
|
|
||||||
The backlinks buffer will show any cites of this key: e.g.
|
|
||||||
|
|
||||||
|
|
||||||
@ -1,11 +0,0 @@
|
|||||||
---
|
|
||||||
title: "Comparing Org-roam With Other Packages"
|
|
||||||
metaTitle: "Comparing Org-roam With Other Packages"
|
|
||||||
metaDescription: "Comparing Org-roam With Other Packages"
|
|
||||||
---
|
|
||||||
|
|
||||||
# Org-brain
|
|
||||||
|
|
||||||
# Zetteldeft
|
|
||||||
|
|
||||||
# Org-zettelkasten
|
|
||||||
@ -1,157 +0,0 @@
|
|||||||
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
|
|
||||||
|
|
||||||
Set `org-roam-directory` to the folder containing all your Org files:
|
|
||||||
|
|
||||||
```emacs-lisp
|
|
||||||
(setq org-roam-directory "/path/to/org/")
|
|
||||||
```
|
|
||||||
|
|
||||||
Every Org file, at any level of nesting, within `/path/to/org/` is
|
|
||||||
considered part of the Org-roam ecosystem.
|
|
||||||
|
|
||||||
### Having More Than One Org-roam Directory
|
|
||||||
|
|
||||||
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`.
|
|
||||||
|
|
||||||
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/"))))
|
|
||||||
```
|
|
||||||
|
|
||||||
All files within that directory will be treated as their own separate
|
|
||||||
set of Org-roam files. Remember to run `org-roam-db-build-cache` from a
|
|
||||||
file within that directory, at least once.
|
|
||||||
|
|
||||||
## Org-roam Buffer
|
|
||||||
|
|
||||||
The Org-roam buffer defaults to popping up from the right. You may
|
|
||||||
choose to set it to pop up from the left with `(setq
|
|
||||||
org-roam-buffer-position 'left)`.
|
|
||||||
|
|
||||||
The Org-roam buffer name can also be renamed: e.g. `(setq
|
|
||||||
org-roam-buffer "*my-buffer-name*")`.
|
|
||||||
|
|
||||||
The Org-roam buffer width is adjustable via `org-roam-buffer-width`.
|
|
||||||
The value of `org-roam-buffer-width` set as a percentage of the total
|
|
||||||
frame width. For example:
|
|
||||||
|
|
||||||
```emacs-lisp
|
|
||||||
(setq org-roam-buffer-width 0.4)
|
|
||||||
```
|
|
||||||
|
|
||||||
Will result in the Org-roam buffer taking up 40% of the screen width.
|
|
||||||
|
|
||||||
You can change backlinks appearance in the buffer by customizing
|
|
||||||
`org-roam-backlink` face (`M-x customize-face org-roam-backlink`).
|
|
||||||
|
|
||||||
## 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. 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")
|
|
||||||
```
|
|
||||||
|
|
||||||
If your version of Org is at least `9.2`, you may also choose to
|
|
||||||
simply style the link differently, by customizing `org-roam-link` face
|
|
||||||
(`M-x customize-face org-roam-link`).
|
|
||||||
|
|
||||||
## Org-roam Files
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
### Index
|
|
||||||
|
|
||||||
As your collection grows, you might want to create an index where you keep
|
|
||||||
links to your main files.
|
|
||||||
|
|
||||||
In Org-roam, you can define the path to your index file by setting `org-roam-index-file`.
|
|
||||||
|
|
||||||
```emacs-lisp
|
|
||||||
(setq org-roam-index-file "index.org")
|
|
||||||
```
|
|
||||||
|
|
||||||
You can then bind `org-roam-jump-to-index` in your configuration to access it (see [Basic Install and
|
|
||||||
Configuration](installation.md/#basic-install-and-configuration) to review how
|
|
||||||
to set key-bindings).
|
|
||||||
|
|
||||||
### 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 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
|
|
||||||
|
|
||||||
Org-roam generates an SVG image using
|
|
||||||
[Graphviz](https://graphviz.org/). To setup graph navigation, see the
|
|
||||||
[Roam Protocol](roam_protocol.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:
|
|
||||||
|
|
||||||
```
|
|
||||||
(setq org-roam-graph-executable "/path/to/dot")
|
|
||||||
```
|
|
||||||
|
|
||||||
You may also choose to use `neato` in place of `dot`, which generates a more compact graph layout.
|
|
||||||
|
|
||||||
```
|
|
||||||
(setq org-roam-graph-executable "/path/to/neato")
|
|
||||||
(setq org-roam-graph-extra-config '(("overlap" . "false")))
|
|
||||||
```
|
|
||||||
|
|
||||||
Org-roam also attempts to use Firefox (located on `PATH`) to view the
|
|
||||||
SVG, you may choose to set it to any compatible program:
|
|
||||||
|
|
||||||
```
|
|
||||||
(setq org-roam-graph-viewer "/path/to/image-viewer")
|
|
||||||
```
|
|
||||||
|
|
||||||
### Excluding Nodes and Edges
|
|
||||||
One may want to exclude certain files to declutter the graph. You can do so by setting `org-roam-graph-exclude-matcher`.
|
|
||||||
|
|
||||||
```
|
|
||||||
(setq org-roam-graph-exclude-matcher '("private" "dailies"))
|
|
||||||
```
|
|
||||||
|
|
||||||
This setting excludes all files whose path contain "private" or "dailies".
|
|
||||||
|
|
||||||
## Org-roam Completion System
|
|
||||||
|
|
||||||
Org-roam offers completion when choosing note titles etc.
|
|
||||||
The completion system is configurable. The default setting,
|
|
||||||
|
|
||||||
```
|
|
||||||
(setq org-roam-completion-system 'default)
|
|
||||||
```
|
|
||||||
|
|
||||||
uses Emacs' standard `completing-read`. If you prefer [Helm](https://emacs-helm.github.io/helm/), use
|
|
||||||
|
|
||||||
```
|
|
||||||
(setq org-roam-completion-system 'helm)
|
|
||||||
```
|
|
||||||
|
|
||||||
Other options included `'ido`, and `'ivy'`.
|
|
||||||
138
doc/ecosystem.md
138
doc/ecosystem.md
@ -1,138 +0,0 @@
|
|||||||
A number of packages work well combined with Org-Roam:
|
|
||||||
|
|
||||||
## Deft
|
|
||||||
|
|
||||||
[Deft][deft] provides a nice interface for browsing and filtering
|
|
||||||
org-roam notes.
|
|
||||||
|
|
||||||
```emacs-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/"))
|
|
||||||
```
|
|
||||||
|
|
||||||
If the title of the Org file is not the first line, you might not get
|
|
||||||
nice titles. You may choose to patch this to use `org-roam`'s
|
|
||||||
functionality. Here I'm using [el-patch](https://github.com/raxod502/el-patch):
|
|
||||||
|
|
||||||
```emacs-lisp
|
|
||||||
(use-package el-patch
|
|
||||||
:straight (:host github
|
|
||||||
:repo "raxod502/el-patch"
|
|
||||||
:branch "develop"))
|
|
||||||
|
|
||||||
(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))))
|
|
||||||
```
|
|
||||||
|
|
||||||
The Deft interface can slow down quickly when the number of files get
|
|
||||||
huge. [Notdeft][notdeft] is a fork of Deft that uses an external
|
|
||||||
search engine and indexer.
|
|
||||||
|
|
||||||
## Org-journal
|
|
||||||
|
|
||||||
[Org-journal](https://github.com/bastibe/org-journal) is a more powerful
|
|
||||||
alternative to the simple function `org-roam-dailies-today`. It provides better
|
|
||||||
journaling capabilities, and a nice calendar interface to see all dated entries.
|
|
||||||
|
|
||||||
```emacs-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"))
|
|
||||||
```
|
|
||||||
|
|
||||||
## Note-taking Add-ons
|
|
||||||
|
|
||||||
These are some plugins that make note-taking in Org-mode more
|
|
||||||
enjoyable.
|
|
||||||
|
|
||||||
### Org-download
|
|
||||||
|
|
||||||
[Org-download][org-download] lets you screenshot and yank images from
|
|
||||||
the web into your notes:
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
```emacs-lisp
|
|
||||||
(use-package org-download
|
|
||||||
:after org
|
|
||||||
:bind
|
|
||||||
(:map org-mode-map
|
|
||||||
(("s-Y" . org-download-screenshot)
|
|
||||||
("s-y" . org-download-yank))))
|
|
||||||
```
|
|
||||||
|
|
||||||
### mathpix.el
|
|
||||||
|
|
||||||
[mathpix.el][mathpix-el] uses [Mathpix's](https://mathpix.com/) API to convert clips into
|
|
||||||
latex equations:
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
```emacs-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))
|
|
||||||
```
|
|
||||||
|
|
||||||
### Org-noter / Interleave
|
|
||||||
|
|
||||||
[Org-noter][org-noter] and [Interleave][interleave] are both projects
|
|
||||||
that allow synchronised annotation of documents (PDF, EPUB etc.)
|
|
||||||
within Org-mode.
|
|
||||||
|
|
||||||
### Bibliography
|
|
||||||
|
|
||||||
[org-roam-bibtex](https://github.com/zaeph/org-roam-bibtex) offers tight
|
|
||||||
integration between [org-ref][org-ref], [helm-bibtex][helm-bibtex] and
|
|
||||||
`org-roam`. This helps you manage your bibliographic notes under `org-roam`.
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
### 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
|
|
||||||
[mathpix-el]: https://github.com/jethrokuan/mathpix.el
|
|
||||||
[org-noter]: https://github.com/weirdNox/org-noter
|
|
||||||
[interleave]: https://github.com/rudolfochrist/interleave
|
|
||||||
[org-ref]: https://github.com/jkitchin/org-ref
|
|
||||||
[helm-bibtex]: https://github.com/tmalsburg/helm-bibtex
|
|
||||||
[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
|
|
||||||
62
doc/index.md
62
doc/index.md
@ -1,62 +0,0 @@
|
|||||||
![org-roam][org-roam-intro-image]
|
|
||||||
|
|
||||||
## What is Org-roam?
|
|
||||||
|
|
||||||
Org-roam is a [Roam][roamresearch] replica built around the
|
|
||||||
all-powerful [Org-mode][org].
|
|
||||||
|
|
||||||
Org-roam is a solution for effortless non-hierarchical note-taking
|
|
||||||
with Org-mode. 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.
|
|
||||||
|
|
||||||
To understand more about Roam, a collection of links are available in
|
|
||||||
[the appendix](notetaking_workflow.md).
|
|
||||||
|
|
||||||
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 use Org-roam?
|
|
||||||
|
|
||||||
##### Private and Secure
|
|
||||||
|
|
||||||
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 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/
|
|
||||||
[org]: https://orgmode.org/
|
|
||||||
@ -1,197 +0,0 @@
|
|||||||
## Basic Install and Configuration
|
|
||||||
|
|
||||||
Org-roam is now available on MELPA, so you can install it via the following
|
|
||||||
command:
|
|
||||||
|
|
||||||
```
|
|
||||||
M-x package-install RET org-roam RET
|
|
||||||
```
|
|
||||||
|
|
||||||
Alternatively, you may use package managers such as [straight][straight] or
|
|
||||||
[quelpa][quelpa] to install the package.
|
|
||||||
|
|
||||||
The recommended method of configuration is to use [use-package][use-package].
|
|
||||||
|
|
||||||
```emacs-lisp
|
|
||||||
(use-package org-roam
|
|
||||||
:hook
|
|
||||||
(after-init . org-roam-mode)
|
|
||||||
: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 j" . org-roam-jump-to-index)
|
|
||||||
("C-c n b" . org-roam-switch-to-buffer)
|
|
||||||
("C-c n g" . org-roam-graph))
|
|
||||||
:map org-mode-map
|
|
||||||
(("C-c n i" . org-roam-insert))))
|
|
||||||
```
|
|
||||||
|
|
||||||
Or without `use-package`:
|
|
||||||
|
|
||||||
```emacs-lisp
|
|
||||||
(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 j") #'org-roam-jump-to-index)
|
|
||||||
(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-graph)
|
|
||||||
(define-key org-mode-map (kbd "C-c n i") #'org-roam-insert)
|
|
||||||
(org-roam-mode +1)
|
|
||||||
```
|
|
||||||
|
|
||||||
The [Configuration](configuration.md) page details some of the common
|
|
||||||
configuration options available.
|
|
||||||
|
|
||||||
### Completion
|
|
||||||
|
|
||||||
Link auto-completion is offered via
|
|
||||||
[company-org-roam](https://github.com/jethrokuan/company-org-roam/), refer to
|
|
||||||
the documentation there for further details.
|
|
||||||
|
|
||||||
## Spacemacs
|
|
||||||
|
|
||||||
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))
|
|
||||||
|
|
||||||
(defun org-roam/init-org-roam ()
|
|
||||||
(use-package org-roam
|
|
||||||
:hook
|
|
||||||
(after-init . org-roam-mode)
|
|
||||||
:custom
|
|
||||||
(org-roam-directory "/path/to/org-files/")
|
|
||||||
:init
|
|
||||||
(progn
|
|
||||||
(spacemacs/declare-prefix "ar" "org-roam")
|
|
||||||
(spacemacs/set-leader-keys
|
|
||||||
"arl" 'org-roam
|
|
||||||
"art" 'org-roam-dailies-today
|
|
||||||
"arf" 'org-roam-find-file
|
|
||||||
"arg" 'org-roam-graph)
|
|
||||||
|
|
||||||
(spacemacs/declare-prefix-for-mode 'org-mode "mr" "org-roam")
|
|
||||||
(spacemacs/set-leader-keys-for-major-mode 'org-mode
|
|
||||||
"rl" 'org-roam
|
|
||||||
"rt" 'org-roam-dailies-today
|
|
||||||
"rb" 'org-roam-switch-to-buffer
|
|
||||||
"rf" 'org-roam-find-file
|
|
||||||
"ri" 'org-roam-insert
|
|
||||||
"rg" 'org-roam-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.
|
|
||||||
|
|
||||||
If you also have the ranger layer installed, the prefix 'ar' conflict
|
|
||||||
with that of the ranger layer. You might want to change it to 'aor'
|
|
||||||
(also change the 'ar' to 'aor' in the other key-binding declarations)
|
|
||||||
|
|
||||||
## Doom Emacs
|
|
||||||
|
|
||||||
[Doom Emacs][doom] has a `+roam` flag on its `org` module for easy
|
|
||||||
installation and configuration. Simply add the flag to the `org` section
|
|
||||||
of your `~/.doom.d/init.el` and run `~/.emacs.d/bin/doom sync`.
|
|
||||||
|
|
||||||
[use-package]: https://github.com/jwiegley/use-package
|
|
||||||
[straight]: https://github.com/raxod502/straight.el
|
|
||||||
[quelpa]: https://github.com/quelpa/quelpa
|
|
||||||
[doom]: https://github.com/hlissner/doom-emacs
|
|
||||||
[doom-getting-started]: https://github.com/hlissner/doom-emacs/blob/develop/docs/getting_started.org#configuring-packages
|
|
||||||
|
|
||||||
## Windows
|
|
||||||
|
|
||||||
On Windows, if you follow the installation instructions above, you will likely get the error message: **"No EmacSQL SQLite binary available, aborting"**, and `org-roam` won't start properly.
|
|
||||||
|
|
||||||
You need to do some additional steps to get `org-roam` to work.
|
|
||||||
|
|
||||||
Essentially, you will need to have a binary file for `emacsql-sqlite` so that your Emacs can work with `sqlite` database -- `org-roam` uses it to track backlinks. The following options have been reported to work by Windows users in the community.
|
|
||||||
|
|
||||||
Option 1. **Windows Subsystem for Linux (WSL)**
|
|
||||||
: This option lets you use Linux on your Windows machine. It's Linux, so you don't need to do anything specific for Windows.
|
|
||||||
|
|
||||||
Option 2. **mingw-x64**
|
|
||||||
: Use mingw-x64. You would spend a bit of time to download it, and get familiar with how it works. You should be able to use Linux tools within your Windows [more contribution welcome].
|
|
||||||
|
|
||||||
Option 3. **scoop**
|
|
||||||
: Use [scoop](https://scoop.sh/) to install a couple of software tools (make and gcc) and manually compile a binary (`.exe`) file yourself. Find a short step-by-step guide below.
|
|
||||||
|
|
||||||
Option 4. **emacsql-sqlite3**
|
|
||||||
: Use another Emacs package called [`emacsql-sqlite3`](https://github.com/cireu/emacsql-sqlite3). You can download an [official binary](https://sqlite.org/download.html) for `sqlite3`. `emacsql-sqlite3` lets you use it. For this option to work, you need to adjust the `org-roam` source code, and get your modified version to work in your Emacs environment. Find a suggestion below.
|
|
||||||
|
|
||||||
### scoop
|
|
||||||
**Step 1.** In PowerShell, install `scoop` ([instruction here](https://scoop.sh/)).
|
|
||||||
|
|
||||||
```powershell
|
|
||||||
iwr -useb get.scoop.sh | iex
|
|
||||||
```
|
|
||||||
|
|
||||||
**Step 2.** In PowerShell, install `make` and `gcc` via scoop
|
|
||||||
|
|
||||||
```powershell
|
|
||||||
scoop install make gcc
|
|
||||||
```
|
|
||||||
|
|
||||||
**Step 3.** In Emacs, install the `emacsql-sqlite` package for your Emacs if it is not done yet.
|
|
||||||
|
|
||||||
**Step 4.** In PowerShell, move to the directory where `emacsql.c` is stored.
|
|
||||||
|
|
||||||
With MELPA, it is likely to be under your ELPA folder:
|
|
||||||
|
|
||||||
```
|
|
||||||
~\AppData\Roaming\.emacs.d\elpa\emacsql-sqlite-20190727.1710\sqlite
|
|
||||||
```
|
|
||||||
|
|
||||||
With Doom Emacs, it should be under your `.emacs\.local`:
|
|
||||||
|
|
||||||
```
|
|
||||||
~\.emacs.d\.local\straight\build\emacsql-sqlite\sqlite
|
|
||||||
```
|
|
||||||
|
|
||||||
Check the files via `dir` command. You should see these files:
|
|
||||||
|
|
||||||
```powershell
|
|
||||||
Mode LastWriteTime Length Name
|
|
||||||
---- ------------- ------ ----
|
|
||||||
-a---- 22/03/2020 12:10 PM 5170 emacsql.c
|
|
||||||
-a---- 22/03/2020 12:10 PM 439 Makefile
|
|
||||||
-a---- 22/03/2020 12:10 PM 7516138 sqlite3.c
|
|
||||||
-a---- 22/03/2020 12:10 PM 526684 sqlite3.h
|
|
||||||
```
|
|
||||||
|
|
||||||
**Step 5.** Compile the `.exe` file with `make`
|
|
||||||
|
|
||||||
```powershell
|
|
||||||
make emacsql-sqlite CC=gcc LDLIBS=
|
|
||||||
```
|
|
||||||
|
|
||||||
You will see the process triggered with lots of text automatically scrolling down; it may take a couple of minutes for compilation to finish.
|
|
||||||
|
|
||||||
Once compilation is done, check that `emacsql-sqlite.exe` has been added to the directory.
|
|
||||||
|
|
||||||
**Step 6.** Relaunch Emacs, use `org-roam`
|
|
||||||
|
|
||||||
When you start `org-roam` (e.g. via `org-roam-mode`), now you should no longer see the "No EmacSQL SQLite binary available, aborting" error. You are good to go.
|
|
||||||
|
|
||||||
|
|
||||||
### emacsql-sqlite3
|
|
||||||
|
|
||||||
1. In Emacs, install the `emacsql-sqlite3` package
|
|
||||||
|
|
||||||
2. Using your text editor, etc. modify `org-roam-db.el`:
|
|
||||||
|
|
||||||
1. Replace `(require 'emacsql-sqlite)` with `(require 'emacsql-sqlite3)`
|
|
||||||
|
|
||||||
2. Comment/deactivate the complete `(defconst org-roam-db--sqlite-available-p ... )`
|
|
||||||
|
|
||||||
3. In `(defun org-roam-db ...`, replace `emacsql-sqlite`
|
|
||||||
with `emacsql-sqlite3`
|
|
||||||
|
|
||||||
3. If you compile `.el` files, ensure to replace `org-roam-db.elc` with the new source you modified.
|
|
||||||
@ -1,24 +0,0 @@
|
|||||||
## Recommended Books
|
|
||||||
- [How to Take Smart Notes][1]
|
|
||||||
|
|
||||||
## Articles
|
|
||||||
- [How to Take Smart Notes in Org-mode - Jethro Kuan][7]
|
|
||||||
- [The Zettelkasten Method - LessWrong 2.0][3]
|
|
||||||
- [Building a second brain in Roam][4]
|
|
||||||
- [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]
|
|
||||||
|
|
||||||
[1]: https://www.goodreads.com/book/show/34507927-how-to-take-smart-notes?ac=1&from_search=true&qid=6L8iEE1FIA&rank=1
|
|
||||||
[2]: https://www.youtube.com/watch?v=RvWic15iXjk
|
|
||||||
[3]: https://www.lesswrong.com/posts/NfdHG6oHBJ8Qxc26s/the-zettelkasten-method-1
|
|
||||||
[4]: https://reddit.com/r/RoamResearch/comments/eho7de/building_a_second_brain_in_roamand_why_you_might
|
|
||||||
[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,61 +0,0 @@
|
|||||||
While exporting your documents to another format such as HTML -- whether using Org's in-built export or ox-hugo -- you can add a backlinks section which would display the backlinks to the current file. This is done via org-export's preprocessing hooks. See more at [Advanced Export Configuration (The Org Manual)](https://orgmode.org/manual/Advanced-Export-Configuration.html#Advanced-Export-Configuration).
|
|
||||||
|
|
||||||
Following are two different configs that might be suitable for different use-cases. Add one of these snippets in your Emacs init file.
|
|
||||||
|
|
||||||
### Only Backlinks
|
|
||||||
|
|
||||||
This will display only the backlinks and not the contents.
|
|
||||||
|
|
||||||
```emacs-lisp
|
|
||||||
(defun my/org-roam--backlinks-list (file)
|
|
||||||
(if (org-roam--org-roam-file-p file)
|
|
||||||
(--reduce-from
|
|
||||||
(concat acc (format "- [[file:%s][%s]]\n"
|
|
||||||
(file-relative-name (car it) org-roam-directory)
|
|
||||||
(org-roam--get-title-or-slug (car it))))
|
|
||||||
"" (org-roam-db-query [:select [from] :from links :where (= to $s1)] file))
|
|
||||||
""))
|
|
||||||
|
|
||||||
(defun my/org-export-preprocessor (backend)
|
|
||||||
(let ((links (my/org-roam--backlinks-list (buffer-file-name))))
|
|
||||||
(unless (string= links "")
|
|
||||||
(save-excursion
|
|
||||||
(goto-char (point-max))
|
|
||||||
(insert (concat "\n* Backlinks\n") links)))))
|
|
||||||
|
|
||||||
(add-hook 'org-export-before-processing-hook 'my/org-export-preprocessor)
|
|
||||||
```
|
|
||||||
|
|
||||||
### Backlinks and Contents
|
|
||||||
|
|
||||||
This would insert both backlinks and the contents, just like the org-roam buffer. This might be especially useful if you host a web version of your personal knowledgebase and want to browse the files along with the backlinks from mobile devices.
|
|
||||||
|
|
||||||
```emacs-lisp
|
|
||||||
(defun my/org-roam--backlinks-list-with-content (file)
|
|
||||||
(with-temp-buffer
|
|
||||||
(if-let* ((backlinks (org-roam--get-backlinks file))
|
|
||||||
(grouped-backlinks (--group-by (nth 0 it) backlinks)))
|
|
||||||
(progn
|
|
||||||
(insert (format "\n\n* %d Backlinks\n"
|
|
||||||
(length backlinks)))
|
|
||||||
(dolist (group grouped-backlinks)
|
|
||||||
(let ((file-from (car group))
|
|
||||||
(bls (cdr group)))
|
|
||||||
(insert (format "** [[file:%s][%s]]\n"
|
|
||||||
file-from
|
|
||||||
(org-roam--get-title-or-slug file-from)))
|
|
||||||
(dolist (backlink bls)
|
|
||||||
(pcase-let ((`(,file-from _ ,props) backlink))
|
|
||||||
(insert (s-trim (s-replace "\n" " " (plist-get props :content))))
|
|
||||||
(insert "\n\n")))))))
|
|
||||||
(buffer-string)))
|
|
||||||
|
|
||||||
(defun my/org-export-preprocessor (backend)
|
|
||||||
(let ((links (my/org-roam--backlinks-list-with-content (buffer-file-name))))
|
|
||||||
(unless (string= links "")
|
|
||||||
(save-excursion
|
|
||||||
(goto-char (point-max))
|
|
||||||
(insert (concat "\n* Backlinks\n") links)))))
|
|
||||||
|
|
||||||
(add-hook 'org-export-before-processing-hook 'my/org-export-preprocessor)
|
|
||||||
```
|
|
||||||
@ -1,2 +0,0 @@
|
|||||||
mkdocs-material==4.6.2
|
|
||||||
pymdown-extensions==6.3
|
|
||||||
@ -1,169 +0,0 @@
|
|||||||
## What is Roam protocol?
|
|
||||||
|
|
||||||
Org-roam extending `org-protocol` with 2 protocols: the `roam-file`
|
|
||||||
and `roam-ref` protocol.
|
|
||||||
|
|
||||||
## The `roam-file` protocol
|
|
||||||
|
|
||||||
This is a simple protocol that opens the path specified by the `file`
|
|
||||||
key (e.g. `org-protocol://roam-file?file=/tmp/file.org`). This is used
|
|
||||||
in the generated graph.
|
|
||||||
|
|
||||||
## The `roam-ref` Protocol
|
|
||||||
|
|
||||||
This protocol finds or creates a new note with a given `ROAM_KEY` (see
|
|
||||||
[Anatomy](anatomy.md)):
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
To use this, create a Firefox bookmarklet as follows:
|
|
||||||
|
|
||||||
```javascript
|
|
||||||
javascript:location.href =
|
|
||||||
'org-protocol://roam-ref?template=r&ref='
|
|
||||||
+ encodeURIComponent(location.href)
|
|
||||||
+ '&title='
|
|
||||||
+ encodeURIComponent(document.title)
|
|
||||||
```
|
|
||||||
or as a keybinding in qutebrowser, adding the following to the autoconfig.yml file:
|
|
||||||
```yml
|
|
||||||
settings:
|
|
||||||
bindings.commands:
|
|
||||||
global:
|
|
||||||
normal:
|
|
||||||
gc: open javascript:void(location.href='org-protocol://roam-ref?template=r&ref='+encodeURIComponent(location.href)+'&title='+encodeURIComponent(document.title))
|
|
||||||
```
|
|
||||||
|
|
||||||
where `template` is the template key for a template in
|
|
||||||
`org-roam-capture-ref-templates`. More documentation on the templating
|
|
||||||
system can be found [here](templating.md).
|
|
||||||
|
|
||||||
These templates should contain a `#+ROAM_KEY: ${ref}` in it.
|
|
||||||
|
|
||||||
## Setting up Org-roam protocol
|
|
||||||
|
|
||||||
To enable org-roam's protocol extensions, you have to add the
|
|
||||||
following to your init file:
|
|
||||||
|
|
||||||
```emacs-lisp
|
|
||||||
(require 'org-roam-protocol)
|
|
||||||
```
|
|
||||||
|
|
||||||
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
|
|
||||||
|
|
||||||
Create a desktop application. I place mine in
|
|
||||||
`~/.local/share/applications/org-protocol.desktop`:
|
|
||||||
|
|
||||||
```
|
|
||||||
[Desktop Entry]
|
|
||||||
Name=Org-Protocol
|
|
||||||
Exec=emacsclient %u
|
|
||||||
Icon=emacs-icon
|
|
||||||
Type=Application
|
|
||||||
Terminal=false
|
|
||||||
MimeType=x-scheme-handler/org-protocol
|
|
||||||
```
|
|
||||||
|
|
||||||
Associate `org-protocol://` links with the desktop application by
|
|
||||||
running in your shell:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
xdg-mime default org-protocol.desktop x-scheme-handler/org-protocol
|
|
||||||
```
|
|
||||||
|
|
||||||
To disable the "confirm" prompt in Chrome, you can also make Chrome
|
|
||||||
show a checkbox to tick, so that the `Org-Protocol Client` app will be used
|
|
||||||
without confirmation. To do this, run in a shell:
|
|
||||||
|
|
||||||
```sh
|
|
||||||
sudo mkdir -p /etc/opt/chrome/policies/managed/
|
|
||||||
sudo tee /etc/opt/chrome/policies/managed/external_protocol_dialog.json >/dev/null <<'EOF'
|
|
||||||
{
|
|
||||||
"ExternalProtocolDialogShowAlwaysOpenCheckbox": true
|
|
||||||
}
|
|
||||||
EOF
|
|
||||||
sudo chmod 644 /etc/opt/chrome/policies/managed/external_protocol_dialog.json
|
|
||||||
```
|
|
||||||
|
|
||||||
and then restart Chrome (for example, by navigating to <chrome://restart>) to
|
|
||||||
make the new policy take effect.
|
|
||||||
|
|
||||||
See [here](https://www.chromium.org/administrators/linux-quick-start)
|
|
||||||
for more info on the `/etc/opt/chrome/policies/managed` directory and
|
|
||||||
[here](https://cloud.google.com/docs/chrome-enterprise/policies/?policy=ExternalProtocolDialogShowAlwaysOpenCheckbox)
|
|
||||||
for information on the `ExternalProtocolDialogShowAlwaysOpenCheckbox`
|
|
||||||
policy.
|
|
||||||
|
|
||||||
|
|
||||||
## Mac OS
|
|
||||||
|
|
||||||
One solution is to use
|
|
||||||
[Platypus](https://github.com/sveinbjornt/Platypus). Here are the
|
|
||||||
instructions for setting up with Platypus and Chrome:
|
|
||||||
|
|
||||||
1. Install and launch Platypus (with [Homebrew](https://brew.sh/)):
|
|
||||||
|
|
||||||
```sh
|
|
||||||
brew cask install platypus
|
|
||||||
```
|
|
||||||
2. Create a script `launch_emacs.sh`:
|
|
||||||
|
|
||||||
```
|
|
||||||
#!/usr/bin/env bash
|
|
||||||
/usr/local/bin/emacsclient --no-wait $1
|
|
||||||
```
|
|
||||||
|
|
||||||
3. Create a Platypus app with the following settings:
|
|
||||||
|
|
||||||
```
|
|
||||||
| Setting | Value |
|
|
||||||
|--------------------------------+---------------------------|
|
|
||||||
| App Name | "OrgProtocol" |
|
|
||||||
| Script Type | "env" · "/usr/bin/env" |
|
|
||||||
| Script Path | "path/to/launch-emacs.sh" |
|
|
||||||
| Interface | None |
|
|
||||||
| Accept dropped items | true |
|
|
||||||
| Remain running after execution | false |
|
|
||||||
```
|
|
||||||
|
|
||||||
Inside `Settings`:
|
|
||||||
|
|
||||||
```
|
|
||||||
| Setting | Value |
|
|
||||||
|--------------------------------+----------------|
|
|
||||||
| Accept dropped files | true |
|
|
||||||
| Register as URI scheme handler | true |
|
|
||||||
| Protocol | "org-protocol" |
|
|
||||||
```
|
|
||||||
|
|
||||||
To disable the "confirm" prompt in Chrome, you can also make Chrome
|
|
||||||
show a checkbox to tick, so that the `OrgProtocol` app will be used
|
|
||||||
without confirmation. To do this, run in a shell:
|
|
||||||
|
|
||||||
```sh
|
|
||||||
defaults write com.google.Chrome ExternalProtocolDialogShowAlwaysOpenCheckbox -bool true
|
|
||||||
```
|
|
||||||
|
|
||||||
|
|
||||||
##### Note for Emacs Mac Port
|
|
||||||
|
|
||||||
If you're using [Emacs Mac Port](https://github.com/railwaycat/homebrew-emacsmacport), it
|
|
||||||
registered its `Emacs.app` as the default handler for the URL scheme
|
|
||||||
`org-protocol`. We have to make our `OrgProtocol.app` the default
|
|
||||||
handler instead (replace `org.yourusername.OrgProtocol` with your app
|
|
||||||
identifier):
|
|
||||||
|
|
||||||
```
|
|
||||||
$ defaults write com.apple.LaunchServices/com.apple.launchservices.secure LSHandlers -array-add \
|
|
||||||
'{"LSHandlerPreferredVersions" = { "LSHandlerRoleAll" = "-"; }; LSHandlerRoleAll = "org.yourusername.OrgProtocol"; LSHandlerURLScheme = "org-protocol";}'
|
|
||||||
```
|
|
||||||
|
|
||||||
Then restart your computer.
|
|
||||||
|
|
||||||
[org-protocol-inst]: https://orgmode.org/worg/org-contrib/org-protocol.html
|
|
||||||
@ -1,123 +0,0 @@
|
|||||||
Rather than creating blank files on `org-roam-insert` and
|
|
||||||
`org-roam-find-file`, it is may be desirable to prefill the file with
|
|
||||||
content. This may include:
|
|
||||||
|
|
||||||
- Time of creation
|
|
||||||
- File it was created from
|
|
||||||
- Clipboard content
|
|
||||||
- Any other data you may want to input manually
|
|
||||||
|
|
||||||
This requires a complex template insertion system, but fortunately,
|
|
||||||
Org ships with a powerful one: `org-capture`. However, org-capture was
|
|
||||||
not designed for such use. Org-roam abuses `org-capture` to some
|
|
||||||
extent, extending its syntax. To first understand how org-roam's
|
|
||||||
templating system works, it may be useful to look into org-capture.
|
|
||||||
|
|
||||||
Org-roam's templates can be customized by modifying the variable
|
|
||||||
`org-roam-capture-templates`.
|
|
||||||
|
|
||||||
## Org-roam Templates
|
|
||||||
|
|
||||||
The org-roam capture template extends org-capture's template with 2
|
|
||||||
additional properties:
|
|
||||||
|
|
||||||
1. `:file-name`: This is the file name template used when a new note
|
|
||||||
is created. Notes can be placed in sub-directories by prepending them to
|
|
||||||
the filename (`sub/file-name`)
|
|
||||||
2. `:head`: This is the template that is inserted on initial note
|
|
||||||
creation.
|
|
||||||
|
|
||||||
### Org-roam Template Expansion
|
|
||||||
|
|
||||||
Org-roam's template definitions also extend org-capture's template
|
|
||||||
syntax, to allow prefilling of strings. In many scenarios,
|
|
||||||
`org-roam-capture--capture` is passed a mapping between variables and strings.
|
|
||||||
For example, during `org-roam-insert`, a title is prompted for. If the
|
|
||||||
title doesn't already exist, we would like to create a new file,
|
|
||||||
without prompting for the title again.
|
|
||||||
|
|
||||||
Variables passed are expanded with the `${var}` syntax. For example,
|
|
||||||
during `org-roam-insert`, `${title}` is prefilled for expansion. Any
|
|
||||||
variables that do not contain strings, are prompted for values using
|
|
||||||
`completing-read`.
|
|
||||||
|
|
||||||
After doing this expansion, the org-capture's template expansion
|
|
||||||
system is used to fill up the rest of the template. You may read up
|
|
||||||
more on this on [org-capture's documentation
|
|
||||||
page](https://orgmode.org/manual/Template-expansion.html#Template-expansion).
|
|
||||||
|
|
||||||
For example, take the template: `"%<%Y%m%d%H%M%S>-${title}"`, with the title
|
|
||||||
`"Foo"`. The template is first expanded into `%<%Y%m%d%H%M%S>-Foo`. Then
|
|
||||||
org-capture expands `%<%Y%m%d%H%M%S>` with timestamp: e.g.
|
|
||||||
`20200213032037-Foo`.
|
|
||||||
|
|
||||||
All of the flexibility afforded by emacs and org-mode are
|
|
||||||
available. For example, if you want to encode a UTC timestamp in the
|
|
||||||
filename, you can take advantage of org-mode's `%(EXP)` template
|
|
||||||
expansion to call `format-time-string` directly to provide its third
|
|
||||||
argument to specify UTC.
|
|
||||||
|
|
||||||
``` emacs-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)
|
|
||||||
```
|
|
||||||
|
|
||||||
Similarly, if you want to change how titles are transformed into
|
|
||||||
slugs, you can override `org-roam--title-to-slug`. For example, to use
|
|
||||||
hyphens instead of underscores:
|
|
||||||
|
|
||||||
|
|
||||||
``` emacs-lisp
|
|
||||||
(defun org-roam--title-to-slug (title)
|
|
||||||
"Convert TITLE to a filename-suitable slug. Uses hyphens rather than underscores."
|
|
||||||
(cl-flet* ((nonspacing-mark-p (char)
|
|
||||||
(eq 'Mn (get-char-code-property char 'general-category)))
|
|
||||||
(strip-nonspacing-marks (s)
|
|
||||||
(apply #'string (seq-remove #'nonspacing-mark-p
|
|
||||||
(ucs-normalize-NFD-string s))))
|
|
||||||
(cl-replace (title pair)
|
|
||||||
(replace-regexp-in-string (car pair) (cdr pair) title)))
|
|
||||||
(let* ((pairs `(("[^[:alnum:][:digit:]]" . "-") ;; convert anything not alphanumeric
|
|
||||||
("--*" . "-") ;; remove sequential underscores
|
|
||||||
("^-" . "") ;; remove starting underscore
|
|
||||||
("-$" . ""))) ;; remove ending underscore
|
|
||||||
(slug (-reduce-from #'cl-replace (strip-nonspacing-marks title) pairs)))
|
|
||||||
(s-downcase slug))))
|
|
||||||
```
|
|
||||||
|
|
||||||
This templating system is used throughout org-roam templates.
|
|
||||||
|
|
||||||
### Template examples
|
|
||||||
|
|
||||||
Here I walkthrough the default template, reproduced below.
|
|
||||||
|
|
||||||
```
|
|
||||||
("d" "default" plain (function org-roam--capture-get-point)
|
|
||||||
"%?"
|
|
||||||
:file-name "%<%Y%m%d%H%M%S>-${slug}"
|
|
||||||
:head "#+TITLE: ${title}\n"
|
|
||||||
:unnarrowed t)
|
|
||||||
```
|
|
||||||
|
|
||||||
1. The template has short key `"d"`. If you have only one template,
|
|
||||||
org-roam automatically chooses this template for you.
|
|
||||||
2. The template is given a description of `"default"`.
|
|
||||||
3. `plain` text is inserted. Other options include Org headings via
|
|
||||||
`entry`.
|
|
||||||
4. `(function org-roam--capture-get-point)` should not be changed.
|
|
||||||
5. `"%?"` is the template inserted on each call to `org-roam-capture--capture`.
|
|
||||||
This template means don't insert any content, but place the cursor
|
|
||||||
here.
|
|
||||||
6. `:file-name` is the file-name template for a new note, if it
|
|
||||||
doesn't yet exist. This creates a file at path that looks like
|
|
||||||
`/path/to/org-roam-directory/20200213032037-foo.org`.
|
|
||||||
7. `:head` contains the initial template to be inserted (once only),
|
|
||||||
at the beginning of the file. Here, the title global attribute is
|
|
||||||
inserted.
|
|
||||||
8. `:unnarrowed t` tells org-capture to show the contents for the
|
|
||||||
whole file, rather than narrowing to just the entry.
|
|
||||||
|
|
||||||
Other options you may want to learn about include `:immediate-finish`.
|
|
||||||
70
doc/tour.md
70
doc/tour.md
@ -1,70 +0,0 @@
|
|||||||
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.
|
|
||||||
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 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.
|
|
||||||
|
|
||||||
## Activating Org-roam
|
|
||||||
|
|
||||||
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 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-db-build-cache`.
|
|
||||||
|
|
||||||
## Finding a Note
|
|
||||||
|
|
||||||
`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.
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
Note that in the above image, the [ivy](https://github.com/abo-abo/swiper)
|
|
||||||
completion frontend is used. The default frontend has some usability issues with
|
|
||||||
non-matching candidates (e.g. when you want to enter a title of a new note,
|
|
||||||
there is no completion candidate), so either `ivy` or `helm` is recommended.
|
|
||||||
|
|
||||||
## Inserting Links
|
|
||||||
|
|
||||||
`org-roam-insert` insert links to existing (or new) notes. Entering a
|
|
||||||
non-existent title will also create a new note with that title.
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
Good usage of Org-roam requires liberally linking files. This allows
|
|
||||||
the build-up of a dense knowledge graph.
|
|
||||||
|
|
||||||
## The Org-roam Buffer
|
|
||||||
|
|
||||||
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
|
|
||||||
|
|
||||||
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:roam-protocol]: roam_protocol.md
|
|
||||||
[roam]: https://www.roamresearch.com/
|
|
||||||
[jethro-blog-post]: https://blog.jethro.dev/posts/how_to_take_smart_notes_org/
|
|
||||||
Reference in New Issue
Block a user