:lang org

Description

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-capture shell 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, 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 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

@hlissner

Become a maintainer?

Module flags

+brain: Enable org-brain integration.
+contacts: Enable 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.
+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.
+ipython: (**DEPRECATED**) Enable ipython integration for babel.
+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 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 sqlite3 to be installed on your system. Incompatible with doom-module:+roam2.
+roam2: Enable integration with org-roam v2. This requires sqlite3 to 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-ipython if doom-module:+ipython
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:org-yt
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
if doom-module:+gnuplot
- doom-package:gnuplot
- doom-package:gnuplot-mode
if doom-module:+present
- doom-package:centered-window
- doom-package:org-tree-slide
- doom-package:org-re-reveal
if doom-module:+pretty
- doom-package:org-superstar
- doom-package:org-fancy-priorities

Hacks

Adds support for a :sync parameter for org src blocks. This overrides :async.
Gracefully degrades :async babel blocks to :sync when doom-package:ob-async would cause errors or issues (such as with a :session parameter, 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).

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 kernels you 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 gnuplot

Arch Linux

pacman -S texlive-core texlive-bin texlive-science texlive-latexextra
pacman -S gnuplot
pacman -S jupyter # required by +jupyter

NixOS

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]))
];

Windows

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/%s
doom-modules:editor/evil/README.org -> ~/.emacs.d/modules/%s
doom-repo:issues -> https://github.com/hlissner/doom-emacs/%s
doom:core/core.el -> ~/.emacs.d/%s
duckduckgo:search terms
gimages:search terms (Google Images)
github:hlissner/doom-emacs
gmap:Toronto, Ontario (Google Maps)
google:search terms
org:todo.org -> {org-directory}/%s
wolfram:sin(x^3)
wikipedia:Emacs
youtube:P196hEuA_Xc (link only)
yt:P196hEuA_Xc (like youtube, but includes an inline preview of the video)

evil-mode keybindings

For evil-mode users, an overview of org-mode keybindings is provided here.

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

Report an issue?

`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:

Org-roam v2 Official Manual
Hitchhiker’s Rough Guide to Org roam V2
Releasing Org-roam v2 - Jethro Kuan’s blog
Thread about the redesign from Org-Roam Discourse

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-directory points to a directory with your v1 files.
Run $ doom sync -u in your shell.
Restart Emacs (if it was previously opened) and run org-roam-migrate-wizard command (M-x org-roam-migrate-wizard RET). The wizard will automatically attempt to backup your previous org-roam-directory to 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.

Frequently asked questions

This module has no FAQs yet. Ask one?

Appendix

🔨 This module has no appendix yet. Write one?

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.org

README.org

:lang org

Description

Maintainers

Module flags

Packages

Hacks

Changelog

Installation

MacOS

Arch Linux

NixOS

Windows

Usage

Invoking the org-capture frame from outside Emacs

Built-in custom link types

evil-mode keybindings

Configuration

Changing `org-directory`

Changing `org-noter-notes-search-path`

Troubleshooting

`org-roam`

Should I go with `+roam` (v1) or `+roam2` (v2)?

Migrating your existing files from v1 (`+roam`) to v2 (`+roam2`)

Frequently asked questions

Appendix

Files

README.org

Latest commit

History

README.org

File metadata and controls

:lang org

Description

Maintainers

Module flags

Packages

Hacks

Changelog

Installation

MacOS

Arch Linux

NixOS

Windows

Usage

Invoking the org-capture frame from outside Emacs

Built-in custom link types

evil-mode keybindings

Configuration

Changing org-directory

Changing org-noter-notes-search-path

Troubleshooting

org-roam

Should I go with +roam (v1) or +roam2 (v2)?

Migrating your existing files from v1 (+roam) to v2 (+roam2)

Frequently asked questions

Appendix

Changing `org-directory`

Changing `org-noter-notes-search-path`

`org-roam`

Should I go with `+roam` (v1) or `+roam2` (v2)?

Migrating your existing files from v1 (`+roam`) to v2 (`+roam2`)