mirror of
https://github.com/org-roam/org-roam
synced 2025-08-01 12:17:21 -05:00
Add documentation
This commit is contained in:
Jethro Kuan
141
README.md
141
README.md
@ -1,21 +1,26 @@
|
||||
# Org-roam
|
||||
[](https://org-roam.readthedocs.io/en/latest/?badge=latest)
|
||||
|
||||
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.
|
||||
Org-roam is a rudimentary [Roam][roamresearch] replica built around
|
||||
the all-powerful [Org-mode][org].
|
||||
|
||||
To learn more about Roam, I recommend the following links:
|
||||
Like Roam, Org-roam offers a powerful and effortless non-hierarchical
|
||||
note-taking approach. With Org-roam, notes flow naturally, making
|
||||
note-taking fun and easy.
|
||||
|
||||
- [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)
|
||||
The goal of the project is to implement core features of Roam around
|
||||
Org-mode, and eventually introduce features enabled by the Emacs
|
||||
ecosystem.
|
||||
|
||||
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.
|
||||
For more documentation, see [the documentation page](https://org-roam.readthedocs.io/en/latest/).
|
||||
|
||||
## Understanding Roam
|
||||
|
||||
To understand 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)
|
||||
|
||||
## Project Status
|
||||
|
||||
@ -30,106 +35,7 @@ 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
|
||||
|
||||
@ -138,6 +44,9 @@ project, but I have thus far found it sufficient.
|
||||
|
||||
## Contributing
|
||||
|
||||
Pull requests with improvements are welcome. For feature requests,
|
||||
create Github issues.
|
||||
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.
|
||||
|
||||
[roamresearch]: https://www.roamresearch.com/
|
||||
[org]: https://orgmode.org/
|
||||
|
||||
Reference in New Issue
Block a user