awesome-emacs/org-roam
1
0
Fork 0
mirror of https://github.com/org-roam/org-roam synced 2025-08-01 12:17:21 -05:00
Code Issues Packages Projects Releases Wiki Activity

(docs): use gh actions to deploy documentation (#616)

Browse Source
This commit is contained in:
Jethro Kuan
2020-05-13 18:45:32 +08:00
committed by GitHub
parent 46975107a2
commit e62bda799a
6 changed files with 170 additions and 159 deletions
Download Patch File Download Diff File Expand all files Collapse all files

30
.github/workflows/docs.yml vendored Normal file
View File

@ -0,0 +1,30 @@
# * docs.yml --- Build the documentation and publish to Github Pages
name: "Docs"
on:
push:
branches:
- master
jobs:
build:
runs-on: ubuntu-latest
strategy:
fail-fast: true
steps:
- uses: actions/checkout@v2
- name: Install deps
run: |
sudo apt-get install makeinfo
- name: Build docs
continue-on-error: false
run: make html
- name: Deploy 🚀
uses: JamesIves/github-pages-deploy-action@releases/v3
with:
ACCESS_TOKEN: ${{ secrets.ACCESS_TOKEN }}
BRANCH: gh-pages # The branch the action should deploy to.
FOLDER: doc # The folder the action should deploy.

1
.github/workflows/test.yml vendored
View File

@ -29,7 +29,6 @@ on:
push: push:
branches: branches:
- master - master
- develop
jobs: jobs:
build: build:

3
Makefile
View File

@ -58,6 +58,9 @@ init:
docs: docs:
@$(MAKE) -C doc all @$(MAKE) -C doc all
html:
@$(MAKE) -C doc html
install: install-docs install: install-docs
install-docs: docs install-docs: docs

5
doc/Makefile
View File

@ -26,10 +26,9 @@ dir: org-roam.info
@printf "Generating $@\n" @printf "Generating $@\n"
@$(MAKEINFO) --html --no-split $(MANUAL_HTML_ARGS) $< @$(MAKEINFO) --html --no-split $(MANUAL_HTML_ARGS) $<
html-dir: $(TEXIFILES) html-dir:
@printf "Generating org-roam/*.html\n" @printf "Generating org-roam/*.html\n"
@$(MAKEINFO) --html $(MANUAL_HTML_ARGS) org-roam.texi @$(MAKEINFO) --html org-roam.texi
done
%.pdf: %.texi %.pdf: %.texi
@printf "Generating $@\n" @printf "Generating $@\n"

36
doc/org-roam.org
View File

@ -8,16 +8,13 @@
#+TEXINFO_DIR_CATEGORY: Emacs #+TEXINFO_DIR_CATEGORY: Emacs
#+TEXINFO_DIR_TITLE: Org-roam: (org-roam). #+TEXINFO_DIR_TITLE: Org-roam: (org-roam).
#+TEXINFO_DIR_DESC: Rudimentary Roam Replica for Emacs. #+TEXINFO_DIR_DESC: Rudimentary Roam Replica for Emacs.
#+SUBTITLE: for version 1.1.0 (v1.1.0-29-g00fc215+1) #+SUBTITLE: for version 1.1.1
#+TEXINFO_DEFFN: t
#+OPTIONS: H:4 num:3 toc:2 creator:t #+OPTIONS: H:4 num:3 toc:2 creator:t
#+PROPERTY: header-args :eval never #+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 #+TEXINFO: @noindent
This manual is for Org-roam version 1.1.0 (v1.1.0-29-g00fc215+1).
This manual is for Org-roam version 1.1.1.
#+BEGIN_QUOTE #+BEGIN_QUOTE
Copyright (C) 2020-2020 Jethro Kuan <jethrokuan95@gmail.com> Copyright (C) 2020-2020 Jethro Kuan <jethrokuan95@gmail.com>
@ -695,28 +692,6 @@ checker, to perform autofixes for the errors. For each error detected,
window displaying the error message, as well as the list of actions that can be window displaying the error message, as well as the list of actions that can be
taken provided in =:actions=. taken provided in =:actions=.
* 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 * _ Copying
:PROPERTIES: :PROPERTIES:
:COPYING: t :COPYING: t
@ -931,9 +906,8 @@ file within that directory, at least once.
* _ :ignore: * _ :ignore:
# Local Variables: # Local Variables:
# eval: (require 'org-man nil t) # before-save-hook: org-make-toc
# eval: (require 'ox-texinfo+ nil t) # after-save-hook: (lambda nil (progn (require 'ox-texinfo nil t) (org-texinfo-export-to-info)))
# eval: (and (require 'ox-extra nil t) (ox-extras-activate '(ignore-headlines)))
# indent-tabs-mode: nil # indent-tabs-mode: nil
# org-src-preserve-indentation: nil # org-src-preserve-indentation: nil
# End: # End:

254
doc/org-roam.texi
View File

@ -31,7 +31,7 @@ General Public License for more details.
@finalout @finalout
@titlepage @titlepage
@title Org-roam User Manual @title Org-roam User Manual
@subtitle for version 1.1.0 (v1.1.0-29-g00fc215+1) @subtitle for version 1.1.1
@author Jethro Kuan @author Jethro Kuan
@page @page
@vskip 0pt plus 1filll @vskip 0pt plus 1filll
@ -45,7 +45,8 @@ General Public License for more details.
@top Org-roam User Manual @top Org-roam User Manual
@noindent @noindent
This manual is for Org-roam version 1.1.0 (v1.1.0-29-g00fc215+1).
This manual is for Org-roam version 1.1.1.
@quotation @quotation
Copyright (C) 2020-2020 Jethro Kuan <jethrokuan95@@gmail.com> Copyright (C) 2020-2020 Jethro Kuan <jethrokuan95@@gmail.com>
@ -75,10 +76,7 @@ General Public License for more details.
* Graphing:: * Graphing::
* Org-roam Completion System:: * Org-roam Completion System::
* Roam Protocol:: * Roam Protocol::
* Keystroke Index:: * Diagnosing and Repairing Files::
* Command Index::
* Function Index::
* Variable Index::
* Appendix:: * Appendix::
* FAQ:: * FAQ::
@ -162,22 +160,18 @@ to further introduce features enabled by the Emacs ecosystem.
Org-roam provides several benefits over other tooling: Org-roam provides several benefits over other tooling:
@itemize @table @asis
@item @item Privacy and Security
Privacy and SecurityEdit your personal wiki completely offline, entirely in your control. Encrypt your notes with GPG@. Edit your personal wiki completely offline, entirely in your control. Encrypt your notes with GPG@.
@item Longevity of Plain Text
@item 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
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 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 @item Leverages the Org-mode ecosystem
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@. 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
@item 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.
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. @end table
@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 @node Installation
@chapter Installation @chapter Installation
@ -193,7 +187,7 @@ Org-roam can be installed using Emacs' package manager or manually from its deve
@node Installing from MELPA @node Installing from MELPA
@section 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}: 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 @samp{package-archives}:
@itemize @itemize
@item @item
@ -324,7 +318,7 @@ to effective use of Org-roam.
@section File Aliases @section File Aliases
Suppose you want a note to be referred to by different names (e.g. 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 ``World War 2'', ``WWII''). You may specify such aliases using the
@samp{#+ROAM_ALIAS} attribute: @samp{#+ROAM_ALIAS} attribute:
@example @example
@ -370,13 +364,10 @@ may be desirable to prefill the file with templated content. This may include:
@itemize @itemize
@item @item
Time of creation Time of creation
@item @item
File it was created from File it was created from
@item @item
Clipboard content Clipboard content
@item @item
Any other data you may want to input manually Any other data you may want to input manually
@end itemize @end itemize
@ -387,6 +378,9 @@ Org-roam abuses @samp{org-capture}, extending its syntax. To first understand ho
org-roam's templating system works, it may be useful to look into basic usage of org-roam's templating system works, it may be useful to look into basic usage of
@samp{org-capture}. @samp{org-capture}.
Org-roam's templates can be customized by modifying the variable
@samp{org-roam-capture-templates}.
@menu @menu
* Template Walkthrough:: * Template Walkthrough::
* Org-roam Template Expansion:: * Org-roam Template Expansion::
@ -406,40 +400,33 @@ the default template, reproduced below.
:unnarrowed t) :unnarrowed t)
@end lisp @end lisp
@itemize @enumerate
@item @item
The template has short key @samp{"d"}. If you have only one template, The template has short key @samp{"d"}. If you have only one template,
org-roam automatically chooses this template for you. org-roam automatically chooses this template for you.
@item @item
The template is given a description of @samp{"default"}. The template is given a description of @samp{"default"}.
@item @item
@samp{plain} text is inserted. Other options include Org headings via @samp{plain} text is inserted. Other options include Org headings via
@samp{entry}. @samp{entry}.
@item @item
@samp{(function org-roam--capture-get-point)} should not be changed. @samp{(function org-roam--capture-get-point)} should not be changed.
@item @item
@samp{"%?"} is the template inserted on each call to @samp{org-roam-capture--capture}. @samp{"%?"} is the template inserted on each call to @samp{org-roam-capture--capture}.
This template means don't insert any content, but place the cursor This template means don't insert any content, but place the cursor
here. here.
@item @item
@samp{:file-name} is the file-name template for a new note, if it doesn't @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 yet exist. This creates a file at path that looks like
@samp{/path/to/org-roam-directory/20200213032037-foo.org}. @samp{/path/to/org-roam-directory/20200213032037-foo.org}.
@item @item
@samp{:head} contains the initial template to be inserted (once only), at @samp{:head} contains the initial template to be inserted (once only), at
the beginning of the file. Here, the title global attribute is the beginning of the file. Here, the title global attribute is
inserted. inserted.
@item @item
@samp{:unnarrowed t} tells org-capture to show the contents for the whole @samp{:unnarrowed t} tells org-capture to show the contents for the whole
file, rather than narrowing to just the entry. file, rather than narrowing to just the entry.
@end itemize @end enumerate
Other options you may want to learn about include @samp{:immediate-finish}. Other options you may want to learn about include @samp{:immediate-finish}.
@ -502,53 +489,57 @@ All of Org-roam's customization options can be viewed via
This section concerns the placement and creation of files. This section concerns the placement and creation of files.
@defvar org-roam-directory @itemize
@item
Variable: org-roam-directory
This is the default path to Org-roam files. All Org files, at any level of This is the default path to Org-roam files. All Org files, at any level of
nesting, are considered part of the Org-roam. nesting, are considered part of the Org-roam.
@end defvar
@defvar org-roam-db-location @item
Variable: org-roam-db-location
Location of the Org-roam database. If this is non-nil, the Org-roam sqlite Location of the Org-roam database. If this is non-nil, the Org-roam sqlite
database is saved here. database is saved here.
It is the user’s responsibility to set this correctly, especially when used It is the user’s responsibility to set this correctly, especially when used
with multiple Org-roam instances. with multiple Org-roam instances.
@end defvar @end itemize
@node The Org-roam Buffer @node The Org-roam Buffer
@section The Org-roam Buffer @section The Org-roam Buffer
The Org-roam buffer displays backlinks for the currently active Org-roam note. The Org-roam buffer displays backlinks for the currently active Org-roam note.
@defopt org-roam-buffer @itemize
@item
User Option: org-roam-buffer
The name of the org-roam buffer. Defaults to @samp{*org-roam*}. The name of the org-roam buffer. Defaults to @samp{*org-roam*}.
@end defopt
@defopt org-roam-buffer-position @item
User Option: org-roam-buffer-position
The position of the Org-roam buffer side window. Valid values are @samp{'left}, The position of the Org-roam buffer side window. Valid values are @samp{'left},
@samp{'right}, @samp{'top}, @samp{'bottom}. @samp{'right}, @samp{'top}, @samp{'bottom}.
@end defopt
@defopt org-roam-buffer-width @item
User Option: org-roam-buffer-width
Width of @samp{org-roam-buffer}. Has an effect only if @samp{org-roam-buffer-position} is Width of @samp{org-roam-buffer}. Has an effect only if @samp{org-roam-buffer-position} is
@samp{'left} or @samp{'right}. @samp{'left} or @samp{'right}.
@end defopt
@defopt org-roam-buffer-height @item
User Option: org-roam-buffer-height
Height of @samp{org-roam-buffer}. Has an effect only if @samp{org-roam-buffer-position} is Height of @samp{org-roam-buffer}. Has an effect only if @samp{org-roam-buffer-position} is
@samp{'top} or @samp{'bottom}. @samp{'top} or @samp{'bottom}.
@end defopt
@defopt org-roam-buffer-no-delete-window @item
User Option: 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}. 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 @end itemize
@node Org-roam Links @node Org-roam Links
@section Org-roam Links @section Org-roam Links
@ -556,14 +547,16 @@ The @samp{no-delete-window} parameter for the org-roam buffer. Setting it to @sa
Org-roam links are regular @samp{file:} links in Org-mode. By default, links are 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}. inserted with the title as the link description with @samp{org-roam-insert}.
@defopt org-roam-link-title-format @itemize
@item
User Option: org-roam-link-title-format
To distinguish between org-roam links and regular links, one may choose to use To distinguish between org-roam links and regular links, one may choose to use
special indicators for Org-roam links. Defaults to @samp{"%s"}. 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, 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. by customizing the @samp{org-roam-link}, and @samp{org-roam-link-current} faces.
@end defopt @end itemize
@node Org-roam Files @node Org-roam Files
@section Org-roam Files @section Org-roam Files
@ -587,7 +580,9 @@ to your main files.
In Org-roam, you can define the path to your index file by setting In Org-roam, you can define the path to your index file by setting
@samp{org-roam-index-file}. @samp{org-roam-index-file}.
@defvar org-roam-index-file @itemize
@item
Variable: org-roam-index-file
Path to the Org-roam index file. Path to the Org-roam index file.
@ -596,12 +591,12 @@ path (absolute or relative to @samp{org-roam-directory}) to the index file. If i
is is a function, the function should return the path 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 @samp{org-roam-index} whose Otherwise, the index is assumed to be a note in @samp{org-roam-index} whose
title is @samp{"Index"}. title is @samp{"Index"}.
@end defvar
@defun org-roam-find-index @item
Function: org-roam-find-index
Opens the Index file in the current @samp{org-roam-directory}. Opens the Index file in the current @samp{org-roam-directory}.
@end defun @end itemize
@node Encryption @node Encryption
@chapter Encryption @chapter Encryption
@ -615,10 +610,12 @@ Note that Emacs will prompt for a password for encrypted files during
cache updates if it requires reading the encrypted file. To reduce the cache updates if it requires reading the encrypted file. To reduce the
number of password prompts, you may wish to cache the password. number of password prompts, you may wish to cache the password.
@defvar org-roam-encrypt-files @itemize
@item
Variable: org-roam-encrypt-files
Whether to encrypt new files. If true, create files with .org.gpg extension. Whether to encrypt new files. If true, create files with .org.gpg extension.
@end defvar @end itemize
@node Graphing @node Graphing
@chapter Graphing @chapter Graphing
@ -629,7 +626,9 @@ notes. This is done by performing SQL queries and generating images using
The entry point to graph creation is @samp{org-roam-graph}. The entry point to graph creation is @samp{org-roam-graph}.
@defun org-roam-graph & optional arg file node-query @itemize
@item
Function: org-roam-graph & optional arg file node-query
Build and possibly display a graph for FILE from NODE-QUERY@. Build and possibly display a graph for FILE from NODE-QUERY@.
If FILE is nil, default to current buffer’s file name. If FILE is nil, default to current buffer’s file name.
@ -638,46 +637,40 @@ ARG may be any of the following values:
@itemize @itemize
@item @item
@samp{nil} show the graph. @samp{nil} show the graph.
@item @item
@samp{C-u} show the graph for FILE@. @samp{C-u} show the graph for FILE@.
@item @item
@samp{C-u N} show the graph for FILE limiting nodes to N steps. @samp{C-u N} show the graph for FILE limiting nodes to N steps.
@item @item
@samp{C-u C-u} build the graph. @samp{C-u C-u} build the graph.
@item @item
@samp{C-u -} build the graph for FILE@. @samp{C-u -} build the graph for FILE@.
@item @item
@samp{C-u -N} build the graph for FILE limiting nodes to N steps. @samp{C-u -N} build the graph for FILE limiting nodes to N steps.
@end itemize @end itemize
@end defun
@defopt org-roam-graph-executable @item
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. 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 You may also choose to use @samp{neato} in place of @samp{dot}, which generates a more
compact graph layout. compact graph layout.
@end defopt
@defopt org-roam-graph-viewer @item
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: Org-roam defaults to using Firefox (located on PATH) to view the SVG, but you may choose to set it to:
@itemize @enumerate
@item @item
A string, which is a path to the program used A string, which is a path to the program used
@item @item
a function accepting a single argument: the graph file path. a function accepting a single argument: the graph file path.
@end itemize @end enumerate
@samp{nil} uses @samp{view-file} to view the graph. @samp{nil} uses @samp{view-file} to view the graph.
@end defopt @end itemize
@menu @menu
* Graph Options:: * Graph Options::
@ -689,36 +682,40 @@ a function accepting a single argument: the graph file path.
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. 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 @itemize
@item
User Option: org-roam-graph-extra-config
Extra options passed to graphviz for the digraph (The "G" attributes). Extra options passed to graphviz for the digraph (The ``G'' attributes).
Example: @samp{'=(("rankdir" . "LR"))} Example: @samp{'=(("rankdir" . "LR"))}
@end defopt
@defopt org-roam-graph-node-extra-config @item
User Option: org-roam-graph-node-extra-config
Extra options for nodes in the graphviz output (The "N" attributes). Extra options for nodes in the graphviz output (The ``N'' attributes).
Example: @samp{'(("color" . "skyblue"))} Example: @samp{'(("color" . "skyblue"))}
@end defopt
@defopt org-roam-graph-edge-extra-config @item
User Option: org-roam-graph-edge-extra-config
Extra options for edges in the graphviz output (The "E" attributes). Extra options for edges in the graphviz output (The ``E'' attributes).
Example: @samp{'(("dir" . "back"))} Example: @samp{'(("dir" . "back"))}
@end defopt
@defopt org-roam-graph-edge-cites-extra-config @item
User Option: org-roam-graph-edge-cites-extra-config
Extra options for citation edges in the graphviz output. Extra options for citation edges in the graphviz output.
Example: @samp{'(("color" . "red"))} Example: @samp{'(("color" . "red"))}
@end defopt @end itemize
@node Excluding Nodes and Edges @node Excluding Nodes and Edges
@section Excluding Nodes and Edges @section Excluding Nodes and Edges
One may want to exclude certain files to declutter the graph. One may want to exclude certain files to declutter the graph.
@defopt org-roam-graph-exclude-matcher @itemize
@item
User Option: org-roam-graph-exclude-matcher
Matcher for excluding nodes from the generated graph. Any nodes and links for Matcher for excluding nodes from the generated graph. Any nodes and links for
file paths matching this string is excluded from the graph. file paths matching this string is excluded from the graph.
@ -727,13 +724,13 @@ If value is a string, the string is the only matcher.
If value is a list, all file paths matching any of the strings If value is a list, all file paths matching any of the strings
are excluded. are excluded.
@end defopt @end itemize
@example @example
(setq org-roam-graph-exclude-matcher '("private" "dailies")) (setq org-roam-graph-exclude-matcher '("private" "dailies"))
@end example @end example
This setting excludes all files whose path contain "private" or "dailies". This setting excludes all files whose path contain ``private'' or ``dailies''.
@node Org-roam Completion System @node Org-roam Completion System
@chapter Org-roam Completion System @chapter Org-roam Completion System
@ -799,7 +796,7 @@ running in your shell:
xdg-mime default org-protocol.desktop x-scheme-handler/org-protocol xdg-mime default org-protocol.desktop x-scheme-handler/org-protocol
@end example @end example
To disable the "confirm" prompt in Chrome, you can also make Chrome 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 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: without confirmation. To do this, run in a shell:
@ -822,29 +819,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 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: setting up with Platypus and Chrome:
@itemize @enumerate
@item @item
Install and launch Platypus (with @uref{https://brew.sh/, Homebrew}): Install and launch Platypus (with @uref{https://brew.sh/, Homebrew}):
@end itemize @end enumerate
@example @example
brew cask install platypus brew cask install platypus
@end example @end example
@itemize @enumerate
@item @item
Create a script @samp{launch_emacs.sh}: Create a script @samp{launch_emacs.sh}:
@end itemize @end enumerate
@example @example
#!/usr/bin/env bash #!/usr/bin/env bash
/usr/local/bin/emacsclient --no-wait $1 /usr/local/bin/emacsclient --no-wait $1
@end example @end example
@itemize @enumerate
@item @item
Create a Platypus app with the following settings: Create a Platypus app with the following settings:
@end itemize @end enumerate
@example @example
| Setting | Value | | Setting | Value |
@ -868,7 +865,7 @@ Inside @samp{Settings}:
| Protocol | "org-protocol" | | Protocol | "org-protocol" |
@end example @end example
To disable the "confirm" prompt in Chrome, you can also make Chrome 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 show a checkbox to tick, so that the @samp{OrgProtocol} app will be used
without confirmation. To do this, run in a shell: without confirmation. To do this, run in a shell:
@ -926,25 +923,41 @@ where @samp{template} is the template key for a template in
@samp{org-roam-capture-ref-templates} (see @ref{The Templating System}). These templates @samp{org-roam-capture-ref-templates} (see @ref{The Templating System}). These templates
should contain a @samp{#+ROAM_KEY: $@{ref@}} in it. should contain a @samp{#+ROAM_KEY: $@{ref@}} in it.
@node Keystroke Index @node Diagnosing and Repairing Files
@appendix Keystroke Index @chapter Diagnosing and Repairing Files
@printindex ky Org-roam provides a utility for diagnosing and repairing problematic files via
@samp{org-roam-doctor}. By default, @samp{org-roam-doctor} runs the check across all Org-roam
files, and this can take some time. To run the check only for the current file,
run @samp{C-u M-x org-roam-doctor}.
@node Command Index @itemize
@appendix Command Index @item
Function: org-roam-doctor &optional this-buffer
@printindex cp Perform a check on Org-roam files to ensure cleanliness. If THIS-BUFFER, run
the check only for the current buffer.
@end itemize
@node Function Index The checks run are defined in @samp{org-roam-doctor--checkers}. Each checker is an instance of @samp{org-roam-doctor-checker}. To define a checker, use @samp{make-org-roam-doctor-checker}. Here is a sample definition:
@appendix Function Index
@printindex fn @lisp
(make-org-roam-doctor-checker
:name 'org-roam-doctor-broken-links
:description "Fix broken links."
:actions '(("d" . ("Unlink" . org-roam-doctor--remove-link))
("r" . ("Replace link" . org-roam-doctor--replace-link))
("R" . ("Replace link (keep label)" . org-roam-doctor--replace-link-keep-label))))
@end lisp
@node Variable Index The @samp{:name} property is the name of the function run. The function takes in the
@appendix Variable Index Org parse tree, and returns a list of @samp{(point error-message)}. @samp{:description} is a
short description of what the checker does. @samp{:actions} is an alist containing
@printindex vr elements of the form @samp{(char . (prompt . function))}. These actions are defined per
checker, to perform autofixes for the errors. For each error detected,
@samp{org-roam-doctor} will move the point to the current error, and pop-up a help
window displaying the error message, as well as the list of actions that can be
taken provided in @samp{:actions}.
@node Appendix @node Appendix
@chapter Appendix @chapter Appendix
@ -957,43 +970,36 @@ should contain a @samp{#+ROAM_KEY: $@{ref@}} in it.
@node Note-taking Workflows @node Note-taking Workflows
@section Note-taking Workflows @section Note-taking Workflows
@table @asis
@item Books
@itemize @itemize
@item
Books@itemize
@item @item
@uref{https://www.goodreads.com/book/show/34507927-how-to-take-smart-notes, How To Take Smart Notes} @uref{https://www.goodreads.com/book/show/34507927-how-to-take-smart-notes, How To Take Smart Notes}
@end itemize @end itemize
@item Articles
@item @itemize
Articles@itemize
@item @item
@uref{https://www.lesswrong.com/posts/NfdHG6oHBJ8Qxc26s/the-zettelkasten-method-1, The Zettelkasten Method - LessWrong 2.0} @uref{https://www.lesswrong.com/posts/NfdHG6oHBJ8Qxc26s/the-zettelkasten-method-1, The Zettelkasten Method - LessWrong 2.0}
@item @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} @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 @item
@uref{https://www.nateliason.com/blog/roam, Roam Research: Why I Love It and How I Use It - Nat Eliason} @uref{https://www.nateliason.com/blog/roam, Roam Research: Why I Love It and How I Use It - Nat Eliason}
@item @item
@uref{https://twitter.com/adam_keesling/status/1196864424725774336?s=20, Adam Keesling's Twitter Thread} @uref{https://twitter.com/adam_keesling/status/1196864424725774336?s=20, Adam Keesling's Twitter Thread}
@item @item
@uref{https://blog.jethro.dev/posts/how_to_take_smart_notes_org/, How To Take Smart Notes With Org-mode · Jethro Kuan} @uref{https://blog.jethro.dev/posts/how_to_take_smart_notes_org/, How To Take Smart Notes With Org-mode · Jethro Kuan}
@end itemize @end itemize
@item Threads
@item @itemize
Threads@itemize
@item @item
@uref{https://news.ycombinator.com/item?id=22473209, Ask HN: How to Take Good Notes} @uref{https://news.ycombinator.com/item?id=22473209, Ask HN: How to Take Good Notes}
@end itemize @end itemize
@item Videos
@item @itemize
Videos@itemize
@item @item
@uref{https://www.youtube.com/watch?v=RvWic15iXjk, How to Use Roam to Outline a New Article in Under 20 Minutes} @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
@end itemize @end table
@node Ecosystem @node Ecosystem
@section Ecosystem @section Ecosystem
@ -1185,5 +1191,5 @@ 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 set of Org-roam files. Remember to run @samp{org-roam-db-build-cache} from a
file within that directory, at least once. file within that directory, at least once.
Emacs 28.0.50 (Org mode 9.3.6) Emacs 28.0.50 (Org mode 9.4)
@bye @bye