mirror of
https://github.com/org-roam/org-roam
synced 2025-08-01 12:17:21 -05:00
Update README
This commit is contained in:
Jethro Kuan
117
README.md
Normal file
117
README.md
Normal file
@ -0,0 +1,117 @@
|
|||||||
|
# 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.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
## Installation
|
||||||
|
|
||||||
|
You should first have [deft](https://jblevins.org/projects/deft/)
|
||||||
|
setup properly. This is only necessary now, and I intend to move away
|
||||||
|
from it once it becomes clearer what org-roam should be presenting.
|
||||||
|
|
||||||
|
```
|
||||||
|
(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 "~/org-files/")
|
||||||
|
(deft-use-filename-as-title t))
|
||||||
|
```
|
||||||
|
|
||||||
|
You can then setup org-roam as follows. 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 deft org
|
||||||
|
:straight (:host "github" :repo "jethrokuan/org-roam")
|
||||||
|
:bind
|
||||||
|
("C-c n l" . org-roam)
|
||||||
|
("C-c n t" . org-roam-today)
|
||||||
|
("C-c n i" . org-roam-insert))
|
||||||
|
```
|
||||||
|
|
||||||
|
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 deft 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 the deft interface. 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 deft 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!
|
||||||
|
|
||||||
|
## Knowledge Bases using Org-Roam
|
||||||
|
|
||||||
|
- [Jethro Kuan](https://braindump.jethro.dev/)
|
||||||
|
([Source](https://github.com/jethrokuan/braindump/tree/master/org))
|
||||||
|
|
||||||
|
## 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.
|
||||||
|
|
||||||
|
## Contributing
|
||||||
|
|
||||||
|
Pull requests with improvements are welcome. For feature requests,
|
||||||
|
create Github issues.
|
||||||
|
|
||||||
77
README.org
77
README.org
@ -1,77 +0,0 @@
|
|||||||
* Org-roam
|
|
||||||
|
|
||||||
** About
|
|
||||||
|
|
||||||
Org-roam is a rudimentary [[https://roamresearch.com/][Roam]] 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* notetaking approach which is *effortless* yet powerful. Notetaking 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 know more about Roam, these following links are recommended.
|
|
||||||
|
|
||||||
- [[reddit.com/r/RoamResearch/comments/eho7de/building_a_second_brain_in_roamand_why_you_might][Building a second brain in Roam]]
|
|
||||||
- [[https://www.nateliason.com/blog/roam][Roam: Why I Love It and How I Use It]]
|
|
||||||
|
|
||||||
The best way to understand the usefulness of this approach is to actually try it.
|
|
||||||
|
|
||||||
|
|
||||||
** Project Status
|
|
||||||
|
|
||||||
As of February 2020, it is in a very early stage of development.
|
|
||||||
|
|
||||||
|
|
||||||
** Screenshot
|
|
||||||
|
|
||||||
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, so there will be no significant slowdown.
|
|
||||||
|
|
||||||
#+DOWNLOADED: screenshot @ 2020-02-03 17:10:40
|
|
||||||
[[file:images/readme/screenshot2020-02-03_17-10-40_.png]]
|
|
||||||
|
|
||||||
** Installation
|
|
||||||
|
|
||||||
You need to have [[https://jblevins.org/projects/deft/][deft]] installed.
|
|
||||||
|
|
||||||
#+begin_src emacs-lisp
|
|
||||||
(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 "~/org-files/")
|
|
||||||
(deft-use-filename-as-title t))
|
|
||||||
|
|
||||||
(use-package org-roam
|
|
||||||
:after deft org
|
|
||||||
:straight (:host "github" :repo "jethrokuan/org-roam")
|
|
||||||
:bind
|
|
||||||
("C-c n l" . org-roam)
|
|
||||||
("C-c n t" . org-roam-today)
|
|
||||||
("C-c n i" . org-roam-insert))
|
|
||||||
#+end_src
|
|
||||||
|
|
||||||
*Failback installation*:
|
|
||||||
|
|
||||||
Clone the git repo locally and in your emacs init.el put something like
|
|
||||||
|
|
||||||
#+begin_src emacs-lisp
|
|
||||||
|
|
||||||
(add-to-list 'load-path "~/Downloads/org-roam")
|
|
||||||
(require 'org-roam)
|
|
||||||
#+end_src
|
|
||||||
|
|
||||||
|
|
||||||
** Quickstart
|
|
||||||
|
|
||||||
Toy scenario: Suppose you want to keep track of all the cool-facts you come across, but it is really effortsome to everytime find the exact file to note an individual cool-fact.
|
|
||||||
|
|
||||||
1. Open a deft file and start writing about anything. Now in any sentence you can call the function ~org-roam-insert~ and choose the filename ~cool-facts~ and then keep on writing whatever you want.
|
|
||||||
|
|
||||||
2. Later 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 deft database are easily accessible from here.
|
|
||||||
|
|
||||||
** Contributing
|
|
||||||
|
|
||||||
Pull requests with improvements are very welcome. For feature requests create Github issues.
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
Reference in New Issue
Block a user