mirror of
https://github.com/org-roam/org-roam
synced 2025-08-01 12:17:21 -05:00
(docs): use gh actions to deploy documentation (#616)
This commit is contained in:
Jethro Kuan
GitHub
30
.github/workflows/docs.yml
vendored
Normal file
30
.github/workflows/docs.yml
vendored
Normal 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
1
.github/workflows/test.yml
vendored
@ -29,7 +29,6 @@ on:
|
||||
push:
|
||||
branches:
|
||||
- master
|
||||
- develop
|
||||
|
||||
jobs:
|
||||
build:
|
||||
|
||||
3
Makefile
3
Makefile
@ -58,6 +58,9 @@ init:
|
||||
docs:
|
||||
@$(MAKE) -C doc all
|
||||
|
||||
html:
|
||||
@$(MAKE) -C doc html
|
||||
|
||||
install: install-docs
|
||||
|
||||
install-docs: docs
|
||||
|
||||
@ -26,10 +26,9 @@ dir: org-roam.info
|
||||
@printf "Generating $@\n"
|
||||
@$(MAKEINFO) --html --no-split $(MANUAL_HTML_ARGS) $<
|
||||
|
||||
html-dir: $(TEXIFILES)
|
||||
html-dir:
|
||||
@printf "Generating org-roam/*.html\n"
|
||||
@$(MAKEINFO) --html $(MANUAL_HTML_ARGS) org-roam.texi
|
||||
done
|
||||
@$(MAKEINFO) --html org-roam.texi
|
||||
|
||||
%.pdf: %.texi
|
||||
@printf "Generating $@\n"
|
||||
|
||||
@ -8,16 +8,13 @@
|
||||
#+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)
|
||||
#+SUBTITLE: for version 1.1.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).
|
||||
|
||||
This manual is for Org-roam version 1.1.1.
|
||||
|
||||
#+BEGIN_QUOTE
|
||||
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
|
||||
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
|
||||
:PROPERTIES:
|
||||
:COPYING: t
|
||||
@ -931,9 +906,8 @@ 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)))
|
||||
# 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
|
||||
# org-src-preserve-indentation: nil
|
||||
# End:
|
||||
|
||||
@ -31,7 +31,7 @@ General Public License for more details.
|
||||
@finalout
|
||||
@titlepage
|
||||
@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
|
||||
@page
|
||||
@vskip 0pt plus 1filll
|
||||
@ -45,7 +45,8 @@ General Public License for more details.
|
||||
@top Org-roam User Manual
|
||||
|
||||
@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
|
||||
Copyright (C) 2020-2020 Jethro Kuan <jethrokuan95@@gmail.com>
|
||||
@ -75,10 +76,7 @@ General Public License for more details.
|
||||
* Graphing::
|
||||
* Org-roam Completion System::
|
||||
* Roam Protocol::
|
||||
* Keystroke Index::
|
||||
* Command Index::
|
||||
* Function Index::
|
||||
* Variable Index::
|
||||
* Diagnosing and Repairing Files::
|
||||
* Appendix::
|
||||
* FAQ::
|
||||
|
||||
@ -162,22 +160,18 @@ 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
|
||||
@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
|
||||
|
||||
@node 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
|
||||
@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
|
||||
@item
|
||||
@ -324,7 +318,7 @@ to effective use of Org-roam.
|
||||
@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
|
||||
``World War 2'', ``WWII''). You may specify such aliases using the
|
||||
@samp{#+ROAM_ALIAS} attribute:
|
||||
|
||||
@example
|
||||
@ -370,13 +364,10 @@ 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
|
||||
@ -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
|
||||
@samp{org-capture}.
|
||||
|
||||
Org-roam's templates can be customized by modifying the variable
|
||||
@samp{org-roam-capture-templates}.
|
||||
|
||||
@menu
|
||||
* Template Walkthrough::
|
||||
* Org-roam Template Expansion::
|
||||
@ -406,40 +400,33 @@ the default template, reproduced below.
|
||||
:unnarrowed t)
|
||||
@end lisp
|
||||
|
||||
@itemize
|
||||
@enumerate
|
||||
@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--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
|
||||
@end enumerate
|
||||
|
||||
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.
|
||||
|
||||
@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
|
||||
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
|
||||
database is saved here.
|
||||
|
||||
It is the user’s responsibility to set this correctly, especially when used
|
||||
with multiple Org-roam instances.
|
||||
@end defvar
|
||||
@end itemize
|
||||
|
||||
@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
|
||||
@itemize
|
||||
@item
|
||||
User Option: org-roam-buffer
|
||||
|
||||
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},
|
||||
@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
|
||||
@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
|
||||
@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}.
|
||||
@end defopt
|
||||
@end itemize
|
||||
|
||||
@node 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
|
||||
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
|
||||
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
|
||||
@end itemize
|
||||
|
||||
@node 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
|
||||
@samp{org-roam-index-file}.
|
||||
|
||||
@defvar org-roam-index-file
|
||||
@itemize
|
||||
@item
|
||||
Variable: 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.
|
||||
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
|
||||
@item
|
||||
Function: org-roam-find-index
|
||||
|
||||
Opens the Index file in the current @samp{org-roam-directory}.
|
||||
@end defun
|
||||
@end itemize
|
||||
|
||||
@node 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
|
||||
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.
|
||||
@end defvar
|
||||
@end itemize
|
||||
|
||||
@node 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}.
|
||||
|
||||
@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@.
|
||||
If FILE is nil, default to current buffer’s file name.
|
||||
@ -638,46 +637,40 @@ 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
|
||||
@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.
|
||||
|
||||
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
|
||||
@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:
|
||||
|
||||
@itemize
|
||||
@enumerate
|
||||
@item
|
||||
A string, which is a path to the program used
|
||||
|
||||
@item
|
||||
a function accepting a single argument: the graph file path.
|
||||
@end itemize
|
||||
@end enumerate
|
||||
|
||||
@samp{nil} uses @samp{view-file} to view the graph.
|
||||
@end defopt
|
||||
@end itemize
|
||||
|
||||
@menu
|
||||
* 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.
|
||||
|
||||
@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"))}
|
||||
@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"))}
|
||||
@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"))}
|
||||
@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.
|
||||
Example: @samp{'(("color" . "red"))}
|
||||
@end defopt
|
||||
@end itemize
|
||||
|
||||
@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
|
||||
@itemize
|
||||
@item
|
||||
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.
|
||||
@ -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
|
||||
are excluded.
|
||||
@end defopt
|
||||
@end itemize
|
||||
|
||||
@example
|
||||
(setq org-roam-graph-exclude-matcher '("private" "dailies"))
|
||||
@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
|
||||
@chapter Org-roam Completion System
|
||||
@ -799,7 +796,7 @@ running in your shell:
|
||||
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
|
||||
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:
|
||||
|
||||
@ -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
|
||||
setting up with Platypus and Chrome:
|
||||
|
||||
@itemize
|
||||
@enumerate
|
||||
@item
|
||||
Install and launch Platypus (with @uref{https://brew.sh/, Homebrew}):
|
||||
@end itemize
|
||||
@end enumerate
|
||||
|
||||
@example
|
||||
brew cask install platypus
|
||||
@end example
|
||||
|
||||
@itemize
|
||||
@enumerate
|
||||
@item
|
||||
Create a script @samp{launch_emacs.sh}:
|
||||
@end itemize
|
||||
@end enumerate
|
||||
|
||||
@example
|
||||
#!/usr/bin/env bash
|
||||
/usr/local/bin/emacsclient --no-wait $1
|
||||
@end example
|
||||
|
||||
@itemize
|
||||
@enumerate
|
||||
@item
|
||||
Create a Platypus app with the following settings:
|
||||
@end itemize
|
||||
@end enumerate
|
||||
|
||||
@example
|
||||
| Setting | Value |
|
||||
@ -868,7 +865,7 @@ Inside @samp{Settings}:
|
||||
| Protocol | "org-protocol" |
|
||||
@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
|
||||
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
|
||||
should contain a @samp{#+ROAM_KEY: $@{ref@}} in it.
|
||||
|
||||
@node Keystroke Index
|
||||
@appendix Keystroke Index
|
||||
@node Diagnosing and Repairing Files
|
||||
@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
|
||||
@appendix Command Index
|
||||
@itemize
|
||||
@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
|
||||
@appendix 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:
|
||||
|
||||
@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
|
||||
@appendix Variable Index
|
||||
|
||||
@printindex vr
|
||||
The @samp{:name} property is the name of the function run. The function takes in the
|
||||
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
|
||||
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
|
||||
@chapter Appendix
|
||||
@ -957,43 +970,36 @@ should contain a @samp{#+ROAM_KEY: $@{ref@}} in it.
|
||||
@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 itemize
|
||||
@end table
|
||||
|
||||
@node 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
|
||||
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
|
||||
|
||||
Reference in New Issue
Block a user