From 9e2998c580918e3bd5dea1e1c4f65ec0c59b0373 Mon Sep 17 00:00:00 2001 From: Jethro Kuan Date: Wed, 13 May 2020 19:24:17 +0800 Subject: [PATCH] (ci): remove old docs, add landing page (#619) --- .gitignore | 1 + doc/Makefile | 1 + doc/anatomy.md | 41 -------- doc/comparison.md | 11 --- doc/configuration.md | 157 ----------------------------- doc/ecosystem.md | 138 -------------------------- doc/index.md | 62 ------------ doc/installation.md | 197 ------------------------------------- doc/notetaking_workflow.md | 24 ----- doc/org_export.md | 61 ------------ doc/requirements.txt | 2 - doc/roam_protocol.md | 169 ------------------------------- doc/templating.md | 123 ----------------------- doc/tour.md | 70 ------------- 14 files changed, 2 insertions(+), 1055 deletions(-) delete mode 100644 doc/anatomy.md delete mode 100644 doc/comparison.md delete mode 100644 doc/configuration.md delete mode 100644 doc/ecosystem.md delete mode 100644 doc/index.md delete mode 100644 doc/installation.md delete mode 100644 doc/notetaking_workflow.md delete mode 100644 doc/org_export.md delete mode 100644 doc/requirements.txt delete mode 100644 doc/roam_protocol.md delete mode 100644 doc/templating.md delete mode 100644 doc/tour.md diff --git a/.gitignore b/.gitignore index e8c35c4..f0da069 100644 --- a/.gitignore +++ b/.gitignore @@ -13,3 +13,4 @@ /doc/mimetype /doc/stats/ /config.mk +/doc/manual/ diff --git a/doc/Makefile b/doc/Makefile index 8de0b05..9f998e5 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -29,6 +29,7 @@ dir: org-roam.info html-dir: @printf "Generating org-roam/*.html\n" @$(MAKEINFO) --html org-roam.texi + mv org-roam manual %.pdf: %.texi @printf "Generating $@\n" diff --git a/doc/anatomy.md b/doc/anatomy.md deleted file mode 100644 index 55a4963..0000000 --- a/doc/anatomy.md +++ /dev/null @@ -1,41 +0,0 @@ -The bulk of Org-roam's functionality is built on top of vanilla -Org-mode. However, to support additional functionality, Org-roam adds -several Org-roam-specific keywords. These functionality are not -crucial to effective use of Org-roam. - -## File Aliases - -Suppose you want a note to be referred to by different names (e.g. -"World War 2", "WWII"). You may specify such aliases using the -`#+ROAM_ALIAS` attribute: - -```org -#+TITLE: World War 2 -#+ROAM_ALIAS: "WWII" "World War II" -``` - - -## File Refs - -Refs are unique identifiers for files. Each note can only have 1 ref. -For example, a note for a website may contain a ref: - -```org -#+TITLE: Google -#+ROAM_KEY: https://www.google.com/ -``` - -These keys come in useful for when taking website notes, using the -`roam-ref` protocol (see [Roam Protocol](roam_protocol.md)). - -Alternatively, add a ref for notes for a specific paper, using its -[org-ref](https://github.com/jkitchin/org-ref) citation key: - -```org -#+TITLE: Neural Ordinary Differential Equations -#+ROAM_KEY: cite:chen18_neural_ordin_differ_equat -``` - -The backlinks buffer will show any cites of this key: e.g. - -![org-ref-citelink](images/org-ref-citelink.png) diff --git a/doc/comparison.md b/doc/comparison.md deleted file mode 100644 index 1700ee7..0000000 --- a/doc/comparison.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -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 diff --git a/doc/configuration.md b/doc/configuration.md deleted file mode 100644 index f547ec7..0000000 --- a/doc/configuration.md +++ /dev/null @@ -1,157 +0,0 @@ -The number of configuration options is deliberately kept small, to -keep the Org-roam codebase manageable. However, we attempt to -accommodate as many usage styles as possible. - -All of Org-roam's customization options can be viewed via `M-x -customize-group org-roam`. - -## Setting the Org-roam Directory - -Set `org-roam-directory` to the folder containing all your Org files: - -```emacs-lisp -(setq org-roam-directory "/path/to/org/") -``` - -Every Org file, at any level of nesting, within `/path/to/org/` is -considered part of the Org-roam ecosystem. - -### Having More Than One Org-roam Directory - -Emacs supports directory-local variables, allowing the value of -`org-roam-directory` to be different in different directories. It does -this by checking for a file named `.dir-locals.el`. - -To add support for multiple directories, override the -`org-roam-directory` variable using directory-local variables. This is -what `.dir-locals.el` may contain: - -```emacs-lisp -((nil . ((org-roam-directory . "/path/to/here/")))) -``` - -All files within that directory will be treated as their own separate -set of Org-roam files. Remember to run `org-roam-db-build-cache` from a -file within that directory, at least once. - -## Org-roam Buffer - -The Org-roam buffer defaults to popping up from the right. You may -choose to set it to pop up from the left with `(setq -org-roam-buffer-position 'left)`. - -The Org-roam buffer name can also be renamed: e.g. `(setq -org-roam-buffer "*my-buffer-name*")`. - -The Org-roam buffer width is adjustable via `org-roam-buffer-width`. -The value of `org-roam-buffer-width` set as a percentage of the total -frame width. For example: - -```emacs-lisp -(setq org-roam-buffer-width 0.4) -``` - -Will result in the Org-roam buffer taking up 40% of the screen width. - -You can change backlinks appearance in the buffer by customizing -`org-roam-backlink` face (`M-x customize-face org-roam-backlink`). - -## Org-roam Links - -By default, links are inserted with the title as the link description. -This can make them hard to distinguish from external links. You may -choose add special indicators for Org-roam links by tweaking -`org-roam-link-title-format`, for example: - -```emacs-lisp -(setq org-roam-link-title-format "R:%s") -``` - -If your version of Org is at least `9.2`, you may also choose to -simply style the link differently, by customizing `org-roam-link` face -(`M-x customize-face org-roam-link`). - -## Org-roam Files - -Org-roam files are created and prefilled using Org-roam's templating -system. The templating system is customizable, and the system is -described in detail in the [Org-roam Template](templating.md) page. - -### Index - -As your collection grows, you might want to create an index where you keep -links to your main files. - -In Org-roam, you can define the path to your index file by setting `org-roam-index-file`. - -```emacs-lisp -(setq org-roam-index-file "index.org") -``` - -You can then bind `org-roam-jump-to-index` in your configuration to access it (see [Basic Install and -Configuration](installation.md/#basic-install-and-configuration) to review how -to set key-bindings). - -### Encryption - -Encryption (via GPG) can be enabled for all new files by setting -`org-roam-encrypt-files` to `t`. When enabled, new files are created -with the `.org.gpg` extension and decryption are handled automatically -by EasyPG. - -Note that Emacs will prompt for a password for encrypted files during -cache updates if it requires reading the encrypted file. To reduce the -number of password prompts, you may wish to cache the password. - -## Org-roam Graph Viewer - -Org-roam generates an SVG image using -[Graphviz](https://graphviz.org/). To setup graph navigation, see the -[Roam Protocol](roam_protocol.md) page. - -Org-roam tries its best to locate the Graphviz executable from your -`PATH`, but if it fails to do so, you may set it manually: - -``` -(setq org-roam-graph-executable "/path/to/dot") -``` - -You may also choose to use `neato` in place of `dot`, which generates a more compact graph layout. - -``` -(setq org-roam-graph-executable "/path/to/neato") -(setq org-roam-graph-extra-config '(("overlap" . "false"))) -``` - -Org-roam also attempts to use Firefox (located on `PATH`) to view the -SVG, you may choose to set it to any compatible program: - -``` -(setq org-roam-graph-viewer "/path/to/image-viewer") -``` - -### Excluding Nodes and Edges -One may want to exclude certain files to declutter the graph. You can do so by setting `org-roam-graph-exclude-matcher`. - -``` -(setq org-roam-graph-exclude-matcher '("private" "dailies")) -``` - -This setting excludes all files whose path contain "private" or "dailies". - -## Org-roam Completion System - -Org-roam offers completion when choosing note titles etc. -The completion system is configurable. The default setting, - -``` -(setq org-roam-completion-system 'default) -``` - -uses Emacs' standard `completing-read`. If you prefer [Helm](https://emacs-helm.github.io/helm/), use - -``` -(setq org-roam-completion-system 'helm) -``` - -Other options included `'ido`, and `'ivy'`. diff --git a/doc/ecosystem.md b/doc/ecosystem.md deleted file mode 100644 index 595e1cb..0000000 --- a/doc/ecosystem.md +++ /dev/null @@ -1,138 +0,0 @@ -A number of packages work well combined with Org-Roam: - -## Deft - -[Deft][deft] provides a nice interface for browsing and filtering -org-roam notes. - -```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 "/path/to/org-roam-files/")) -``` - -If the title of the Org file is not the first line, you might not get -nice titles. You may choose to patch this to use `org-roam`'s -functionality. Here I'm using [el-patch](https://github.com/raxod502/el-patch): - -```emacs-lisp -(use-package el-patch - :straight (:host github - :repo "raxod502/el-patch" - :branch "develop")) - -(eval-when-compile - (require 'el-patch)) - -(use-package deft - ;; same as above... - :config/el-patch - (defun deft-parse-title (file contents) - "Parse the given FILE and CONTENTS and determine the title. -If `deft-use-filename-as-title' is nil, the title is taken to -be the first non-empty line of the FILE. Else the base name of the FILE is -used as title." - (el-patch-swap (if deft-use-filename-as-title - (deft-base-filename file) - (let ((begin (string-match "^.+$" contents))) - (if begin - (funcall deft-parse-title-function - (substring contents begin (match-end 0)))))) - (org-roam--get-title-or-slug file)))) -``` - -The Deft interface can slow down quickly when the number of files get -huge. [Notdeft][notdeft] is a fork of Deft that uses an external -search engine and indexer. - -## Org-journal - -[Org-journal](https://github.com/bastibe/org-journal) is a more powerful -alternative to the simple function `org-roam-dailies-today`. It provides better -journaling capabilities, and a nice calendar interface to see all dated entries. - -```emacs-lisp -(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")) -``` - -## Note-taking Add-ons - -These are some plugins that make note-taking in Org-mode more -enjoyable. - -### Org-download - -[Org-download][org-download] lets you screenshot and yank images from -the web into your notes: - -![org-download](images/org-download.gif) - -```emacs-lisp -(use-package org-download - :after org - :bind - (:map org-mode-map - (("s-Y" . org-download-screenshot) - ("s-y" . org-download-yank)))) -``` - -### mathpix.el - -[mathpix.el][mathpix-el] uses [Mathpix's](https://mathpix.com/) API to convert clips into -latex equations: - -![mathpix](images/mathpix.gif) - -```emacs-lisp -(use-package mathpix.el - :straight (:host github :repo "jethrokuan/mathpix.el") - :custom ((mathpix-app-id "app-id") - (mathpix-app-key "app-key")) - :bind - ("C-x m" . mathpix-screenshot)) -``` - -### Org-noter / Interleave - -[Org-noter][org-noter] and [Interleave][interleave] are both projects -that allow synchronised annotation of documents (PDF, EPUB etc.) -within Org-mode. - -### Bibliography - -[org-roam-bibtex](https://github.com/zaeph/org-roam-bibtex) offers tight -integration between [org-ref][org-ref], [helm-bibtex][helm-bibtex] and -`org-roam`. This helps you manage your bibliographic notes under `org-roam`. - -![org-download](images/org-roam-bibtex.gif) - -### Spaced Repetition - -[Org-fc][org-fc] is a spaced repetition system that scales well with a -large number of files. Other alternatives include -[org-drill][org-drill], and [pamparam][pamparam]. - -[deft]: https://jblevins.org/projects/deft/ -[notdeft]: https://github.com/hasu/notdeft -[org-download]: https://github.com/abo-abo/org-download -[mathpix-el]: https://github.com/jethrokuan/mathpix.el -[org-noter]: https://github.com/weirdNox/org-noter -[interleave]: https://github.com/rudolfochrist/interleave -[org-ref]: https://github.com/jkitchin/org-ref -[helm-bibtex]: https://github.com/tmalsburg/helm-bibtex -[org-fc]: https://github.com/l3kn/org-fc/ -[org-drill]: https://orgmode.org/worg/org-contrib/org-drill.html -[pamparam]: https://github.com/abo-abo/pamparam diff --git a/doc/index.md b/doc/index.md deleted file mode 100644 index 633de7c..0000000 --- a/doc/index.md +++ /dev/null @@ -1,62 +0,0 @@ -![org-roam][org-roam-intro-image] - -## What is Org-roam? - -Org-roam is a [Roam][roamresearch] replica built around the -all-powerful [Org-mode][org]. - -Org-roam is a solution for effortless non-hierarchical note-taking -with Org-mode. With Org-roam, notes flow naturally, making note-taking -fun and easy. Org-roam should also work as a plug-and-play solution -for anyone already using Org-mode for their personal wiki. - -To understand more about Roam, a collection of links are available in -[the appendix](notetaking_workflow.md). - -Org-roam aims to implement the core features of Roam, leveraging the -mature ecosystem around Org-mode where possible. Eventually, we hope -to further introduce features enabled by the Emacs ecosystem. - -## Why use Org-roam? - -##### Private and Secure - -Edit your personal wiki completely offline, entirely in your control. -Encrypt your notes with GPG. - -##### Longevity - -Unlike web solutions like Roam research, the notes are first and -foremost plain Org-mode files -- Org-roam simply builds up an -auxilliary database to give the personal wiki superpowers. Having your -notes in plain-text is crucial for the longevity of your wiki. Never -have to worry about proprietary web solutions being taken down. Edit -your plain-text notes in notepad if all other editors cease to exist. - -##### Free and Open-source - -Org-roam is free and open-source, which means that if you feel unhappy -with any part of Org-roam, you may choose to extend Org-roam, or open -a PR. - -##### Leverage the Org-mode Ecosystem - -Over the years, Emacs and Org-mode has developed into a mature system -for plain-text organization. Building upon Org-mode already puts -Org-roam light-years ahead of many other solutions. - -Emacs is also a fantastic interface for editing text, and we can -inherit many of the powerful text-navigation and editing packages -available to Emacs. - -There are several packages that are similar to Org-roam, see the -[Comparison](comparison.md) page for a detailed comparison. - -## Project Status - -As of March 2020, most of the core functionality and interfaces have -stabilized, and a stable release is near. - -[org-roam-intro-image]: images/org-roam-intro.png -[roamresearch]: https://www.roamresearch.com/ -[org]: https://orgmode.org/ diff --git a/doc/installation.md b/doc/installation.md deleted file mode 100644 index 5fc327c..0000000 --- a/doc/installation.md +++ /dev/null @@ -1,197 +0,0 @@ -## Basic Install and Configuration - -Org-roam is now available on MELPA, so you can install it via the following -command: - -``` -M-x package-install RET org-roam RET -``` - -Alternatively, you may use package managers such as [straight][straight] or -[quelpa][quelpa] to install the package. - -The recommended method of configuration is to use [use-package][use-package]. - -```emacs-lisp -(use-package org-roam - :hook - (after-init . org-roam-mode) - :custom - (org-roam-directory "/path/to/org-files/") - :bind (:map org-roam-mode-map - (("C-c n l" . org-roam) - ("C-c n f" . org-roam-find-file) - ("C-c n j" . org-roam-jump-to-index) - ("C-c n b" . org-roam-switch-to-buffer) - ("C-c n g" . org-roam-graph)) - :map org-mode-map - (("C-c n i" . org-roam-insert)))) -``` - -Or without `use-package`: - -```emacs-lisp -(require 'org-roam) -(define-key org-roam-mode-map (kbd "C-c n l") #'org-roam) -(define-key org-roam-mode-map (kbd "C-c n f") #'org-roam-find-file) -(define-key org-roam-mode-map (kbd "C-c n j") #'org-roam-jump-to-index) -(define-key org-roam-mode-map (kbd "C-c n b") #'org-roam-switch-to-buffer) -(define-key org-roam-mode-map (kbd "C-c n g") #'org-roam-graph) -(define-key org-mode-map (kbd "C-c n i") #'org-roam-insert) -(org-roam-mode +1) -``` - -The [Configuration](configuration.md) page details some of the common -configuration options available. - -### Completion - -Link auto-completion is offered via -[company-org-roam](https://github.com/jethrokuan/company-org-roam/), refer to -the documentation there for further details. - -## Spacemacs - -If you are using Spacemacs, install org-roam by creating a simple layer that -wraps Org-roam. Paste the following into a new file -`~/.emacs.d/private/org-roam/packages.el`. - -```emacs-lisp -(defconst org-roam-packages - '(org-roam)) - -(defun org-roam/init-org-roam () - (use-package org-roam - :hook - (after-init . org-roam-mode) - :custom - (org-roam-directory "/path/to/org-files/") - :init - (progn - (spacemacs/declare-prefix "ar" "org-roam") - (spacemacs/set-leader-keys - "arl" 'org-roam - "art" 'org-roam-dailies-today - "arf" 'org-roam-find-file - "arg" 'org-roam-graph) - - (spacemacs/declare-prefix-for-mode 'org-mode "mr" "org-roam") - (spacemacs/set-leader-keys-for-major-mode 'org-mode - "rl" 'org-roam - "rt" 'org-roam-dailies-today - "rb" 'org-roam-switch-to-buffer - "rf" 'org-roam-find-file - "ri" 'org-roam-insert - "rg" 'org-roam-graph)))) -``` - -Next, append `org-roam` to the `dotspacemacs-configuration-layers` -list in your `.spacemacs` configuration file. Reload (`SPC f e R`) or -restart Emacs to load `org-roam`. It's functions are available under -the prefix `SPC a r` and `, r` when visiting an org-mode buffer. - -If you also have the ranger layer installed, the prefix 'ar' conflict -with that of the ranger layer. You might want to change it to 'aor' -(also change the 'ar' to 'aor' in the other key-binding declarations) - -## Doom Emacs - -[Doom Emacs][doom] has a `+roam` flag on its `org` module for easy -installation and configuration. Simply add the flag to the `org` section -of your `~/.doom.d/init.el` and run `~/.emacs.d/bin/doom sync`. - -[use-package]: https://github.com/jwiegley/use-package -[straight]: https://github.com/raxod502/straight.el -[quelpa]: https://github.com/quelpa/quelpa -[doom]: https://github.com/hlissner/doom-emacs -[doom-getting-started]: https://github.com/hlissner/doom-emacs/blob/develop/docs/getting_started.org#configuring-packages - -## Windows - -On Windows, if you follow the installation instructions above, you will likely get the error message: **"No EmacSQL SQLite binary available, aborting"**, and `org-roam` won't start properly. - -You need to do some additional steps to get `org-roam` to work. - -Essentially, you will need to have a binary file for `emacsql-sqlite` so that your Emacs can work with `sqlite` database -- `org-roam` uses it to track backlinks. The following options have been reported to work by Windows users in the community. - -Option 1. **Windows Subsystem for Linux (WSL)** -: This option lets you use Linux on your Windows machine. It's Linux, so you don't need to do anything specific for Windows. - -Option 2. **mingw-x64** -: Use mingw-x64. You would spend a bit of time to download it, and get familiar with how it works. You should be able to use Linux tools within your Windows [more contribution welcome]. - -Option 3. **scoop** -: Use [scoop](https://scoop.sh/) to install a couple of software tools (make and gcc) and manually compile a binary (`.exe`) file yourself. Find a short step-by-step guide below. - -Option 4. **emacsql-sqlite3** -: Use another Emacs package called [`emacsql-sqlite3`](https://github.com/cireu/emacsql-sqlite3). You can download an [official binary](https://sqlite.org/download.html) for `sqlite3`. `emacsql-sqlite3` lets you use it. For this option to work, you need to adjust the `org-roam` source code, and get your modified version to work in your Emacs environment. Find a suggestion below. - -### scoop -**Step 1.** In PowerShell, install `scoop` ([instruction here](https://scoop.sh/)). - -```powershell -iwr -useb get.scoop.sh | iex -``` - -**Step 2.** In PowerShell, install `make` and `gcc` via scoop - -```powershell -scoop install make gcc -``` - -**Step 3.** In Emacs, install the `emacsql-sqlite` package for your Emacs if it is not done yet. - -**Step 4.** In PowerShell, move to the directory where `emacsql.c` is stored. - -With MELPA, it is likely to be under your ELPA folder: - -``` -~\AppData\Roaming\.emacs.d\elpa\emacsql-sqlite-20190727.1710\sqlite -``` - -With Doom Emacs, it should be under your `.emacs\.local`: - -``` -~\.emacs.d\.local\straight\build\emacsql-sqlite\sqlite -``` - -Check the files via `dir` command. You should see these files: - -```powershell -Mode LastWriteTime Length Name ----- ------------- ------ ---- --a---- 22/03/2020 12:10 PM 5170 emacsql.c --a---- 22/03/2020 12:10 PM 439 Makefile --a---- 22/03/2020 12:10 PM 7516138 sqlite3.c --a---- 22/03/2020 12:10 PM 526684 sqlite3.h -``` - -**Step 5.** Compile the `.exe` file with `make` - -```powershell -make emacsql-sqlite CC=gcc LDLIBS= -``` - -You will see the process triggered with lots of text automatically scrolling down; it may take a couple of minutes for compilation to finish. - -Once compilation is done, check that `emacsql-sqlite.exe` has been added to the directory. - -**Step 6.** Relaunch Emacs, use `org-roam` - -When you start `org-roam` (e.g. via `org-roam-mode`), now you should no longer see the "No EmacSQL SQLite binary available, aborting" error. You are good to go. - - -### emacsql-sqlite3 - -1. In Emacs, install the `emacsql-sqlite3` package - -2. Using your text editor, etc. modify `org-roam-db.el`: - - 1. Replace `(require 'emacsql-sqlite)` with `(require 'emacsql-sqlite3)` - - 2. Comment/deactivate the complete `(defconst org-roam-db--sqlite-available-p ... )` - - 3. In `(defun org-roam-db ...`, replace `emacsql-sqlite` -with `emacsql-sqlite3` - -3. If you compile `.el` files, ensure to replace `org-roam-db.elc` with the new source you modified. diff --git a/doc/notetaking_workflow.md b/doc/notetaking_workflow.md deleted file mode 100644 index 987e511..0000000 --- a/doc/notetaking_workflow.md +++ /dev/null @@ -1,24 +0,0 @@ -## Recommended Books -- [How to Take Smart Notes][1] - -## Articles -- [How to Take Smart Notes in Org-mode - Jethro Kuan][7] -- [The Zettelkasten Method - LessWrong 2.0][3] -- [Building a second brain in Roam][4] -- [Roam: Why I Love It and How I Use It][5] -- [Adam Keesling's Twitter Thread][6] - -## Threads -- [Ask HN: How to Take Good Notes][8] - -## What to Do With Your Notes -- [How to Use Roam to Outline a New Article in Under 20 Minutes][2] - -[1]: https://www.goodreads.com/book/show/34507927-how-to-take-smart-notes?ac=1&from_search=true&qid=6L8iEE1FIA&rank=1 -[2]: https://www.youtube.com/watch?v=RvWic15iXjk -[3]: https://www.lesswrong.com/posts/NfdHG6oHBJ8Qxc26s/the-zettelkasten-method-1 -[4]: https://reddit.com/r/RoamResearch/comments/eho7de/building_a_second_brain_in_roamand_why_you_might -[5]: https://www.nateliason.com/blog/roam -[6]: https://twitter.com/adam_keesling/status/1196864424725774336?s=20 -[7]: https://blog.jethro.dev/posts/how_to_take_smart_notes_org/ -[8]: https://news.ycombinator.com/item?id=22473209 diff --git a/doc/org_export.md b/doc/org_export.md deleted file mode 100644 index 87d3ac3..0000000 --- a/doc/org_export.md +++ /dev/null @@ -1,61 +0,0 @@ -While exporting your documents to another format such as HTML -- whether using Org's in-built export or ox-hugo -- you can add a backlinks section which would display the backlinks to the current file. This is done via org-export's preprocessing hooks. See more at [Advanced Export Configuration (The Org Manual)](https://orgmode.org/manual/Advanced-Export-Configuration.html#Advanced-Export-Configuration). - -Following are two different configs that might be suitable for different use-cases. Add one of these snippets in your Emacs init file. - -### Only Backlinks - -This will display only the backlinks and not the contents. - -```emacs-lisp -(defun my/org-roam--backlinks-list (file) - (if (org-roam--org-roam-file-p file) - (--reduce-from - (concat acc (format "- [[file:%s][%s]]\n" - (file-relative-name (car it) org-roam-directory) - (org-roam--get-title-or-slug (car it)))) - "" (org-roam-db-query [:select [from] :from links :where (= to $s1)] file)) - "")) - -(defun my/org-export-preprocessor (backend) - (let ((links (my/org-roam--backlinks-list (buffer-file-name)))) - (unless (string= links "") - (save-excursion - (goto-char (point-max)) - (insert (concat "\n* Backlinks\n") links))))) - -(add-hook 'org-export-before-processing-hook 'my/org-export-preprocessor) -``` - -### Backlinks and Contents - -This would insert both backlinks and the contents, just like the org-roam buffer. This might be especially useful if you host a web version of your personal knowledgebase and want to browse the files along with the backlinks from mobile devices. - -```emacs-lisp -(defun my/org-roam--backlinks-list-with-content (file) - (with-temp-buffer - (if-let* ((backlinks (org-roam--get-backlinks file)) - (grouped-backlinks (--group-by (nth 0 it) backlinks))) - (progn - (insert (format "\n\n* %d Backlinks\n" - (length backlinks))) - (dolist (group grouped-backlinks) - (let ((file-from (car group)) - (bls (cdr group))) - (insert (format "** [[file:%s][%s]]\n" - file-from - (org-roam--get-title-or-slug file-from))) - (dolist (backlink bls) - (pcase-let ((`(,file-from _ ,props) backlink)) - (insert (s-trim (s-replace "\n" " " (plist-get props :content)))) - (insert "\n\n"))))))) - (buffer-string))) - - (defun my/org-export-preprocessor (backend) - (let ((links (my/org-roam--backlinks-list-with-content (buffer-file-name)))) - (unless (string= links "") - (save-excursion - (goto-char (point-max)) - (insert (concat "\n* Backlinks\n") links))))) - - (add-hook 'org-export-before-processing-hook 'my/org-export-preprocessor) -``` diff --git a/doc/requirements.txt b/doc/requirements.txt deleted file mode 100644 index 7b617a2..0000000 --- a/doc/requirements.txt +++ /dev/null @@ -1,2 +0,0 @@ -mkdocs-material==4.6.2 -pymdown-extensions==6.3 diff --git a/doc/roam_protocol.md b/doc/roam_protocol.md deleted file mode 100644 index 288124c..0000000 --- a/doc/roam_protocol.md +++ /dev/null @@ -1,169 +0,0 @@ -## What is Roam protocol? - -Org-roam extending `org-protocol` with 2 protocols: the `roam-file` -and `roam-ref` protocol. - -## The `roam-file` protocol - -This is a simple protocol that opens the path specified by the `file` -key (e.g. `org-protocol://roam-file?file=/tmp/file.org`). This is used -in the generated graph. - -## The `roam-ref` Protocol - -This protocol finds or creates a new note with a given `ROAM_KEY` (see -[Anatomy](anatomy.md)): - -![roam-ref](images/roam-ref.gif) - -To use this, create a Firefox bookmarklet as follows: - -```javascript -javascript:location.href = -'org-protocol://roam-ref?template=r&ref=' -+ encodeURIComponent(location.href) -+ '&title=' -+ encodeURIComponent(document.title) -``` -or as a keybinding in qutebrowser, adding the following to the autoconfig.yml file: -```yml -settings: - bindings.commands: - global: - normal: - gc: open javascript:void(location.href='org-protocol://roam-ref?template=r&ref='+encodeURIComponent(location.href)+'&title='+encodeURIComponent(document.title)) -``` - -where `template` is the template key for a template in -`org-roam-capture-ref-templates`. More documentation on the templating -system can be found [here](templating.md). - -These templates should contain a `#+ROAM_KEY: ${ref}` in it. - -## Setting up Org-roam protocol - -To enable org-roam's protocol extensions, you have to add the -following to your init file: - -```emacs-lisp -(require 'org-roam-protocol) -``` - -The instructions for setting up `org-protocol` can be found -[here][org-protocol-inst], but they are reproduced below. - -We will also need to create a desktop application for `emacsclient`. -The instructions for various platforms are shown below: - -## Linux - -Create a desktop application. I place mine in -`~/.local/share/applications/org-protocol.desktop`: - -``` -[Desktop Entry] -Name=Org-Protocol -Exec=emacsclient %u -Icon=emacs-icon -Type=Application -Terminal=false -MimeType=x-scheme-handler/org-protocol -``` - -Associate `org-protocol://` links with the desktop application by -running in your shell: - -```bash -xdg-mime default org-protocol.desktop x-scheme-handler/org-protocol -``` - -To disable the "confirm" prompt in Chrome, you can also make Chrome -show a checkbox to tick, so that the `Org-Protocol Client` app will be used -without confirmation. To do this, run in a shell: - -```sh -sudo mkdir -p /etc/opt/chrome/policies/managed/ -sudo tee /etc/opt/chrome/policies/managed/external_protocol_dialog.json >/dev/null <<'EOF' -{ - "ExternalProtocolDialogShowAlwaysOpenCheckbox": true -} -EOF -sudo chmod 644 /etc/opt/chrome/policies/managed/external_protocol_dialog.json -``` - -and then restart Chrome (for example, by navigating to ) to -make the new policy take effect. - -See [here](https://www.chromium.org/administrators/linux-quick-start) -for more info on the `/etc/opt/chrome/policies/managed` directory and -[here](https://cloud.google.com/docs/chrome-enterprise/policies/?policy=ExternalProtocolDialogShowAlwaysOpenCheckbox) -for information on the `ExternalProtocolDialogShowAlwaysOpenCheckbox` -policy. - - -## Mac OS - -One solution is to use -[Platypus](https://github.com/sveinbjornt/Platypus). Here are the -instructions for setting up with Platypus and Chrome: - -1. Install and launch Platypus (with [Homebrew](https://brew.sh/)): - -```sh -brew cask install platypus -``` -2. Create a script `launch_emacs.sh`: - -``` -#!/usr/bin/env bash -/usr/local/bin/emacsclient --no-wait $1 -``` - -3. Create a Platypus app with the following settings: - -``` -| Setting | Value | -|--------------------------------+---------------------------| -| App Name | "OrgProtocol" | -| Script Type | "env" ยท "/usr/bin/env" | -| Script Path | "path/to/launch-emacs.sh" | -| Interface | None | -| Accept dropped items | true | -| Remain running after execution | false | -``` - -Inside `Settings`: - -``` -| Setting | Value | -|--------------------------------+----------------| -| Accept dropped files | true | -| Register as URI scheme handler | true | -| Protocol | "org-protocol" | -``` - -To disable the "confirm" prompt in Chrome, you can also make Chrome -show a checkbox to tick, so that the `OrgProtocol` app will be used -without confirmation. To do this, run in a shell: - -```sh -defaults write com.google.Chrome ExternalProtocolDialogShowAlwaysOpenCheckbox -bool true -``` - - -##### Note for Emacs Mac Port - -If you're using [Emacs Mac Port](https://github.com/railwaycat/homebrew-emacsmacport), it -registered its `Emacs.app` as the default handler for the URL scheme -`org-protocol`. We have to make our `OrgProtocol.app` the default -handler instead (replace `org.yourusername.OrgProtocol` with your app -identifier): - -``` -$ defaults write com.apple.LaunchServices/com.apple.launchservices.secure LSHandlers -array-add \ -'{"LSHandlerPreferredVersions" = { "LSHandlerRoleAll" = "-"; }; LSHandlerRoleAll = "org.yourusername.OrgProtocol"; LSHandlerURLScheme = "org-protocol";}' -``` - -Then restart your computer. - -[org-protocol-inst]: https://orgmode.org/worg/org-contrib/org-protocol.html diff --git a/doc/templating.md b/doc/templating.md deleted file mode 100644 index a952764..0000000 --- a/doc/templating.md +++ /dev/null @@ -1,123 +0,0 @@ -Rather than creating blank files on `org-roam-insert` and -`org-roam-find-file`, it is may be desirable to prefill the file with -content. This may include: - -- Time of creation -- File it was created from -- Clipboard content -- Any other data you may want to input manually - -This requires a complex template insertion system, but fortunately, -Org ships with a powerful one: `org-capture`. However, org-capture was -not designed for such use. Org-roam abuses `org-capture` to some -extent, extending its syntax. To first understand how org-roam's -templating system works, it may be useful to look into org-capture. - -Org-roam's templates can be customized by modifying the variable -`org-roam-capture-templates`. - -## Org-roam Templates - -The org-roam capture template extends org-capture's template with 2 -additional properties: - -1. `:file-name`: This is the file name template used when a new note - is created. Notes can be placed in sub-directories by prepending them to - the filename (`sub/file-name`) -2. `:head`: This is the template that is inserted on initial note - creation. - -### Org-roam Template Expansion - -Org-roam's template definitions also extend org-capture's template -syntax, to allow prefilling of strings. In many scenarios, -`org-roam-capture--capture` is passed a mapping between variables and strings. -For example, during `org-roam-insert`, a title is prompted for. If the -title doesn't already exist, we would like to create a new file, -without prompting for the title again. - -Variables passed are expanded with the `${var}` syntax. For example, -during `org-roam-insert`, `${title}` is prefilled for expansion. Any -variables that do not contain strings, are prompted for values using -`completing-read`. - -After doing this expansion, the org-capture's template expansion -system is used to fill up the rest of the template. You may read up -more on this on [org-capture's documentation -page](https://orgmode.org/manual/Template-expansion.html#Template-expansion). - -For example, take the template: `"%<%Y%m%d%H%M%S>-${title}"`, with the title -`"Foo"`. The template is first expanded into `%<%Y%m%d%H%M%S>-Foo`. Then -org-capture expands `%<%Y%m%d%H%M%S>` with timestamp: e.g. -`20200213032037-Foo`. - -All of the flexibility afforded by emacs and org-mode are -available. For example, if you want to encode a UTC timestamp in the -filename, you can take advantage of org-mode's `%(EXP)` template -expansion to call `format-time-string` directly to provide its third -argument to specify UTC. - -``` emacs-lisp -("d" "default" plain (function org-roam--capture-get-point) - "%?" - :file-name "%(format-time-string \"%Y-%m-%d--%H-%M-%SZ--${slug}\" (current-time) t)" - :head "#+TITLE: ${title}\n" - :unnarrowed t) -``` - -Similarly, if you want to change how titles are transformed into -slugs, you can override `org-roam--title-to-slug`. For example, to use -hyphens instead of underscores: - - -``` emacs-lisp - (defun org-roam--title-to-slug (title) - "Convert TITLE to a filename-suitable slug. Uses hyphens rather than underscores." - (cl-flet* ((nonspacing-mark-p (char) - (eq 'Mn (get-char-code-property char 'general-category))) - (strip-nonspacing-marks (s) - (apply #'string (seq-remove #'nonspacing-mark-p - (ucs-normalize-NFD-string s)))) - (cl-replace (title pair) - (replace-regexp-in-string (car pair) (cdr pair) title))) - (let* ((pairs `(("[^[:alnum:][:digit:]]" . "-") ;; convert anything not alphanumeric - ("--*" . "-") ;; remove sequential underscores - ("^-" . "") ;; remove starting underscore - ("-$" . ""))) ;; remove ending underscore - (slug (-reduce-from #'cl-replace (strip-nonspacing-marks title) pairs))) - (s-downcase slug)))) -``` - -This templating system is used throughout org-roam templates. - -### Template examples - -Here I walkthrough the default template, reproduced below. - -``` -("d" "default" plain (function org-roam--capture-get-point) - "%?" - :file-name "%<%Y%m%d%H%M%S>-${slug}" - :head "#+TITLE: ${title}\n" - :unnarrowed t) -``` - -1. The template has short key `"d"`. If you have only one template, - org-roam automatically chooses this template for you. -2. The template is given a description of `"default"`. -3. `plain` text is inserted. Other options include Org headings via - `entry`. -4. `(function org-roam--capture-get-point)` should not be changed. -5. `"%?"` is the template inserted on each call to `org-roam-capture--capture`. - This template means don't insert any content, but place the cursor - here. -6. `:file-name` is the file-name template for a new note, if it -doesn't yet exist. This creates a file at path that looks like - `/path/to/org-roam-directory/20200213032037-foo.org`. -7. `:head` contains the initial template to be inserted (once only), - at the beginning of the file. Here, the title global attribute is - inserted. -8. `:unnarrowed t` tells org-capture to show the contents for the - whole file, rather than narrowing to just the entry. - -Other options you may want to learn about include `:immediate-finish`. diff --git a/doc/tour.md b/doc/tour.md deleted file mode 100644 index 0ba594e..0000000 --- a/doc/tour.md +++ /dev/null @@ -1,70 +0,0 @@ -Org-roam was built to support a workflow that was not possible with -vanilla Org-mode. This flow is modelled after the [Zettelkasten -method][zettelkasten], and many of [Roam Research][roam]'s workflows. -It is crucial to understand that Org-roam does not auto-magically make -note-taking better -- it's changing the note-taking workflow that -does. - -To understand more about the methods and madness, the [Note-Taking -Workflow][appendix:ntw] page contains a page of useful references. The -author has also written [a post][jethro-blog-post] about how he uses -Org-roam. - -## Activating Org-roam - -Org-roam's entry point is the global minor `org-roam-mode`. This sets -up Emacs with several hooks, for keeping the org-roam cache -consistently updated, as well as showing the backlinks buffer. - -The cache is a sqlite database named `org-roam.db`, which resides at -the root of the `org-roam-directory`. Activating `org-roam-mode` -builds the cache, which may take a while the first time, but is -generally instantaneous in subsequent runs. To build the cache -manually again, run `M-x org-roam-db-build-cache`. - -## Finding a Note - -`org-roam-find-file` shows the list of titles for notes that reside in -`org-roam-directory`. Selecting a note title will bring you to the -corresponding note. Entering a title of a note that does not yet exist -will create a new note with that title. - -![org-roam-find-file](images/org-roam-find-file.gif) - -Note that in the above image, the [ivy](https://github.com/abo-abo/swiper) -completion frontend is used. The default frontend has some usability issues with -non-matching candidates (e.g. when you want to enter a title of a new note, -there is no completion candidate), so either `ivy` or `helm` is recommended. - -## Inserting Links - -`org-roam-insert` insert links to existing (or new) notes. Entering a -non-existent title will also create a new note with that title. - -![org-roam-insert](images/org-roam-insert-filetag.gif) - -Good usage of Org-roam requires liberally linking files. This allows -the build-up of a dense knowledge graph. - -## The Org-roam Buffer - -The Org-roam buffer is often displayed in the side window. It shows -backlinks for the currently active Org-roam note, along with some -surrounding context. - -![org-roam-buffer](images/org-roam-buffer.gif) - -## Exporting the Graph - -Org-roam also uses Graphviz to generate a graph, with notes as nodes, -and links between them as edges. The generated graph can be used to -navigate to the files, but this requires some additional setup -described in the [Roam Protocol][appendix:roam-protocol] page. - -![org-roam-graph](images/org-roam-graph.gif) - -[zettelkasten]: https://zettelkasten.de/ -[appendix:ntw]: notetaking_workflow.md -[appendix:roam-protocol]: roam_protocol.md -[roam]: https://www.roamresearch.com/ -[jethro-blog-post]: https://blog.jethro.dev/posts/how_to_take_smart_notes_org/