mirror of
https://github.com/org-roam/org-roam
synced 2025-08-01 12:17:21 -05:00
144 lines
4.7 KiB
Markdown
144 lines
4.7 KiB
Markdown
# Org-roam
|
|
|
|
Org-roam is a rudimentary [Roam](https://roamresearch.com/) replica in
|
|
Org-mode. This project intends to adaptively implement the core
|
|
features of Roam in org-mode and eventually introduce newer features
|
|
suitable for the Emacs ecosystem. It offers a **non-hierarchical**
|
|
note-taking approach which is **effortless** yet powerful. Note-taking
|
|
becomes fluent and easy when you don't have to worry about *where* a
|
|
particular note should go: you just start writing from anywhere about
|
|
anything.
|
|
|
|
To learn more about Roam, I recommend the following links:
|
|
|
|
- [Building a second brain in Roam](https://reddit.com/r/RoamResearch/comments/eho7de/building_a_second_brain_in_roamand_why_you_might)
|
|
- [Roam: Why I Love It and How I Use It](https://www.nateliason.com/blog/roam)
|
|
|
|
It is difficult to explain the workflow in words, so the best way to
|
|
figure out whether this is for you is to try it.
|
|
|
|
## Project Status
|
|
|
|
As of February 2020, it is in a very early stage of development.
|
|
|
|
## A Preview
|
|
|
|
Here's a screenshot of `org-roam`. The `org-roam` buffer shows
|
|
backlinks for the active org buffer in the left window, as well as the
|
|
surrounding content in the backlink file. The backlink database is
|
|
built asynchronously in the background, and is not noticeable to the
|
|
end user. The graph is generated from the link structure, and can be
|
|
used to navigate to the respective files.
|
|
|
|
|
|
|
|
## Installation
|
|
|
|
The recommended method is using
|
|
[use-package](https://github.com/jwiegley/use-package) and
|
|
[straight](https://github.com/raxod502/straight.el), or a similar
|
|
package manager.
|
|
|
|
```
|
|
(use-package org-roam
|
|
:after org
|
|
:hook (org-mode . org-roam-mode)
|
|
:straight (:host github :repo "jethrokuan/org-roam")
|
|
:custom
|
|
(org-roam-directory "/path/to/org-files/")
|
|
(org-roam-link-representation 'title) ;; or keep it as 'id
|
|
:bind
|
|
("C-c n l" . org-roam)
|
|
("C-c n t" . org-roam-today)
|
|
("C-c n f" . org-roam-find-file)
|
|
("C-c n i" . org-roam-insert)
|
|
("C-c n g" . org-roam-show-graph))
|
|
```
|
|
|
|
If not using package.el, you can also clone it into your Emacs
|
|
directory and add it to your load path:
|
|
|
|
```
|
|
git clone https://github.com/jethrokuan/org-roam/ ~/.emacs.d/elisp/org-roam
|
|
```
|
|
|
|
```
|
|
(add-to-list 'load-path "./elisp")
|
|
(require 'org-roam)
|
|
```
|
|
|
|
## Quickstart
|
|
|
|
Suppose you want to keep track of all the cool-facts you come across.
|
|
|
|
1. Open a org-roam file and start writing about anything. You can choose
|
|
to jot it in your daily file with `org-roam-today`, or pick a file
|
|
using `org-roam-find-file`. Anywhere near your cool fact, run `M-x
|
|
org-roam-insert` and choose the filename `cool-facts` and then keep
|
|
on writing whatever you want. You can choose to create existing
|
|
files, or create a new file if necessary.
|
|
2. When you open `cool-facts.org` and call `org-roam` you will
|
|
see all the places you have referenced this file. So all the
|
|
cool-facts you have writen anywhere in your database are
|
|
easily accessible from here.
|
|
3. Note that `cool-facts.org` doesn't even have to contain any
|
|
content: it can just be used as an index page for referencing all
|
|
cool facts that you've written across your notes!
|
|
|
|
## Synergistic Packages in the Org Ecosystem
|
|
|
|
A number of packages work well combined with Org-roam:
|
|
|
|
[Deft](https://jblevins.org/projects/deft/) provides a nice
|
|
interface for browsing and filtering org-roam notes.
|
|
|
|
```
|
|
(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/")
|
|
(deft-use-filename-as-title t))
|
|
```
|
|
|
|
[Org-journal](https://github.com/bastibe/org-journal) is a more
|
|
powerful alternative to the simple function `org-roam-today`, that
|
|
provides better journaling capabilities, and a nice calendar interface
|
|
to see all dated entries.
|
|
|
|
```
|
|
(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"))
|
|
```
|
|
|
|
## Similar Projects
|
|
|
|
- [org-zettelkasten](https://github.com/l3kn/org-zettelkasten)
|
|
- [zetteldeft](https://github.com/EFLS/zetteldeft)
|
|
|
|
The main differentiating factor of this project is that links are just
|
|
natural file links, with no dependence on special tagging with e.g.
|
|
org IDs, or special indicators. This constraints the utility of the
|
|
project, but I have thus far found it sufficient.
|
|
|
|
## Knowledge Bases using Org-Roam
|
|
|
|
- [Jethro Kuan](https://braindump.jethro.dev/)
|
|
([Source](https://github.com/jethrokuan/braindump/tree/master/org))
|
|
|
|
## Contributing
|
|
|
|
Pull requests with improvements are welcome. For feature requests,
|
|
create Github issues.
|
|
|