From c8241008e7251e1cc74baed49da9814303e1e1f0 Mon Sep 17 00:00:00 2001 From: jethrokuan Date: Wed, 11 Nov 2020 05:01:25 +0000 Subject: [PATCH] =?UTF-8?q?Deploying=20to=20gh-pages=20from=20=20@=20aef71?= =?UTF-8?q?f1623d5c224db261b8e5c33bdd463992256=20=F0=9F=9A=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...Capturing-and-finding-daily_002dnotes.html | 42 ++- manual/Configuration.html | 14 +- manual/Diagnosing-and-Repairing-Files.html | 8 +- manual/Directories-and-Files.html | 20 +- manual/Encryption.html | 8 +- manual/Excluding-Nodes-and-Edges.html | 8 +- manual/Graph-Options.html | 26 +- manual/Graphing.html | 30 +- ...dy-matches-one-of-the-candidates_003f.html | 15 +- manual/Index-File.html | 14 +- manual/Inserting-Links.html | 38 +-- manual/Installation-_00281_0029.html | 12 +- .../Installing-from-the-Git-Repository.html | 9 +- manual/Introduction.html | 28 +- manual/Navigation.html | 20 +- manual/Note_002dtaking-Workflows.html | 27 +- manual/Org_002droam-Faces.html | 8 +- manual/Tags.html | 7 +- manual/Template-Walkthrough.html | 11 +- manual/The-Org_002droam-Buffer.html | 32 +- manual/The-Templating-System.html | 3 + manual/Titles.html | 6 +- org-roam.org | 4 + org-roam.texi | 317 +++++++++--------- 24 files changed, 389 insertions(+), 318 deletions(-) diff --git a/manual/Capturing-and-finding-daily_002dnotes.html b/manual/Capturing-and-finding-daily_002dnotes.html index ee9791b..9e5e322 100644 --- a/manual/Capturing-and-finding-daily_002dnotes.html +++ b/manual/Capturing-and-finding-daily_002dnotes.html @@ -69,50 +69,56 @@ Next:

15.2 Capturing and finding daily-notes

- +

There are variants of those commands for -yesterday and -tomorrow:

- +

There are also commands which allow you to use Emacs’s calendar to find the date

- +

diff --git a/manual/Configuration.html b/manual/Configuration.html index c7c88cb..4b58e41 100644 --- a/manual/Configuration.html +++ b/manual/Configuration.html @@ -71,15 +71,17 @@ Next: Variable: org-roam-dailies-directory +

Path to daily-notes. -

