README.md

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.

• Documentation
• Discourse
• Slack
• Frequently Asked Questions
• Changelog

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 instructions

You can install org-roam from MELPA or MELPA Stable using package.el:

M-x package-install RET org-roam RET

Using straight.el

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:

1. Install the package by cloning it with git from the source repository.
2. 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.

Configuration

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
  ;; If you're using a vertical completion framework, you might want a more informative completion interface
  (setq org-roam-node-display-template (concat "${title:*} " (propertize "${tags:10}" 'face 'org-tag)))
  (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.

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

• Jethro Kuan (Source)
• Alexey Shmalko
• Sidharth Arya

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.