From 4cad2cf6e6ec0617001f216ca79ce9cf649717c2 Mon Sep 17 00:00:00 2001 From: Jethro Kuan Date: Sun, 3 May 2020 18:06:27 +0800 Subject: [PATCH] (internal): use Make and Org to build manual (#546) --- .gitignore | 13 + Makefile | 11 + default.mk | 106 ++++ doc/AUTHORS.md | 37 ++ doc/Makefile | 127 +++++ doc/htmlxref.cnf | 15 + doc/org-roam.org | 904 ++++++++++++++++++++++++++++++++++ doc/org-roam.texi | 1189 +++++++++++++++++++++++++++++++++++++++++++++ 8 files changed, 2402 insertions(+) create mode 100644 default.mk create mode 100644 doc/AUTHORS.md create mode 100644 doc/Makefile create mode 100644 doc/htmlxref.cnf create mode 100644 doc/org-roam.org create mode 100644 doc/org-roam.texi diff --git a/.gitignore b/.gitignore index 6fc14e7..e8c35c4 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,15 @@ /.sandbox/ **/*.elc +/doc/dir +/doc/*.info +/doc/*.html +/doc/*.pdf +/doc/*.epub +/doc/META_INF/ +/doc/OEBPS/ +/doc/dir +/doc/epub.xml +/doc/org-roam/ +/doc/mimetype +/doc/stats/ +/config.mk diff --git a/Makefile b/Makefile index ce9cdd8..3062ea0 100644 --- a/Makefile +++ b/Makefile @@ -54,3 +54,14 @@ endif .DEFAULT: init init: @./makem.sh $(DEBUG) $(VERBOSE) $(SANDBOX) $(INSTALL_DEPS) $(INSTALL_LINTERS) + +docs: + @$(MAKE) -C doc all + +install: install-docs + +install-docs: docs + @$(MAKE) -C doc install-docs + +install-info: info + @$(MAKE) -C doc install-info diff --git a/default.mk b/default.mk new file mode 100644 index 0000000..3bab1cc --- /dev/null +++ b/default.mk @@ -0,0 +1,106 @@ +TOP := $(dir $(lastword $(MAKEFILE_LIST))) + +## User options ###################################################### +# +# You can override these settings in "config.mk" or on the command +# line. +# +# You might also want to set LOAD_PATH. If you do, then it must +# contain "-L .". +# +# If you don't do so, then the default is set in the "Load-Path" +# section below. The default assumes that all dependencies are +# installed either at "../", or when using package.el +# at "ELPA_DIR/-". + +sharedir ?= $(HOME)/.local/share +lispdir ?= $(sharedir)/emacs/site-lisp/org-roam +infodir ?= $(sharedir)/info +docdir ?= $(sharedir)/doc/org-roam +statsdir ?= $(TOP)/doc/stats + +CP ?= install -p -m 644 +MKDIR ?= install -p -m 755 -d +RMDIR ?= rm -rf +TAR ?= tar +SED ?= sed + +EMACSBIN ?= emacs +BATCH = $(EMACSBIN) -Q --batch $(LOAD_PATH) + +INSTALL_INFO ?= $(shell command -v ginstall-info || printf install-info) +MAKEINFO ?= makeinfo +MANUAL_HTML_ARGS ?= --css-ref /assets/page.css + +## Files ############################################################# + +PKG = org-roam +PACKAGES = org-roam + +TEXIPAGES = $(addsuffix .texi,$(PACKAGES)) +INFOPAGES = $(addsuffix .info,$(PACKAGES)) +HTMLFILES = $(addsuffix .html,$(PACKAGES)) +HTMLDIRS = $(PACKAGES) +PDFFILES = $(addsuffix .pdf,$(PACKAGES)) +EPUBFILES = $(addsuffix .epub,$(PACKAGES)) + +ELS = org-roam-buffer.el +ELS += org-roam-capture.el +ELS += org-roam-compat.el +ELS += org-roam-completion.el +ELS += org-roam-dailies.el +ELS += org-roam-db.el +ELS += org-roam.el +ELS += org-roam-graph.el +ELS += org-roam-macs.el +ELS += org-roam-protocol.el +ELCS = $(ELS:.el=.elc) +ELMS = org-roam.el $(filter-out $(addsuffix .el,$(PACKAGES)),$(ELS)) +ELGS = org-roam-autoloads.el org-roam-version.el + +## Versions ########################################################## + +VERSION ?= $(shell test -e $(TOP).git && git describe --tags --abbrev=0 | cut -c2-) + +EMACS_VERSION = 26.1 + +EMACSOLD := $(shell $(BATCH) --eval \ + "(and (version< emacs-version \"$(EMACS_VERSION)\") (princ \"true\"))") +ifeq "$(EMACSOLD)" "true" + $(error At least version $(EMACS_VERSION) of Emacs is required) +endif + +## Load-Path ######################################################### + +ifndef LOAD_PATH + +ELPA_DIR ?= $(HOME)/.emacs.d/elpa + +SYSTYPE := $(shell $(EMACSBIN) -Q --batch --eval "(princ system-type)") +ifeq ($(SYSTYPE), windows-nt) + CYGPATH := $(shell cygpath --version 2>/dev/null) +endif + +LOAD_PATH = -L $(TOP) + +# When making changes here, then don't forget to adjust "Makefile", +# ".travis.yml", ".github/ISSUE_TEMPLATE/bug_report.md", +# `magit-emacs-Q-command' and the "Installing from the Git Repository" +# info node accordingly. Also don't forget to "rgrep \b\b". + +endif # ifndef LOAD_PATH + +ifndef ORG_LOAD_PATH +ORG_LOAD_PATH = $(LOAD_PATH) +ORG_LOAD_PATH += -L $(TOP)../ox-texinfo-plus +ORG_LOAD_PATH += -L $(TOP)../org-mode/contrib/lisp +ORG_LOAD_PATH += -L $(TOP)../org-mode/lisp +endif + +## Publish ########################################################### + +PUBLISH_TARGETS ?= html html-dir pdf epub + +DOCBOOK_XSL ?= /usr/share/xml/docbook/stylesheet/docbook-xsl/epub/docbook.xsl + +EPUBTRASH = epub.xml META-INF OEBPS diff --git a/doc/AUTHORS.md b/doc/AUTHORS.md new file mode 100644 index 0000000..d928862 --- /dev/null +++ b/doc/AUTHORS.md @@ -0,0 +1,37 @@ +Authors +======= + +The following people have contributed to Org-Roam. + +Names below are sorted alphabetically. + +Author +------ + +- Jethro Kuan + +Maintainers +---------- + +- Jethro Kuan +- Leo Vivier + +Contributors +------------ + +- Alexey Shmalko +- James Ravn +- Jethro Kuan +- Johann Klähn +- Josh English +- Jürgen Hötzel +- Langston Barrett +- Leo Vivier +- Michael Glaesemann +- Michael Herold +- Noboru +- N V <44036031+progfolio@users.noreply.github.com> +- Rafael Accácio Nogueira +- Roland Coeurjoly +- Sayan +- Tim Quelch diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 0000000..2ab3896 --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,127 @@ +-include ../config.mk +include ../default.mk + +## ################################################################### + +.PHONY: texi install clean AUTHORS.md stats + +all: info + +## Build ############################################################# + +info: $(INFOPAGES) dir +html: $(HTMLFILES) +pdf: $(PDFFILES) +epub: $(EPUBFILES) + +%.info: %.texi + @printf "Generating $@\n" + @$(MAKEINFO) --no-split $< -o $@ + +dir: org-roam.info + @printf "Generating dir\n" + @echo $^ | xargs -n 1 $(INSTALL_INFO) --dir=$@ + +%.html: %.texi + @printf "Generating $@\n" + @$(MAKEINFO) --html --no-split $(MANUAL_HTML_ARGS) $< + +html-dir: $(TEXIFILES) + @printf "Generating org-roam/*.html\n" + @$(MAKEINFO) --html $(MANUAL_HTML_ARGS) org-roam.texi + done + +%.pdf: %.texi + @printf "Generating $@\n" + @texi2pdf --clean $< > /dev/null + +%.epub: %.texi + @printf "Generating $@\n" + @$(MAKEINFO) --docbook $< -o epub.xml + @xsltproc $(DOCBOOK_XSL) epub.xml 2> /dev/null + @echo "application/epub+zip" > mimetype + @zip -X --quiet --recurse-paths -0 $@ mimetype + @zip -X --quiet --recurse-paths -9 --no-dir-entries $@ META-INF OEBPS + @$(RMDIR) $(EPUBTRASH) + +## Install ########################################################### + +install: install-info install-docs + +install-docs: install-info + @$(MKDIR) $(DESTDIR)$(docdir) + $(CP) AUTHORS.md $(DESTDIR)$(docdir) + +install-info: info + @$(MKDIR) $(DESTDIR)$(infodir) + $(CP) $(INFOPAGES) $(DESTDIR)$(infodir) + +## Clean ############################################################# + +clean: + @printf "Cleaning doc/*...\n" + @$(RMDIR) dir $(INFOPAGES) $(HTMLFILES) $(HTMLDIRS) $(PDFFILES) + @$(RMDIR) $(EPUBFILES) $(EPUBTRASH) + +## Release management ################################################ + +ORG_ARGS = --batch -Q $(ORG_LOAD_PATH) +ORG_ARGS += -l ox-extra -l ox-texinfo+ +ORG_ARGS += --eval "(or (require 'org-man nil t) (require 'ol-man))" +ORG_EVAL = --eval "(ox-extras-activate '(ignore-headlines))" +ORG_EVAL += --eval "(setq indent-tabs-mode nil)" +ORG_EVAL += --eval "(setq org-src-preserve-indentation nil)" +ORG_EVAL += --funcall org-texinfo-export-to-texinfo + +# This target first bumps version strings in the Org source. The +# necessary tools might be missing so other targets do not depend +# on this target and it has to be run explicitly when appropriate. +# +# AMEND=t make texi Update manual to be amended to HEAD. +# VERSION=N make texi Update manual for release. +# +texi: + @$(EMACSBIN) $(ORG_ARGS) $(PKG).org $(ORG_EVAL) + @printf "\n" >> $(PKG).texi + @rm -f $(PKG).texi~ + +stats: + @printf "Generating statistics\n" + @gitstats -c style=/assets/stats.css -c max_authors=999 $(TOP) $(statsdir) + +authors: AUTHORS.md + +AUTHORS.md: + @printf "Generating AUTHORS.md..." + @test -e $(TOP).git \ + && (printf "$$AUTHORS_HEADER\n" > $@ \ + && git log --pretty=format:'- %aN <%aE>' | sort -u >> $@ \ + && printf "done\n" ; ) \ + || printf "FAILED (non-fatal)\n" + +# Templates ########################################################## + +define AUTHORS_HEADER +Authors +======= + +The following people have contributed to Org-Roam. + +Names below are sorted alphabetically. + +Author +------ + +- Jethro Kuan + +Maintainers +---------- + +- Jethro Kuan +- Leo Vivier + +Contributors +------------ + +endef +export AUTHORS_HEADER diff --git a/doc/htmlxref.cnf b/doc/htmlxref.cnf new file mode 100644 index 0000000..59c6aa7 --- /dev/null +++ b/doc/htmlxref.cnf @@ -0,0 +1,15 @@ +# https://www.gnu.org/software/texinfo/manual/texinfo/html_node/HTML-Xref-Configuration.html + +EMACS = https://www.gnu.org/software/emacs/manual + +auth mono ${EMACS}/html_mono/auth.html +auth node ${EMACS}/html_node/auth/ + +ediff mono ${EMACS}/html_mono/ediff.html +ediff node ${EMACS}/html_node/ediff/ + +elisp mono ${EMACS}/html_mono/elisp.html +elisp node ${EMACS}/html_node/elisp/ + +emacs mono ${EMACS}/html_mono/emacs.html +emacs node ${EMACS}/html_node/emacs/ diff --git a/doc/org-roam.org b/doc/org-roam.org new file mode 100644 index 0000000..37475a8 --- /dev/null +++ b/doc/org-roam.org @@ -0,0 +1,904 @@ +#+TITLE: Org-roam User Manual +:PREAMBLE: +#+AUTHOR: Jethro Kuan +#+EMAIL: jethrokuan95@gmail.com +#+DATE: 2020-2020 +#+LANGUAGE: en + +#+TEXINFO_DIR_CATEGORY: Emacs +#+TEXINFO_DIR_TITLE: Org-roam: (org-roam). +#+TEXINFO_DIR_DESC: Rudimentary Roam Replica for Emacs. +#+SUBTITLE: for version 1.1.0 (v1.1.0-29-g00fc215+1) + +#+TEXINFO_DEFFN: t +#+OPTIONS: H:4 num:3 toc:2 creator:t +#+PROPERTY: header-args :eval never +#+BIND: ox-texinfo+-before-export-hook ox-texinfo+-update-copyright-years +#+BIND: ox-texinfo+-before-export-hook ox-texinfo+-update-version-strings + +#+TEXINFO: @noindent +This manual is for Org-roam version 1.1.0 (v1.1.0-29-g00fc215+1). + +#+BEGIN_QUOTE +Copyright (C) 2020-2020 Jethro Kuan + +You can redistribute this document and/or modify it under the terms +of the GNU General Public License as published by the Free Software +Foundation, either version 3 of the License, or (at your option) any +later version. + +This document is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +General Public License for more details. +#+END_QUOTE + +:END: + +* Introduction + +Org-roam is a [[https://roamresearch.com/][Roam Research]] replica built around the +all-powerful [[https://orgmode.org/][Org-mode]]. + +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 +[[*Note-taking Workflows][Note-taking Workflows]]. + +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. + +Org-roam provides several benefits over other tooling: + +- Privacy and Security :: Edit your personal wiki completely offline, entirely in your control. Encrypt your notes with GPG. +- Longevity of Plain Text :: 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. +- Leverages 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. +- Built on Emacs :: 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. +* Installation +** _ :ignore: +Org-roam can be installed using Emacs' package manager or manually from its development repository. + +** Installing from MELPA + +Org-roam is available from Melpa and Melpa-Stable. If you haven't used Emacs' package manager before, you may familiarize yourself with it by reading the documentation in the Emacs manual, see info:emacs#Packages. Then, add one of the archives to =package-archives=: + +- To use Melpa: + +#+BEGIN_SRC emacs-lisp + (require 'package) + (add-to-list 'package-archives + '("melpa" . "http://melpa.org/packages/") t) +#+END_SRC + +- To use Melpa-Stable: + +#+BEGIN_SRC emacs-lisp + (require 'package) + (add-to-list 'package-archives + '("melpa-stable" . "http://stable.melpa.org/packages/") t) +#+END_SRC + +Once you have added your preferred archive, you need to update the +local package list using: + +#+BEGIN_EXAMPLE + M-x package-refresh-contents RET +#+END_EXAMPLE + +Once you have done that, you can install Org-roam and its dependencies +using: + +#+BEGIN_EXAMPLE + M-x package-install RET org-roam RET +#+END_EXAMPLE + +Now see [[*Post-Installation Tasks][Post-Installation Tasks]]. + +** TODO Installing from the Git Repository + +** TODO Post-Installation Tasks + +* Getting Started + +This short tutorial describes the essential commands used in Org-roam, to help +you get started. + +First, it is important to understand how Org-roam was designed. Org-roam was +built to support a workflow that was not possible with vanilla Org-mode. This +flow is modelled after the [[https://zettelkasten.de/][Zettelkasten Method]], and many of [[https://roamresearch.com][Roam Research's]] +workflows. Org-roam does not magically make note-taking better -- this often +requires a radical change in your current note-taking workflow. To understand +more about the methods and madness, see [[*Note-taking Workflows][Note-taking Workflows]]. + +To begin using Org-roam, one should set the =org-roam-directory= to the directory +containing your notes. For this tutorial, create an empty directory, and set the +=org-roam-directory=: + +#+BEGIN_SRC emacs-lisp +(make-directory "~/org-roam") +(setq org-roam-directory "~/org-roam") +#+END_SRC + +We encourage using a flat hierarchy for storing notes, but some prefer using +folders for storing specific kinds of notes (e.g. websites, papers). This is +fine; Org-roam searches recursively within =org-roam-directory= for any notes. +Instead of relying on the file hierarchy for any form of categorization, we +solely rely on links between files to establish connections between notes. + +Next, we need to enable the global minor mode =org-roam-mode=. This sets up Emacs +with several hooks, builds a cache and keeps it consistent. We recommend +starting =org-roam-mode= on startup: + +#+BEGIN_SRC emacs-lisp +(add-hook 'after-init-hook 'org-roam-mode) +#+END_SRC + +To build the cache manually, one can run =M-x org-roam-db-build-cache=. The cache +is a sqlite database named =org-roam.db=, which defaults to residing in the root +=org-roam-directory=. Cache builds may take a while the first time, but is often +instantaneous in subsequent runs. + +Let us now create our first note. Call =M-x org-roam-find-file=. This shows a list +of titles for notes that reside in =org-roam-directory=. It should show nothing +right now, since there are no notes in the directory. Entering the title of the +note you wish to create, and pressing =RET= should begin the note creation +process. This process uses =org-capture='s templating system, and can be freely +customized (see [[*The Templating System][The Templating System]]). Using the default template, pressing =C-c +C-c= finishes the note capture. Running =M-x org-roam-find-file= again should show +the note you have created, and selecting that entry will bring you to that note. + +The crux of Org-roam is making it easy to create notes, and link them together. +To link notes together, we call =M-x org-roam-insert=. This brings up a prompt +with a list of title for existing notes. Selecting an existing entry will create +and insert a link to the current file. Entering a non-existent title will create +a new note with that title. Good usage of Org-roam requires liberally linking +files: this facilitates building up a dense knowledge graph of inter-connected +notes. + +Org-roam provides an interface to view backlinks. It shows backlinks for the +currently active Org-roam note, along with some surrounding context. To toggle +the visibility of this buffer, call =M-x org-roam=. + +For a visual representation of the notes and their connections, Org-roam also +provides graphing capabilities, using Graphviz. It generates graphs 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 (see [[*Roam Protocol][Roam +Protocol]]). + +* Anatomy of an Org-roam File + +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: + +#+BEGIN_SRC org + #+TITLE: World War 2 + #+ROAM_ALIAS: "WWII" "World War II" +#+END_SRC + +** 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: + +#+BEGIN_SRC org + #+TITLE: Google + #+ROAM_KEY: https://www.google.com/ +#+END_SRC + +These keys come in useful for when taking website notes, using the +=roam-ref= protocol (see [[*Roam Protocol][Roam Protocol]]). + +Alternatively, add a ref for notes for a specific paper, using its +[[https://github.com/jkitchin/org-ref][org-ref]] citation key: + +#+BEGIN_SRC org + #+TITLE: Neural Ordinary Differential Equations + #+ROAM_KEY: cite:chen18_neural_ordin_differ_equat +#+END_SRC + +The backlinks buffer will show any cites of this key: e.g. + +#+CAPTION: org-ref-citelink +[[file:images/org-ref-citelink.png]] +* The Templating System + +Rather than creating blank files on =org-roam-insert= and =org-roam-find-file=, it +may be desirable to prefill the file with templated 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. Fortunately, Org ships with a +powerful one: =org-capture=. However, org-capture was not designed for such use. +Org-roam abuses =org-capture=, extending its syntax. To first understand how +org-roam's templating system works, it may be useful to look into basic usage of +=org-capture=. + +** Template Walkthrough + +To demonstrate the additions made to org-capture templates. Here, we walkthrough +the default template, reproduced below. + +#+BEGIN_SRC emacs-lisp + ("d" "default" plain (function org-roam--capture-get-point) + "%?" + :file-name "%<%Y%m%d%H%M%S>-${slug}" + :head "#+TITLE: ${title}\n" + :unnarrowed t) +#+END_SRC + +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=. + 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=. + +** Org-roam Template Expansion + +Org-roam's template definitions also extend org-capture's template syntax, to +allow prefilling of strings. We have seen a glimpse of this in [[*Template Walkthrough][Template +Walkthrough]]. + +In org-roam templates, the =${var}= syntax allows for the expansion of +variables, stored in =org-roam-capture--info=. For example, during +=org-roam-insert=, the user is prompted for a title. Upon entering a +non-existent title, the =title= key in =org-roam-capture--info= is set to the +provided title. =${title}= is then expanded into the provided title during the +org-capture process. 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 [[https://orgmode.org/manual/Template-expansion.html#Template-expansion][org-capture's documentation page]]. + +To illustrate this dual expansion process, take for example the template string: +="%<%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. + +#+BEGIN_SRC 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) +#+END_SRC + +* Concepts and Configuration +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=. + +** Directories and Files + +This section concerns the placement and creation of files. + +- Variable: org-roam-directory + + This is the default path to Org-roam files. All Org files, at any level of + nesting, are considered part of the Org-roam. + +- Variable: org-roam-db-location + + Location of the Org-roam database. If this is non-nil, the Org-roam sqlite + database is saved here. + + It is the user’s responsibility to set this correctly, especially when used + with multiple Org-roam instances. + +** The Org-roam Buffer + +The Org-roam buffer displays backlinks for the currently active Org-roam note. + +- User Option: org-roam-buffer + + The name of the org-roam buffer. Defaults to =*org-roam*=. + +- User Option: org-roam-buffer-position + + The position of the Org-roam buffer side window. Valid values are ='left=, + ='right=, ='top=, ='bottom=. + +- User Option: org-roam-buffer-width + + Width of =org-roam-buffer=. Has an effect only if =org-roam-buffer-position= is + ='left= or ='right=. + +- User Option: org-roam-buffer-height + + Height of =org-roam-buffer=. Has an effect only if =org-roam-buffer-position= is + ='top= or ='bottom=. + +- User Option: org-roam-buffer-no-delete-window + + The =no-delete-window= parameter for the org-roam buffer. Setting it to ='t= prevents the window from being deleted when calling =delete-other-windows=. + +** Org-roam Links + +Org-roam links are regular =file:= links in Org-mode. By default, links are +inserted with the title as the link description with =org-roam-insert=. + +- User Option: org-roam-link-title-format + + To distinguish between org-roam links and regular links, one may choose to use + special indicators for Org-roam links. Defaults to ="%s"=. + + If your version of Org is at least =9.2=, consider styling the link differently, + by customizing the =org-roam-link=, and =org-roam-link-current= faces. + +** Org-roam Files + +Org-roam files are created and prefilled using Org-roam's templating +system. The templating system is customizable (see [[*The Templating System][The Templating System]]). + +* Navigating Around + +** Index File + +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=. + +- Variable: org-roam-index-file + + Path to the Org-roam index file. + + The path can be a string or a function. If it is a string, it should be the + path (absolute or relative to =org-roam-directory=) to the index file. If it + is is a function, the function should return the path to the index file. + Otherwise, the index is assumed to be a note in =org-roam-index= whose + title is ="Index"=. + +- Function: org-roam-find-index + + Opens the Index file in the current =org-roam-directory=. + +* Encryption + +One may wish to keep private, encrypted files. Org-roam supports encryption (via +GPG), which 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. + +- Variable: org-roam-encrypt-files + + Whether to encrypt new files. If true, create files with .org.gpg extension. + +* Graphing + +Org-roam provides graphing capabilities to explore interconnections between +notes. This is done by performing SQL queries and generating images using +[[https://graphviz.org/][Graphviz]]. The graph can also be navigated: see [[*Roam Protocol][Roam Protocol]]. + +The entry point to graph creation is =org-roam-graph=. + +- Function: org-roam-graph & optional arg file node-query + + Build and possibly display a graph for FILE from NODE-QUERY. + If FILE is nil, default to current buffer’s file name. + ARG may be any of the following values: + + - =nil= show the graph. + - =C-u= show the graph for FILE. + - =C-u N= show the graph for FILE limiting nodes to N steps. + - =C-u C-u= build the graph. + - =C-u -= build the graph for FILE. + - =C-u -N= build the graph for FILE limiting nodes to N steps. + +- User Option: org-roam-graph-executable + + Path to the graphing executable (in this case, Graphviz). Set this if Org-roam is unable to find the Graphviz executable on your system. + + You may also choose to use =neato= in place of =dot=, which generates a more + compact graph layout. + +- User Option: org-roam-graph-viewer + + Org-roam defaults to using Firefox (located on PATH) to view the SVG, but you may choose to set it to: + + 1. A string, which is a path to the program used + 2. a function accepting a single argument: the graph file path. + + =nil= uses =view-file= to view the graph. + +** Graph Options + +Graphviz provides many options for customizing the graph output, and Org-roam supports some of them. See https://graphviz.gitlab.io/_pages/doc/info/attrs.html for customizable options. + +- User Option: org-roam-graph-extra-config + + Extra options passed to graphviz for the digraph (The "G" attributes). + Example: ='=(("rankdir" . "LR"))= + +- User Option: org-roam-graph-node-extra-config + + Extra options for nodes in the graphviz output (The "N" attributes). + Example: ='(("color" . "skyblue"))= + +- User Option: org-roam-graph-edge-extra-config + + Extra options for edges in the graphviz output (The "E" attributes). + Example: ='(("dir" . "back"))= + +- User Option: org-roam-graph-edge-cites-extra-config + + Extra options for citation edges in the graphviz output. + Example: ='(("color" . "red"))= + +** Excluding Nodes and Edges + +One may want to exclude certain files to declutter the graph. + +- User Option: org-roam-graph-exclude-matcher + + Matcher for excluding nodes from the generated graph. Any nodes and links for + file paths matching this string is excluded from the graph. + + If value is a string, the string is the only matcher. + + If value is a list, all file paths matching any of the strings + are excluded. + +#+BEGIN_EXAMPLE + (setq org-roam-graph-exclude-matcher '("private" "dailies")) +#+END_EXAMPLE + +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, + +#+BEGIN_SRC emacs-lisp + (setq org-roam-completion-system 'default) +#+END_SRC + +uses Emacs' standard =completing-read=. If you prefer +[[https://emacs-helm.github.io/helm/][Helm]], use + +#+BEGIN_SRC emacs-lisp + (setq org-roam-completion-system 'helm) +#+END_SRC + +Other options include ='ido=, and ='ivy=. + +* Roam Protocol +** _ :ignore: +Org-roam extending =org-protocol= with 2 protocols: the =roam-file= +and =roam-ref= protocol. + +** Installation + +To enable Org-roam's protocol extensions, you have to add the following to your init file: + +#+BEGIN_SRC emacs-lisp +(require 'org-roam-protocol) +#+END_SRC + +The instructions for setting up =org-protocol== are reproduced below. + +We will also need to create a desktop application for =emacsclient=. The +instructions for various platforms are shown below. + +For Linux users, create a desktop application in =~/.local/share/applications/org-protocol.desktop=: + +#+begin_example +[Desktop Entry] +Name=Org-Protocol +Exec=emacsclient %u +Icon=emacs-icon +Type=Application +Terminal=false +MimeType=x-scheme-handler/org-protocol +#+end_example + +Associate =org-protocol://= links with the desktop application by +running in your shell: + +#+BEGIN_SRC bash +xdg-mime default org-protocol.desktop x-scheme-handler/org-protocol +#+END_SRC + +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: + +#+BEGIN_SRC bash +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 +#+END_SRC + +and then restart Chrome (for example, by navigating to ) to +make the new policy take effect. + +See [[https://www.chromium.org/administrators/linux-quick-start][here]] for more info on the =/etc/opt/chrome/policies/managed= directory and +[[https://cloud.google.com/docs/chrome-enterprise/policies/?policy=ExternalProtocolDialogShowAlwaysOpenCheckbox][here]] for information on the =ExternalProtocolDialogShowAlwaysOpenCheckbox= policy. + +For MacOS, one solution is to use [[https://github.com/sveinbjornt/Platypus][Platypus]]. Here are the instructions for +setting up with Platypus and Chrome: + +1. Install and launch Platypus (with [[https://brew.sh/][Homebrew]]): + +#+BEGIN_SRC bash +brew cask install platypus +#+END_SRC + +2. Create a script =launch_emacs.sh=: + +#+BEGIN_SRC bash +#!/usr/bin/env bash +/usr/local/bin/emacsclient --no-wait $1 +#+END_SRC + +3. Create a Platypus app with the following settings: + +#+begin_example +| 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 | +#+end_example + + +Inside =Settings=: + +#+begin_example +| Setting | Value | +|--------------------------------+----------------| +| Accept dropped files | true | +| Register as URI scheme handler | true | +| Protocol | "org-protocol" | +#+end_example + +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: + +#+BEGIN_SRC bash +defaults write com.google.Chrome ExternalProtocolDialogShowAlwaysOpenCheckbox -bool true +#+END_SRC + + +If you're using [[https://github.com/railwaycat/homebrew-emacsmacport][Emacs Mac Port]], it registered its `Emacs.app` as the default +handler for the URL scheme `org-protocol`. To make =OrgProtocol.app= +the default handler instead, run: + +#+BEGIN_SRC bash +defaults write com.apple.LaunchServices/com.apple.launchservices.secure LSHandlers -array-add \ +'{"LSHandlerPreferredVersions" = { "LSHandlerRoleAll" = "-"; }; LSHandlerRoleAll = "org.yourusername.OrgProtocol"; LSHandlerURLScheme = "org-protocol";}' +#+END_SRC + +Then restart your computer. + + +** 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 of an Org-roam File][Anatomy of an Org-roam File]]): + +[[file:images/roam-ref.gif]] + +To use this, create a Firefox bookmarklet as follows: + +#+BEGIN_SRC javascript +javascript:location.href = +'org-protocol://roam-ref?template=r&ref=' ++ encodeURIComponent(location.href) ++ '&title=' ++ encodeURIComponent(document.title) +#+END_SRC + +or as a keybinding in =qutebrowser=, adding the following to the =autoconfig.yml= file: + +#+BEGIN_SRC yaml +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)) +#+END_SRC + +where =template= is the template key for a template in +=org-roam-capture-ref-templates= (see [[*The Templating System][The Templating System]]). These templates +should contain a =#+ROAM_KEY: ${ref}= in it. + +* Keystroke Index +:PROPERTIES: +:APPENDIX: t +:INDEX: ky +:COOKIE_DATA: recursive +:END: +* Command Index +:PROPERTIES: +:APPENDIX: t +:INDEX: cp +:END: +* Function Index +:PROPERTIES: +:APPENDIX: t +:INDEX: fn +:END: +* Variable Index +:PROPERTIES: +:APPENDIX: t +:INDEX: vr +:END: + +* _ Copying +:PROPERTIES: +:COPYING: t +:END: + +#+BEGIN_QUOTE +Copyright (C) 2020-2020 Jethro Kuan + +You can redistribute this document and/or modify it under the terms +of the GNU General Public License as published by the Free Software +Foundation, either version 3 of the License, or (at your option) any +later version. + +This document is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +General Public License for more details. +#+END_QUOTE + +* Appendix +** Note-taking Workflows +- Books :: + - [[https://www.goodreads.com/book/show/34507927-how-to-take-smart-notes][How To Take Smart Notes]] +- Articles :: + - [[https://www.lesswrong.com/posts/NfdHG6oHBJ8Qxc26s/the-zettelkasten-method-1][The Zettelkasten Method - LessWrong 2.0]] + - [[https://reddit.com/r/RoamResearch/comments/eho7de/building_a_second_brain_in_roamand_why_you_might][Building a Second Brain in Roam...And Why You Might Want To : RoamResearch]] + - [[https://www.nateliason.com/blog/roam][Roam Research: Why I Love It and How I Use It - Nat Eliason]] + - [[https://twitter.com/adam_keesling/status/1196864424725774336?s=20][Adam Keesling's Twitter Thread]] + - [[https://blog.jethro.dev/posts/how_to_take_smart_notes_org/][How To Take Smart Notes With Org-mode · Jethro Kuan]] +- Threads :: + - [[https://news.ycombinator.com/item?id=22473209][Ask HN: How to Take Good Notes]] +- Videos :: + - [[https://www.youtube.com/watch?v=RvWic15iXjk][How to Use Roam to Outline a New Article in Under 20 Minutes]] +** Ecosystem +A number of packages work well combined with Org-Roam: + +*** Deft + :PROPERTIES: + :CUSTOM_ID: deft + :END: + +[[https://jblevins.org/projects/deft/][Deft]] provides a nice interface +for browsing and filtering org-roam notes. + +#+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 "/path/to/org-roam-files/")) +#+END_SRC + +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 +[[https://github.com/raxod502/el-patch][el-patch]]: + +#+BEGIN_SRC 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)))) +#+END_SRC + +The Deft interface can slow down quickly when the number of files get +huge. [[https://github.com/hasu/notdeft][Notdeft]] is a fork of Deft +that uses an external search engine and indexer. + +*** Org-journal + :PROPERTIES: + :CUSTOM_ID: org-journal + :END: + +[[https://github.com/bastibe/org-journal][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. + +#+BEGIN_SRC 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")) +#+END_SRC + +*** Note-taking Add-ons + :PROPERTIES: + :CUSTOM_ID: note-taking-add-ons + :END: + +These are some plugins that make note-taking in Org-mode more enjoyable. + +**** Org-download + :PROPERTIES: + :CUSTOM_ID: org-download + :END: + +[[https://github.com/abo-abo/org-download][Org-download]] lets you +screenshot and yank images from the web into your notes: + +#+CAPTION: org-download +[[file:images/org-download.gif]] + +#+BEGIN_SRC emacs-lisp + (use-package org-download + :after org + :bind + (:map org-mode-map + (("s-Y" . org-download-screenshot) + ("s-y" . org-download-yank)))) +#+END_SRC + +**** mathpix.el + :PROPERTIES: + :CUSTOM_ID: mathpix.el + :END: + +[[https://github.com/jethrokuan/mathpix.el][mathpix.el]] uses +[[https://mathpix.com/][Mathpix's]] API to convert clips into latex +equations: + +#+CAPTION: mathpix +[[file:images/mathpix.gif]] + +#+BEGIN_SRC 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)) +#+END_SRC + +**** Org-noter / Interleave + :PROPERTIES: + :CUSTOM_ID: org-noter-interleave + :END: + +[[https://github.com/weirdNox/org-noter][Org-noter]] and +[[https://github.com/rudolfochrist/interleave][Interleave]] are both +projects that allow synchronised annotation of documents (PDF, EPUB +etc.) within Org-mode. + +**** Bibliography + :PROPERTIES: + :CUSTOM_ID: bibliography + :END: + +[[https://github.com/zaeph/org-roam-bibtex][org-roam-bibtex]] offers +tight integration between +[[https://github.com/jkitchin/org-ref][org-ref]], +[[https://github.com/tmalsburg/helm-bibtex][helm-bibtex]] and +=org-roam=. This helps you manage your bibliographic notes under +=org-roam=. + +**** Spaced Repetition + :PROPERTIES: + :CUSTOM_ID: spaced-repetition + :END: + +[[https://github.com/l3kn/org-fc/][Org-fc]] is a spaced repetition +system that scales well with a large number of files. Other alternatives +include +[[https://orgmode.org/worg/org-contrib/org-drill.html][org-drill]], and +[[https://github.com/abo-abo/pamparam][pamparam]]. + +* FAQ +** How do I have 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: + +#+BEGIN_SRC emacs-lisp + ((nil . ((org-roam-directory . "/path/to/here/")))) +#+END_SRC + +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. + +* _ :ignore: +# Local Variables: +# eval: (require 'org-man nil t) +# eval: (require 'ox-texinfo+ nil t) +# eval: (and (require 'ox-extra nil t) (ox-extras-activate '(ignore-headlines))) +# indent-tabs-mode: nil +# org-src-preserve-indentation: nil +# End: diff --git a/doc/org-roam.texi b/doc/org-roam.texi new file mode 100644 index 0000000..a01b928 --- /dev/null +++ b/doc/org-roam.texi @@ -0,0 +1,1189 @@ +\input texinfo @c -*- texinfo -*- +@c %**start of header +@setfilename org-roam.info +@settitle Org-roam User Manual +@documentencoding UTF-8 +@documentlanguage en +@c %**end of header + +@copying +@quotation +Copyright (C) 2020-2020 Jethro Kuan + +You can redistribute this document and/or modify it under the terms +of the GNU General Public License as published by the Free Software +Foundation, either version 3 of the License, or (at your option) any +later version. + +This document is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE@. See the GNU +General Public License for more details. + +@end quotation +@end copying + +@dircategory Emacs +@direntry +* Org-roam: (org-roam). Rudimentary Roam Replica for Emacs. +@end direntry + +@finalout +@titlepage +@title Org-roam User Manual +@subtitle for version 1.1.0 (v1.1.0-29-g00fc215+1) +@author Jethro Kuan +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + +@contents + +@ifnottex +@node Top +@top Org-roam User Manual + +@noindent +This manual is for Org-roam version 1.1.0 (v1.1.0-29-g00fc215+1). + +@quotation +Copyright (C) 2020-2020 Jethro Kuan + +You can redistribute this document and/or modify it under the terms +of the GNU General Public License as published by the Free Software +Foundation, either version 3 of the License, or (at your option) any +later version. + +This document is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE@. See the GNU +General Public License for more details. + +@end quotation +@end ifnottex + +@menu +* Introduction:: +* Installation:: +* Getting Started:: +* Anatomy of an Org-roam File:: +* The Templating System:: +* Concepts and Configuration:: +* Navigating Around:: +* Encryption:: +* Graphing:: +* Org-roam Completion System:: +* Roam Protocol:: +* Keystroke Index:: +* Command Index:: +* Function Index:: +* Variable Index:: +* Appendix:: +* FAQ:: + +@detailmenu +--- The Detailed Node Listing --- + +Installation + +* Installing from MELPA:: +* Installing from the Git Repository:: +* Post-Installation Tasks:: + +Anatomy of an Org-roam File + +* File Aliases:: +* File Refs:: + +The Templating System + +* Template Walkthrough:: +* Org-roam Template Expansion:: + +Concepts and Configuration + +* Directories and Files:: +* The Org-roam Buffer:: +* Org-roam Links:: +* Org-roam Files:: + +Navigating Around + +* Index File:: + +Graphing + +* Graph Options:: +* Excluding Nodes and Edges:: + +Roam Protocol + +* Installation: Installation (1). +* The @samp{roam-file} protocol:: +* The @samp{roam-ref} Protocol:: + +Appendix + +* Note-taking Workflows:: +* Ecosystem:: + +Ecosystem + +* Deft:: +* Org-journal:: +* Note-taking Add-ons:: + + +FAQ + +* How do I have more than one Org-roam directory?:: + +@end detailmenu +@end menu + +@node Introduction +@chapter Introduction + +Org-roam is a @uref{https://roamresearch.com/, Roam Research} replica built around the +all-powerful @uref{https://orgmode.org/, Org-mode}. + +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 +@ref{Note-taking Workflows}. + +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. + +Org-roam provides several benefits over other tooling: + +@itemize + @item + Privacy and SecurityEdit your personal wiki completely offline, entirely in your control. Encrypt your notes with GPG@. + +@item + Longevity of Plain TextUnlike 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 + +@item + Free and Open SourceOrg-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@. + +@item + Leverages the Org-mode ecosystemOver 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. + +@item + Built on EmacsEmacs is also a fantastic interface for editing text, and we can inherit many of the powerful text-navigation and editing packages available to Emacs. +@end itemize + +@node Installation +@chapter Installation + +Org-roam can be installed using Emacs' package manager or manually from its development repository. + +@menu +* Installing from MELPA:: +* Installing from the Git Repository:: +* Post-Installation Tasks:: +@end menu + +@node Installing from MELPA +@section Installing from MELPA + +Org-roam is available from Melpa and Melpa-Stable. If you haven't used Emacs' package manager before, you may familiarize yourself with it by reading the documentation in the Emacs manual, see @ref{Packages,,,emacs,}. Then, add one of the archives to @samp{package-archives}: + +@itemize +@item +To use Melpa: +@end itemize + +@lisp +(require 'package) +(add-to-list 'package-archives + '("melpa" . "http://melpa.org/packages/") t) +@end lisp + +@itemize +@item +To use Melpa-Stable: +@end itemize + +@lisp +(require 'package) +(add-to-list 'package-archives + '("melpa-stable" . "http://stable.melpa.org/packages/") t) +@end lisp + +Once you have added your preferred archive, you need to update the +local package list using: + +@example +M-x package-refresh-contents RET +@end example + +Once you have done that, you can install Org-roam and its dependencies +using: + +@example +M-x package-install RET org-roam RET +@end example + +Now see @ref{Post-Installation Tasks}. + +@node Installing from the Git Repository +@section @strong{TODO} Installing from the Git Repository + +@node Post-Installation Tasks +@section @strong{TODO} Post-Installation Tasks + +@node Getting Started +@chapter Getting Started + +This short tutorial describes the essential commands used in Org-roam, to help +you get started. + +First, it is important to understand how Org-roam was designed. Org-roam was +built to support a workflow that was not possible with vanilla Org-mode. This +flow is modelled after the @uref{https://zettelkasten.de/, Zettelkasten Method}, and many of @uref{https://roamresearch.com, Roam Research's} +workflows. Org-roam does not magically make note-taking better -- this often +requires a radical change in your current note-taking workflow. To understand +more about the methods and madness, see @ref{Note-taking Workflows}. + +To begin using Org-roam, one should set the @samp{org-roam-directory} to the directory +containing your notes. For this tutorial, create an empty directory, and set the +@samp{org-roam-directory}: + +@lisp +(make-directory "~/org-roam") +(setq org-roam-directory "~/org-roam") +@end lisp + +We encourage using a flat hierarchy for storing notes, but some prefer using +folders for storing specific kinds of notes (e.g. websites, papers). This is +fine; Org-roam searches recursively within @samp{org-roam-directory} for any notes. +Instead of relying on the file hierarchy for any form of categorization, we +solely rely on links between files to establish connections between notes. + +Next, we need to enable the global minor mode @samp{org-roam-mode}. This sets up Emacs +with several hooks, builds a cache and keeps it consistent. We recommend +starting @samp{org-roam-mode} on startup: + +@lisp +(add-hook 'after-init-hook 'org-roam-mode) +@end lisp + +To build the cache manually, one can run @samp{M-x org-roam-db-build-cache}. The cache +is a sqlite database named @samp{org-roam.db}, which defaults to residing in the root +@samp{org-roam-directory}. Cache builds may take a while the first time, but is often +instantaneous in subsequent runs. + +Let us now create our first note. Call @samp{M-x org-roam-find-file}. This shows a list +of titles for notes that reside in @samp{org-roam-directory}. It should show nothing +right now, since there are no notes in the directory. Entering the title of the +note you wish to create, and pressing @samp{RET} should begin the note creation +process. This process uses @samp{org-capture}'s templating system, and can be freely +customized (see @ref{The Templating System}). Using the default template, pressing @samp{C-c +C-c} finishes the note capture. Running @samp{M-x org-roam-find-file} again should show +the note you have created, and selecting that entry will bring you to that note. + +The crux of Org-roam is making it easy to create notes, and link them together. +To link notes together, we call @samp{M-x org-roam-insert}. This brings up a prompt +with a list of title for existing notes. Selecting an existing entry will create +and insert a link to the current file. Entering a non-existent title will create +a new note with that title. Good usage of Org-roam requires liberally linking +files: this facilitates building up a dense knowledge graph of inter-connected +notes. + +Org-roam provides an interface to view backlinks. It shows backlinks for the +currently active Org-roam note, along with some surrounding context. To toggle +the visibility of this buffer, call @samp{M-x org-roam}. + +For a visual representation of the notes and their connections, Org-roam also +provides graphing capabilities, using Graphviz. It generates graphs 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 (see @ref{Roam Protocol, , Roam +Protocol}). + +@node Anatomy of an Org-roam File +@chapter Anatomy of an Org-roam File + +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. + +@menu +* File Aliases:: +* File Refs:: +@end menu + +@node File Aliases +@section 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 +@samp{#+ROAM_ALIAS} attribute: + +@example +#+TITLE: World War 2 +#+ROAM_ALIAS: "WWII" "World War II" +@end example + +@node File Refs +@section 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: + +@example +#+TITLE: Google +#+ROAM_KEY: https://www.google.com/ +@end example + +These keys come in useful for when taking website notes, using the +@samp{roam-ref} protocol (see @ref{Roam Protocol}). + +Alternatively, add a ref for notes for a specific paper, using its +@uref{https://github.com/jkitchin/org-ref, org-ref} citation key: + +@example +#+TITLE: Neural Ordinary Differential Equations +#+ROAM_KEY: cite:chen18_neural_ordin_differ_equat +@end example + +The backlinks buffer will show any cites of this key: e.g. + +@float Figure +@image{images/org-ref-citelink,,,,png} +@caption{org-ref-citelink} +@end float + +@node The Templating System +@chapter The Templating System + +Rather than creating blank files on @samp{org-roam-insert} and @samp{org-roam-find-file}, it +may be desirable to prefill the file with templated content. This may include: + +@itemize +@item +Time of creation + +@item +File it was created from + +@item +Clipboard content + +@item +Any other data you may want to input manually +@end itemize + +This requires a complex template insertion system. Fortunately, Org ships with a +powerful one: @samp{org-capture}. However, org-capture was not designed for such use. +Org-roam abuses @samp{org-capture}, extending its syntax. To first understand how +org-roam's templating system works, it may be useful to look into basic usage of +@samp{org-capture}. + +@menu +* Template Walkthrough:: +* Org-roam Template Expansion:: +@end menu + +@node Template Walkthrough +@section Template Walkthrough + +To demonstrate the additions made to org-capture templates. Here, we walkthrough +the default template, reproduced below. + +@lisp +("d" "default" plain (function org-roam--capture-get-point) + "%?" + :file-name "%<%Y%m%d%H%M%S>-$@{slug@}" + :head "#+TITLE: $@{title@}\n" + :unnarrowed t) +@end lisp + +@itemize +@item +The template has short key @samp{"d"}. If you have only one template, +org-roam automatically chooses this template for you. + +@item +The template is given a description of @samp{"default"}. + +@item +@samp{plain} text is inserted. Other options include Org headings via +@samp{entry}. + +@item +@samp{(function org-roam--capture-get-point)} should not be changed. + +@item +@samp{"%?"} is the template inserted on each call to @samp{org-roam--capture}. +This template means don't insert any content, but place the cursor +here. + +@item +@samp{: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 +@samp{/path/to/org-roam-directory/20200213032037-foo.org}. + +@item +@samp{:head} contains the initial template to be inserted (once only), at +the beginning of the file. Here, the title global attribute is +inserted. + +@item +@samp{:unnarrowed t} tells org-capture to show the contents for the whole +file, rather than narrowing to just the entry. +@end itemize + +Other options you may want to learn about include @samp{:immediate-finish}. + +@node Org-roam Template Expansion +@section Org-roam Template Expansion + +Org-roam's template definitions also extend org-capture's template syntax, to +allow prefilling of strings. We have seen a glimpse of this in @ref{Template Walkthrough, , Template +Walkthrough}. + +In org-roam templates, the @samp{$@{var@}} syntax allows for the expansion of +variables, stored in @samp{org-roam-capture--info}. For example, during +@samp{org-roam-insert}, the user is prompted for a title. Upon entering a +non-existent title, the @samp{title} key in @samp{org-roam-capture--info} is set to the +provided title. @samp{$@{title@}} is then expanded into the provided title during the +org-capture process. Any variables that do not contain strings, are prompted for +values using @samp{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 @uref{https://orgmode.org/manual/Template-expansion.html#Template-expansion, org-capture's documentation page}. + +To illustrate this dual expansion process, take for example the template string: +@samp{"%<%Y%m%d%H%M%S>-$@{title@}"}, with the title @samp{"Foo"}. The template is first +expanded into @samp{%<%Y%m%d%H%M%S>-Foo}. Then org-capture expands @samp{%<%Y%m%d%H%M%S>} +with timestamp: e.g. @samp{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 @samp{%(EXP)} template expansion to call @samp{format-time-string} +directly to provide its third argument to specify UTC@. + +@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) +@end lisp + +@node Concepts and Configuration +@chapter Concepts and Configuration + +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 +@samp{M-x customize-group org-roam}. + +@menu +* Directories and Files:: +* The Org-roam Buffer:: +* Org-roam Links:: +* Org-roam Files:: +@end menu + +@node Directories and Files +@section Directories and Files + +This section concerns the placement and creation of files. + +@defvar org-roam-directory + +This is the default path to Org-roam files. All Org files, at any level of +nesting, are considered part of the Org-roam. +@end defvar + +@defvar org-roam-db-location + +Location of the Org-roam database. If this is non-nil, the Org-roam sqlite +database is saved here. + +It is the user’s responsibility to set this correctly, especially when used +with multiple Org-roam instances. +@end defvar + +@node The Org-roam Buffer +@section The Org-roam Buffer + +The Org-roam buffer displays backlinks for the currently active Org-roam note. + +@defopt org-roam-buffer + +The name of the org-roam buffer. Defaults to @samp{*org-roam*}. +@end defopt + +@defopt org-roam-buffer-position + +The position of the Org-roam buffer side window. Valid values are @samp{'left}, +@samp{'right}, @samp{'top}, @samp{'bottom}. +@end defopt + +@defopt org-roam-buffer-width + +Width of @samp{org-roam-buffer}. Has an effect only if @samp{org-roam-buffer-position} is +@samp{'left} or @samp{'right}. +@end defopt + +@defopt org-roam-buffer-height + +Height of @samp{org-roam-buffer}. Has an effect only if @samp{org-roam-buffer-position} is +@samp{'top} or @samp{'bottom}. +@end defopt + +@defopt org-roam-buffer-no-delete-window + +The @samp{no-delete-window} parameter for the org-roam buffer. Setting it to @samp{'t} prevents the window from being deleted when calling @samp{delete-other-windows}. +@end defopt + +@node Org-roam Links +@section Org-roam Links + +Org-roam links are regular @samp{file:} links in Org-mode. By default, links are +inserted with the title as the link description with @samp{org-roam-insert}. + +@defopt org-roam-link-title-format + +To distinguish between org-roam links and regular links, one may choose to use +special indicators for Org-roam links. Defaults to @samp{"%s"}. + +If your version of Org is at least @samp{9.2}, consider styling the link differently, +by customizing the @samp{org-roam-link}, and @samp{org-roam-link-current} faces. +@end defopt + +@node Org-roam Files +@section Org-roam Files + +Org-roam files are created and prefilled using Org-roam's templating +system. The templating system is customizable (see @ref{The Templating System}). + +@node Navigating Around +@chapter Navigating Around + +@menu +* Index File:: +@end menu + +@node Index File +@section Index File + +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 +@samp{org-roam-index-file}. + +@defvar org-roam-index-file + +Path to the Org-roam index file. + +The path can be a string or a function. If it is a string, it should be the +path (absolute or relative to @samp{org-roam-directory}) to the index file. If it +is is a function, the function should return the path to the index file. +Otherwise, the index is assumed to be a note in @samp{org-roam-index} whose +title is @samp{"Index"}. +@end defvar + +@defun org-roam-find-index + +Opens the Index file in the current @samp{org-roam-directory}. +@end defun + +@node Encryption +@chapter Encryption + +One may wish to keep private, encrypted files. Org-roam supports encryption (via +GPG), which can be enabled for all new files by setting @samp{org-roam-encrypt-files} +to @samp{t}. When enabled, new files are created with the @samp{.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. + +@defvar org-roam-encrypt-files + +Whether to encrypt new files. If true, create files with .org.gpg extension. +@end defvar + +@node Graphing +@chapter Graphing + +Org-roam provides graphing capabilities to explore interconnections between +notes. This is done by performing SQL queries and generating images using +@uref{https://graphviz.org/, Graphviz}. The graph can also be navigated: see @ref{Roam Protocol}. + +The entry point to graph creation is @samp{org-roam-graph}. + +@defun org-roam-graph & optional arg file node-query + +Build and possibly display a graph for FILE from NODE-QUERY@. +If FILE is nil, default to current buffer’s file name. +ARG may be any of the following values: + +@itemize +@item +@samp{nil} show the graph. + +@item +@samp{C-u} show the graph for FILE@. + +@item +@samp{C-u N} show the graph for FILE limiting nodes to N steps. + +@item +@samp{C-u C-u} build the graph. + +@item +@samp{C-u -} build the graph for FILE@. + +@item +@samp{C-u -N} build the graph for FILE limiting nodes to N steps. +@end itemize +@end defun + +@defopt org-roam-graph-executable + +Path to the graphing executable (in this case, Graphviz). Set this if Org-roam is unable to find the Graphviz executable on your system. + +You may also choose to use @samp{neato} in place of @samp{dot}, which generates a more +compact graph layout. +@end defopt + +@defopt org-roam-graph-viewer + +Org-roam defaults to using Firefox (located on PATH) to view the SVG, but you may choose to set it to: + +@itemize +@item +A string, which is a path to the program used + +@item +a function accepting a single argument: the graph file path. +@end itemize + +@samp{nil} uses @samp{view-file} to view the graph. +@end defopt + +@menu +* Graph Options:: +* Excluding Nodes and Edges:: +@end menu + +@node Graph Options +@section Graph Options + +Graphviz provides many options for customizing the graph output, and Org-roam supports some of them. See @uref{https://graphviz.gitlab.io/_pages/doc/info/attrs.html} for customizable options. + +@defopt org-roam-graph-extra-config + +Extra options passed to graphviz for the digraph (The "G" attributes). +Example: @samp{'=(("rankdir" . "LR"))} +@end defopt + +@defopt org-roam-graph-node-extra-config + +Extra options for nodes in the graphviz output (The "N" attributes). +Example: @samp{'(("color" . "skyblue"))} +@end defopt + +@defopt org-roam-graph-edge-extra-config + +Extra options for edges in the graphviz output (The "E" attributes). +Example: @samp{'(("dir" . "back"))} +@end defopt + +@defopt org-roam-graph-edge-cites-extra-config + +Extra options for citation edges in the graphviz output. +Example: @samp{'(("color" . "red"))} +@end defopt + +@node Excluding Nodes and Edges +@section Excluding Nodes and Edges + +One may want to exclude certain files to declutter the graph. + +@defopt org-roam-graph-exclude-matcher + +Matcher for excluding nodes from the generated graph. Any nodes and links for +file paths matching this string is excluded from the graph. + +If value is a string, the string is the only matcher. + +If value is a list, all file paths matching any of the strings +are excluded. +@end defopt + +@example +(setq org-roam-graph-exclude-matcher '("private" "dailies")) +@end example + +This setting excludes all files whose path contain "private" or "dailies". + +@node Org-roam Completion System +@chapter Org-roam Completion System + +Org-roam offers completion when choosing note titles etc. The completion +system is configurable. The default setting, + +@lisp +(setq org-roam-completion-system 'default) +@end lisp + +uses Emacs' standard @samp{completing-read}. If you prefer +@uref{https://emacs-helm.github.io/helm/, Helm}, use + +@lisp +(setq org-roam-completion-system 'helm) +@end lisp + +Other options include @samp{'ido}, and @samp{'ivy}. + +@node Roam Protocol +@chapter Roam Protocol + +Org-roam extending @samp{org-protocol} with 2 protocols: the @samp{roam-file} +and @samp{roam-ref} protocol. + +@menu +* Installation: Installation (1). +* The @samp{roam-file} protocol:: +* The @samp{roam-ref} Protocol:: +@end menu + +@node Installation (1) +@section Installation + +To enable Org-roam's protocol extensions, you have to add the following to your init file: + +@lisp +(require 'org-roam-protocol) +@end lisp + +The instructions for setting up @samp{org-protocol=} are reproduced below. + +We will also need to create a desktop application for @samp{emacsclient}. The +instructions for various platforms are shown below. + +For Linux users, create a desktop application in @samp{~/.local/share/applications/org-protocol.desktop}: + +@example +[Desktop Entry] +Name=Org-Protocol +Exec=emacsclient %u +Icon=emacs-icon +Type=Application +Terminal=false +MimeType=x-scheme-handler/org-protocol +@end example + +Associate @samp{org-protocol://} links with the desktop application by +running in your shell: + +@example +xdg-mime default org-protocol.desktop x-scheme-handler/org-protocol +@end example + +To disable the "confirm" prompt in Chrome, you can also make Chrome +show a checkbox to tick, so that the @samp{Org-Protocol Client} app will be used +without confirmation. To do this, run in a shell: + +@example +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 +@end example + +and then restart Chrome (for example, by navigating to ) to +make the new policy take effect. + +See @uref{https://www.chromium.org/administrators/linux-quick-start, here} for more info on the @samp{/etc/opt/chrome/policies/managed} directory and +@uref{https://cloud.google.com/docs/chrome-enterprise/policies/?policy=ExternalProtocolDialogShowAlwaysOpenCheckbox, here} for information on the @samp{ExternalProtocolDialogShowAlwaysOpenCheckbox} policy. + +For MacOS, one solution is to use @uref{https://github.com/sveinbjornt/Platypus, Platypus}. Here are the instructions for +setting up with Platypus and Chrome: + +@itemize +@item +Install and launch Platypus (with @uref{https://brew.sh/, Homebrew}): +@end itemize + +@example +brew cask install platypus +@end example + +@itemize +@item +Create a script @samp{launch_emacs.sh}: +@end itemize + +@example +#!/usr/bin/env bash +/usr/local/bin/emacsclient --no-wait $1 +@end example + +@itemize +@item +Create a Platypus app with the following settings: +@end itemize + +@example +| 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 | +@end example + + +Inside @samp{Settings}: + +@example +| Setting | Value | +|--------------------------------+----------------| +| Accept dropped files | true | +| Register as URI scheme handler | true | +| Protocol | "org-protocol" | +@end example + +To disable the "confirm" prompt in Chrome, you can also make Chrome +show a checkbox to tick, so that the @samp{OrgProtocol} app will be used +without confirmation. To do this, run in a shell: + +@example +defaults write com.google.Chrome ExternalProtocolDialogShowAlwaysOpenCheckbox -bool true +@end example + + +If you're using @uref{https://github.com/railwaycat/homebrew-emacsmacport, Emacs Mac Port}, it registered its `Emacs.app` as the default +handler for the URL scheme `org-protocol`. To make @samp{OrgProtocol.app} +the default handler instead, run: + +@example +defaults write com.apple.LaunchServices/com.apple.launchservices.secure LSHandlers -array-add \ +'@{"LSHandlerPreferredVersions" = @{ "LSHandlerRoleAll" = "-"; @}; LSHandlerRoleAll = "org.yourusername.OrgProtocol"; LSHandlerURLScheme = "org-protocol";@}' +@end example + +Then restart your computer. + +@node The @samp{roam-file} protocol +@section The @samp{roam-file} protocol + +This is a simple protocol that opens the path specified by the @samp{file} +key (e.g. @samp{org-protocol://roam-file?file=/tmp/file.org}). This is used +in the generated graph. + +@node The @samp{roam-ref} Protocol +@section The @samp{roam-ref} Protocol + +This protocol finds or creates a new note with a given @samp{ROAM_KEY} (see @ref{Anatomy of an Org-roam File}): + +@image{images/roam-ref,,,,gif} + +To use this, create a Firefox bookmarklet as follows: + +@example +javascript:location.href = +'org-protocol://roam-ref?template=r&ref=' ++ encodeURIComponent(location.href) ++ '&title=' ++ encodeURIComponent(document.title) +@end example + +or as a keybinding in @samp{qutebrowser}, adding the following to the @samp{autoconfig.yml} file: + +@example +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)) +@end example + +where @samp{template} is the template key for a template in +@samp{org-roam-capture-ref-templates} (see @ref{The Templating System}). These templates +should contain a @samp{#+ROAM_KEY: $@{ref@}} in it. + +@node Keystroke Index +@appendix Keystroke Index + +@printindex ky + +@node Command Index +@appendix Command Index + +@printindex cp + +@node Function Index +@appendix Function Index + +@printindex fn + +@node Variable Index +@appendix Variable Index + +@printindex vr + +@node Appendix +@chapter Appendix + +@menu +* Note-taking Workflows:: +* Ecosystem:: +@end menu + +@node Note-taking Workflows +@section Note-taking Workflows + +@itemize + @item + Books@itemize +@item +@uref{https://www.goodreads.com/book/show/34507927-how-to-take-smart-notes, How To Take Smart Notes} +@end itemize + +@item + Articles@itemize +@item +@uref{https://www.lesswrong.com/posts/NfdHG6oHBJ8Qxc26s/the-zettelkasten-method-1, The Zettelkasten Method - LessWrong 2.0} + +@item +@uref{https://reddit.com/r/RoamResearch/comments/eho7de/building_a_second_brain_in_roamand_why_you_might, Building a Second Brain in Roam@dots{}And Why You Might Want To : RoamResearch} + +@item +@uref{https://www.nateliason.com/blog/roam, Roam Research: Why I Love It and How I Use It - Nat Eliason} + +@item +@uref{https://twitter.com/adam_keesling/status/1196864424725774336?s=20, Adam Keesling's Twitter Thread} + +@item +@uref{https://blog.jethro.dev/posts/how_to_take_smart_notes_org/, How To Take Smart Notes With Org-mode · Jethro Kuan} +@end itemize + +@item + Threads@itemize +@item +@uref{https://news.ycombinator.com/item?id=22473209, Ask HN: How to Take Good Notes} +@end itemize + +@item + Videos@itemize +@item +@uref{https://www.youtube.com/watch?v=RvWic15iXjk, How to Use Roam to Outline a New Article in Under 20 Minutes} +@end itemize +@end itemize + +@node Ecosystem +@section Ecosystem + +A number of packages work well combined with Org-Roam: + +@menu +* Deft:: +* Org-journal:: +* Note-taking Add-ons:: +@end menu + +@node Deft +@subsection Deft + +@uref{https://jblevins.org/projects/deft/, Deft} provides a nice interface +for browsing and filtering org-roam notes. + +@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/")) +@end lisp + +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 @samp{org-roam}'s +functionality. Here I'm using +@uref{https://github.com/raxod502/el-patch, el-patch}: + +@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)))) +@end lisp + +The Deft interface can slow down quickly when the number of files get +huge. @uref{https://github.com/hasu/notdeft, Notdeft} is a fork of Deft +that uses an external search engine and indexer. + +@node Org-journal +@subsection Org-journal + +@uref{https://github.com/bastibe/org-journal, Org-journal} is a more +powerful alternative to the simple function @samp{org-roam-dailies-today}. It +provides better journaling capabilities, and a nice calendar interface +to see all dated entries. + +@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")) +@end lisp + +@node Note-taking Add-ons +@subsection Note-taking Add-ons + +These are some plugins that make note-taking in Org-mode more enjoyable. + +@menu +* Org-download:: +* mathpix.el: mathpixel. +* Org-noter / Interleave:: +* Bibliography:: +* Spaced Repetition:: +@end menu + +@node Org-download +@unnumberedsubsubsec Org-download + +@uref{https://github.com/abo-abo/org-download, Org-download} lets you +screenshot and yank images from the web into your notes: + +@float Figure +@image{images/org-download,,,,gif} +@caption{org-download} +@end float + +@lisp +(use-package org-download + :after org + :bind + (:map org-mode-map + (("s-Y" . org-download-screenshot) + ("s-y" . org-download-yank)))) +@end lisp + +@node mathpixel +@unnumberedsubsubsec mathpix.el + +@uref{https://github.com/jethrokuan/mathpix.el, mathpix.el} uses +@uref{https://mathpix.com/, Mathpix's} API to convert clips into latex +equations: + +@float Figure +@image{images/mathpix,,,,gif} +@caption{mathpix} +@end float + +@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)) +@end lisp + +@node Org-noter / Interleave +@unnumberedsubsubsec Org-noter / Interleave + +@uref{https://github.com/weirdNox/org-noter, Org-noter} and +@uref{https://github.com/rudolfochrist/interleave, Interleave} are both +projects that allow synchronised annotation of documents (PDF, EPUB +etc.) within Org-mode. + +@node Bibliography +@unnumberedsubsubsec Bibliography + +@uref{https://github.com/zaeph/org-roam-bibtex, org-roam-bibtex} offers +tight integration between +@uref{https://github.com/jkitchin/org-ref, org-ref}, +@uref{https://github.com/tmalsburg/helm-bibtex, helm-bibtex} and +@samp{org-roam}. This helps you manage your bibliographic notes under +@samp{org-roam}. + +@node Spaced Repetition +@unnumberedsubsubsec Spaced Repetition + +@uref{https://github.com/l3kn/org-fc/, Org-fc} is a spaced repetition +system that scales well with a large number of files. Other alternatives +include +@uref{https://orgmode.org/worg/org-contrib/org-drill.html, org-drill}, and +@uref{https://github.com/abo-abo/pamparam, pamparam}. + +@node FAQ +@chapter FAQ + +@menu +* How do I have more than one Org-roam directory?:: +@end menu + +@node How do I have more than one Org-roam directory? +@section How do I have more than one Org-roam directory? + +Emacs supports directory-local variables, allowing the value of +@samp{org-roam-directory} to be different in different directories. It does this by +checking for a file named @samp{.dir-locals.el}. + +To add support for multiple directories, override the @samp{org-roam-directory} +variable using directory-local variables. This is what @samp{.dir-locals.el} may +contain: + +@lisp +((nil . ((org-roam-directory . "/path/to/here/")))) +@end lisp + +All files within that directory will be treated as their own separate +set of Org-roam files. Remember to run @samp{org-roam-db-build-cache} from a +file within that directory, at least once. + +Emacs 28.0.50 (Org mode 9.3.6) +@bye