Skip to content

Commit 3615259

Browse files
jethrokuanjethrokuan
authored
(feat)export: init (#2138)
1 parent a69968f commit 3615259

4 files changed

Lines changed: 366 additions & 255 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22
## TBD
33
### Breaking
44
### Added
5+
- [#2138](https://github.com/org-roam/org-roam/pull/2138) export: add new module
6+
57
### Removed
68
### Fixed
79
- [#2130](https://github.com/org-roam/org-roam/pull/2130) buffer: unlinked-references section now also searches within symlinked directories

‎doc/org-roam.org‎

Lines changed: 111 additions & 99 deletions
Original file line numberDiff line numberDiff line change
@@ -134,7 +134,7 @@ A slip-box requires a method for quickly capturing ideas. These are called
134134
*fleeting notes*: they are simple reminders of information or ideas that will
135135
need to be processed later on, or trashed. This is typically accomplished using
136136
~org-capture~ (see info:org#Capture), or using Org-roam's daily notes
137-
functionality (see [[*Org-roam Dailies][Org-roam Dailies]]). This provides a central inbox for collecting
137+
functionality (see [[*org-roam-dailies][org-roam-dailies]]). This provides a central inbox for collecting
138138
thoughts, to be processed later into permanent notes.
139139

140140
*Permanent notes*
@@ -765,7 +765,7 @@ With the above example, if another node links to https://www.google.com/, it
765765
will show up as a “reference backlink”.
766766

767767
These keys also come in useful for when taking website notes, using the
768-
~roam-ref~ protocol (see [[*Org-roam Protocol][Roam Protocol]]).
768+
~roam-ref~ protocol (see [[*org-roam-protocol][org-roam-protocol]]).
769769

770770
You may assign multiple refs to a single node, for example when you want
771771
multiple papers in a series to share the same note, or an article has a citation
@@ -896,13 +896,95 @@ Note that the Org-roam database stores metadata information in plain-text
896896
(headline text, for example), so if this information is private to you then you
897897
should also ensure the database is encrypted.
898898

899-
* Org-roam Protocol
899+
* The Templating System
900+
901+
Org-roam extends the ~org-capture~ system, providing a smoother note-taking
902+
experience. However, these extensions mean Org-roam capture templates are
903+
incompatible with ~org-capture~ templates.
904+
905+
Org-roam's templates are specified by ~org-roam-capture-templates~. Just like
906+
~org-capture-templates~, ~org-roam-capture-templates~ can contain multiple
907+
templates. If ~org-roam-capture-templates~ only contains one template, there
908+
will be no prompt for template selection.
909+
910+
** Template Walkthrough
911+
912+
To demonstrate the additions made to org-capture templates. Here, we explain
913+
the default template, reproduced below. You will find most of the elements
914+
of the template are similar to ~org-capture~ templates.
915+
916+
#+BEGIN_SRC emacs-lisp
917+
(("d" "default" plain "%?"
918+
:target (file+head "%<%Y%m%d%H%M%S>-${slug}.org"
919+
"#+title: ${title}\n")
920+
:unnarrowed t))
921+
#+END_SRC
922+
923+
1. The template has short key ~"d"~. If you have only one template, org-roam
924+
automatically chooses this template for you.
925+
2. The template is given a description of ~"default"~.
926+
3. ~plain~ text is inserted. Other options include Org headings via
927+
~entry~.
928+
4. Notice that the ~target~ that's usually in Org-capture templates is missing
929+
here.
930+
5. ~"%?"~ is the template inserted on each call to ~org-roam-capture-~.
931+
This template means don't insert any content, but place the cursor here.
932+
6. ~:target~ is a compulsory specification in the Org-roam capture template. The
933+
first element of the list indicates the type of the target, the second
934+
element indicates the location of the captured node, and the rest of the
935+
elements indicate prefilled template that will be inserted and the position
936+
of the point will be adjusted for. The latter behavior varies from type to
937+
type of the capture target.
938+
7. ~:unnarrowed t~ tells org-capture to show the contents for the whole file,
939+
rather than narrowing to just the entry. This is part of the Org-capture
940+
templates.
941+
942+
See the ~org-roam-capture-templates~ documentation for more details and
943+
customization options.
944+
945+
** Org-roam Template Expansion
946+
947+
Org-roam's template definitions also extend org-capture's template syntax, to
948+
allow prefilling of strings. We have seen a glimpse of this in [[*Template Walkthrough][Template
949+
Walkthrough]].
950+
951+
Org-roam provides the ~${foo}~ syntax for substituting variables with known
952+
strings. ~${foo}~'s substitution is performed as follows:
953+
954+
1. If ~foo~ is a function, ~foo~ is called with the current node as its
955+
argument.
956+
2. Else if ~org-roam-node-foo~ is a function, ~foo~ is called with the current node
957+
as its argument. The ~org-roam-node-~ prefix defines many of Org-roam's node
958+
accessors such as ~org-roam-node-title~ and ~org-roam-node-level~.
959+
3. Else look up ~org-roam-capture--info~ for ~foo~. This is an internal variable
960+
that is set before the capture process begins.
961+
4. If none of the above applies, read a string using ~completing-read~.
962+
a. Org-roam also provides the ~${foo=default_val}~ syntax, where if a default
963+
value is provided, will be the initial value for the ~foo~ key during
964+
minibuffer completion.
965+
966+
One can check the list of available keys for nodes by inspecting the
967+
~org-roam-node~ struct. At the time of writing, it is:
968+
969+
#+begin_src emacs-lisp
970+
(cl-defstruct (org-roam-node (:constructor org-roam-node-create)
971+
(:copier nil))
972+
"A heading or top level file with an assigned ID property."
973+
file file-hash file-atime file-mtime
974+
id level point todo priority scheduled deadline title properties olp
975+
tags aliases refs)
976+
#+end_src
977+
978+
This makes ~${file}~, ~${file-hash}~ etc. all valid substitutions.
979+
980+
* Extensions
981+
** org-roam-protocol
900982

901983
Org-roam provides extensions for capturing content from external applications
902984
such as the browser, via ~org-protocol~. Org-roam extends ~org-protocol~ with 2
903985
protocols: the ~roam-node~ and ~roam-ref~ protocols.
904986

905-
** Installation
987+
*** Installation
906988

907989
To enable Org-roam's protocol extensions, simply add the following to your init
908990
file:
@@ -923,7 +1005,7 @@ registered. Hence, to use ~org-protocol~, once must:
9231005

9241006
The instructions for the latter for each operating system is detailed below.
9251007

926-
*** Linux
1008+
**** Linux
9271009
For Linux users, create a desktop application in
9281010
~~/.local/share/applications/org-protocol.desktop~:
9291011

@@ -964,7 +1046,7 @@ make the new policy take effect.
9641046
See [[https://www.chromium.org/administrators/linux-quick-start][here]] for more info on the ~/etc/opt/chrome/policies/managed~ directory and
9651047
[[https://cloud.google.com/docs/chrome-enterprise/policies/?policy=ExternalProtocolDialogShowAlwaysOpenCheckbox][here]] for information on the ~ExternalProtocolDialogShowAlwaysOpenCheckbox~ policy.
9661048

967-
*** Mac OS
1049+
**** Mac OS
9681050
For Mac OS, we need to create our own application.
9691051

9701052
1. Launch Script Editor
@@ -1019,7 +1101,7 @@ defaults write com.apple.LaunchServices/com.apple.launchservices.secure LSHandle
10191101

10201102
Then restart your computer.
10211103

1022-
**** Testing org-protocol
1104+
***** Testing org-protocol
10231105

10241106
To test that you have the handler setup and registered properly from the command
10251107
line you can run:
@@ -1042,7 +1124,7 @@ You may need to manually register your handler, like this:
10421124
#+end_src
10431125

10441126
Here is a link to the lsregister command that is really useful: https://eclecticlight.co/2019/03/25/lsregister-a-valuable-undocumented-command-for-launchservices/
1045-
*** Windows
1127+
**** Windows
10461128
For Windows, create a temporary ~org-protocol.reg~ file:
10471129

10481130
#+BEGIN_SRC text
@@ -1067,13 +1149,13 @@ Windows, replace the last line with:
10671149
After executing the .reg file, the protocol is registered and you can delete the
10681150
file.
10691151

1070-
** The roam-node protocol
1152+
*** The roam-node protocol
10711153

10721154
The roam-node protocol opens the node with ID specified by the ~node~ key (e.g.
10731155
~org-protocol://roam-node?node=node-id~). ~org-roam-graph~ uses this to make the
10741156
graph navigable.
10751157

1076-
** The roam-ref protocol
1158+
*** The roam-ref protocol
10771159

10781160
This protocol finds or creates a new note with a given ~ROAM_REFS~:
10791161

@@ -1101,93 +1183,11 @@ or as a keybinding in ~qutebrowser~ in , using the ~config.py~ file (see
11011183
where ~template~ is the template key for a template in
11021184
~org-roam-capture-ref-templates~ (see [[*The Templating System][The Templating System]]).
11031185

1104-
* The Templating System
1105-
1106-
Org-roam extends the ~org-capture~ system, providing a smoother note-taking
1107-
experience. However, these extensions mean Org-roam capture templates are
1108-
incompatible with ~org-capture~ templates.
1109-
1110-
Org-roam's templates are specified by ~org-roam-capture-templates~. Just like
1111-
~org-capture-templates~, ~org-roam-capture-templates~ can contain multiple
1112-
templates. If ~org-roam-capture-templates~ only contains one template, there
1113-
will be no prompt for template selection.
1114-
1115-
** Template Walkthrough
1116-
1117-
To demonstrate the additions made to org-capture templates. Here, we explain
1118-
the default template, reproduced below. You will find most of the elements
1119-
of the template are similar to ~org-capture~ templates.
1120-
1121-
#+BEGIN_SRC emacs-lisp
1122-
(("d" "default" plain "%?"
1123-
:target (file+head "%<%Y%m%d%H%M%S>-${slug}.org"
1124-
"#+title: ${title}\n")
1125-
:unnarrowed t))
1126-
#+END_SRC
1127-
1128-
1. The template has short key ~"d"~. If you have only one template, org-roam
1129-
automatically chooses this template for you.
1130-
2. The template is given a description of ~"default"~.
1131-
3. ~plain~ text is inserted. Other options include Org headings via
1132-
~entry~.
1133-
4. Notice that the ~target~ that's usually in Org-capture templates is missing
1134-
here.
1135-
5. ~"%?"~ is the template inserted on each call to ~org-roam-capture-~.
1136-
This template means don't insert any content, but place the cursor here.
1137-
6. ~:target~ is a compulsory specification in the Org-roam capture template. The
1138-
first element of the list indicates the type of the target, the second
1139-
element indicates the location of the captured node, and the rest of the
1140-
elements indicate prefilled template that will be inserted and the position
1141-
of the point will be adjusted for. The latter behavior varies from type to
1142-
type of the capture target.
1143-
7. ~:unnarrowed t~ tells org-capture to show the contents for the whole file,
1144-
rather than narrowing to just the entry. This is part of the Org-capture
1145-
templates.
1146-
1147-
See the ~org-roam-capture-templates~ documentation for more details and
1148-
customization options.
1149-
1150-
** Org-roam Template Expansion
1151-
1152-
Org-roam's template definitions also extend org-capture's template syntax, to
1153-
allow prefilling of strings. We have seen a glimpse of this in [[*Template Walkthrough][Template
1154-
Walkthrough]].
1155-
1156-
Org-roam provides the ~${foo}~ syntax for substituting variables with known
1157-
strings. ~${foo}~'s substitution is performed as follows:
1158-
1159-
1. If ~foo~ is a function, ~foo~ is called with the current node as its
1160-
argument.
1161-
2. Else if ~org-roam-node-foo~ is a function, ~foo~ is called with the current node
1162-
as its argument. The ~org-roam-node-~ prefix defines many of Org-roam's node
1163-
accessors such as ~org-roam-node-title~ and ~org-roam-node-level~.
1164-
3. Else look up ~org-roam-capture--info~ for ~foo~. This is an internal variable
1165-
that is set before the capture process begins.
1166-
4. If none of the above applies, read a string using ~completing-read~.
1167-
a. Org-roam also provides the ~${foo=default_val}~ syntax, where if a default
1168-
value is provided, will be the initial value for the ~foo~ key during
1169-
minibuffer completion.
1170-
1171-
One can check the list of available keys for nodes by inspecting the
1172-
~org-roam-node~ struct. At the time of writing, it is:
1173-
1174-
#+begin_src emacs-lisp
1175-
(cl-defstruct (org-roam-node (:constructor org-roam-node-create)
1176-
(:copier nil))
1177-
"A heading or top level file with an assigned ID property."
1178-
file file-hash file-atime file-mtime
1179-
id level point todo priority scheduled deadline title properties olp
1180-
tags aliases refs)
1181-
#+end_src
1182-
1183-
This makes ~${file}~, ~${file-hash}~ etc. all valid substitutions.
1184-
1185-
* Graphing
1186+
** org-roam-graph
11861187

11871188
Org-roam provides basic graphing capabilities to explore interconnections
11881189
between notes, in ~org-roam-graph~. This is done by performing SQL queries and
1189-
generating images using [[https://graphviz.org/][Graphviz]]. The graph can also be navigated: see [[*Org-roam Protocol][Roam
1190-
Protocol]].
1190+
generating images using [[https://graphviz.org/][Graphviz]]. The graph can also be navigated: see [[*org-roam-protocol][org-roam-protocol]].
11911191

11921192
The entry point to graph creation is ~org-roam-graph~.
11931193

@@ -1228,7 +1228,7 @@ ARG may be any of the following values:
12281228
(org-roam-graph--open (concat "file://///wsl$/Ubuntu" file)))))
12291229
#+END_SRC
12301230

1231-
** Graph Options
1231+
*** Graph Options
12321232

12331233
Graphviz provides many options for customizing the graph output, and Org-roam
12341234
supports some of them. See https://graphviz.gitlab.io/_pages/doc/info/attrs.html
@@ -1254,12 +1254,12 @@ for customizable options.
12541254
Extra options for edges in the graphviz output (The "E" attributes).
12551255
Example: ~'(("dir" . "back"))~
12561256

1257-
* Org-roam Dailies
1257+
** org-roam-dailies
12581258

12591259
Org-roam provides journaling capabilities akin to
12601260
Org-journal with ~org-roam-dailies~.
12611261

1262-
** Configuration
1262+
*** Configuration
12631263

12641264
For ~org-roam-dailies~ to work, you need to define two variables:
12651265

@@ -1285,7 +1285,7 @@ Here is a sane default configuration:
12851285

12861286
See [[*The Templating System][The Templating System]] for creating new templates.
12871287

1288-
** Usage
1288+
*** Usage
12891289

12901290
~org-roam-dailies~ provides these interactive functions:
12911291

@@ -1339,6 +1339,18 @@ There are also commands which allow you to use Emacs’s ~calendar~ to find the
13391339
- Function: ~org-roam-dailies-goto-next-note~
13401340

13411341
When in an daily-note, find the next one.
1342+
** org-roam-export
1343+
1344+
Because Org-roam files are plain org files, they can be exported easily using
1345+
~org-export~ to a variety of formats, including ~html~ and ~pdf~. However,
1346+
Org-roam relies heavily on ID links, which Org's html export has poor support
1347+
of. To fix this, Org-roam provides a bunch of overrides to better support
1348+
export. To use them, simply run:
1349+
1350+
#+begin_src emacs-lisp
1351+
(require 'org-roam-export)
1352+
#+end_src
1353+
13421354
* Performance Optimization
13431355
** Garbage Collection
13441356

@@ -1412,7 +1424,7 @@ The Deft interface can slow down quickly when the number of files get huge.
14121424

14131425
[[https://github.com/bastibe/org-journal][Org-journal]] provides journaling capabilities to Org-mode. A lot of its
14141426
functionalities have been incorporated into Org-roam under the name
1415-
[[*Org-roam Dailies][~org-roam-dailies~]]. It remains a good tool if you want to isolate your verbose
1427+
[[*org-roam-dailies][~org-roam-dailies~]]. It remains a good tool if you want to isolate your verbose
14161428
journal entries from the ideas you would write on a scratchpad.
14171429

14181430
#+BEGIN_SRC emacs-lisp

0 commit comments

Comments
 (0)