diff --git a/README.md b/README.md new file mode 100644 index 0000000..3eb72ce --- /dev/null +++ b/README.md @@ -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. + +![img](images/readme/screenshot2020-02-03_17-10-40_.png) + +## 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. + diff --git a/README.org b/README.org deleted file mode 100644 index fe00de0..0000000 --- a/README.org +++ /dev/null @@ -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. - - -