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.
package.el
Using Toggle instructions
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.
straight.el
Using Toggle instructions
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 instructions
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
git
from 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.