b6a898d6d6
Instead of using various capture template variables, like
org-roam-dailies-capture-templates or org-roam-capture-ref-templates,
just use org-roam-capture-templates for everything.
From now on, each individual template will able to optionally specify a
more detailed context for which they're dedicated for, using :kind and
:action properties. Both of them accept either, a symbol or a list of
symbols.
If it's a list, then it can optionally start with :not symbol to
indicate inverse logic, otherwise it will act akin to memq. If it's a
symbol, then it will work akin to eq, but with support for special 'any
value, which indicates that it will work in any contexts; 'any can be
also used inside of the list based values.
Org-roam and the built-in extension will provide the following contexts:
- :action {capture,goto,any}
- :kind {normal,daily,protocol,any}
but third party extensions / users can easily extend them for their own
needs.
If :action isn't specified it will implicitly default to 'capture, while
:kind will default to 'normal contexts.
BREAKING CHANGE: org-roam-dailies-capture-templates and
org-roam-capture-ref-templates are now removed in the favor of unified
approach.
Org-roam 
Org-roam is a plain-text knowledge management system. It brings some of Roam's more powerful features into the Org-mode ecosystem.
Org-roam borrows principles from the Zettelkasten method, providing a solution for non-hierarchical note-taking. It should also work as a plug-and-play solution for anyone already using Org-mode for their personal wiki.
- Private and Secure: Edit your personal wiki completely offline, entirely in your control. Encrypt your notes with GPG. Take lasting notes in plain-text.
- Networked Thought: Connect notes and thoughts together with ease using backlinks. Discover surprising and previously unseen connections in your notes with the built-in graph visualization.
- Extensible and Powerful: Leverage Emacs' fantastic text-editing interface, and the mature Emacs and Org-mode ecosystem of packages.
- Free and Open Source: Org-roam is licensed under the GNU General Public License version 3 or later.
Installation
Down below you will find basic installation instructions for how to quickly
install org-roam using various environments for various purposes. For more
detailed information, please read the manual.
Using package.el
Toggle instuctions
You can install org-roam from MELPA or MELPA
Stable using package.el:
M-x package-install RET org-roam RET
Here's a very basic sample for configuration of org-roam using use-package:
(use-package org-roam
:ensure t
:custom
(org-roam-directory (file-truename "/path/to/org-files/"))
:bind (("C-c n l" . org-roam-buffer-toggle)
("C-c n f" . org-roam-node-find)
("C-c n g" . org-roam-graph)
("C-c n i" . org-roam-node-insert)
("C-c n c" . org-roam-capture)
;; Dailies
("C-c n j" . org-roam-dailies-capture-today))
:config
(org-roam-db-autosync-mode)
;; If using org-roam-protocol
(require 'org-roam-protocol))
Note that the file-truename function is only necessary when you use symbolic
link to org-roam-directory. Org-roam won't automatically resolve symbolic link
to the directory.
Using straight.el
Toggle instuctions
Installation from MELPA or MELPA Stable using straight.el:
(straight-use-package 'org-roam)
Or with use-package:
(use-package org-roam
:straight t
...)
If you need to install the package directly from the source repository, instead of from MELPA, the next sample shows how to do so:
(use-package org-roam
:straight (:host github :repo "org-roam/org-roam"
:files (:defaults "extensions/*"))
...)
If you plan to use your own local fork for the development and contribution, the next sample will get you there:
(use-package org-roam
:straight (:local-repo "/path/to/org-roam-fork"
:files (:defaults "extensions/*")
:build (:not compile))
...)
Using Doom Emacs
Toggle instuctions
Doom's :lang org module comes with support for org-roam, but it's not
enabled by default. To activate it pass +roam2 flag to org module in your
$DOOMDIR/init.el (e.g. (org +roam2)), save the file and run doom sync -u
in your shell.
To provide better stability, Doom pins the package to a specific commit. If you
need to unpin it (not recommended doing that, request Doom to bump the package
instead) use the next in your packages.el:
(unpin! org-roam)
If for some reasons you want to use a different recipe for org-roam, you can
use the next form in your packages.el to install the package from a recipe
repository (e.g. MELPA):
(package! org-roam)
You can pass :pin "commit hash" to pin the package to a specific commit.
With the next sample you can install the package directly from the source repository:
(package! org-roam
:recipe (:host github :repo "org-roam/org-roam"
:files (:defaults "extensions/*")))
And if you plan to use your own local fork for the development or contribution, the next sample will get you there:
(package! org-roam
:recipe (:local-repo "/path/to/org-roam-fork"
:files (:defaults "extensions/*")
:build (:not compile)))
Without a package manager
Toggle instructions
To install the package without using a package manager you have the next two options:
- Install the package by cloning it with
gitfrom the source repository. - Or install the package by downloading the latest release version.
In both of the cases you will need to ensure that you have all the required dependencies. These include:
- dash
- f
- s
- org (9.4 is the minimal required version!)
- emacsql
- emacsql-sqlite
- magit-section
- filenotify-recursive
After installing the package, you will need to properly setup load-path to the
package:
(add-to-list 'load-path "/path/to/org-roam/")
(add-to-list 'load-path "/path/to-org-roam/extensions/")
After which you should be able to resolve (require 'org-roam) call without any
problems.
Org-roam also comes with .texi files to integrate with Emacs' built-in Info
system. Read the manual to find more details for how to install them manually.
Getting Started
David Wilson of System Crafters has produced an introductory video that covers the basic commands:
Getting Help
Before creating a new topic/issue, please be mindful of our time and ensure that it has not already been addressed on GitHub or on Discourse.
- If you are new to Emacs and have problem setting up Org-roam, please ask your question on Slack, channel #how-do-i.
- For quick questions, please ask them on Slack, channel #troubleshooting.
- If something is not working as it should, or if you would like to suggest a new feature, please create a new issue.
- If you have questions about your workflow with the slip-box method, please find a relevant topic on Discourse, or create a new one.
Knowledge Bases using Org-roam
Contributing
To report bugs and suggest new feature use the issue tracker. If you have some code which you would like to be merged, then open a pull request. Please also see CONTRIBUTING.md.
License
Copyright © Jethro Kuan and contributors. Distributed under the GNU General Public License, Version 3.