:lang org
Description unfold
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 var:org-directory).
- 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-captureshell script and fn:+org-capture/open-frame. - 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 doom-module:+dragndrop flag).
- Integration with pandoc, 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 fn:+org/export-to-clipboard and fn:+org/export-to-clipboard-as-rich-text).
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.
https://www.mfoot.com/blog/2015/11/22/literate-emacs-configuration-with-org-mode/
Maintainers
Module flags
- +brain
- Enable doom-package:org-brain integration.
- +contacts
- Enable doom-package:org-contacts integration.
- +dragndrop
- Enable drag-and-drop support for images and files; inserts inline previews for images and an icon+link for other media types.
- +crypt
- Enable doom-package:org-crypt integraiton for encryption and decryption on org files.
- +gnuplot
- Install gnuplot & gnuplot-mode, which enables rendering images from gnuplot src blocks or plotting tables with fn:org-plot/gnuplot (bound to SPC m b p, by default).
- +hugo
- Enable integration with hugo to export from Emacs well-formed (blackfriday) markdown.
- +journal
- Enable doom-package:org-journal integration.
- +jupyter
- Enable Jupyter integration for babel.
- +noter
- Enable doom-package:org-noter integration. Keeps notes in sync with a document. Requires doom-module::tools pdf, DocView, or nov.el to be enabled.
- +pandoc
- Enable pandoc integration into the Org exporter.
- +passwords
- Enable doom-package:org-passwords integration.
- +pomodoro
- Enable a pomodoro timer for clocking time on tasks.
- +present
- Enable integration with reveal.js, beamer and org-tree-slide, so Emacs can be used for presentations. It automatically downloads reveal.js.
- +pretty
- Enable pretty unicode symbols for bullets+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.
- +roam
-
Enable integration with org-roam v1. This requires
sqlite3to be installed on your system. Incompatible with doom-module:+roam2. - +roam2
-
Enable integration with org-roam v2. This requires
sqlite3to be installed on your system. Incompatible with doom-module:+roam.
Packages
- doom-package:evil-org if doom-module::editor evil
- doom-package:htmlize
- doom-package:jupyter if doom-module:+jupyter
- doom-package:ob-ammonite if doom-module::lang scala
- doom-package:ob-async
- doom-package:ob-crystal if doom-module::lang crystal
- doom-package:ob-go if doom-module::lang go
- doom-package:ob-nim if doom-module::lang nim
- doom-package:ob-racket if doom-module::lang racket
- doom-package:ob-restclient if doom-module::lang rest
- doom-package:ob-rust if doom-module::lang rust
- doom-package:org-contacts if doom-module:+contacts
- doom-package:org-cliplink
- doom-package:org-download if doom-module:+dragndrop
- doom-package:orgit
- doom-package:org-noter if doom-module:+noter
- doom-package:org-pdftools if doom-module::tools pdf
- doom-package:org-plus-contrib
- doom-package:org-passwords if doom-module:+passwords
- doom-package:org-pomodoro if doom-module:+pomodoro
- doom-package:org-roam (v1) if doom-module:+roam
- doom-package:org-roam (v2) if doom-module:+roam2
- doom-package:ox-clip
- doom-package:ox-hugo if doom-module:+hugo
- doom-package:ox-pandoc if doom-module:+pandoc
- doom-package:ox-rst if doom-module::lang rst
- doom-package:toc-org
Hacks
- Adds support for a
:syncparameter for org src blocks. This overrides:async. - Gracefully degrades
:asyncbabel blocks to:syncwhen doom-package:ob-async would cause errors or issues (such as with a:sessionparameter, which doom-package: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 doom-module::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 face:error face 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:
(after! evil-org (remove-hook 'org-tab-first-hook #'+org-cycle-only-current-subtree-h)) - (Evil users) Nearby tables are formatted when exiting insert or replace mode (see fn:+org-enable-auto-reformat-tables-h).
- Statistics cookies are updated when saving the buffer of exiting insert mode (see fn:+org-enable-auto-update-cookies-h).
- Org-protocol has been lazy loaded (see fn:+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
fn:+org-init-babel-lazy-loader-h); loaded when a src block is executed. No need
to use var:org-babel-do-load-languages in 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 var:org-capture-template, it will be resolved relative to var:org-directory, instead of var:default-directory (see fn:+org--capture-expand-variable-file-a).
TODO Changelog
This module does not have a changelog yet.
Installation
Enable this module in your doom! block.
This module has no hard requirements, but these soft requirements are needed to use Org's more esoteric features:
- For inline LaTeX previews, doom-executable:latex and doom-executable:dvipng is needed.
- To render GNUPlot images (with doom-module:+gnuplot flag) the doom-executable:gnuplot program is needed.
- To execute babel code blocks, you need whatever dependencies those languages
need. It is recommended you enable the associated doom-module::lang module and ensure its
dependencies are met, e.g. install the doom-executable:ruby executable for ruby support. To
use
jupyter kernelsyou need the doom-module:+jupyter flag, the associated kernel as well as the doom-executable:jupyter program. - doom-package:org-roam (with doom-module:+roam or doom-module:+roam2 flag) requires doom-executable:sqlite3 to be installed.
MacOS
brew install --cask mactex
brew install gnuplotArch Linux
pacman -S texlive-core texlive-bin texlive-science texlive-latexextra
pacman -S gnuplot
For doom-module:+jupyter, install jupyterlab or jupyter-notebook (source).
Debian & Ubuntu
apt-get install texlive dvipng
apt-get install gnuplotNixOS
environment.systemPackages = with pkgs; [
# any less than medium isn't guaranteed to work
texlive.combined.scheme-medium
# required by +jupyter
(python38.withPackages(ps: with ps; [jupyter]))
];TODO Windows
TODO Usage
This module's usage documentation is incomplete. Complete it?
Invoking the org-capture frame from outside Emacs
The simplest way to use the org-capture frame is through the bin/org-capture
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.
emacsclient --eval '(+org-capture/open-frame INITIAL-INPUT KEY)'Built-in custom link types
This module defines a number of custom link types in +org-init-custom-links-h.
They are (with examples):
doom-docs:index.org->~/.emacs.d/docs/%sdoom-modules:editor/evil/README.org->~/.emacs.d/modules/%sdoom-repo:issues->https://github.com/hlissner/doom-emacs/%sdoom:core/core.el->~/.emacs.d/%sduckduckgo:search termsgimages:search terms(Google Images)github:hlissner/doom-emacsgmap:Toronto, Ontario(Google Maps)google:search termskagi:search termsorg:todo.org->{org-directory}/%swolfram:sin(x^3)wikipedia:Emacsyoutube:P196hEuA_Xc(link only)
evil-mode keybindings
For evil-mode users, an overview of org-mode keybindings is provided here.
TODO Configuration
This module's configuration documentation is incomplete. Complete it?
Changing org-directory
org-directory must be set before doom-package:org has loaded:
;; in $DOOMDIR/config.el
(setq org-directory "~/new/org/location/")
Changing org-noter-notes-search-path
;; in $DOOMDIR/config.el
(setq org-noter-notes-search-path '("~/notes/path/"))Troubleshooting
org-roam
Should I go with +roam (v1) or +roam2 (v2)?
Long story short: if you're new to doom-package:org-roam and haven't used it, then you should
go with doom-module:+roam2; if you already have an org-roam-directory with the v1 files in
it, then you can keep use doom-module:+roam for the time being, but it will eventually be
removed, so you should migrate at your earliest convenience.
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.
To learn more about v2 you can use the next resources:
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
your org-roam-directory before attempting to migrate.
In order to migrate from v1 to v2 using Doom follow the next steps:
- Enable doom-module:+roam2 flag (and disable doom-module:+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 -uin your shell. - Restart Emacs (if it was previously opened) and run
org-roam-migrate-wizardcommand (M-x org-roam-migrate-wizard RET). The wizard will automatically attempt to backup your previousorg-roam-directorytoorg-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.
Frequently asked questions
This module has no FAQs yet. Ask one?
TODO Appendix
This module has no appendix yet. Write one?