Organize your plain life in plain text
This module adds org-mode support to Doom Emacs, along with a number of adjustments, extensions and reasonable defaults to make it more performant and intuitive out of the box:
- A custom, centralized attachment system that stores files in one place, rather
than in the same directory as the input file(s) (only applies to attachments
from files in/under
- Executable code blocks with support for a variety of languages and tools (depending on what :lang modules are enabled).
- Supports an external org-capture workflow through the bin/org-capture shell
- A configuration for using org-mode for slide-show presentations or exporting org files to reveal.js slideshows.
- Drag-and-drop support for images (with inline preview) and media files (drops a file icon and a short link) (requires +dragndrop flag).
- Integration with pandoc, ipython, jupyter, reveal.js, beamer, and others (requires flags).
- Export-to-clipboard functionality, for copying text into formatted html,
markdown or rich text to the clipboard (see
Org is a system for writing plain text notes with syntax highlighting, code execution, task scheduling, agenda management, and many more. The whole idea is that you can write notes and mix them with references to things like articles, images, and example code combined with the output of that code after it is executed.
1.1. Module flags
- Enable org-brain integration.
- Enable drag-and-drop support for images and files; inserts inline previews for images and an icon+link for other media types.
- Install gnuplot and
gnuplot-mode, which enables rendering images from gnuplot src blocks or plotting tables with
org-plot/gnuplot(bound to <localleader> b p, by default).
- Enables integration with hugo to export from Emacs well-formed (blackfriday) markdown.
- (DEPRECATED) Enable ipython integration for babel.
- Enable org-journal integration.
- Enable Jupyter integration for babel.
- Enable org-noter integration. Keeps notes in sync with a document. Requires pdf-tools (:tools pdf), DocView, or nov.el to be enabled.
- Enable pandoc integration into the Org exporter.
- Enable a pomodoro timer for clocking time on tasks.
- Enable integration with reveal.js, beamer and org-tree-slide, so Emacs can be used for presentations. It automatically downloads reveal.js.
- Enables pretty unicode symbols for bullets and priorities, and better syntax highlighting for latex. Keep in mind: this can be expensive. If org becomes too slow, it’d be wise to disable this flag.
- Enables integration with org-roam v1. Requires sqlite3 on your system. Incompatible with +roam2.
- Enables integration with org-roam v2. Requires sqlite3 on your system. Incompatible with +roam. This flag will replace +roam in mid-2022.
- if :lang crystal
- if :lang go
- if :lang nim
- if :lang racket
- if :lang rest
- if :lang rst
- if :lang rust
- if :lang scala
- if :editor evil
- if :tools pdf
- if +dragndrop
- if +gnuplot
- if +hugo
- if +ipython
- if +jupyter
- if +pandoc
- if +pomodoro
- if +present
- if +pretty
- if +roam
- org-roam (v1)
- if +roam2
- org-roam (v2)
- if +noter
- Adds support for a
:syncparameter for org src blocks. This overrides
- Gracefully degrades
:asyncbabel blocks to
:syncwhen ob-async would cause errors or issues (such as with a
:sessionparameter, which ob-async does not support, or when exporting org documents).
- The window is recentered when following links.
- The breadcrumbs displayed in eldoc when hovering over an org headline has been reworked to strip out link syntax and normalize font-size disparities.
- If :ui workspaces is enabled, persp-mode won’t register org agenda buffers that are temporarily opened in the background.
- Temporary org agenda files aren’t added to recentf.
file:links are highlighted with the
errorface if they are broken.
TAB was changed to toggle only the visibility state of the current subtree, rather than cycle through it recursively. This can be reversed with:
- (Evil users) Nearby tables are formatted when exiting insert or replace mode
- Statistics cookies are updated when saving the buffer of exiting insert mode
- Org-protocol has been lazy loaded (see
+org-init-protocol-lazy-loader-h); loaded when the server receives a request for an org-protocol:// url.
- Babel and babel plugins are now lazy loaded (see
+org-init-babel-lazy-loader-h); loaded when a src block is executed. No need to use
org-babel-do-load-languagesin your config, just install your babel packages to extend language support (and ensure its
org-babel-execute:*function is autoloaded).
- If a variable is used as a file path in
org-capture-template, it will be resolved relative to
org-directory, instead of
Org has a few soft dependencies that you will need to make use of Org’s more esoteric features:
- For inline LaTeX previews,
- To render GNUPlot images (with +gnuplot flag) the
gnuplotprogram is needed.
- To execute babel code blocks, you need whatever dependencies those languages
need. It is recommended you enable the associated :lang module and ensure its
dependencies are met, e.g. install the ruby executable for ruby support. To
jupyter kernelsyou need the +jupyter flag, the associated kernel as well as the
- org-roam (with +roam or +roam2 flag) requires sqlite3 to be installed.
2.2. Arch Linux
2.4. TODO Windows
This module’s usage documentation is incomplete. Complete it?
3.1. Invoking the org-capture frame from outside Emacs
The simplest way to use the org-capture frame is through the
script. I’d recommend binding a shortcut key to it. If Emacs isn’t running, it
will spawn a temporary daemon for you.
Alternatively, you can call
+org-capture/open-frame directly, e.g.
3.2. Built-in custom link types
This module defines a number of custom link types in
They are (with examples):
gimages:search terms(Google Images)
gmap:Toronto, Ontario(Google Maps)
yt:P196hEuA_Xc(like youtube, but includes an inline preview of the video)
This module’s configuration documentation is incomplete. Complete it?
5.1.1. Should I go with +roam (v1) or +roam2 (v2)?
Long story short: if you’re new to org-roam and haven’t used it, then you should
go with +roam2; if you already have an
org-roam-directory with the v1 files in
it, then you can keep use +roam for a time being.
V1 isn’t actively maintained anymore and is now basically EOL. This means that the feature disparity between the both will continue to grow, while its existing bugs and problems won’t be addressed, at least by the main maintainers. V2 can be considered as a complete rewrite of the package so it comes with a lot of breaking changes.
While v1 won’t be actively maintained anymore, it still will be available in Doom for a while, at least until there will be a reliable tool that will migrate your data from v1 to v2.
To learn more about v2 you can use the next resources:
5.1.2. Migrating your existing files from v1 (+roam) to v2 (+roam2)
V2 comes with a migration wizard for v1 users. It’s new, which means issues can
appear during the migration process. Because of that, don’t forget to backup
org-roam-directory before attempting to migrate.
In order to migrate from v1 to v2 using Doom follow the next steps:
- Enable +roam2 flag (and disable +roam if it was previously enabled) in your init.el.
- Ensure your
org-roam-directorypoints to a directory with your v1 files.
- Run $ doom sync -u in your shell.
- Restart Emacs (if it was previously opened) and run
M-x org-roam-migrate-wizard RET). The wizard will automatically attempt to backup your previous
org-roam-directoryto org-roam.bak, but just in case backup it yourself too.
- After the wizard is done you should be good to go. Verify the integrity of your data and whether it did everything as expected. In case of failure report your issue.
6. TODO Appendix
This module has no appendix yet. Write one?