org-roam.info (97661B)
1 This is org-roam.info, produced by makeinfo version 6.7 from 2 org-roam.texi. 3 4 Copyright (C) 2020-2022 Jethro Kuan <jethrokuan95@gmail.com> 5 6 You can redistribute this document and/or modify it under the terms 7 of the GNU General Public License as published by the Free Software 8 Foundation, either version 3 of the License, or (at your option) 9 any later version. 10 11 This document is distributed in the hope that it will be useful, 12 but WITHOUT ANY WARRANTY; without even the implied warranty of 13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14 General Public License for more details. 15 16 INFO-DIR-SECTION Emacs 17 START-INFO-DIR-ENTRY 18 * Org-roam: (org-roam). Roam Research for Emacs. 19 END-INFO-DIR-ENTRY 20 21 22 File: org-roam.info, Node: Top, Next: Introduction, Up: (dir) 23 24 Org-roam User Manual 25 ******************** 26 27 28 This manual is for Org-roam version 2.2.2. 29 30 Copyright (C) 2020-2022 Jethro Kuan <jethrokuan95@gmail.com> 31 32 You can redistribute this document and/or modify it under the terms 33 of the GNU General Public License as published by the Free Software 34 Foundation, either version 3 of the License, or (at your option) 35 any later version. 36 37 This document is distributed in the hope that it will be useful, 38 but WITHOUT ANY WARRANTY; without even the implied warranty of 39 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 40 General Public License for more details. 41 42 * Menu: 43 44 * Introduction:: 45 * Target Audience:: 46 * A Brief Introduction to the Zettelkasten Method:: 47 * Installation:: 48 * Getting Started:: 49 * Customizing Node Caching:: 50 * The Org-roam Buffer:: 51 * Node Properties:: 52 * Citations:: 53 * Completion:: 54 * Encryption:: 55 * The Templating System:: 56 * Extensions:: 57 * Performance Optimization:: 58 * The Org-mode Ecosystem:: 59 * FAQ:: 60 * Developer's Guide to Org-roam:: 61 * Appendix:: 62 * Keystroke Index:: 63 * Command Index:: 64 * Function Index:: 65 * Variable Index:: 66 67 — The Detailed Node Listing — 68 69 Installation 70 71 * Installing from MELPA:: 72 * Installing from Source:: 73 * Installation Troubleshooting:: 74 75 Installation Troubleshooting 76 77 * C Compiler:: 78 79 C Compiler 80 81 * C Compiler for Windows:: 82 83 Getting Started 84 85 * The Org-roam Node:: 86 * Links between Nodes:: 87 * Setting up Org-roam:: 88 * Creating and Linking Nodes:: 89 * Customizing Node Completions:: 90 91 Customizing Node Caching 92 93 * How to cache:: 94 * What to cache:: 95 * When to cache:: 96 97 The Org-roam Buffer 98 99 * Navigating the Org-roam Buffer:: 100 * Configuring what is displayed in the buffer:: 101 * Configuring the Org-roam buffer display:: 102 * Styling the Org-roam buffer:: 103 104 Node Properties 105 106 * Standard Org properties:: 107 * Titles and Aliases:: 108 * Tags:: 109 * Refs:: 110 111 Citations 112 113 * Using the Cached Information:: 114 115 Completion 116 117 * Completing within Link Brackets:: 118 * Completing anywhere:: 119 120 The Templating System 121 122 * Template Walkthrough:: 123 * Org-roam Template Expansion:: 124 125 Extensions 126 127 * org-roam-protocol:: 128 * org-roam-graph:: 129 * org-roam-dailies:: 130 * org-roam-export:: 131 132 org-roam-protocol 133 134 * Installation: Installation (1). 135 * The roam-node protocol:: 136 * The roam-ref protocol:: 137 138 Installation 139 140 * Linux:: 141 * Mac OS:: 142 * Windows:: 143 144 org-roam-graph 145 146 * Graph Options:: 147 148 org-roam-dailies 149 150 * Configuration:: 151 * Usage:: 152 153 Performance Optimization 154 155 * Garbage Collection:: 156 157 The Org-mode Ecosystem 158 159 * Browsing History with winner-mode:: 160 * Versioning Notes:: 161 * Full-text search with Deft:: 162 * Org-journal:: 163 * Org-download:: 164 * mathpix.el: mathpixel. 165 * Org-noter / Interleave:: 166 * Bibliography:: 167 * Spaced Repetition:: 168 169 FAQ 170 171 * How do I have more than one Org-roam directory?:: 172 * How do I create a note whose title already matches one of the candidates?:: 173 * How can I stop Org-roam from creating IDs everywhere?:: 174 * How do I migrate from Roam Research?:: 175 * How to migrate from Org-roam v1?:: 176 * How do I publish my notes with an Internet-friendly graph?:: 177 * I’m seeing this “Selecting deleted buffer” error. What do I do?: I'm seeing this ``Selecting deleted buffer'' error What do I do?. 178 179 How do I publish my notes with an Internet-friendly graph? 180 181 * Configure org-mode for publishing:: 182 * Overriding the default link creation function:: 183 * Copying the generated file to the export directory:: 184 185 Developer’s Guide to Org-roam 186 187 * Org-roam's Design Principle:: 188 * Building Extensions and Advanced Customization of Org-roam:: 189 190 Building Extensions and Advanced Customization of Org-roam 191 192 * Accessing the Database:: 193 * Accessing and Modifying Nodes:: 194 * Extending the Capture System:: 195 196 Appendix 197 198 * Note-taking Workflows:: 199 * Ecosystem:: 200 201 202 203 File: org-roam.info, Node: Introduction, Next: Target Audience, Prev: Top, Up: Top 204 205 1 Introduction 206 ************** 207 208 Org-roam is a tool for networked thought. It reproduces some of Roam 209 Research’s (https://roamresearch.com/) (1) key features within Org-mode 210 (https://orgmode.org/). 211 212 Org-roam allows for effortless non-hierarchical note-taking: with 213 Org-roam, notes flow naturally, making note-taking fun and easy. 214 Org-roam augments the Org-mode syntax, and will work for anyone already 215 using Org-mode for their personal wiki. 216 217 Org-roam leverages the mature ecosystem around Org-mode. For 218 example, it has first-class support for org-ref 219 (https://github.com/jkitchin/org-ref) for citation management, and is 220 able to piggyback off Org’s excellent LaTeX and source-block evaluation 221 capabilities. 222 223 Org-roam provides these benefits over other tooling: 224 225 • *Privacy and Security:* Your personal wiki belongs only to you, 226 entirely offline and in your control. Encrypt your notes with GPG. 227 228 • *Longevity of Plain Text:* Unlike web solutions like Roam Research, 229 the notes are first and foremost plain Org-mode files – Org-roam 230 simply builds an auxiliary database to give the personal wiki 231 superpowers. Having your notes in plain-text is crucial for the 232 longevity of your wiki. Never have to worry about proprietary web 233 solutions being taken down. The notes are still functional even if 234 Org-roam ceases to exist. 235 236 • *Free and Open Source:* Org-roam is free and open-source, which 237 means that if you feel unhappy with any part of Org-roam, you may 238 choose to extend Org-roam, or open a pull request. 239 240 • *Leverage the Org-mode ecosystem:* Over the decades, Emacs and 241 Org-mode has developed into a mature system for plain-text 242 organization. Building upon Org-mode already puts Org-roam 243 light-years ahead of many other solutions. 244 245 • *Built on Emacs:* Emacs is also a fantastic interface for editing 246 text, and Org-roam inherits many of the powerful text-navigation 247 and editing packages available to Emacs. 248 249 ---------- Footnotes ---------- 250 251 (1) To understand more about Roam, a collection of links are 252 available in *note Note-taking Workflows::. 253 254 255 File: org-roam.info, Node: Target Audience, Next: A Brief Introduction to the Zettelkasten Method, Prev: Introduction, Up: Top 256 257 2 Target Audience 258 ***************** 259 260 Org-roam is a tool that will appear unfriendly to anyone unfamiliar with 261 Emacs and Org-mode, but it is also extremely powerful to those willing 262 to put effort in mastering the intricacies. Org-roam stands on the 263 shoulders of giants. Emacs was first created in 1976, and remains the 264 tool of choice for many for editing text and designing textual 265 interfaces. The malleability of Emacs allowed the creation of Org-mode, 266 an all-purpose plain-text system for maintaining TODO lists, planning 267 projects, and authoring documents. Both of these tools are incredibly 268 vast and require significant time investment to master. 269 270 Org-roam assumes only basic familiarity with these tools. It is not 271 difficult to get up and running with basic text-editing functionality, 272 but one will only fully appreciate the power of building Roam 273 functionality into Emacs and Org-mode when the usage of these tools 274 become more advanced. 275 276 One key advantage to Org-roam is that building on top of Emacs gives 277 it malleability. This is especially important for note-taking 278 workflows. It is our belief that note-taking workflows are extremely 279 personal, and there is no one tool that’s perfect for you. Org-mode and 280 Org-roam allows you to discover what works for you, and build that 281 perfect tool for yourself. 282 283 If you are new to the software, and choose to take this leap of 284 faith, I hope you find yourself equally entranced as Neal Stephenson 285 was. 286 287 Emacs outshines all other editing software in approximately the 288 same way that the noonday sun does the stars. It is not just 289 bigger and brighter; it simply makes everything else vanish. – 290 Neal Stephenson, In the Beginning was the Command Line (1998) 291 292 293 File: org-roam.info, Node: A Brief Introduction to the Zettelkasten Method, Next: Installation, Prev: Target Audience, Up: Top 294 295 3 A Brief Introduction to the Zettelkasten Method 296 ************************************************* 297 298 Org-roam provides utilities for maintaining a digital slip-box. This 299 section aims to provide a brief introduction to the “slip-box”, or 300 “Zettelkasten” method. By providing some background on the method, we 301 hope that the design decisions of Org-roam will become clear, and that 302 will aid in using Org-roam appropriately. In this section we will 303 introduce terms commonly used within the Zettelkasten community and the 304 Org-roam forums. 305 306 The Zettelkasten is a personal tool for thinking and writing. It 307 places heavy emphasis on connecting ideas, building up a web of thought. 308 Hence, it is well suited for knowledge workers and intellectual tasks, 309 such as conducting research. The Zettelkasten can act as a research 310 partner, where conversations with it may produce new and surprising 311 lines of thought. 312 313 This method is attributed to German sociologist Niklas Luhmann, who 314 using the method had produced volumes of written works. Luhmann’s 315 slip-box was simply a box of cards. These cards are small – often only 316 large enough to fit a single concept. The size limitation encourages 317 ideas to be broken down into individual concepts. These ideas are 318 explicitly linked together. The breakdown of ideas encourages 319 tangential exploration of ideas, increasing the surface for thought. 320 Making linking explicit between notes also encourages one to think about 321 the connections between concepts. 322 323 At the corner of each note, Luhmann ascribed each note with an 324 ordered ID, allowing him to link and jump between notes. In Org-roam, 325 we simply use hyperlinks. 326 327 Org-roam is the slip-box, digitalized in Org-mode. Every zettel 328 (card) is a plain-text, Org-mode file. In the same way one would 329 maintain a paper slip-box, Org-roam makes it easy to create new zettels, 330 pre-filling boilerplate content using a powerful templating system. 331 332 *Fleeting notes* 333 334 A slip-box requires a method for quickly capturing ideas. These are 335 called *fleeting notes*: they are simple reminders of information or 336 ideas that will need to be processed later on, or trashed. This is 337 typically accomplished using ‘org-capture’ (see *note (org)Capture::), 338 or using Org-roam’s daily notes functionality (see *note 339 org-roam-dailies::). This provides a central inbox for collecting 340 thoughts, to be processed later into permanent notes. 341 342 *Permanent notes* 343 344 Permanent notes are further split into two categories: *literature 345 notes* and *concept notes*. Literature notes can be brief annotations 346 on a particular source (e.g. book, website or paper), that you’d like 347 to access later on. Concept notes require much more care in authoring: 348 they need to be self-explanatory and detailed. Org-roam’s templating 349 system supports the addition of different templates to facilitate the 350 creation of these notes. 351 352 For further reading on the Zettelkasten method, “How to Take Smart 353 Notes” by Sonke Ahrens is a decent guide. 354 355 356 File: org-roam.info, Node: Installation, Next: Getting Started, Prev: A Brief Introduction to the Zettelkasten Method, Up: Top 357 358 4 Installation 359 ************** 360 361 Org-roam can be installed using Emacs’ package manager or manually from 362 its development repository. 363 364 * Menu: 365 366 * Installing from MELPA:: 367 * Installing from Source:: 368 * Installation Troubleshooting:: 369 370 371 File: org-roam.info, Node: Installing from MELPA, Next: Installing from Source, Up: Installation 372 373 4.1 Installing from MELPA 374 ========================= 375 376 Org-roam is available from Melpa and Melpa-Stable. If you haven’t used 377 Emacs’ package manager before, you may familiarize yourself with it by 378 reading the documentation in the Emacs manual, see *note 379 (emacs)Packages::. Then, add one of the archives to ‘package-archives’: 380 381 • To use Melpa: 382 383 (require 'package) 384 (add-to-list 'package-archives 385 '("melpa" . "http://melpa.org/packages/") t) 386 387 • To use Melpa-Stable: 388 389 (require 'package) 390 (add-to-list 'package-archives 391 '("melpa-stable" . "http://stable.melpa.org/packages/") t) 392 393 Org-roam also depends on a recent version of Org, which can be 394 obtained in Org’s package repository (see *note (org)Installation::). 395 396 Once you have done that, you can install Org-roam and its 397 dependencies using: 398 399 M-x package-install RET org-roam RET 400 401 402 File: org-roam.info, Node: Installing from Source, Next: Installation Troubleshooting, Prev: Installing from MELPA, Up: Installation 403 404 4.2 Installing from Source 405 ========================== 406 407 You may install Org-roam directly from the repository on GitHub 408 (https://github.com/org-roam/org-roam) if you like. This will give you 409 access to the latest version hours or days before it appears on MELPA, 410 and months (or more) before it is added to the Debian or Ubuntu 411 repositories. This will also give you access to various developmental 412 branches that may be available. 413 414 Note, however, that development version, and especially any feature 415 branches, may not always be in working order. You’ll need to be 416 prepared to do some debugging, or to manually roll-back to working 417 versions, if you install from GitHub. 418 419 Installing from GitHub requires that you clone the repository: 420 421 git clone https://github.com/org-roam/org-roam.git /path/to/org/roam 422 423 where ‘./path/to/org/roam’ is the location you will store your copy 424 of the code. 425 426 Next, you need to add this location to your load path, and ‘require’ 427 the Org-roam library. Add the following code to your ‘.emacs’: 428 429 (add-to-list 'load-path "/path/to/org/roam") 430 (require 'org-roam) 431 432 You now have Org-roam installed. However, you don’t necessarily have 433 the dependencies that it requires. These include: 434 435 • dash 436 437 • f 438 439 • s 440 441 • org 442 443 • emacsql 444 445 • emacsql-sqlite 446 447 • magit-section 448 449 You can install this manually as well, or get the latest version from 450 MELPA. You may wish to use use-package 451 (https://github.com/jwiegley/use-package), straight.el 452 (https://github.com/raxod502/straight.el) to help manage this. 453 454 If you would like to install the manual for access from Emacs’ 455 built-in Info system, you’ll need to compile the .texi source file, and 456 install it in an appropriate location. 457 458 To compile the .texi source file, from a terminal navigate to the 459 ‘/doc’ subdirectory of the Org-roam repository, and run the following: 460 461 make infodir=/path/to/my/info/files install-info 462 463 Where ‘/path/to/my/info/files’ is the location where you keep info 464 files. This target directory needs to be stored in the variable 465 ‘Info-default-directory-list‘. If you aren’t using one of the default 466 info locations, you can configure this with the following in your 467 ‘.emacs’ file: 468 469 (require 'info) 470 (add-to-list 'Info-default-directory-list 471 "/path/to/my/info/files") 472 473 You can also use one of the default locations, such as: 474 475 • _usr/local/share/info_ 476 477 • _usr/share/info_ 478 479 • _usr/local/share/info_ 480 481 If you do this, you’ll need to make sure you have write-access to 482 that location, or run the above ‘make’ command as root. 483 484 Now that the info file is ready, you need to add it to the 485 corresponding ‘dir’ file: 486 487 install-info /path/to/my/info/files/org-roam.info /path/to/my/info/files/dir 488 489 490 File: org-roam.info, Node: Installation Troubleshooting, Prev: Installing from Source, Up: Installation 491 492 4.3 Installation Troubleshooting 493 ================================ 494 495 * Menu: 496 497 * C Compiler:: 498 499 500 File: org-roam.info, Node: C Compiler, Up: Installation Troubleshooting 501 502 4.3.1 C Compiler 503 ---------------- 504 505 Org-roam relies on an Emacs package called ‘emacsql’ and 506 ‘emacsql-sqlite’ to work with the ‘sqlite’ database. Both of them 507 should be installed automatically in your Emacs environment as a 508 prerequisite for Org-roam when you install it. 509 510 ‘emacsql-sqlite’ requires a C compiler (e.g. ‘gcc’ or ‘clang’) to be 511 present in your computer. How to install a C compiler depends on the OS 512 that you use. 513 514 * Menu: 515 516 * C Compiler for Windows:: 517 518 519 File: org-roam.info, Node: C Compiler for Windows, Up: C Compiler 520 521 C Compiler for Windows 522 ...................... 523 524 One of the easiest ways to install a C compiler in Windows is to use 525 MSYS2 (https://www.msys2.org/) as at the time of this writing: 526 527 • Download and use the installer in the official MSYS2 website 528 529 • Run MSYS2 and in its terminal, type the following and answer “Y” to 530 proceed – this will install ‘gcc’ in your PC: 531 532 pacman -S gcc 533 534 • On Windows, add ‘C:\msys64\usr\bin’ (command ‘where gcc’ in MSYS2 535 terminal can tell you the correct path) to ‘PATH’ in your 536 environmental variables 537 538 • Launch Emacs and call ‘M-x org-roam-db-autosync-mode’ (launch Emacs 539 after defining the path, so that Emacs can recognize it) 540 541 This will automatically start compiling ‘emacsql-sqlite’; you should 542 see a message in minibuffer. It may take a while until compilation 543 completes. Once complete, you should see a new file 544 ‘emacsql-sqlite.exe’ created in a subfolder named ‘sqlite’ under 545 ‘emacsql-sqlite’ installation folder. It’s typically in your Emacs 546 configuration folder like this: 547 ‘/.config/emacs/elpa/emacsql-sqlite-20190727.1710/sqlite’ 548 549 550 File: org-roam.info, Node: Getting Started, Next: Customizing Node Caching, Prev: Installation, Up: Top 551 552 5 Getting Started 553 ***************** 554 555 * Menu: 556 557 * The Org-roam Node:: 558 * Links between Nodes:: 559 * Setting up Org-roam:: 560 * Creating and Linking Nodes:: 561 * Customizing Node Completions:: 562 563 564 File: org-roam.info, Node: The Org-roam Node, Next: Links between Nodes, Up: Getting Started 565 566 5.1 The Org-roam Node 567 ===================== 568 569 We first begin with some terminology we’ll use throughout the manual. 570 We term the basic denomination in Org-roam a node. We define a node as 571 follows: 572 573 A node is any headline or top level file with an ID. 574 575 For example, with this example file content: 576 577 :PROPERTIES: 578 :ID: foo 579 :END: 580 #+title: Foo 581 582 * Bar 583 :PROPERTIES: 584 :ID: bar 585 :END: 586 587 We create two nodes: 588 589 • A file node “Foo” with id ‘foo’. 590 591 • A headline node “Bar” with id ‘bar’. 592 593 Headlines without IDs will not be considered Org-roam nodes. Org IDs 594 can be added to files or headlines via the interactive command ‘M-x 595 org-id-get-create’. 596 597 598 File: org-roam.info, Node: Links between Nodes, Next: Setting up Org-roam, Prev: The Org-roam Node, Up: Getting Started 599 600 5.2 Links between Nodes 601 ======================= 602 603 We link between nodes using Org’s standard ID link (e.g. ‘id:foo’). 604 While only ID links will be considered during the computation of links 605 between nodes, Org-roam caches all other links in the documents for 606 external use. 607 608 609 File: org-roam.info, Node: Setting up Org-roam, Next: Creating and Linking Nodes, Prev: Links between Nodes, Up: Getting Started 610 611 5.3 Setting up Org-roam 612 ======================= 613 614 Org-roam’s capabilities stem from its aggressive caching: it crawls all 615 files within ‘org-roam-directory’, and maintains a cache of all links 616 and nodes. 617 618 To start using Org-roam, pick a location to store the Org-roam files. 619 The directory that will contain your notes is specified by the variable 620 ‘org-roam-directory’. Org-roam searches recursively within 621 ‘org-roam-directory’ for notes. This variable needs to be set before 622 any calls to Org-roam functions. 623 624 For this tutorial, create an empty directory, and set 625 ‘org-roam-directory’: 626 627 (make-directory "~/org-roam") 628 (setq org-roam-directory (file-truename "~/org-roam")) 629 630 The ‘file-truename’ function is only necessary when you use symbolic 631 links inside ‘org-roam-directory’: Org-roam does not resolve symbolic 632 links. One can however instruct Emacs to always resolve symlinks, at a 633 performance cost: 634 635 (setq find-file-visit-truename t) 636 637 Next, we setup Org-roam to run functions on file changes to maintain 638 cache consistency. This is achieved by running ‘M-x 639 org-roam-db-autosync-mode’. To ensure that Org-roam is available on 640 startup, place this in your Emacs configuration: 641 642 (org-roam-db-autosync-mode) 643 644 To build the cache manually, run ‘M-x org-roam-db-sync’. Cache 645 builds may take a while the first time, but subsequent builds are often 646 instantaneous because they only reprocess modified files. 647 648 649 File: org-roam.info, Node: Creating and Linking Nodes, Next: Customizing Node Completions, Prev: Setting up Org-roam, Up: Getting Started 650 651 5.4 Creating and Linking Nodes 652 ============================== 653 654 Org-roam makes it easy to create notes and link them together. There 655 are 2 main functions for creating nodes: 656 657 • ‘org-roam-node-insert’: creates a node if it does not exist, and 658 inserts a link to the node at point. 659 660 • ‘org-roam-node-find’: creates a node if it does not exist, and 661 visits the node. 662 663 • ‘org-roam-capture’: creates a node if it does not exist, and 664 restores the current window configuration upon completion. 665 666 Let’s first try ‘org-roam-node-find’. Calling ‘M-x 667 org-roam-node-find’ will show a list of titles for nodes that reside in 668 ‘org-roam-directory’. It should show nothing right now, since there are 669 no notes in the directory. Enter the title of the note you wish to 670 create, and press ‘RET’. This begins the note creation process. This 671 process uses ‘org-capture’’s templating system, and can be customized 672 (see *note The Templating System::). Using the default template, 673 pressing ‘C-c C-c’ finishes the note capture. 674 675 Now that we have a node, we can try inserting a link to the node 676 using ‘M-x org-roam-node-insert’. This brings up the list of nodes, 677 which should contain the node you just created. Selecting the node will 678 insert an ‘id:’ link to the node. If you instead entered a title that 679 does not exist, you will once again be brought through the node creation 680 process. 681 682 One can also conveniently insert links via the completion-at-point 683 functions Org-roam provides (see *note Completion::). 684 685 686 File: org-roam.info, Node: Customizing Node Completions, Prev: Creating and Linking Nodes, Up: Getting Started 687 688 5.5 Customizing Node Completions 689 ================================ 690 691 Node selection is achieved via the ‘completing-read’ interface, 692 typically through ‘org-roam-node-read‘. The presentation of these nodes 693 are governed by ‘org-roam-node-display-template’. 694 695 -- Variable: org-roam-node-display-template 696 697 Configures display formatting for Org-roam node. 698 699 Patterns of form “${field-name:length}” are interpolated based on 700 the current node. 701 702 Each “field-name” is replaced with the return value of each 703 corresponding accessor function for org-roam-node, e.g. “${title}” 704 will be interpolated by the result of org-roam-node-title. You can 705 also define custom accessors using cl-defmethod. For example, you 706 can define: 707 708 (cl-defmethod org-roam-node-my-title ((node org-roam-node)) (concat 709 “My ” (org-roam-node-title node))) 710 711 and then reference it here or in the capture templates as 712 “${my-title}”. 713 714 “length” is an optional specifier and declares how many characters 715 can be used to display the value of the corresponding field. If 716 it’s not specified, the field will be inserted as is, i.e. it 717 won’t be aligned nor trimmed. If it’s an integer, the field will 718 be aligned accordingly and all the exceeding characters will be 719 trimmed out. If it’s “*”, the field will use as many characters as 720 possible and will be aligned accordingly. 721 722 A closure can also be assigned to this variable in which case the 723 closure is evaluated and the return value is used as the template. 724 The closure must evaluate to a valid template string. 725 726 If you’re using a vertical completion framework, such as Ivy and 727 Selectrum, Org-roam supports the generation of an aligned, tabular 728 completion interface. For example, to include a column for tags up to 729 10 character widths wide, one can set ‘org-roam-node-display-template’ 730 as such: 731 732 (setq org-roam-node-display-template 733 (concat "${title:*} " 734 (propertize "${tags:10}" 'face 'org-tag))) 735 736 737 File: org-roam.info, Node: Customizing Node Caching, Next: The Org-roam Buffer, Prev: Getting Started, Up: Top 738 739 6 Customizing Node Caching 740 ************************** 741 742 * Menu: 743 744 * How to cache:: 745 * What to cache:: 746 * When to cache:: 747 748 749 File: org-roam.info, Node: How to cache, Next: What to cache, Up: Customizing Node Caching 750 751 6.1 How to cache 752 ================ 753 754 Org-roam uses a sqlite database to perform caching, but there are 755 multiple Emacs libraries that can be used. The default used by Org-roam 756 is ‘emacs-sqlite’. Below the pros and cons of each package is used: 757 758 **emacs-sqlite** (https://github.com/skeeto/emacsql) 759 760 The default option used by Org-roam. This library is the most mature 761 and well-supported and is imported by default in Org-roam. 762 763 One downside of using ‘emacs-sqlite’ is that using it requires 764 compilation and can cause issues in some environments (especially 765 Windows). If you have issues producing the customized binary required 766 by ‘emacs-sqlite’, consider using ‘emacs-sqlite3’. 767 768 **emacs-sqlite3** (https://github.com/cireu/emacsql-sqlite3) 769 770 ‘emacs-sqlite3’ uses the official sqlite3 binary that can be obtained 771 from your system’s package manager. This is useful if you have issues 772 producing the ‘sqlite3’ binary required by the other packages. However, 773 it is not recommended because it has some compatibility issues with 774 Emacs, but should work for most regular cases. See Chris Wellon’s blog 775 post (https://nullprogram.com/blog/2014/02/06/) for more information. 776 777 To use ‘emacsql-sqlite3’, ensure that the package is installed, and 778 set: 779 780 (setq org-roam-database-connector 'sqlite3) 781 782 **emacssql-sqlite-module** 783 (https://melpa.org/#/emacsql-sqlite-module) (previously 784 emacsql-libsqlite3) 785 786 ‘emacs-sqlite-module’ is a relatively young package which uses an 787 Emacs module that exposes parts of the SQLite C API to Emacs Lisp, 788 instead of using subprocess as ‘emacsql-sqlite’ does. It is expected to 789 be a more performant drop-in replacement for ‘emacs-sqlite’. 790 791 (setq org-roam-database-connector 'sqlite-module) 792 793 **emacsql-sqlite-builtin** 794 (https://melpa.org/#/emacsql-sqlite-builtin) 795 796 ‘emacsql-sqlite-builtin’ uses the in-built SQLite support for Emacs 797 29 and later. This is the recommended option if you are using a version 798 of Emacs that supports it. 799 800 (setq org-roam-database-connector 'sqlite-builtin) 801 802 803 File: org-roam.info, Node: What to cache, Next: When to cache, Prev: How to cache, Up: Customizing Node Caching 804 805 6.2 What to cache 806 ================= 807 808 By default, all nodes (any headline or file with an ID) are cached by 809 Org-roam. There are instances where you may want to have headlines with 810 ID, but not have them cached by Org-roam. 811 812 To exclude a headline from the Org-roam database, set the 813 ‘ROAM_EXCLUDE’ property to a non-nil value. For example: 814 815 * Foo 816 :PROPERTIES: 817 :ID: foo 818 :ROAM_EXCLUDE: t 819 :END: 820 821 One can also set ‘org-roam-db-node-include-function’. For example, 822 to exclude all headlines with the ‘ATTACH’ tag from the Org-roam 823 database, one can set: 824 825 (setq org-roam-db-node-include-function 826 (lambda () 827 (not (member "ATTACH" (org-get-tags))))) 828 829 Org-roam relied on the obtained Org AST for the buffer to parse 830 links. However, links appearing in some places (e.g. within property 831 drawers) are not considered by the Org AST to be links. Therefore, 832 Org-roam takes special care of additionally trying to process these 833 links. Use ‘org-roam-db-extra-links-elements’ to specify which 834 additional Org AST element types to consider. 835 836 -- Variable: org-roam-db-extra-links-elements 837 838 The list of Org element types to include for parsing by Org-roam. 839 840 By default, when parsing Org’s AST, links within keywords and 841 property drawers are not parsed as links. Sometimes however, it is 842 desirable to parse and cache these links (e.g. hiding links in a 843 property drawer). 844 845 Additionally, one may want to ignore certain keys from being excluded 846 within property drawers. For example, we would not want ‘ROAM_REFS’ 847 links to be self-referential. Hence, to exclude specific keys, we use 848 ‘org-roam-db-extra-links-exclude-keys’. 849 850 -- Variable: org-roam-db-extra-links-exclude-keys 851 852 Keys to ignore when mapping over links. 853 854 The car of the association list is the Org element type (e.g. 855 keyword). The cdr is a list of case-insensitive strings to exclude 856 from being treated as links. 857 858 859 File: org-roam.info, Node: When to cache, Prev: What to cache, Up: Customizing Node Caching 860 861 6.3 When to cache 862 ================= 863 864 By default, Org-roam is eager in caching: each time an Org-roam file is 865 modified and saved, it updates the database for the corresponding file. 866 This keeps the database up-to-date, causing the least surprise when 867 using the interactive commands. 868 869 However, depending on how large your Org files are, database updating 870 can be a slow operation. You can disable the automatic updating of the 871 database by setting ‘org-roam-db-update-on-save’ to ‘nil’. 872 873 -- Variable: org-roam-db-update-on-save 874 875 If t, update the Org-roam database upon saving the file. Disable 876 this if your files are large and updating the database is slow. 877 878 879 File: org-roam.info, Node: The Org-roam Buffer, Next: Node Properties, Prev: Customizing Node Caching, Up: Top 880 881 7 The Org-roam Buffer 882 ********************* 883 884 Org-roam provides the Org-roam buffer: an interface to view 885 relationships with other notes (backlinks, reference links, unlinked 886 references etc.). There are two main commands to use here: 887 888 • ‘org-roam-buffer-toggle’: Launch an Org-roam buffer that tracks the 889 node currently at point. This means that the content of the buffer 890 changes as the point is moved, if necessary. 891 892 • ‘org-roam-buffer-display-dedicated’: Launch an Org-roam buffer for 893 a specific node without visiting its file. Unlike 894 ‘org-roam-buffer-toggle’ you can have multiple such buffers and 895 their content won’t be automatically replaced with a new node at 896 point. 897 898 To bring up a buffer that tracks the current node at point, call ‘M-x 899 org-roam-buffer-toggle’. 900 901 -- Function: org-roam-buffer-toggle 902 903 Toggle display of the ‘org-roam-buffer’. 904 905 To bring up a buffer that’s dedicated for a specific node, call ‘M-x 906 org-roam-buffer-display-dedicated’. 907 908 -- Function: org-roam-buffer-display-dedicated 909 910 Launch node dedicated Org-roam buffer without visiting the node 911 itself. 912 913 * Menu: 914 915 * Navigating the Org-roam Buffer:: 916 * Configuring what is displayed in the buffer:: 917 * Configuring the Org-roam buffer display:: 918 * Styling the Org-roam buffer:: 919 920 921 File: org-roam.info, Node: Navigating the Org-roam Buffer, Next: Configuring what is displayed in the buffer, Up: The Org-roam Buffer 922 923 7.1 Navigating the Org-roam Buffer 924 ================================== 925 926 The Org-roam buffer uses ‘magit-section’, making the typical 927 ‘magit-section’ keybindings available. Here are several of the more 928 useful ones: 929 930 • ‘M-{N}’: ‘magit-section-show-level-{N}-all’ 931 932 • ‘n’: ‘magit-section-forward’ 933 934 • ‘<TAB>’: ‘magit-section-toggle’ 935 936 • ‘<RET>’: ‘org-roam-buffer-visit-thing’ 937 938 ‘org-roam-buffer-visit-thing’ is a placeholder command, that is 939 replaced by section-specific commands such as ‘org-roam-node-visit’. 940 941 942 File: org-roam.info, Node: Configuring what is displayed in the buffer, Next: Configuring the Org-roam buffer display, Prev: Navigating the Org-roam Buffer, Up: The Org-roam Buffer 943 944 7.2 Configuring what is displayed in the buffer 945 =============================================== 946 947 There are currently 3 provided widget types: 948 949 • BacklinksView (preview of) nodes that link to this node 950 951 • Reference LinksNodes that reference this node (see *note Refs::) 952 953 • Unlinked referencesView nodes that contain text that match the 954 nodes title/alias but are not linked 955 956 To configure what sections are displayed in the buffer, set 957 ~org-roam-mode-sections. 958 959 (setq org-roam-mode-sections 960 (list #'org-roam-backlinks-section 961 #'org-roam-reflinks-section 962 ;; #'org-roam-unlinked-references-section 963 )) 964 965 Note that computing unlinked references may be slow, and has not been 966 added in by default. 967 968 For each section function, you can pass args along to modify its 969 behaviour. For example, if you want to render unique sources for 970 backlinks (and also keep rendering reference links), set 971 ‘org-roam-mode-sections’ as follows: 972 973 (setq org-roam-mode-sections 974 '((org-roam-backlinks-section :unique t) 975 org-roam-reflinks-section)) 976 977 978 File: org-roam.info, Node: Configuring the Org-roam buffer display, Next: Styling the Org-roam buffer, Prev: Configuring what is displayed in the buffer, Up: The Org-roam Buffer 979 980 7.3 Configuring the Org-roam buffer display 981 =========================================== 982 983 Org-roam does not control how the pop-up buffer is displayed: this is 984 left to the user. The author’s recommended configuration is as follows: 985 986 (add-to-list 'display-buffer-alist 987 '("\\*org-roam\\*" 988 (display-buffer-in-direction) 989 (direction . right) 990 (window-width . 0.33) 991 (window-height . fit-window-to-buffer))) 992 993 Crucially, the window is a regular window (not a side-window), and 994 this allows for predictable navigation: 995 996 • ‘RET’ navigates to thing-at-point in the current window, replacing 997 the Org-roam buffer. 998 999 • ‘C-u RET’ navigates to thing-at-point in the other window. 1000 1001 For users that prefer using a side-window for the org-roam buffer, 1002 the following example configuration should provide a good starting 1003 point: 1004 1005 (add-to-list 'display-buffer-alist 1006 '("\\*org-roam\\*" 1007 (display-buffer-in-side-window) 1008 (side . right) 1009 (slot . 0) 1010 (window-width . 0.33) 1011 (window-parameters . ((no-other-window . t) 1012 (no-delete-other-windows . t))))) 1013 1014 1015 File: org-roam.info, Node: Styling the Org-roam buffer, Prev: Configuring the Org-roam buffer display, Up: The Org-roam Buffer 1016 1017 7.4 *TODO* Styling the Org-roam buffer 1018 ====================================== 1019 1020 1021 File: org-roam.info, Node: Node Properties, Next: Citations, Prev: The Org-roam Buffer, Up: Top 1022 1023 8 Node Properties 1024 ***************** 1025 1026 * Menu: 1027 1028 * Standard Org properties:: 1029 * Titles and Aliases:: 1030 * Tags:: 1031 * Refs:: 1032 1033 1034 File: org-roam.info, Node: Standard Org properties, Next: Titles and Aliases, Up: Node Properties 1035 1036 8.1 Standard Org properties 1037 =========================== 1038 1039 Org-roam caches most of the standard Org properties. The full list now 1040 includes: 1041 1042 • outline level 1043 1044 • todo state 1045 1046 • priority 1047 1048 • scheduled 1049 1050 • deadline 1051 1052 • tags 1053 1054 1055 File: org-roam.info, Node: Titles and Aliases, Next: Tags, Prev: Standard Org properties, Up: Node Properties 1056 1057 8.2 Titles and Aliases 1058 ====================== 1059 1060 Each node has a single title. For file nodes, this is specified with 1061 the ‘#+title‘ property for the file. For headline nodes, this is the 1062 main text. 1063 1064 Nodes can also have multiple aliases. Aliases allow searching for 1065 nodes via an alternative name. For example, one may want to assign a 1066 well-known acronym (AI) to a node titled “Artificial Intelligence”. 1067 1068 To assign an alias to a node, add the “ROAM_ALIASES” property to the 1069 node: 1070 1071 * Artificial Intelligence 1072 :PROPERTIES: 1073 :ROAM_ALIASES: AI 1074 :END: 1075 1076 Alternatively, Org-roam provides some functions to add or remove 1077 aliases. 1078 1079 -- Function: org-roam-alias-add alias 1080 1081 Add ALIAS to the node at point. When called interactively, prompt 1082 for the alias to add. 1083 1084 -- Function: org-roam-alias-remove 1085 1086 Remove an alias from the node at point. 1087 1088 1089 File: org-roam.info, Node: Tags, Next: Refs, Prev: Titles and Aliases, Up: Node Properties 1090 1091 8.3 Tags 1092 ======== 1093 1094 Tags for top-level (file) nodes are pulled from the variable 1095 ‘org-file-tags’, which is set by the ‘#+filetags’ keyword, as well as 1096 other tags the file may have inherited. Tags for headline level nodes 1097 are regular Org tags. 1098 1099 Note that the ‘#+filetags’ keyword results in tags being inherited by 1100 headers within the file. This makes it impossible for selective tag 1101 inheritance: i.e. either tag inheritance is turned off, or all headline 1102 nodes will inherit the tags from the file node. This is a design 1103 compromise of Org-roam. 1104 1105 1106 File: org-roam.info, Node: Refs, Prev: Tags, Up: Node Properties 1107 1108 8.4 Refs 1109 ======== 1110 1111 Refs are unique identifiers for nodes. These keys allow references to 1112 the key to show up in the Org-roam buffer. For example, a node for a 1113 website may use the URL as the ref, and a node for a paper may use an 1114 Org-ref citation key. 1115 1116 To add a ref, add to the “ROAM_REFS” property as follows: 1117 1118 * Google 1119 :PROPERTIES: 1120 :ROAM_REFS: https://www.google.com/ 1121 :END: 1122 1123 With the above example, if another node links to 1124 <https://www.google.com/>, it will show up as a “reference backlink”. 1125 1126 These keys also come in useful for when taking website notes, using 1127 the ‘roam-ref’ protocol (see *note org-roam-protocol::). 1128 1129 You may assign multiple refs to a single node, for example when you 1130 want multiple papers in a series to share the same note, or an article 1131 has a citation key and a URL at the same time. 1132 1133 Org-roam also provides some functions to add or remove refs. 1134 1135 -- Function: org-roam-ref-add ref 1136 1137 Add REF to the node at point. When called interactively, prompt 1138 for the ref to add. 1139 1140 -- Function: org-roam-ref-remove 1141 1142 Remove a ref from the node at point. 1143 1144 1145 File: org-roam.info, Node: Citations, Next: Completion, Prev: Node Properties, Up: Top 1146 1147 9 Citations 1148 *********** 1149 1150 Since version 9.5, Org has first-class support for citations. Org-roam 1151 supports the caching of both these in-built citations (of form 1152 ‘[cite:@key]’) and org-ref (https://github.com/jkitchin/org-ref) 1153 citations (of form cite:key). 1154 1155 Org-roam attempts to load both the ‘org-ref’ and ‘org-cite’ package 1156 when indexing files, so no further setup from the user is required for 1157 citation support. 1158 1159 * Menu: 1160 1161 * Using the Cached Information:: 1162 1163 1164 File: org-roam.info, Node: Using the Cached Information, Up: Citations 1165 1166 9.1 Using the Cached Information 1167 ================================ 1168 1169 It is common to use take reference notes for academic papers. To 1170 designate the node to be the canonical node for the academic paper, we 1171 can use its unique citation key: 1172 1173 * Probabilistic Robotics 1174 :PROPERTIES: 1175 :ID: 51b7b82c-bbb4-4822-875a-ed548cffda10 1176 :ROAM_REFS: @thrun2005probabilistic 1177 :END: 1178 1179 or 1180 1181 * Probabilistic Robotics 1182 :PROPERTIES: 1183 :ID: 51b7b82c-bbb4-4822-875a-ed548cffda10 1184 :ROAM_REFS: [cite:@thrun2005probabilistic] 1185 :END: 1186 1187 for ‘org-cite’, or: 1188 1189 * Probabilistic Robotics 1190 :PROPERTIES: 1191 :ID: 51b7b82c-bbb4-4822-875a-ed548cffda10 1192 :ROAM_REFS: cite:thrun2005probabilistic 1193 :END: 1194 1195 for ‘org-ref’. 1196 1197 When another node has a citation for that key, we can see it using 1198 the ‘Reflinks’ section of the Org-roam buffer. 1199 1200 Extension developers may be interested in retrieving the citations 1201 within their notes. This information can be found within the ‘citation’ 1202 table of the Org-roam database. 1203 1204 1205 File: org-roam.info, Node: Completion, Next: Encryption, Prev: Citations, Up: Top 1206 1207 10 Completion 1208 ************* 1209 1210 Completions for Org-roam are provided via ‘completion-at-point’. 1211 Org-roam currently provides completions in two scenarios: 1212 1213 • When within an Org bracket link 1214 1215 • Anywhere 1216 1217 Completions are installed locally in all Org-roam files. To trigger 1218 completions, call ‘M-x completion-at-point’. If using ‘company-mode’, 1219 add ‘company-capf’ to ‘company-backends’. 1220 1221 Completions respect ‘completion-styles’: the user is free to choose 1222 how candidates are matched. An example of a completion style that has 1223 grown in popularity is orderless 1224 (https://github.com/oantolin/orderless). 1225 1226 * Menu: 1227 1228 * Completing within Link Brackets:: 1229 * Completing anywhere:: 1230 1231 1232 File: org-roam.info, Node: Completing within Link Brackets, Next: Completing anywhere, Up: Completion 1233 1234 10.1 Completing within Link Brackets 1235 ==================================== 1236 1237 Completions within link brackets are provided by 1238 ‘org-roam-complete-link-at-point’. 1239 1240 The completion candidates are the titles and aliases for all Org-roam 1241 nodes. Upon choosing a candidate, a ‘roam:Title’ link will be inserted, 1242 linking to node of choice. 1243 1244 1245 File: org-roam.info, Node: Completing anywhere, Prev: Completing within Link Brackets, Up: Completion 1246 1247 10.2 Completing anywhere 1248 ======================== 1249 1250 The same completions can be triggered anywhere for the symbol at point 1251 if not within a bracketed link. This is provided by 1252 ‘org-roam-complete-everywhere’. Similarly, the completion candidates 1253 are the titles and aliases for all Org-roam nodes, and upon choosing a 1254 candidate a ‘roam:Title’ link will be inserted linking to the node of 1255 choice. 1256 1257 This is disable by default. To enable it, set 1258 ‘org-roam-completion-everywhere’ to ‘t’: 1259 1260 (setq org-roam-completion-everywhere t) 1261 1262 -- Variable: org-roam-completion-everywhere 1263 1264 When non-nil, provide link completion matching outside of Org links. 1265 1266 1267 File: org-roam.info, Node: Encryption, Next: The Templating System, Prev: Completion, Up: Top 1268 1269 11 Encryption 1270 ************* 1271 1272 Emacs has support for creating and editing encrypted gpg files, and 1273 Org-roam need not provide additional tooling. To create encrypted 1274 files, simply add the ‘.gpg’ extension in your Org-roam capture 1275 templates. For example: 1276 1277 (setq org-roam-capture-templates '(("d" "default" plain "%?" 1278 :target (file+head "${slug}.org.gpg" 1279 "#+title: ${title}\n") 1280 :unnarrowed t))) 1281 1282 Note that the Org-roam database stores metadata information in 1283 plain-text (headline text, for example), so if this information is 1284 private to you then you should also ensure the database is encrypted. 1285 1286 1287 File: org-roam.info, Node: The Templating System, Next: Extensions, Prev: Encryption, Up: Top 1288 1289 12 The Templating System 1290 ************************ 1291 1292 Org-roam extends the ‘org-capture’ system, providing a smoother 1293 note-taking experience. However, these extensions mean Org-roam capture 1294 templates are incompatible with ‘org-capture’ templates. 1295 1296 Org-roam’s templates are specified by ‘org-roam-capture-templates’. 1297 Just like ‘org-capture-templates’, ‘org-roam-capture-templates’ can 1298 contain multiple templates. If ‘org-roam-capture-templates’ only 1299 contains one template, there will be no prompt for template selection. 1300 1301 * Menu: 1302 1303 * Template Walkthrough:: 1304 * Org-roam Template Expansion:: 1305 1306 1307 File: org-roam.info, Node: Template Walkthrough, Next: Org-roam Template Expansion, Up: The Templating System 1308 1309 12.1 Template Walkthrough 1310 ========================= 1311 1312 To demonstrate the additions made to org-capture templates. Here, we 1313 explain the default template, reproduced below. You will find most of 1314 the elements of the template are similar to ‘org-capture’ templates. 1315 1316 (("d" "default" plain "%?" 1317 :target (file+head "%<%Y%m%d%H%M%S>-${slug}.org" 1318 "#+title: ${title}\n") 1319 :unnarrowed t)) 1320 1321 • The template has short key ‘"d"’. If you have only one template, 1322 org-roam automatically chooses this template for you. 1323 1324 • The template is given a description of ‘"default"’. 1325 1326 • ‘plain’ text is inserted. Other options include Org headings via 1327 ‘entry’. 1328 1329 • Notice that the ‘target’ that’s usually in Org-capture templates is 1330 missing here. 1331 1332 • ‘"%?"’ is the template inserted on each call to 1333 ‘org-roam-capture-’. This template means don’t insert any content, 1334 but place the cursor here. 1335 1336 • ‘:target’ is a compulsory specification in the Org-roam capture 1337 template. The first element of the list indicates the type of the 1338 target, the second element indicates the location of the captured 1339 node, and the rest of the elements indicate prefilled template that 1340 will be inserted and the position of the point will be adjusted 1341 for. The latter behavior varies from type to type of the capture 1342 target. 1343 1344 • ‘:unnarrowed t’ tells org-capture to show the contents for the 1345 whole file, rather than narrowing to just the entry. This is part 1346 of the Org-capture templates. 1347 1348 See the ‘org-roam-capture-templates’ documentation for more details 1349 and customization options. 1350 1351 1352 File: org-roam.info, Node: Org-roam Template Expansion, Prev: Template Walkthrough, Up: The Templating System 1353 1354 12.2 Org-roam Template Expansion 1355 ================================ 1356 1357 Org-roam’s template definitions also extend org-capture’s template 1358 syntax, to allow prefilling of strings. We have seen a glimpse of this 1359 in *note Template Walkthrough: Template Walkthrough. 1360 1361 Org-roam provides the ‘${foo}’ syntax for substituting variables with 1362 known strings. ‘${foo}’’s substitution is performed as follows: 1363 1364 • If ‘foo’ is a function, ‘foo’ is called with the current node as 1365 its argument. 1366 1367 • Else if ‘org-roam-node-foo’ is a function, ‘foo’ is called with the 1368 current node as its argument. The ‘org-roam-node-’ prefix defines 1369 many of Org-roam’s node accessors such as ‘org-roam-node-title’ and 1370 ‘org-roam-node-level’. 1371 1372 • Else look up ‘org-roam-capture--info’ for ‘foo’. This is an 1373 internal variable that is set before the capture process begins. 1374 1375 • If none of the above applies, read a string using 1376 ‘completing-read’. 1377 • Org-roam also provides the ‘${foo=default_val}’ syntax, where 1378 if a default value is provided, will be the initial value for 1379 the ‘foo’ key during minibuffer completion. 1380 1381 One can check the list of available keys for nodes by inspecting the 1382 ‘org-roam-node’ struct. At the time of writing, it is: 1383 1384 (cl-defstruct (org-roam-node (:constructor org-roam-node-create) 1385 (:copier nil)) 1386 "A heading or top level file with an assigned ID property." 1387 file file-hash file-atime file-mtime 1388 id level point todo priority scheduled deadline title properties olp 1389 tags aliases refs) 1390 1391 This makes ‘${file}’, ‘${file-hash}’ etc. all valid substitutions. 1392 1393 1394 File: org-roam.info, Node: Extensions, Next: Performance Optimization, Prev: The Templating System, Up: Top 1395 1396 13 Extensions 1397 ************* 1398 1399 * Menu: 1400 1401 * org-roam-protocol:: 1402 * org-roam-graph:: 1403 * org-roam-dailies:: 1404 * org-roam-export:: 1405 1406 1407 File: org-roam.info, Node: org-roam-protocol, Next: org-roam-graph, Up: Extensions 1408 1409 13.1 org-roam-protocol 1410 ====================== 1411 1412 Org-roam provides extensions for capturing content from external 1413 applications such as the browser, via ‘org-protocol’. Org-roam extends 1414 ‘org-protocol’ with 2 protocols: the ‘roam-node’ and ‘roam-ref’ 1415 protocols. 1416 1417 * Menu: 1418 1419 * Installation: Installation (1). 1420 * The roam-node protocol:: 1421 * The roam-ref protocol:: 1422 1423 1424 File: org-roam.info, Node: Installation (1), Next: The roam-node protocol, Up: org-roam-protocol 1425 1426 13.1.1 Installation 1427 ------------------- 1428 1429 To enable Org-roam’s protocol extensions, simply add the following to 1430 your init file: 1431 1432 (require 'org-roam-protocol) 1433 1434 We also need to set up ‘org-protocol’: the instructions for setting 1435 up ‘org-protocol’ are reproduced here. 1436 1437 On a high-level, external calls are passed to Emacs via 1438 ‘emacsclient’. ‘org-protocol’ intercepts these and runs custom actions 1439 based on the protocols registered. Hence, to use ‘org-protocol’, once 1440 must: 1441 1442 • launch the ‘emacsclient’ process 1443 1444 • Register ‘org-protocol://’ as a valid scheme-handler 1445 1446 The instructions for the latter for each operating system is detailed 1447 below. 1448 1449 * Menu: 1450 1451 * Linux:: 1452 * Mac OS:: 1453 * Windows:: 1454 1455 1456 File: org-roam.info, Node: Linux, Next: Mac OS, Up: Installation (1) 1457 1458 Linux 1459 ..... 1460 1461 For Linux users, create a desktop application in 1462 ‘~/.local/share/applications/org-protocol.desktop’: 1463 1464 [Desktop Entry] 1465 Name=Org-Protocol 1466 Exec=emacsclient %u 1467 Icon=emacs-icon 1468 Type=Application 1469 Terminal=false 1470 MimeType=x-scheme-handler/org-protocol 1471 1472 Associate ‘org-protocol://’ links with the desktop application by 1473 running in your shell: 1474 1475 xdg-mime default org-protocol.desktop x-scheme-handler/org-protocol 1476 1477 To disable the “confirm” prompt in Chrome, you can also make Chrome 1478 show a checkbox to tick, so that the ‘Org-Protocol Client’ app will be 1479 used without confirmation. To do this, run in a shell: 1480 1481 sudo mkdir -p /etc/opt/chrome/policies/managed/ 1482 sudo tee /etc/opt/chrome/policies/managed/external_protocol_dialog.json >/dev/null <<'EOF' 1483 { 1484 "ExternalProtocolDialogShowAlwaysOpenCheckbox": true 1485 } 1486 EOF 1487 sudo chmod 644 /etc/opt/chrome/policies/managed/external_protocol_dialog.json 1488 1489 and then restart Chrome (for example, by navigating to 1490 <chrome://restart>) to make the new policy take effect. 1491 1492 See here (https://www.chromium.org/administrators/linux-quick-start) 1493 for more info on the ‘/etc/opt/chrome/policies/managed’ directory and 1494 here 1495 (https://cloud.google.com/docs/chrome-enterprise/policies/?policy=ExternalProtocolDialogShowAlwaysOpenCheckbox) 1496 for information on the ‘ExternalProtocolDialogShowAlwaysOpenCheckbox’ 1497 policy. 1498 1499 1500 File: org-roam.info, Node: Mac OS, Next: Windows, Prev: Linux, Up: Installation (1) 1501 1502 Mac OS 1503 ...... 1504 1505 For Mac OS, we need to create our own application. 1506 1507 • Launch Script Editor 1508 1509 • Use the following script, paying attention to the path to 1510 ‘emacsclient’: 1511 1512 on open location this_URL 1513 set EC to "/usr/local/bin/emacsclient --no-wait " 1514 set filePath to quoted form of this_URL 1515 do shell script EC & filePath 1516 tell application "Emacs" to activate 1517 end open location 1518 1519 • Save the script in ‘/Applications/OrgProtocolClient.app’, changing 1520 the script type to “Application”, rather than “Script”. 1521 1522 • Edit ‘/Applications/OrgProtocolClient.app/Contents/Info.plist’, 1523 adding the following before the last ‘</dict>’ tag: 1524 1525 <key>CFBundleURLTypes</key> 1526 <array> 1527 <dict> 1528 <key>CFBundleURLName</key> 1529 <string>org-protocol handler</string> 1530 <key>CFBundleURLSchemes</key> 1531 <array> 1532 <string>org-protocol</string> 1533 </array> 1534 </dict> 1535 </array> 1536 1537 • Save the file, and run the ‘OrgProtocolClient.app’ to register the 1538 protocol. 1539 1540 To disable the “confirm” prompt in Chrome, you can also make Chrome 1541 show a checkbox to tick, so that the ‘OrgProtocol’ app will be used 1542 without confirmation. To do this, run in a shell: 1543 1544 defaults write com.google.Chrome ExternalProtocolDialogShowAlwaysOpenCheckbox -bool true 1545 1546 If you’re using Emacs Mac Port 1547 (https://github.com/railwaycat/homebrew-emacsmacport), it registered its 1548 ‘Emacs.app‘ as the default handler for the URL scheme ‘org-protocol‘. 1549 To make ‘OrgProtocol.app’ the default handler instead, run: 1550 1551 defaults write com.apple.LaunchServices/com.apple.launchservices.secure LSHandlers -array-add \ 1552 '{"LSHandlerPreferredVersions" = { "LSHandlerRoleAll" = "-"; }; LSHandlerRoleAll = "org.yourusername.OrgProtocol"; LSHandlerURLScheme = "org-protocol";}' 1553 1554 Then restart your computer. 1555 1556 • Testing org-protocol 1557 1558 To test that you have the handler setup and registered properly 1559 from the command line you can run: 1560 1561 open org-protocol://roam-ref\?template=r\&ref=test\&title=this 1562 1563 If you get an error similar too this or the wrong handler is run: 1564 1565 No application knows how to open URL 1566 org-protocol://roam-ref?template=r&ref=test&title=this (Error 1567 Domain=NSOSStatusErrorDomain Code=-10814 1568 “kLSApplicationNotFoundErr: E.g. no application claims the 1569 file” UserInfo={_LSLine=1489, _LSFunction=runEvaluator}). 1570 1571 You may need to manually register your handler, like this: 1572 1573 /System/Library/Frameworks/CoreServices.framework/Versions/A/Frameworks/LaunchServices.framework/Versions/A/Support/lsregister -R -f /Applications/OrgProtocolClient.app 1574 1575 Here is a link to the lsregister command that is really useful: 1576 <https://eclecticlight.co/2019/03/25/lsregister-a-valuable-undocumented-command-for-launchservices/> 1577 1578 1579 File: org-roam.info, Node: Windows, Prev: Mac OS, Up: Installation (1) 1580 1581 Windows 1582 ....... 1583 1584 For Windows, create a temporary ‘org-protocol.reg’ file: 1585 1586 REGEDIT4 1587 1588 [HKEY_CLASSES_ROOT\org-protocol] 1589 @="URL:Org Protocol" 1590 "URL Protocol"="" 1591 [HKEY_CLASSES_ROOT\org-protocol\shell] 1592 [HKEY_CLASSES_ROOT\org-protocol\shell\open] 1593 [HKEY_CLASSES_ROOT\org-protocol\shell\open\command] 1594 @="\"C:\\Windows\\System32\\wsl.exe\" emacsclient \"%1\"" 1595 1596 The above will forward the protocol to WSL. If you run Emacs 1597 natively on Windows, replace the last line with: 1598 1599 @="\"c:\\path\\to\\emacs\\bin\\emacsclientw.exe\" \"%1\"" 1600 1601 After executing the .reg file, the protocol is registered and you can 1602 delete the file. 1603 1604 1605 File: org-roam.info, Node: The roam-node protocol, Next: The roam-ref protocol, Prev: Installation (1), Up: org-roam-protocol 1606 1607 13.1.2 The roam-node protocol 1608 ----------------------------- 1609 1610 The roam-node protocol opens the node with ID specified by the ‘node’ 1611 key (e.g. ‘org-protocol://roam-node?node=node-id’). ‘org-roam-graph’ 1612 uses this to make the graph navigable. 1613 1614 1615 File: org-roam.info, Node: The roam-ref protocol, Prev: The roam-node protocol, Up: org-roam-protocol 1616 1617 13.1.3 The roam-ref protocol 1618 ---------------------------- 1619 1620 This protocol finds or creates a new note with a given ‘ROAM_REFS’: 1621 1622 1623 1624 To use this, create the following bookmarklet 1625 (https://en.wikipedia.org/wiki/Bookmarklet) in your browser: 1626 1627 javascript:location.href = 1628 'org-protocol://roam-ref?template=r&ref=' 1629 + encodeURIComponent(location.href) 1630 + '&title=' 1631 + encodeURIComponent(document.title) 1632 + '&body=' 1633 + encodeURIComponent(window.getSelection()) 1634 1635 or as a keybinding in ‘qutebrowser’ in , using the ‘config.py’ file 1636 (see Configuring qutebrowser 1637 (https://github.com/qutebrowser/qutebrowser/blob/master/doc/help/configuring.asciidoc)): 1638 1639 config.bind("<Ctrl-r>", "open javascript:location.href='org-protocol://roam-ref?template=r&ref='+encodeURIComponent(location.href)+'&title='+encodeURIComponent(document.title)") 1640 1641 where ‘template’ is the template key for a template in 1642 ‘org-roam-capture-ref-templates’ (see *note The Templating System::). 1643 1644 1645 File: org-roam.info, Node: org-roam-graph, Next: org-roam-dailies, Prev: org-roam-protocol, Up: Extensions 1646 1647 13.2 org-roam-graph 1648 =================== 1649 1650 Org-roam provides basic graphing capabilities to explore 1651 interconnections between notes, in ‘org-roam-graph’. This is done by 1652 performing SQL queries and generating images using Graphviz 1653 (https://graphviz.org/). The graph can also be navigated: see *note 1654 org-roam-protocol::. 1655 1656 The entry point to graph creation is ‘org-roam-graph’. 1657 1658 -- Function: org-roam-graph & optional arg node 1659 1660 Build and display a graph for NODE. ARG may be any of the following 1661 values: 1662 1663 • ‘nil’ show the full graph. 1664 1665 • ‘integer’ an integer argument ‘N’ will show the graph for the 1666 connected components to node up to ‘N’ steps away. 1667 -- User Option: org-roam-graph-executable 1668 1669 Path to the graphing executable (in this case, Graphviz). Set this 1670 if Org-roam is unable to find the Graphviz executable on your 1671 system. 1672 1673 You may also choose to use ‘neato’ in place of ‘dot’, which 1674 generates a more compact graph layout. 1675 1676 -- User Option: org-roam-graph-viewer 1677 1678 Org-roam defaults to using Firefox (located on PATH) to view the 1679 SVG, but you may choose to set it to: 1680 1681 • A string, which is a path to the program used 1682 1683 • a function accepting a single argument: the graph file path. 1684 1685 ‘nil’ uses ‘view-file’ to view the graph. 1686 1687 If you are using WSL2 and would like to open the graph in Windows, 1688 you can use the second option to set the browser and network file 1689 path: 1690 1691 (setq org-roam-graph-viewer 1692 (lambda (file) 1693 (let ((org-roam-graph-viewer "/mnt/c/Program Files/Mozilla Firefox/firefox.exe")) 1694 (org-roam-graph--open (concat "file://///wsl$/Ubuntu" file))))) 1695 1696 * Menu: 1697 1698 * Graph Options:: 1699 1700 1701 File: org-roam.info, Node: Graph Options, Up: org-roam-graph 1702 1703 13.2.1 Graph Options 1704 -------------------- 1705 1706 Graphviz provides many options for customizing the graph output, and 1707 Org-roam supports some of them. See 1708 <https://graphviz.gitlab.io/_pages/doc/info/attrs.html> for customizable 1709 options. 1710 1711 -- User Option: org-roam-graph-filetype 1712 1713 The file type to generate for graphs. This defaults to ‘"svg"’. 1714 1715 -- User Option: org-roam-graph-extra-config 1716 1717 Extra options passed to graphviz for the digraph (The “G” 1718 attributes). Example: ‘'~(("rankdir" . "LR"))’ 1719 1720 -- User Option: org-roam-graph-node-extra-config 1721 1722 An alist of options to style the nodes. The car of the alist node 1723 type such as ‘"id"’, or ‘"http"’. The cdr of the list is another 1724 alist of Graphviz node options (the “N” attributes). 1725 1726 -- User Option: org-roam-graph-edge-extra-config 1727 1728 Extra options for edges in the graphviz output (The “E” 1729 attributes). Example: ‘'(("dir" . "back"))’ 1730 1731 1732 File: org-roam.info, Node: org-roam-dailies, Next: org-roam-export, Prev: org-roam-graph, Up: Extensions 1733 1734 13.3 org-roam-dailies 1735 ===================== 1736 1737 Org-roam provides journaling capabilities akin to Org-journal with 1738 ‘org-roam-dailies’. 1739 1740 * Menu: 1741 1742 * Configuration:: 1743 * Usage:: 1744 1745 1746 File: org-roam.info, Node: Configuration, Next: Usage, Up: org-roam-dailies 1747 1748 13.3.1 Configuration 1749 -------------------- 1750 1751 For ‘org-roam-dailies’ to work, you need to define two variables: 1752 1753 -- Variable: ‘org-roam-dailies-directory’ 1754 1755 Path to daily-notes. This path is relative to 1756 ‘org-roam-directory’. 1757 1758 -- Variable: ‘org-roam-dailies-capture-templates’ 1759 1760 Capture templates for daily-notes in Org-roam. 1761 1762 Here is a sane default configuration: 1763 1764 (setq org-roam-dailies-directory "daily/") 1765 1766 (setq org-roam-dailies-capture-templates 1767 '(("d" "default" entry 1768 "* %?" 1769 :target (file+head "%<%Y-%m-%d>.org" 1770 "#+title: %<%Y-%m-%d>\n")))) 1771 1772 See *note The Templating System:: for creating new templates. 1773 1774 1775 File: org-roam.info, Node: Usage, Prev: Configuration, Up: org-roam-dailies 1776 1777 13.3.2 Usage 1778 ------------ 1779 1780 ‘org-roam-dailies’ provides these interactive functions: 1781 1782 -- Function: ‘org-roam-dailies-capture-today’ &optional goto 1783 1784 Create an entry in the daily note for today. 1785 1786 When ‘goto’ is non-nil, go to the note without creating an entry. 1787 1788 -- Function: ‘org-roam-dailies-goto-today’ 1789 1790 Find the daily note for today, creating it if necessary. 1791 1792 There are variants of those commands for ‘-yesterday’ and 1793 ‘-tomorrow’: 1794 1795 -- Function: ‘org-roam-dailies-capture-yesterday’ n &optional goto 1796 1797 Create an entry in the daily note for yesterday. 1798 1799 With numeric argument ‘n’, use the daily note ‘n’ days in the past. 1800 1801 -- Function: ‘org-roam-dailies-goto-yesterday’ 1802 1803 With numeric argument N, use the daily-note N days in the future. 1804 1805 There are also commands which allow you to use Emacs’s ‘calendar’ to 1806 find the date 1807 1808 -- Function: ‘org-roam-dailies-capture-date’ 1809 1810 Create an entry in the daily note for a date using the calendar. 1811 1812 Prefer past dates, unless ‘prefer-future’ is non-nil. 1813 1814 With a ’C-u’ prefix or when ‘goto’ is non-nil, go the note without 1815 creating an entry. 1816 1817 -- Function: ‘org-roam-dailies-goto-date’ 1818 1819 Find the daily note for a date using the calendar, creating it if 1820 necessary. 1821 1822 Prefer past dates, unless ‘prefer-future’ is non-nil. 1823 1824 -- Function: ‘org-roam-dailies-find-directory’ 1825 1826 Find and open ‘org-roam-dailies-directory’. 1827 1828 -- Function: ‘org-roam-dailies-goto-previous-note’ 1829 1830 When in an daily-note, find the previous one. 1831 1832 -- Function: ‘org-roam-dailies-goto-next-note’ 1833 1834 When in an daily-note, find the next one. 1835 1836 1837 File: org-roam.info, Node: org-roam-export, Prev: org-roam-dailies, Up: Extensions 1838 1839 13.4 org-roam-export 1840 ==================== 1841 1842 Because Org-roam files are plain org files, they can be exported easily 1843 using ‘org-export’ to a variety of formats, including ‘html’ and ‘pdf’. 1844 However, Org-roam relies heavily on ID links, which Org’s html export 1845 has poor support of. To fix this, Org-roam provides a bunch of 1846 overrides to better support export. To use them, simply run: 1847 1848 (require 'org-roam-export) 1849 1850 1851 File: org-roam.info, Node: Performance Optimization, Next: The Org-mode Ecosystem, Prev: Extensions, Up: Top 1852 1853 14 Performance Optimization 1854 *************************** 1855 1856 * Menu: 1857 1858 * Garbage Collection:: 1859 1860 1861 File: org-roam.info, Node: Garbage Collection, Up: Performance Optimization 1862 1863 14.1 Garbage Collection 1864 ======================= 1865 1866 During the cache-build process, Org-roam generates a lot of in-memory 1867 data-structures (such as the Org file’s AST), which are discarded after 1868 use. These structures are garbage collected at regular intervals (see 1869 *note info:elisp#Garbage Collection: (elisp)Garbage Collection.). 1870 1871 Org-roam provides the option ‘org-roam-db-gc-threshold’ to 1872 temporarily change the threshold value for GC to be triggered during 1873 these memory-intensive operations. To reduce the number of garbage 1874 collection processes, one may set ‘org-roam-db-gc-threshold’ to a high 1875 value (such as ‘most-positive-fixnum’): 1876 1877 (setq org-roam-db-gc-threshold most-positive-fixnum) 1878 1879 1880 File: org-roam.info, Node: The Org-mode Ecosystem, Next: FAQ, Prev: Performance Optimization, Up: Top 1881 1882 15 The Org-mode Ecosystem 1883 ************************* 1884 1885 Because Org-roam is built on top of Org-mode, it benefits from the vast 1886 number of packages already available. 1887 1888 * Menu: 1889 1890 * Browsing History with winner-mode:: 1891 * Versioning Notes:: 1892 * Full-text search with Deft:: 1893 * Org-journal:: 1894 * Org-download:: 1895 * mathpix.el: mathpixel. 1896 * Org-noter / Interleave:: 1897 * Bibliography:: 1898 * Spaced Repetition:: 1899 1900 1901 File: org-roam.info, Node: Browsing History with winner-mode, Next: Versioning Notes, Up: The Org-mode Ecosystem 1902 1903 15.1 Browsing History with winner-mode 1904 ====================================== 1905 1906 ‘winner-mode’ is a global minor mode that allows one to undo and redo 1907 changes in the window configuration. It is included with GNU Emacs 1908 since version 20. 1909 1910 ‘winner-mode’ can be used as a simple version of browser history for 1911 Org-roam. Each click through org-roam links (from both Org files and 1912 the backlinks buffer) causes changes in window configuration, which can 1913 be undone and redone using ‘winner-mode’. To use ‘winner-mode’, simply 1914 enable it, and bind the appropriate interactive functions: 1915 1916 (winner-mode +1) 1917 (define-key winner-mode-map (kbd "<M-left>") #'winner-undo) 1918 (define-key winner-mode-map (kbd "<M-right>") #'winner-redo) 1919 1920 1921 1922 File: org-roam.info, Node: Versioning Notes, Next: Full-text search with Deft, Prev: Browsing History with winner-mode, Up: The Org-mode Ecosystem 1923 1924 15.2 Versioning Notes 1925 ===================== 1926 1927 Since Org-roam notes are just plain text, it is trivial to track changes 1928 in your notes database using version control systems such as Git 1929 (https://git-scm.com/). Simply initialize ‘org-roam-directory’ as a Git 1930 repository, and commit your files at regular or appropriate intervals. 1931 Magit (https://magit.vc/) is a great interface to Git within Emacs. 1932 1933 In addition, it may be useful to observe how a particular note has 1934 evolved, by looking at the file history. Git-timemachine 1935 (https://gitlab.com/pidu/git-timemachine) allows you to visit historic 1936 versions of a tracked Org-roam note. 1937 1938 1939 File: org-roam.info, Node: Full-text search with Deft, Next: Org-journal, Prev: Versioning Notes, Up: The Org-mode Ecosystem 1940 1941 15.3 Full-text search with Deft 1942 =============================== 1943 1944 Deft (https://jblevins.org/projects/deft/) provides a nice interface for 1945 browsing and filtering org-roam notes. 1946 1947 (use-package deft 1948 :after org 1949 :bind 1950 ("C-c n d" . deft) 1951 :custom 1952 (deft-recursive t) 1953 (deft-use-filter-string-for-filename t) 1954 (deft-default-extension "org") 1955 (deft-directory org-roam-directory)) 1956 1957 The Deft interface can slow down quickly when the number of files get 1958 huge. Notdeft (https://github.com/hasu/notdeft) is a fork of Deft that 1959 uses an external search engine and indexer. 1960 1961 1962 File: org-roam.info, Node: Org-journal, Next: Org-download, Prev: Full-text search with Deft, Up: The Org-mode Ecosystem 1963 1964 15.4 Org-journal 1965 ================ 1966 1967 Org-journal (https://github.com/bastibe/org-journal) provides journaling 1968 capabilities to Org-mode. A lot of its functionalities have been 1969 incorporated into Org-roam under the name *note ‘org-roam-dailies’: 1970 org-roam-dailies. It remains a good tool if you want to isolate your 1971 verbose journal entries from the ideas you would write on a scratchpad. 1972 1973 (use-package org-journal 1974 :bind 1975 ("C-c n j" . org-journal-new-entry) 1976 :custom 1977 (org-journal-date-prefix "#+title: ") 1978 (org-journal-file-format "%Y-%m-%d.org") 1979 (org-journal-dir "/path/to/journal/files/") 1980 (org-journal-date-format "%A, %d %B %Y")) 1981 1982 1983 File: org-roam.info, Node: Org-download, Next: mathpixel, Prev: Org-journal, Up: The Org-mode Ecosystem 1984 1985 15.5 Org-download 1986 ================= 1987 1988 Org-download (https://github.com/abo-abo/org-download) lets you 1989 screenshot and yank images from the web into your notes: 1990 1991 1992 1993 Figure: org-download 1994 1995 (use-package org-download 1996 :after org 1997 :bind 1998 (:map org-mode-map 1999 (("s-Y" . org-download-screenshot) 2000 ("s-y" . org-download-yank)))) 2001 2002 2003 File: org-roam.info, Node: mathpixel, Next: Org-noter / Interleave, Prev: Org-download, Up: The Org-mode Ecosystem 2004 2005 15.6 mathpix.el 2006 =============== 2007 2008 mathpix.el (https://github.com/jethrokuan/mathpix.el) uses Mathpix’s 2009 (https://mathpix.com/) API to convert clips into latex equations: 2010 2011 2012 2013 Figure: mathpix 2014 2015 (use-package mathpix.el 2016 :straight (:host github :repo "jethrokuan/mathpix.el") 2017 :custom ((mathpix-app-id "app-id") 2018 (mathpix-app-key "app-key")) 2019 :bind 2020 ("C-x m" . mathpix-screenshot)) 2021 2022 2023 File: org-roam.info, Node: Org-noter / Interleave, Next: Bibliography, Prev: mathpixel, Up: The Org-mode Ecosystem 2024 2025 15.7 Org-noter / Interleave 2026 =========================== 2027 2028 Org-noter (https://github.com/weirdNox/org-noter) and Interleave 2029 (https://github.com/rudolfochrist/interleave) are both projects that 2030 allow synchronised annotation of documents (PDF, EPUB etc.) within 2031 Org-mode. 2032 2033 2034 File: org-roam.info, Node: Bibliography, Next: Spaced Repetition, Prev: Org-noter / Interleave, Up: The Org-mode Ecosystem 2035 2036 15.8 Bibliography 2037 ================= 2038 2039 Org 9.5 added native citation and bibliography functionality, called 2040 “org-cite”, which org-roam supports. 2041 2042 org-roam-bibtex (https://github.com/org-roam/org-roam-bibtex) offers 2043 tight integration between org-ref (https://github.com/jkitchin/org-ref), 2044 helm-bibtex (https://github.com/tmalsburg/helm-bibtex) and ‘org-roam’. 2045 This helps you manage your bibliographic notes under ‘org-roam’. 2046 2047 For example, though helm-bibtex provides the ability to visit notes 2048 for bibliographic entries, org-roam-bibtex extends it with the ability 2049 to visit the file with the right ‘ROAM_REFS’. 2050 2051 2052 File: org-roam.info, Node: Spaced Repetition, Prev: Bibliography, Up: The Org-mode Ecosystem 2053 2054 15.9 Spaced Repetition 2055 ====================== 2056 2057 Org-fc (https://www.leonrische.me/fc/index.html) is a spaced repetition 2058 system that scales well with a large number of files. Other 2059 alternatives include org-drill 2060 (https://orgmode.org/worg/org-contrib/org-drill.html), and pamparam 2061 (https://github.com/abo-abo/pamparam). 2062 2063 To use Anki for spaced repetition, anki-editor 2064 (https://github.com/louietan/anki-editor) allows you to write your cards 2065 in Org-mode, and sync your cards to Anki via anki-connect 2066 (https://github.com/FooSoft/anki-connect#installation). 2067 2068 2069 File: org-roam.info, Node: FAQ, Next: Developer's Guide to Org-roam, Prev: The Org-mode Ecosystem, Up: Top 2070 2071 16 FAQ 2072 ****** 2073 2074 * Menu: 2075 2076 * How do I have more than one Org-roam directory?:: 2077 * How do I create a note whose title already matches one of the candidates?:: 2078 * How can I stop Org-roam from creating IDs everywhere?:: 2079 * How do I migrate from Roam Research?:: 2080 * How to migrate from Org-roam v1?:: 2081 * How do I publish my notes with an Internet-friendly graph?:: 2082 * I’m seeing this “Selecting deleted buffer” error. What do I do?: I'm seeing this ``Selecting deleted buffer'' error What do I do?. 2083 2084 2085 File: org-roam.info, Node: How do I have more than one Org-roam directory?, Next: How do I create a note whose title already matches one of the candidates?, Up: FAQ 2086 2087 16.1 How do I have more than one Org-roam directory? 2088 ==================================================== 2089 2090 Emacs supports directory-local variables, allowing the value of 2091 ‘org-roam-directory’ to be different in different directories. It does 2092 this by checking for a file named ‘.dir-locals.el’. 2093 2094 To add support for multiple directories, override the 2095 ‘org-roam-directory’ variable using directory-local variables. This is 2096 what ‘.dir-locals.el’ may contain: 2097 2098 ((nil . ((org-roam-directory . "/path/to/alt/org-roam-dir") 2099 (org-roam-db-location . "/path/to/alt/org-roam-dir/org-roam.db")))) 2100 2101 Note ‘org-roam-directory’ and ‘org-roam-db-location’ should be an 2102 absolute path, not relative. 2103 2104 Alternatively, use ‘eval’ if you wish to call functions: 2105 2106 ((nil . ((eval . (setq-local 2107 org-roam-directory (expand-file-name (locate-dominating-file 2108 default-directory ".dir-locals.el")))) 2109 (eval . (setq-local 2110 org-roam-db-location (expand-file-name "org-roam.db" 2111 org-roam-directory)))))) 2112 2113 All files within that directory will be treated as their own separate 2114 set of Org-roam files. Remember to run ‘org-roam-db-sync’ from a file 2115 within that directory, at least once. 2116 2117 2118 File: org-roam.info, Node: How do I create a note whose title already matches one of the candidates?, Next: How can I stop Org-roam from creating IDs everywhere?, Prev: How do I have more than one Org-roam directory?, Up: FAQ 2119 2120 16.2 How do I create a note whose title already matches one of the candidates? 2121 ============================================================================== 2122 2123 This situation arises when, for example, one would like to create a note 2124 titled “bar” when “barricade” already exists. 2125 2126 The solution is dependent on the mini-buffer completion framework in 2127 use. Here are the solutions: 2128 2129 • Ivycall ‘ivy-immediate-done’, typically bound to ‘C-M-j’. 2130 Alternatively, set ‘ivy-use-selectable-prompt’ to ‘t’, so that 2131 “bar” is now selectable. 2132 2133 • HelmOrg-roam should provide a selectable “[?] bar” candidate at 2134 the top of the candidate list. 2135 2136 2137 File: org-roam.info, Node: How can I stop Org-roam from creating IDs everywhere?, Next: How do I migrate from Roam Research?, Prev: How do I create a note whose title already matches one of the candidates?, Up: FAQ 2138 2139 16.3 How can I stop Org-roam from creating IDs everywhere? 2140 ========================================================== 2141 2142 Other than the interactive commands that Org-roam provides, Org-roam 2143 does not create IDs everywhere. If you are noticing that IDs are being 2144 created even when you don’t want them to be (e.g. when tangling an Org 2145 file), check the value you have set for ‘org-id-link-to-org-use-id’: 2146 setting it to ‘'create-if-interactive’ is a popular option. 2147 2148 2149 File: org-roam.info, Node: How do I migrate from Roam Research?, Next: How to migrate from Org-roam v1?, Prev: How can I stop Org-roam from creating IDs everywhere?, Up: FAQ 2150 2151 16.4 How do I migrate from Roam Research? 2152 ========================================= 2153 2154 Fabio has produced a command-line tool that converts markdown files 2155 exported from Roam Research into Org-roam compatible markdown. More 2156 instructions are provided in the repository 2157 (https://github.com/fabioberger/roam-migration). 2158 2159 2160 File: org-roam.info, Node: How to migrate from Org-roam v1?, Next: How do I publish my notes with an Internet-friendly graph?, Prev: How do I migrate from Roam Research?, Up: FAQ 2161 2162 16.5 How to migrate from Org-roam v1? 2163 ===================================== 2164 2165 Those coming from Org-roam v1 will do well treating v2 as entirely new 2166 software. V2 has a smaller core and fewer moving parts, while retaining 2167 the bulk of its functionality. It is recommended to read the 2168 documentation above about nodes. 2169 2170 It is still desirable to migrate notes collected in v1 to v2. To 2171 migrate your v1 notes to v2, use ‘M-x org-roam-migrate-wizard’. This 2172 blog post 2173 (https://d12frosted.io/posts/2021-06-11-path-to-org-roam-v2.html) 2174 provides a good overview of what’s new in v2 and how to migrate. 2175 2176 Essentially, to migrate notes from v1 to v2, one must: 2177 2178 • Add IDs to all existing notes. These are located in top-level 2179 property drawers (Although note that in v2, not all files need to 2180 have IDs). 2181 2182 • Update the Org-roam database to conform to the new schema. 2183 2184 • Replace ‘#+ROAM_KEY’ into the ‘ROAM_REFS’ property 2185 2186 • Replace ‘#+ROAM_ALIAS’ into the ‘ROAM_ALIASES’ property 2187 2188 • Move ‘#+ROAM_TAGS’ into the ‘#+FILETAGS’ property for file-level 2189 nodes, and the ‘ROAM_TAGS’ property for headline nodes 2190 2191 • Replace existing file links with ID links. 2192 2193 2194 File: org-roam.info, Node: How do I publish my notes with an Internet-friendly graph?, Next: I'm seeing this ``Selecting deleted buffer'' error What do I do?, Prev: How to migrate from Org-roam v1?, Up: FAQ 2195 2196 16.6 How do I publish my notes with an Internet-friendly graph? 2197 =============================================================== 2198 2199 The default graph builder creates a graph with an org-protocol 2200 (https://orgmode.org/worg/org-contrib/org-protocol.html) handler which 2201 is convenient when you’re working locally but inconvenient when you want 2202 to publish your notes for remote access. Likewise, it defaults to 2203 displaying the graph in Emacs which has the exact same caveats. This 2204 problem is solvable in the following way using org-mode’s native 2205 publishing (https://orgmode.org/manual/Publishing.html) capability: 2206 2207 • configure org-mode to publish your org-roam notes as a project. 2208 2209 • create a function that overrides the default org-protocol link 2210 creation function(‘org-roam-default-link-builder’). 2211 2212 • create a hook that’s called at the end of graph creation to copy 2213 the generated graph to the appropriate place. 2214 2215 The example code below is used to publish to a local directory where 2216 a separate shell script copies the files to the remote site. 2217 2218 * Menu: 2219 2220 * Configure org-mode for publishing:: 2221 * Overriding the default link creation function:: 2222 * Copying the generated file to the export directory:: 2223 2224 2225 File: org-roam.info, Node: Configure org-mode for publishing, Next: Overriding the default link creation function, Up: How do I publish my notes with an Internet-friendly graph? 2226 2227 16.6.1 Configure org-mode for publishing 2228 ---------------------------------------- 2229 2230 This has two steps: 2231 • Setting of a _roam_ project that publishes your notes. 2232 2233 • Configuring the _sitemap.html_ generation. 2234 2235 • Setting up ‘org-publish’ to generate the graph. 2236 2237 This will require code like the following: 2238 (defun roam-sitemap (title list) 2239 (concat "#+OPTIONS: ^:nil author:nil html-postamble:nil\n" 2240 "#+SETUPFILE: ./simple_inline.theme\n" 2241 "#+TITLE: " title "\n\n" 2242 (org-list-to-org list) "\nfile:sitemap.svg")) 2243 2244 (setq my-publish-time 0) ; see the next section for context 2245 (defun roam-publication-wrapper (plist filename pubdir) 2246 (org-roam-graph) 2247 (org-html-publish-to-html plist filename pubdir) 2248 (setq my-publish-time (cadr (current-time)))) 2249 2250 (setq org-publish-project-alist 2251 '(("roam" 2252 :base-directory "~/roam" 2253 :auto-sitemap t 2254 :sitemap-function roam-sitemap 2255 :sitemap-title "Roam notes" 2256 :publishing-function roam-publication-wrapper 2257 :publishing-directory "~/roam-export" 2258 :section-number nil 2259 :table-of-contents nil 2260 :style "<link rel=\"stylesheet\" href=\"../other/mystyle.cs\" type=\"text/css\">"))) 2261 2262 2263 File: org-roam.info, Node: Overriding the default link creation function, Next: Copying the generated file to the export directory, Prev: Configure org-mode for publishing, Up: How do I publish my notes with an Internet-friendly graph? 2264 2265 16.6.2 Overriding the default link creation function 2266 ---------------------------------------------------- 2267 2268 The code below will generate a link to the generated html file instead 2269 of the default org-protocol link. 2270 (defun org-roam-custom-link-builder (node) 2271 (let ((file (org-roam-node-file node))) 2272 (concat (file-name-base file) ".html"))) 2273 2274 (setq org-roam-graph-link-builder 'org-roam-custom-link-builder) 2275 2276 2277 File: org-roam.info, Node: Copying the generated file to the export directory, Prev: Overriding the default link creation function, Up: How do I publish my notes with an Internet-friendly graph? 2278 2279 16.6.3 Copying the generated file to the export directory 2280 --------------------------------------------------------- 2281 2282 The default behavior of ‘org-roam-graph’ is to generate the graph and 2283 display it in Emacs. There is an ‘org-roam-graph-generation-hook’ 2284 available that provides access to the file names so they can be copied 2285 to the publishing directory. Example code follows: 2286 2287 (add-hook 'org-roam-graph-generation-hook 2288 (lambda (dot svg) (if (< (- (cadr (current-time)) my-publish-time) 5) 2289 (progn (copy-file svg "~/roam-export/sitemap.svg" 't) 2290 (kill-buffer (file-name-nondirectory svg)) 2291 (setq my-publish-time 0))))) 2292 2293 2294 File: org-roam.info, Node: I'm seeing this ``Selecting deleted buffer'' error What do I do?, Prev: How do I publish my notes with an Internet-friendly graph?, Up: FAQ 2295 2296 16.7 I’m seeing this “Selecting deleted buffer” error. What do I do? 2297 ==================================================================== 2298 2299 The “selecting deleted buffer” error usually occurs when you don’t have 2300 a working ‘emacsql-sqlite’ executable. Org-roam relies on this 2301 executable to function properly, and doesn’t catch this error. This 2302 issue is most commonly seen on Windows setups. You can browse through 2303 the various GitHub issues posted about this here 2304 (https://github.com/org-roam/org-roam/issues?q=is%3Aissue+selecting+deleted). 2305 2306 To fix this, you can try the following: 2307 2308 • If on Windows, try replacing your system binary with this one 2309 (https://github.com/nobiot/emacsql-sqlite.exe) that has been proven 2310 to work 2311 2312 • Use the ‘emacsql-sqlite3’ option rather than compiling your own 2313 emacsql binary (see *note How to cache::). 2314 2315 2316 File: org-roam.info, Node: Developer's Guide to Org-roam, Next: Appendix, Prev: FAQ, Up: Top 2317 2318 17 Developer’s Guide to Org-roam 2319 ******************************** 2320 2321 * Menu: 2322 2323 * Org-roam's Design Principle:: 2324 * Building Extensions and Advanced Customization of Org-roam:: 2325 2326 2327 File: org-roam.info, Node: Org-roam's Design Principle, Next: Building Extensions and Advanced Customization of Org-roam, Up: Developer's Guide to Org-roam 2328 2329 17.1 Org-roam’s Design Principle 2330 ================================ 2331 2332 Org-roam is primarily motivated by the need for a dual representation. 2333 We (humans) love operating in a plain-text environment. The syntax 2334 rules of Org-mode are simple and fit snugly within our brain. This also 2335 allows us to use the tools and packages we love to explore and edit our 2336 notes. Org-mode is simply the most powerful plain-text format 2337 available, with support for images, LaTeX, TODO planning and much more. 2338 2339 But this plain-text format is simply ill-suited for exploration of 2340 these notes: plain-text is simply not amenable for answering 2341 large-scale, complex queries (e.g. how many tasks do I have that are 2342 due by next week?). Interfaces such as Org-agenda slow to a crawl when 2343 the number of files becomes unwieldy, which can quickly become the case. 2344 2345 At its core, Org-roam provides a database abstraction layer, 2346 providing a dual representation of what’s already available in 2347 plain-text. This allows us (humans) to continue working with 2348 plain-text, while programs can utilize the database layer to perform 2349 complex queries. These capabilities include, but are not limited to: 2350 2351 • link graph traversal and visualization 2352 2353 • Instantaneous SQL-like queries on headlines 2354 • What are my TODOs, scheduled for X, or due by Y? 2355 2356 • Accessing the properties of a node, such as its tags, refs, TODO 2357 state or priority 2358 2359 All of these functionality is powered by this database abstraction 2360 layer. Hence, at its core Org-roam’s primary goal is to provide a 2361 resilient dual representation that is cheap to maintain, easy to 2362 understand, and is as up-to-date as it possibly can. Org-roam also then 2363 exposes an API to this database abstraction layer for users who would 2364 like to perform programmatic queries on their Org files. 2365 2366 2367 File: org-roam.info, Node: Building Extensions and Advanced Customization of Org-roam, Prev: Org-roam's Design Principle, Up: Developer's Guide to Org-roam 2368 2369 17.2 Building Extensions and Advanced Customization of Org-roam 2370 =============================================================== 2371 2372 Because Org-roam’s core functionality is small, it is possible and 2373 sometimes desirable to build extensions on top of it. These extensions 2374 may one or more of the following functionalities: 2375 2376 • Access to Org-roam’s database 2377 2378 • Usage/modification of Org-roam’s interactive commands 2379 2380 Org-roam provides no guarantees that extensions will continue to 2381 function as Org-roam evolves, but by following these simple rules, 2382 extensions can be made robust to local changes in Org-roam. 2383 2384 • Extensions should not modify the database schema. Any extension 2385 that requires the caching of additional data should make a request 2386 upstream to Org-roam. 2387 2388 • Extensions requiring access to the database should explicitly state 2389 support for the database version (‘org-roam-db-version’), and only 2390 conditionally load when support is available. 2391 2392 * Menu: 2393 2394 * Accessing the Database:: 2395 * Accessing and Modifying Nodes:: 2396 * Extending the Capture System:: 2397 2398 2399 File: org-roam.info, Node: Accessing the Database, Next: Accessing and Modifying Nodes, Up: Building Extensions and Advanced Customization of Org-roam 2400 2401 17.2.1 Accessing the Database 2402 ----------------------------- 2403 2404 Access to the database is provided singularly by ‘org-roam-db-query’, 2405 for example: 2406 2407 (org-roam-db-query [:select * :from nodes]) 2408 2409 One can refer to the database schema by looking up 2410 ‘org-roam-db--table-schemata’. There are multiple helper functions 2411 within Org-roam that call ‘org-roam-db-query’, these are subject to 2412 change. To ensure that extensions/customizations are robust to change, 2413 extensions should only use ‘org-roam-db-query’, and perhaps replicate 2414 the SQL query if necessary. 2415 2416 2417 File: org-roam.info, Node: Accessing and Modifying Nodes, Next: Extending the Capture System, Prev: Accessing the Database, Up: Building Extensions and Advanced Customization of Org-roam 2418 2419 17.2.2 Accessing and Modifying Nodes 2420 ------------------------------------ 2421 2422 The node interface is cleanly defined using ‘cl-defstruct’. The primary 2423 method to access nodes is ‘org-roam-node-at-point’ and 2424 ‘org-roam-node-read’: 2425 2426 -- Function: org-roam-node-at-point &optional assert 2427 2428 Return the node at point. If ASSERT, throw an error if there is no 2429 node at point. 2430 2431 -- Function: org-roam-node-read &optional initial-input filter-fn 2432 sort-fn 2433 require-match 2434 2435 Read and return an ‘org-roam-node’. INITIAL-INPUT is the initial 2436 minibuffer prompt value. FILTER-FN is a function to filter out 2437 nodes: it takes a single argument (an ‘org-roam-node’), and when 2438 nil is returned the node will be filtered out. SORT-FN is a 2439 function to sort nodes. See 2440 ‘org-roam-node-read-sort-by-file-mtime’ for an example sort 2441 function. If REQUIRE-MATCH, the minibuffer prompt will require a 2442 match. 2443 2444 Once you obtain the node, you can use the accessors for the node, 2445 e.g. ‘org-roam-node-id’ or ‘org-roam-node-todo’. 2446 2447 It is possible to define (or override existing) properties on nodes. 2448 This is simply done using a ‘cl-defmethod’ on the ‘org-roam-node’ 2449 struct: 2450 2451 (cl-defmethod org-roam-node-namespace ((node org-roam-node)) 2452 "Return the namespace for NODE. 2453 The namespace is the final directory of the file for the node." 2454 (file-name-nondirectory 2455 (directory-file-name 2456 (file-name-directory (org-roam-node-file node))))) 2457 2458 The snippet above defines a new property ‘namespace’ on 2459 ‘org-roam-node’, which making it available for use in capture templates. 2460 2461 2462 File: org-roam.info, Node: Extending the Capture System, Prev: Accessing and Modifying Nodes, Up: Building Extensions and Advanced Customization of Org-roam 2463 2464 17.2.3 Extending the Capture System 2465 ----------------------------------- 2466 2467 Org-roam applies some patching over Org’s capture system to smooth out 2468 the user experience, and sometimes it is desirable to use Org-roam’s 2469 capturing system instead. The exposed function to be used in extensions 2470 is ‘org-roam-capture-’: 2471 2472 -- Function: org-roam-capture- &key goto keys node info props templates 2473 2474 Main entry point. GOTO and KEYS correspond to ‘org-capture’ 2475 arguments. INFO is a plist for filling up Org-roam’s capture 2476 templates. NODE is an ‘org-roam-node’ construct containing 2477 information about the node. PROPS is a plist containing additional 2478 Org-roam properties for each template. TEMPLATES is a list of 2479 org-roam templates. 2480 2481 An example of an extension using ‘org-roam-capture-’ is 2482 ‘org-roam-dailies’ itself: 2483 2484 (defun org-roam-dailies--capture (time &optional goto) 2485 "Capture an entry in a daily-note for TIME, creating it if necessary. 2486 2487 When GOTO is non-nil, go the note without creating an entry." 2488 (org-roam-capture- :goto (when goto '(4)) 2489 :node (org-roam-node-create) 2490 :templates org-roam-dailies-capture-templates 2491 :props (list :override-default-time time)) 2492 (when goto (run-hooks 'org-roam-dailies-find-file-hook))) 2493 2494 2495 File: org-roam.info, Node: Appendix, Next: Keystroke Index, Prev: Developer's Guide to Org-roam, Up: Top 2496 2497 18 Appendix 2498 *********** 2499 2500 * Menu: 2501 2502 * Note-taking Workflows:: 2503 * Ecosystem:: 2504 2505 2506 File: org-roam.info, Node: Note-taking Workflows, Next: Ecosystem, Up: Appendix 2507 2508 18.1 Note-taking Workflows 2509 ========================== 2510 2511 • Books 2512 • How To Take Smart Notes 2513 (https://www.goodreads.com/book/show/34507927-how-to-take-smart-notes) 2514 2515 • Articles 2516 • The Zettelkasten Method - LessWrong 2.0 2517 (https://www.lesswrong.com/posts/NfdHG6oHBJ8Qxc26s/the-zettelkasten-method-1) 2518 2519 • Building a Second Brain in Roam...And Why You Might Want To : 2520 RoamResearch 2521 (https://reddit.com/r/RoamResearch/comments/eho7de/building_a_second_brain_in_roamand_why_you_might) 2522 2523 • Roam Research: Why I Love It and How I Use It - Nat Eliason 2524 (https://www.nateliason.com/blog/roam) 2525 2526 • Adam Keesling’s Twitter Thread 2527 (https://twitter.com/adam_keesling/status/1196864424725774336?s=20) 2528 2529 • How To Take Smart Notes With Org-mode · Jethro Kuan 2530 (https://blog.jethro.dev/posts/how_to_take_smart_notes_org/) 2531 2532 • Threads 2533 • Ask HN: How to Take Good Notes 2534 (https://news.ycombinator.com/item?id=22473209) 2535 2536 • Videos 2537 • How to Use Roam to Outline a New Article in Under 20 Minutes 2538 (https://www.youtube.com/watch?v=RvWic15iXjk) 2539 2540 2541 File: org-roam.info, Node: Ecosystem, Prev: Note-taking Workflows, Up: Appendix 2542 2543 18.2 Ecosystem 2544 ============== 2545 2546 2547 File: org-roam.info, Node: Keystroke Index, Next: Command Index, Prev: Appendix, Up: Top 2548 2549 Appendix A Keystroke Index 2550 ************************** 2551 2552 2553 File: org-roam.info, Node: Command Index, Next: Function Index, Prev: Keystroke Index, Up: Top 2554 2555 Appendix B Command Index 2556 ************************ 2557 2558 2559 File: org-roam.info, Node: Function Index, Next: Variable Index, Prev: Command Index, Up: Top 2560 2561 Appendix C Function Index 2562 ************************* 2563 2564 2565 * Menu: 2566 2567 * org-roam-alias-add: Titles and Aliases. (line 25) 2568 * org-roam-alias-remove: Titles and Aliases. (line 30) 2569 * org-roam-buffer-display-dedicated: The Org-roam Buffer. (line 30) 2570 * org-roam-buffer-toggle: The Org-roam Buffer. (line 23) 2571 * org-roam-capture-: Extending the Capture System. 2572 (line 11) 2573 * org-roam-dailies-capture-date: Usage. (line 34) 2574 * org-roam-dailies-capture-today: Usage. (line 8) 2575 * org-roam-dailies-capture-yesterday: Usage. (line 21) 2576 * org-roam-dailies-find-directory: Usage. (line 50) 2577 * org-roam-dailies-goto-date: Usage. (line 43) 2578 * org-roam-dailies-goto-next-note: Usage. (line 58) 2579 * org-roam-dailies-goto-previous-note: Usage. (line 54) 2580 * org-roam-dailies-goto-today: Usage. (line 14) 2581 * org-roam-dailies-goto-yesterday: Usage. (line 27) 2582 * org-roam-graph: org-roam-graph. (line 14) 2583 * org-roam-node-at-point: Accessing and Modifying Nodes. 2584 (line 10) 2585 * org-roam-node-read: Accessing and Modifying Nodes. 2586 (line 15) 2587 * org-roam-ref-add: Refs. (line 30) 2588 * org-roam-ref-remove: Refs. (line 35) 2589 2590 2591 File: org-roam.info, Node: Variable Index, Prev: Function Index, Up: Top 2592 2593 Appendix D Variable Index 2594 ************************* 2595 2596 2597 * Menu: 2598 2599 * org-roam-completion-everywhere: Completing anywhere. (line 18) 2600 * org-roam-dailies-capture-templates: Configuration. (line 13) 2601 * org-roam-dailies-directory: Configuration. (line 8) 2602 * org-roam-db-extra-links-elements: What to cache. (line 34) 2603 * org-roam-db-extra-links-exclude-keys: What to cache. (line 48) 2604 * org-roam-db-update-on-save: When to cache. (line 15) 2605 * org-roam-graph-edge-extra-config: Graph Options. (line 26) 2606 * org-roam-graph-executable: org-roam-graph. (line 23) 2607 * org-roam-graph-extra-config: Graph Options. (line 15) 2608 * org-roam-graph-filetype: Graph Options. (line 11) 2609 * org-roam-graph-node-extra-config: Graph Options. (line 20) 2610 * org-roam-graph-viewer: org-roam-graph. (line 32) 2611 * org-roam-node-display-template: Customizing Node Completions. 2612 (line 10) 2613 2614 Emacs 29.0.50 (Org mode 9.6) 2615 2616 2617 Tag Table: 2618 Node: Top754 2619 Node: Introduction4514 2620 Ref: Introduction-Footnote-16659 2621 Node: Target Audience6768 2622 Node: A Brief Introduction to the Zettelkasten Method8644 2623 Node: Installation11802 2624 Node: Installing from MELPA12166 2625 Node: Installing from Source13181 2626 Node: Installation Troubleshooting16164 2627 Node: C Compiler16366 2628 Node: C Compiler for Windows16937 2629 Node: Getting Started18178 2630 Node: The Org-roam Node18470 2631 Node: Links between Nodes19298 2632 Node: Setting up Org-roam19703 2633 Node: Creating and Linking Nodes21310 2634 Node: Customizing Node Completions23030 2635 Node: Customizing Node Caching25250 2636 Node: How to cache25486 2637 Node: What to cache27679 2638 Node: When to cache29807 2639 Node: The Org-roam Buffer30576 2640 Node: Navigating the Org-roam Buffer32032 2641 Node: Configuring what is displayed in the buffer32748 2642 Node: Configuring the Org-roam buffer display34079 2643 Node: Styling the Org-roam buffer35580 2644 Node: Node Properties35792 2645 Node: Standard Org properties36011 2646 Node: Titles and Aliases36361 2647 Node: Tags37362 2648 Node: Refs38022 2649 Node: Citations39222 2650 Node: Using the Cached Information39788 2651 Node: Completion40935 2652 Node: Completing within Link Brackets41731 2653 Node: Completing anywhere42181 2654 Node: Encryption42957 2655 Node: The Templating System43713 2656 Node: Template Walkthrough44430 2657 Node: Org-roam Template Expansion46274 2658 Node: Extensions48161 2659 Node: org-roam-protocol48397 2660 Node: Installation (1)48859 2661 Node: Linux49701 2662 Node: Mac OS51227 2663 Ref: Testing org-protocol53265 2664 Node: Windows54278 2665 Node: The roam-node protocol55021 2666 Node: The roam-ref protocol55408 2667 Node: org-roam-graph56586 2668 Node: Graph Options58483 2669 Node: org-roam-dailies59505 2670 Node: Configuration59792 2671 Node: Usage60601 2672 Node: org-roam-export62397 2673 Node: Performance Optimization62917 2674 Node: Garbage Collection63123 2675 Node: The Org-mode Ecosystem63917 2676 Node: Browsing History with winner-mode64414 2677 Node: Versioning Notes65286 2678 Node: Full-text search with Deft66077 2679 Node: Org-journal66828 2680 Node: Org-download67640 2681 Node: mathpixel68157 2682 Node: Org-noter / Interleave68736 2683 Node: Bibliography69128 2684 Node: Spaced Repetition69889 2685 Node: FAQ70545 2686 Node: How do I have more than one Org-roam directory?71152 2687 Node: How do I create a note whose title already matches one of the candidates?72723 2688 Node: How can I stop Org-roam from creating IDs everywhere?73643 2689 Node: How do I migrate from Roam Research?74337 2690 Node: How to migrate from Org-roam v1?74834 2691 Node: How do I publish my notes with an Internet-friendly graph?76243 2692 Node: Configure org-mode for publishing77685 2693 Node: Overriding the default link creation function79171 2694 Node: Copying the generated file to the export directory79843 2695 Node: I'm seeing this ``Selecting deleted buffer'' error What do I do?80814 2696 Node: Developer's Guide to Org-roam81872 2697 Node: Org-roam's Design Principle82146 2698 Node: Building Extensions and Advanced Customization of Org-roam84136 2699 Node: Accessing the Database85398 2700 Node: Accessing and Modifying Nodes86127 2701 Node: Extending the Capture System88003 2702 Node: Appendix89545 2703 Node: Note-taking Workflows89732 2704 Node: Ecosystem91014 2705 Node: Keystroke Index91131 2706 Node: Command Index91282 2707 Node: Function Index91435 2708 Node: Variable Index93213 2709 2710 End Tag Table 2711 2712 2713 Local Variables: 2714 coding: utf-8 2715 End: