Add documentation

README.md

@@ -1,21 +1,26 @@
-# Org-roam
+[![Documentation Status](https://readthedocs.org/projects/org-roam/badge/?version=latest)](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.
 
-![img](images/readme/screen.png)
-
-## 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.
+![img](doc/images/org-roam-graph.gif)
 
 ## 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/

doc/comparison.md

@@ -0,0 +1,11 @@
+---
+title: "Comparing Org-Roam With Other Packages"
+metaTitle: "Comparing Org-Roam With Other Packages"
+metaDescription: "Comparing Org-Roam With Other Packages"
+---
+
+# Org-brain
+
+# Zetteldeft
+
+# Org-zettelkasten

doc/ecosystem.md

@@ -0,0 +1,37 @@
+## Ecosystem
+
+A number of packages work well combined with Org-Roam:
+
+### Deft
+[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
+[Org-journal](https://github.com/bastibe/org-journal) is a more
+powerful alternative to the simple function `org-roam-today`. It
+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"))
+```

doc/index.md

@@ -0,0 +1,41 @@
+![org-roam][org-roam-intro-image]
+
+## What is Org-Roam?
+
+Org-roam is a rudimentary [Roam][roamresearch] replica built around
+the all-powerful [Org-mode][org]. 
+
+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. 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)
+
+The goal of the project is to implement core features of Roam around
+Org-mode, and eventually introduce features enabled by the Emacs
+ecosystem. 
+
+## Why build Org-Roam?
+
+With Org-roam, you:
+
+1. Never have to leave Emacs.
+2. Can leverage all the powerful features of Org-mode: LaTeX, tables,
+   and the whole to-do ecosystem (org-agenda etc.)
+3. Be in full control your second brain, and access it offline. Never
+   share your data with anyone
+
+There are several packages that are similar to Org-roam, see the
+[Comparison](comparison.md) page for a detailed comparison.
+
+## Project Status
+
+As of February 2020, it is in a very early stage of development. 
+
+[org-roam-intro-image]: images/org-roam-intro.png
+[roamresearch]: https://www.roamresearch.com/
+[org]: https://orgmode.org/

doc/installation.md

@@ -0,0 +1,35 @@
+## Installation
+
+The recommended method is using [use-package][use-package] and
+[straight][straight], 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)
+```
+
+[use-package]: https://github.com/jwiegley/use-package
+[straight]: https://github.com/raxod502/straight.el

doc/tour.md

@@ -0,0 +1,20 @@
+### A Tour of Org-Roam
+
+All of this starts from the note. A note is just a simple `.org` file
+in the directory. Any org file in the directory is considered part of
+the org-roam ecosystem. Notes are quickly linked together (and created
+if necessary) using `org-roam-insert`.
+
+![org-roam-insert](images/org-roam-insert.gif)
+
+Org-roam tracks all of these file links, and builds a cache
+asynchronously in the background. This cache is used to populate the
+backlinks buffer, which shows files that link to the current file, as
+well as some preview contents:
+
+![org-roam-buffer](images/org-roam-buffer.gif)
+
+These file links also form a graph. The generated graph is navigable
+in Emacs.
+
+![org-roam-graph](images/org-roam-graph.gif)

mkdocs.yml

@@ -0,0 +1,14 @@
+site_name: "Org-Roam: Roam + Org-Mode = 💝"
+repo_url: https://github.com/jethrokuan/org-roam/
+edit_uri: edit/master/doc/
+site_favicon: favicon.ico
+copyright: "Copyright (C) 2020 Jethro Kuan and contributors"
+docs_dir: doc
+pages:
+- Home: index.md
+- A Tour of Org-Roam: tour.md
+- Installation: installation.md
+- Ecosystem: ecosystem.md
+- Similar Packages: comparison.md
+theme: readthedocs
+

shell.nix

@@ -0,0 +1,10 @@
+let
+  pkgs = import <nixpkgs> {};
+in
+pkgs.mkShell {
+  name = "docs";
+  buildInput = with pkgs; [
+    mkdocs
+    python3Packages.alabaster
+  ];
+}