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

M-x package-install RET org-roam RET

Using straight.el

(straight-use-package 'org-roam)

(use-package org-roam
  :straight t
  ...)

(use-package org-roam
  :straight (:host github :repo "org-roam/org-roam"
             :files (:defaults "extensions/*"))
  ...)

(use-package org-roam
  :straight (:local-repo "/path/to/org-roam-fork"
             :files (:defaults "extensions/*")
             :build (:not compile))
  ...)

Using Doom Emacs

(unpin! org-roam)

(package! org-roam)

(package! org-roam
  :recipe (:host github :repo "org-roam/org-roam"
           :files (:defaults "extensions/*")))

(package! org-roam
  :recipe (:local-repo "/path/to/org-roam-fork"
           :files (:defaults "extensions/*")
           :build (:not compile)))

Without a package manager

(add-to-list 'load-path "/path/to/org-roam/")
(add-to-list 'load-path "/path/to-org-roam/extensions/")

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
• Martin Edström

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.