-
  • Variable: org-roam-dailies-capture-templates +

    • +
    +
    Variable: org-roam-dailies-capture-templates
    +

    Capture templates for daily-notes in Org-roam. -

    +

    Here is a sane default configuration:

    diff --git a/manual/Diagnosing-and-Repairing-Files.html b/manual/Diagnosing-and-Repairing-Files.html index 97b2f4a..506c039 100644 --- a/manual/Diagnosing-and-Repairing-Files.html +++ b/manual/Diagnosing-and-Repairing-Files.html @@ -74,12 +74,12 @@ Next: C-u M-x org-roam-doctor, but note that this may take some time.

    -     +

    The checks run are defined in org-roam-doctor--checkers. Each checker is an instance of org-roam-doctor-checker. To define a checker, use diff --git a/manual/Directories-and-Files.html b/manual/Directories-and-Files.html index 42d3028..9a69fea 100644 --- a/manual/Directories-and-Files.html +++ b/manual/Directories-and-Files.html @@ -71,24 +71,28 @@ Next: 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 +

    • +
    +
    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. -

    -
  • Variable: org-roam-file-exclude-regexp +

    • +
    +
    Variable: org-roam-file-exclude-regexp
    +

    Files matching this regular expression are excluded from the Org-roam. -

    +

    diff --git a/manual/Encryption.html b/manual/Encryption.html index 159fd5b..6a99193 100644 --- a/manual/Encryption.html +++ b/manual/Encryption.html @@ -78,11 +78,11 @@ decryption are handled automatically by EasyPG. cache updates if it requires reading the encrypted file. To reduce the number of password prompts, you may wish to cache the password.

    - +

    diff --git a/manual/Excluding-Nodes-and-Edges.html b/manual/Excluding-Nodes-and-Edges.html index 924a437..4a4d816 100644 --- a/manual/Excluding-Nodes-and-Edges.html +++ b/manual/Excluding-Nodes-and-Edges.html @@ -71,9 +71,9 @@ Previous: +

    (setq org-roam-graph-exclude-matcher '("private" "dailies"))
diff --git a/manual/Graph-Options.html b/manual/Graph-Options.html
index 9a9ad6f..fb7e857 100644
--- a/manual/Graph-Options.html
+++ b/manual/Graph-Options.html
@@ -71,27 +71,33 @@ Next: 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
-
+
      
+
      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
+
      
 
+
      
+
      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
+
      
 
+
      
+
      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
+
      
 
+
      
+
      User Option: org-roam-graph-edge-cites-extra-config
      
+
      
 
      Extra options for citation edges in the graphviz output.
 Example: '(("color" . "red"))
-
    
+
    
 
 
 
diff --git a/manual/Graphing.html b/manual/Graphing.html
index d4c481a..352aab2 100644
--- a/manual/Graphing.html
+++ b/manual/Graphing.html
@@ -75,37 +75,47 @@ notes. This is done by performing SQL queries and generating images using
 
    
 
    The entry point to graph creation is org-roam-graph.
 
    
-
      
-
    •  Function: org-roam-graph & optional arg file node-query
-
+
      
+
      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
-
+
      
+
      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
+
      
 
+
      
+
      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:
 
      
-
        
+
          
 
        •  A string, which is a path to the program used
+
 
        •  a function accepting a single argument: the graph file path.
-
      
+
    
 
 
    nil uses view-file to view the graph.
 
    
@@ -117,7 +127,7 @@ compact graph layout.
       (let ((org-roam-graph-viewer "/mnt/c/Program Files/Mozilla Firefox/firefox.exe"))
         (org-roam-graph--open (concat "file://///wsl$/Ubuntu" file)))))
    - +
    • Graph Options:   diff --git a/manual/How-do-I-create-a-note-whose-title-already-matches-one-of-the-candidates_003f.html b/manual/How-do-I-create-a-note-whose-title-already-matches-one-of-the-candidates_003f.html index cdcd23a..b303d69 100644 --- a/manual/How-do-I-create-a-note-whose-title-already-matches-one-of-the-candidates_003f.html +++ b/manual/How-do-I-create-a-note-whose-title-already-matches-one-of-the-candidates_003f.html @@ -74,16 +74,13 @@ Previous: -
    Ivy
    -

    call ivy-immediate-done, typically bound to C-M-j. Alternatively, set ivy-use-selectable-prompt to t, so that “bar” is now selectable. -

    -
    Helm
    -

    Org-roam should provide a selectable “[?] bar” candidate at the top of the candidate list. -

    - +
      +
    • Ivycall ivy-immediate-done, typically bound to C-M-j. Alternatively, set ivy-use-selectable-prompt to t, so that “bar” is now selectable. -

      Emacs 27.1.50 (Org mode 9.4) +

    • HelmOrg-roam should provide a selectable “[?] bar” candidate at the top of the candidate list. +
    + +

    Emacs 28.0.50 (Org mode 9.4)

    diff --git a/manual/Index-File.html b/manual/Index-File.html index 67ebb0e..e9b17e0 100644 --- a/manual/Index-File.html +++ b/manual/Index-File.html @@ -75,9 +75,9 @@ 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 - +
      +
      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 @@ -85,11 +85,13 @@ path (absolute or relative to org-roam-directory) to the index file 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 +

      +
      +
      Function: org-roam-find-index
      +

      Opens the Index file in the current org-roam-directory. -

    +

    diff --git a/manual/Inserting-Links.html b/manual/Inserting-Links.html index f4cc571..2537174 100644 --- a/manual/Inserting-Links.html +++ b/manual/Inserting-Links.html @@ -83,17 +83,13 @@ populate the Org-roam database. The link can then be inserted via

    An alternative mode of insertion is using Org-roam’s roam links. Org-roam registers this link type, and interprets the path as follows:

    -
    -
    [[roam:title]]
    -

    links to an Org-roam file with title or alias “title” -

    -
    [[roam:*headline]]
    -

    links to the headline “headline” in the current Org-roam file -

    -
    [[roam:title*headline]]
    -

    links to the headline “headline” in the Org-roam file with title or alias “title” -

    -
    +
      +
    • [[roam:title]]links to an Org-roam file with title or alias “title” + +
    • [[roam:*headline]]links to the headline “headline” in the current Org-roam file + +
    • [[roam:title*headline]]links to the headline “headline” in the Org-roam file with title or alias “title” +

    roam links support auto-completion via completion-at-point: simply call completion-at-point within a roam link. Users of company-mode may want to @@ -111,28 +107,32 @@ prepend company-capf to the beginning of variable company-bac (backward-char 2)) -

      -
    • User Option: org-roam-link-title-format - +
      +
      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. -

      -
    • User Option: org-roam-completion-ignore-case +

      +
      +
      User Option: org-roam-completion-ignore-case
      +

      When non-nil, the roam link completions are ignore case. For example, calling completion-at-point within [[roam:fo]] will present a completion for a file with title “Foo”. Defaults to t. -

      -
    • User Option: org-roam-link-auto-replace +

      +
      +
      User Option: org-roam-link-auto-replace
      +

      When non-nil, roam links will be replaced with file or id links when they are navigated to, and on file save, when a match is found. This is desirable to maintain compatibility with vanilla Org, but resolved links are harder to edit. Defaults to t. -

    +

    diff --git a/manual/Installation-_00281_0029.html b/manual/Installation-_00281_0029.html index c6c1168..576b6e6 100644 --- a/manual/Installation-_00281_0029.html +++ b/manual/Installation-_00281_0029.html @@ -122,26 +122,26 @@ make the new policy take effect.

    For MacOS, one solution is to use Platypus. Here are the instructions for setting up with Platypus and Chrome:

    -
      +
      • Install and launch Platypus (with Homebrew): -
    + 
    brew cask install platypus
    -
      +
      • Create a script launch_emacs.sh: -
    + 
    #!/usr/bin/env bash
 /usr/local/bin/emacsclient --no-wait $1
    -
      +
      • Create a Platypus app with the following settings: -
    + 
    | Setting                        | Value                     |
