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