diff --git a/manual/Installing-from-the-Git-Repository.html b/manual/Installing-from-the-Git-Repository.html
index c2e2a7f..1a40d8f 100644
--- a/manual/Installing-from-the-Git-Repository.html
+++ b/manual/Installing-from-the-Git-Repository.html
@@ -92,10 +92,15 @@ Next: 
 
      
 
    •  dash
+
 
    •  f
+
 
    •  s
+
 
    •  org
+
 
    •  emacsql
+
 
    •  emacsql-sqlite3
 
    
 
@@ -114,14 +119,16 @@ Next:     
 
    (require 'info)
 (add-to-list 'Info-default-directory-list
-             "/path/to/my/info/files")
+         "/path/to/my/info/files")

    You can also use one of the default locations, such as:

    • usr/local/share/info +
    • usr/share/info +
    • usr/local/share/info
    diff --git a/manual/Introduction.html b/manual/Introduction.html index 44ef376..08ec4cc 100644 --- a/manual/Introduction.html +++ b/manual/Introduction.html @@ -86,23 +86,17 @@ 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. -

    -
    +
      +
    • Privacy and SecurityEdit your personal wiki completely offline, entirely in your control. Encrypt your notes with GPG. + +
    • 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 + +
    • 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. + +
    • 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. + +
    • 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. +
    diff --git a/manual/Navigation.html b/manual/Navigation.html index 00e5f42..ec8b0bf 100644 --- a/manual/Navigation.html +++ b/manual/Navigation.html @@ -71,19 +71,23 @@ Previous: Function: org-roam-dailies-find-directory +

    Find and open org-roam-dailies-directory. -

    -
  • Function: org-roam-dailies-find-previous-note +

    • +
    +
    Function: org-roam-dailies-find-previous-note
    +

    When in an daily-note, find the previous one. -

    -
  • Function: org-roam-dailies-find-next-note +

    • +
    +
    Function: org-roam-dailies-find-next-note
    +

    When in an daily-note, find the next one. -

    +

    diff --git a/manual/Note_002dtaking-Workflows.html b/manual/Note_002dtaking-Workflows.html index 878cc6e..273958f 100644 --- a/manual/Note_002dtaking-Workflows.html +++ b/manual/Note_002dtaking-Workflows.html @@ -69,32 +69,31 @@ Next: ,

    19.1 Note-taking Workflows

    -
    -
    Books
    -
    -
    Articles
    -
    -
    Threads
    -
    -
    Videos
    -
    -
    + diff --git a/manual/Org_002droam-Faces.html b/manual/Org_002droam-Faces.html index 1a86c74..f5f5fb9 100644 --- a/manual/Org_002droam-Faces.html +++ b/manual/Org_002droam-Faces.html @@ -72,13 +72,13 @@ Previous: Org-roam introduces several faces to distinguish links within the same buffer. These faces are enabled by default in Org-roam notes.

    -
      -
    • User Option: org-roam-link-use-custom-faces - +
      +
      User Option: org-roam-link-use-custom-faces
      +

      When t, use custom faces only inside Org-roam notes. When everywhere, the custom face is applied additionally to non Org-roam notes. When nil, do not use Org-roam’s custom faces. -

    +

    The org-roam-link face is the face applied to links to other Org-roam files. This distinguishes internal links from external links (e.g. external web links). diff --git a/manual/Tags.html b/manual/Tags.html index ce9c723..41b482b 100644 --- a/manual/Tags.html +++ b/manual/Tags.html @@ -77,18 +77,21 @@ notes: differentiating between bibliographical and structure notes during intera variable org-roam-tag-sources, to control how tags are extracted. The tag extraction methods supported are:

    -
      +
      • 'prop: This extracts tags from the #+roam_tags property. Tags are space delimited, and can be multi-word using double quotes. +
      • 'all-directories: All sub-directories relative to org-roam-directory are extracted as tags. That is, if a file is located at relative path foo/bar/file.org, the file will have tags foo and bar. +
      • 'last-directory: Extracts the last directory relative to org-roam-directory as the tag. That is, if a file is located at relative path foo/bar/file.org, the file will have tag bar. +
      • 'first-directory: Extracts the first directory relative to org-roam-directory as the tag. That is, if a file is located at relative path foo/bar/file.org, the file will have tag foo. -
    +

    By default, only the 'prop extraction method is enabled. To enable the other extraction methods, you may modify org-roam-tag-sources: diff --git a/manual/Template-Walkthrough.html b/manual/Template-Walkthrough.html index 078797c..3e55229 100644 --- a/manual/Template-Walkthrough.html +++ b/manual/Template-Walkthrough.html @@ -80,28 +80,35 @@ the default template, reproduced below. :unnarrowed t)

    -
      +
      • The template has short key "d". If you have only one template, org-roam automatically chooses this template for you. +
      • The template is given a description of "default". +
      • plain text is inserted. Other options include Org headings via entry. +
      • (function org-roam--capture-get-point) should not be changed. +
      • "%?" 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. +
      • :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. This template also allows you to specify if you want the note to go into a subdirectory. For example, the template private/${slug} will create notes in /path/to/org-roam-directory/private. +
      • :head contains the initial template to be inserted (once only), at the beginning of the file. Here, the title global attribute is inserted. +
      • :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/manual/The-Org_002droam-Buffer.html b/manual/The-Org_002droam-Buffer.html index 7b34a78..ab6610f 100644 --- a/manual/The-Org_002droam-Buffer.html +++ b/manual/The-Org_002droam-Buffer.html @@ -71,35 +71,43 @@ Next: User Option: org-roam-buffer +

    The name of the org-roam buffer. Defaults to *org-roam*. -

    -
  • User Option: org-roam-buffer-position +

    • +
    +
    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 +

    • +
    +
    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 +

    • +
    +
    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-window-parameters +

    • +
    +
    User Option: org-roam-buffer-window-parameters
    +

    Additional window parameters for the org-roam-buffer side window.

    For example one can prevent the window from being deleted when calling delete-other-windows, by setting it with the following:

    (setq org-roam-buffer-window-parameters '((no-delete-other-windows . t))) -

    +

    diff --git a/manual/The-Templating-System.html b/manual/The-Templating-System.html index c296d74..dddfdb6 100644 --- a/manual/The-Templating-System.html +++ b/manual/The-Templating-System.html @@ -75,8 +75,11 @@ include:

    • Time of creation +
    • File it was created from +
    • Clipboard content +
    • Any other data you may want to input manually
    diff --git a/manual/Titles.html b/manual/Titles.html index bae5ecd..4964357 100644 --- a/manual/Titles.html +++ b/manual/Titles.html @@ -79,12 +79,14 @@ like “World War 2”, it may be desirable to also refer to it using th variable org-roam-title-sources, to control how the titles are extracted. The title extraction methods supported are:

    -
      +
      • 'title: This extracts the title using the file #+title property +
      • 'headline: This extracts the title from the first headline in the Org file +
      • 'alias: This extracts a list of titles using the #+roam_alias property. The aliases are space-delimited, and can be multi-worded using quotes -
    +

    Take for example the following org file:

    diff --git a/org-roam.org b/org-roam.org index 7654840..82bcd7d 100644 --- a/org-roam.org +++ b/org-roam.org @@ -5,6 +5,8 @@ #+date: 2020-2020 #+language: en + +#+texinfo_deffn: t #+texinfo_dir_category: Emacs #+texinfo_dir_title: Org-roam: (org-roam). #+texinfo_dir_desc: Rudimentary Roam Replica for Emacs. @@ -14,6 +16,7 @@ #+property: header-args :eval never #+texinfo: @noindent +#+texinfo: @noindent This manual is for Org-roam version 1.2.2. #+BEGIN_QUOTE @@ -1444,6 +1447,7 @@ are the solutions: # Local Variables: # eval: (require 'ol-info) +# eval: (require 'ox-texinfo+ nil t) # before-save-hook: org-make-toc # after-save-hook: (lambda nil (progn (require 'ox-texinfo nil t) (org-texinfo-export-to-info))) # indent-tabs-mode: nil diff --git a/org-roam.texi b/org-roam.texi index 10bf1c1..45581e7 100644 --- a/org-roam.texi +++ b/org-roam.texi @@ -46,6 +46,7 @@ General Public License for more details. @noindent +@noindent This manual is for Org-roam version 1.2.2. @quotation @@ -183,18 +184,22 @@ to further introduce features enabled by the Emacs ecosystem. Org-roam provides several benefits over other tooling: -@table @asis -@item Privacy and Security -Edit your personal wiki completely offline, entirely in your control. Encrypt your notes with GPG@. -@item 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 -@item 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@. -@item 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. -@item 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. -@end table +@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 Target Audience @chapter Target Audience @@ -381,14 +386,19 @@ You now have Org-roam installed. However, you don't necessarily have the depende @itemize @item dash + @item f + @item s + @item org + @item emacsql + @item emacsql-sqlite3 @end itemize @@ -408,7 +418,7 @@ Where @code{/path/to/my/info/files} is the location where you keep info files. T @lisp (require 'info) (add-to-list 'Info-default-directory-list - "/path/to/my/info/files") + "/path/to/my/info/files") @end lisp You can also use one of the default locations, such as: @@ -416,8 +426,10 @@ You can also use one of the default locations, such as: @itemize @item @emph{usr/local/share/info} + @item @emph{usr/share/info} + @item @emph{usr/local/share/info} @end itemize @@ -547,15 +559,17 @@ Org-roam calls @code{org-roam--extract-titles} to extract titles. It uses the variable @code{org-roam-title-sources}, to control how the titles are extracted. The title extraction methods supported are: -@enumerate +@itemize @item @code{'title}: This extracts the title using the file @code{#+title} property + @item @code{'headline}: This extracts the title from the first headline in the Org file + @item @code{'alias}: This extracts a list of titles using the @code{#+roam_alias} property. The aliases are space-delimited, and can be multi-worded using quotes -@end enumerate +@end itemize Take for example the following org file: @@ -598,22 +612,25 @@ Org-roam calls @code{org-roam--extract-tags} to extract tags from files. It uses variable @code{org-roam-tag-sources}, to control how tags are extracted. The tag extraction methods supported are: -@enumerate +@itemize @item @code{'prop}: This extracts tags from the @code{#+roam_tags} property. Tags are space delimited, and can be multi-word using double quotes. + @item @code{'all-directories}: All sub-directories relative to @code{org-roam-directory} are extracted as tags. That is, if a file is located at relative path @code{foo/bar/file.org}, the file will have tags @code{foo} and @code{bar}. + @item @code{'last-directory}: Extracts the last directory relative to @code{org-roam-directory} as the tag. That is, if a file is located at relative path @code{foo/bar/file.org}, the file will have tag @code{bar}. + @item @code{'first-directory}: Extracts the first directory relative to @code{org-roam-directory} as the tag. That is, if a file is located at relative path @code{foo/bar/file.org}, the file will have tag @code{foo}. -@end enumerate +@end itemize By default, only the @code{'prop} extraction method is enabled. To enable the other extraction methods, you may modify @code{org-roam-tag-sources}: @@ -666,10 +683,13 @@ 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 @@ -706,21 +726,26 @@ the default template, reproduced below. :unnarrowed t) @end lisp -@enumerate +@itemize @item The template has short key @code{"d"}. If you have only one template, org-roam automatically chooses this template for you. + @item The template is given a description of @code{"default"}. + @item @code{plain} text is inserted. Other options include Org headings via @code{entry}. + @item @code{(function org-roam--capture-get-point)} should not be changed. + @item @code{"%?"} is the template inserted on each call to @code{org-roam-capture--capture}. This template means don't insert any content, but place the cursor here. + @item @code{: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 @@ -728,14 +753,16 @@ exist. This creates a file at path that looks like allows you to specify if you want the note to go into a subdirectory. For example, the template @code{private/$@{slug@}} will create notes in @code{/path/to/org-roam-directory/private}. + @item @code{:head} contains the initial template to be inserted (once only), at the beginning of the file. Here, the title global attribute is inserted. + @item @code{:unnarrowed t} tells org-capture to show the contents for the whole file, rather than narrowing to just the entry. -@end enumerate +@end itemize Other options you may want to learn about include @code{:immediate-finish}. @@ -798,59 +825,55 @@ All of Org-roam's customization options can be viewed via This section concerns the placement and creation of files. -@itemize -@item -Variable: org-roam-directory +@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 -@item -Variable: org-roam-db-location +@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 -@item -Variable: org-roam-file-exclude-regexp +@defvar org-roam-file-exclude-regexp Files matching this regular expression are excluded from the Org-roam. -@end itemize +@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. -@itemize -@item -User Option: org-roam-buffer +@defopt org-roam-buffer The name of the org-roam buffer. Defaults to @code{*org-roam*}. +@end defopt -@item -User Option: org-roam-buffer-position +@defopt org-roam-buffer-position The position of the Org-roam buffer side window. Valid values are @code{'left}, @code{'right}, @code{'top}, @code{'bottom}. +@end defopt -@item -User Option: org-roam-buffer-width +@defopt org-roam-buffer-width Width of @code{org-roam-buffer}. Has an effect only if @code{org-roam-buffer-position} is @code{'left} or @code{'right}. +@end defopt -@item -User Option: org-roam-buffer-height +@defopt org-roam-buffer-height Height of @code{org-roam-buffer}. Has an effect only if @code{org-roam-buffer-position} is @code{'top} or @code{'bottom}. +@end defopt -@item -User Option: org-roam-buffer-window-parameters +@defopt org-roam-buffer-window-parameters Additional window parameters for the org-roam-buffer side window. @@ -858,7 +881,7 @@ For example one can prevent the window from being deleted when calling @code{delete-other-windows}, by setting it with the following: @code{(setq org-roam-buffer-window-parameters '((no-delete-other-windows . t)))} -@end itemize +@end defopt @node Org-roam Files @section Org-roam Files @@ -872,14 +895,12 @@ system. The templating system is customizable (see @ref{The Templating System}). Org-roam introduces several faces to distinguish links within the same buffer. These faces are enabled by default in Org-roam notes. -@itemize -@item -User Option: org-roam-link-use-custom-faces +@defopt org-roam-link-use-custom-faces When @code{t}, use custom faces only inside Org-roam notes. When @code{everywhere}, the custom face is applied additionally to non Org-roam notes. When @code{nil}, do not use Org-roam's custom faces. -@end itemize +@end defopt The @code{org-roam-link} face is the face applied to links to other Org-roam files. This distinguishes internal links from external links (e.g. external web links). @@ -906,14 +927,16 @@ populate the Org-roam database. The link can then be inserted via An alternative mode of insertion is using Org-roam's @code{roam} links. Org-roam registers this link type, and interprets the path as follows: -@table @asis -@item @code{[[roam:title]]} -links to an Org-roam file with title or alias ``title'' -@item @code{[[roam:*headline]]} -links to the headline ``headline'' in the current Org-roam file -@item @code{[[roam:title*headline]]} -links to the headline ``headline'' in the Org-roam file with title or alias ``title'' -@end table +@itemize + @item + @code{[[roam:title]]}links to an Org-roam file with title or alias ``title'' + +@item + @code{[[roam:*headline]]}links to the headline ``headline'' in the current Org-roam file + +@item + @code{[[roam:title*headline]]}links to the headline ``headline'' in the Org-roam file with title or alias ``title'' +@end itemize @code{roam} links support auto-completion via @code{completion-at-point}: simply call @code{completion-at-point} within a roam link. Users of @code{company-mode} may want to @@ -931,31 +954,29 @@ To easily insert @code{roam} links, one may wish to use a package like @uref{htt (backward-char 2)) @end lisp -@itemize -@item -User Option: org-roam-link-title-format +@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 @code{"%s"}. If your version of Org is at least @code{9.2}, consider styling the link differently, by customizing the @code{org-roam-link}, and @code{org-roam-link-current} faces. +@end defopt -@item -User Option: org-roam-completion-ignore-case +@defopt org-roam-completion-ignore-case When non-nil, the @code{roam} link completions are ignore case. For example, calling @code{completion-at-point} within @code{[[roam:fo]]} will present a completion for a file with title ``Foo''. Defaults to @code{t}. +@end defopt -@item -User Option: org-roam-link-auto-replace +@defopt org-roam-link-auto-replace When non-nil, @code{roam} links will be replaced with @code{file} or @code{id} links when they are navigated to, and on file save, when a match is found. This is desirable to maintain compatibility with vanilla Org, but resolved links are harder to edit. Defaults to @code{t}. -@end itemize +@end defopt @node Navigating Around @chapter Navigating Around @@ -973,9 +994,7 @@ to your main files. In Org-roam, you can define the path to your index file by setting @code{org-roam-index-file}. -@itemize -@item -Variable: org-roam-index-file +@defvar org-roam-index-file Path to the Org-roam index file. @@ -984,12 +1003,12 @@ path (absolute or relative to @code{org-roam-directory}) to the index file. If i is is a function, the function should return the path to the index file. Otherwise, the index is assumed to be a note in @code{org-roam-index} whose title is @code{"Index"}. +@end defvar -@item -Function: org-roam-find-index +@defun org-roam-find-index Opens the Index file in the current @code{org-roam-directory}. -@end itemize +@end defun @node Encryption @chapter Encryption @@ -1003,12 +1022,10 @@ 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. -@itemize -@item -Variable: org-roam-encrypt-files +@defvar org-roam-encrypt-files Whether to encrypt new files. If true, create files with .org.gpg extension. -@end itemize +@end defvar @node Graphing @chapter Graphing @@ -1019,9 +1036,7 @@ notes. This is done by performing SQL queries and generating images using The entry point to graph creation is @code{org-roam-graph}. -@itemize -@item -Function: org-roam-graph & optional arg file node-query +@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. @@ -1030,37 +1045,43 @@ ARG may be any of the following values: @itemize @item @code{nil} show the graph. + @item @code{C-u} show the graph for FILE@. + @item @code{C-u N} show the graph for FILE limiting nodes to N steps. + @item @code{C-u C-u} build the graph. + @item @code{C-u -} build the graph for FILE@. + @item @code{C-u -N} build the graph for FILE limiting nodes to N steps. @end itemize +@end defun -@item -User Option: org-roam-graph-executable +@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 @code{neato} in place of @code{dot}, which generates a more compact graph layout. +@end defopt -@item -User Option: org-roam-graph-viewer +@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: -@enumerate +@itemize @item A string, which is a path to the program used + @item a function accepting a single argument: the graph file path. -@end enumerate +@end itemize @code{nil} uses @code{view-file} to view the graph. @@ -1072,7 +1093,7 @@ If you are using WSL2 and would like to open the graph in Windows, you can use t (let ((org-roam-graph-viewer "/mnt/c/Program Files/Mozilla Firefox/firefox.exe")) (org-roam-graph--open (concat "file://///wsl$/Ubuntu" file))))) @end lisp -@end itemize +@end defopt @menu * Graph Options:: @@ -1084,40 +1105,36 @@ If you are using WSL2 and would like to open the graph in Windows, you can use t 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. -@itemize -@item -User Option: org-roam-graph-extra-config +@defopt org-roam-graph-extra-config Extra options passed to graphviz for the digraph (The ``G'' attributes). Example: @code{'~(("rankdir" . "LR"))} +@end defopt -@item -User Option: org-roam-graph-node-extra-config +@defopt org-roam-graph-node-extra-config Extra options for nodes in the graphviz output (The ``N'' attributes). Example: @code{'(("color" . "skyblue"))} +@end defopt -@item -User Option: org-roam-graph-edge-extra-config +@defopt org-roam-graph-edge-extra-config Extra options for edges in the graphviz output (The ``E'' attributes). Example: @code{'(("dir" . "back"))} +@end defopt -@item -User Option: org-roam-graph-edge-cites-extra-config +@defopt org-roam-graph-edge-cites-extra-config Extra options for citation edges in the graphviz output. Example: @code{'(("color" . "red"))} -@end itemize +@end defopt @node Excluding Nodes and Edges @section Excluding Nodes and Edges One may want to exclude certain files to declutter the graph. -@itemize -@item -User Option: org-roam-graph-exclude-matcher +@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. @@ -1126,7 +1143,7 @@ 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 itemize +@end defopt @example (setq org-roam-graph-exclude-matcher '("private" "dailies")) @@ -1229,29 +1246,29 @@ See @uref{https://www.chromium.org/administrators/linux-quick-start, here} for m 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: -@enumerate +@itemize @item Install and launch Platypus (with @uref{https://brew.sh/, Homebrew}): -@end enumerate +@end itemize @example brew cask install platypus @end example -@enumerate +@itemize @item Create a script @code{launch_emacs.sh}: -@end enumerate +@end itemize @example #!/usr/bin/env bash /usr/local/bin/emacsclient --no-wait $1 @end example -@enumerate +@itemize @item Create a Platypus app with the following settings: -@end enumerate +@end itemize @example | Setting | Value | @@ -1371,17 +1388,15 @@ Org-roam provides journaling capabilities akin to For @code{org-roam-dailies} to work, you need to define two variables: -@itemize -@item -Variable: @code{org-roam-dailies-directory} +@defvar @code{org-roam-dailies-directory} Path to daily-notes. +@end defvar -@item -Variable: @code{org-roam-dailies-capture-templates} +@defvar @code{org-roam-dailies-capture-templates} Capture templates for daily-notes in Org-roam. -@end itemize +@end defvar Here is a sane default configuration: @@ -1429,41 +1444,35 @@ template @code{j} will put its notes under the heading ‘Journal’. When you @node Capturing and finding daily-notes @section Capturing and finding daily-notes -@itemize -@item -Function: @code{org-roam-dailies-capture-today} &optional goto +@defun @code{org-roam-dailies-capture-today} &optional goto Create an entry in the daily note for today. When @code{goto} is non-nil, go the note without creating an entry. +@end defun -@item -Function: @code{org-roam-dailies-find-today} +@defun @code{org-roam-dailies-find-today} Find the daily note for today, creating it if necessary. -@end itemize +@end defun There are variants of those commands for @code{-yesterday} and @code{-tomorrow}: -@itemize -@item -Function: @code{org-roam-dailies-capture-yesterday} n &optional goto +@defun @code{org-roam-dailies-capture-yesterday} n &optional goto Create an entry in the daily note for yesteday. With numeric argument @code{n}, use the daily note @code{n} days in the past. +@end defun -@item -Function: @code{org-roam-dailies-find-yesterday} +@defun @code{org-roam-dailies-find-yesterday} With numeric argument N, use the daily-note N days in the future. -@end itemize +@end defun There are also commands which allow you to use Emacs’s @code{calendar} to find the date -@itemize -@item -Function: @code{org-roam-dailies-capture-date} +@defun @code{org-roam-dailies-capture-date} Create an entry in the daily note for a date using the calendar. @@ -1471,36 +1480,34 @@ Prefer past dates, unless @code{prefer-future} is non-nil. With a 'C-u' prefix or when @code{goto} is non-nil, go the note without creating an entry. +@end defun -@item -Function: @code{org-roam-dailies-find-date} +@defun @code{org-roam-dailies-find-date} Find the daily note for a date using the calendar, creating it if necessary. Prefer past dates, unless @code{prefer-future} is non-nil. -@end itemize +@end defun @node Navigation @section Navigation You can navigate between daily-notes: -@itemize -@item -Function: @code{org-roam-dailies-find-directory} +@defun @code{org-roam-dailies-find-directory} Find and open @code{org-roam-dailies-directory}. +@end defun -@item -Function: @code{org-roam-dailies-find-previous-note} +@defun @code{org-roam-dailies-find-previous-note} When in an daily-note, find the previous one. +@end defun -@item -Function: @code{org-roam-dailies-find-next-note} +@defun @code{org-roam-dailies-find-next-note} When in an daily-note, find the next one. -@end itemize +@end defun @node Diagnosing and Repairing Files @chapter Diagnosing and Repairing Files @@ -1510,13 +1517,11 @@ Org-roam provides a utility for diagnosing and repairing problematic files via Org-roam file. To run the check only for the current file, run @code{C-u M-x org-roam-doctor}, but note that this may take some time. -@itemize -@item -Function: org-roam-doctor &optional this-buffer +@defun org-roam-doctor &optional this-buffer Perform a check on Org-roam files to ensure cleanliness. If THIS-BUFFER, run the check only for the current buffer. -@end itemize +@end defun The checks run are defined in @code{org-roam-doctor--checkers}. Each checker is an instance of @code{org-roam-doctor-checker}. To define a checker, use @@ -1597,36 +1602,43 @@ operations. To reduce the number of garbage collection processes, one may set @node Note-taking Workflows @section Note-taking Workflows -@table @asis -@item Books @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 + 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 + Threads@itemize @item @uref{https://news.ycombinator.com/item?id=22473209, Ask HN: How to Take Good Notes} @end itemize -@item Videos -@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 table +@end itemize @node Ecosystem @section Ecosystem @@ -1855,12 +1867,13 @@ This situation arises when, for example, one would like to create a note titled The solution is dependent on the mini-buffer completion framework in use. Here are the solutions: -@table @asis -@item Ivy -call @code{ivy-immediate-done}, typically bound to @code{C-M-j}. Alternatively, set @code{ivy-use-selectable-prompt} to @code{t}, so that ``bar'' is now selectable. -@item Helm -Org-roam should provide a selectable ``[?] bar'' candidate at the top of the candidate list. -@end table +@itemize + @item + Ivycall @code{ivy-immediate-done}, typically bound to @code{C-M-j}. Alternatively, set @code{ivy-use-selectable-prompt} to @code{t}, so that ``bar'' is now selectable. -Emacs 27.1.50 (Org mode 9.4) -@bye \ No newline at end of file +@item + HelmOrg-roam should provide a selectable ``[?] bar'' candidate at the top of the candidate list. +@end itemize + +Emacs 28.0.50 (Org mode 9.4) +@bye