310 lines
14 KiB
Org Mode
310 lines
14 KiB
Org Mode
#+title: :lang org
|
|
#+subtitle: Organize your plain life in plain text
|
|
#+created: February 20, 2017
|
|
#+since: 2.0.0
|
|
|
|
* 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-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).
|
|
|
|
#+begin_quote
|
|
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/
|
|
#+end_quote
|
|
|
|
** Maintainers
|
|
- [[doom-user:][@hlissner]]
|
|
|
|
[[doom-contrib-maintainer:][Become a maintainer?]]
|
|
|
|
** 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 [[kbd:][SPC m b p]], by
|
|
default).
|
|
- +hugo ::
|
|
Enable integration with [[https://gohugo.io][hugo]] to export from Emacs well-formed ([[https://github.com/russross/blackfriday][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]], [[https://www.gnu.org/software/emacs/manual/html_node/emacs/Document-View.html][DocView]], or [[https://github.com/wasamasa/nov.el][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 [[https://github.com/hakimel/reveal.js][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 [[https://github.com/org-roam/org-roam-v1][org-roam v1]]. This requires ~sqlite3~ to be installed
|
|
on your system. /Incompatible with [[doom-module:+roam2]]./
|
|
- +roam2 ::
|
|
Enable integration with [[https://github.com/org-roam/org-roam][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:
|
|
|
|
#+begin_src emacs-lisp
|
|
(after! evil-org
|
|
(remove-hook 'org-tab-first-hook #'+org-cycle-only-current-subtree-h))
|
|
#+end_src
|
|
- (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 section will be machine generated. Don't edit it by hand.
|
|
/This module does not have a changelog yet./
|
|
|
|
* Installation
|
|
[[id:01cffea4-3329-45e2-a892-95a384ab2338][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
|
|
#+begin_src sh
|
|
brew install --cask mactex
|
|
brew install gnuplot
|
|
#+end_src
|
|
|
|
** Arch Linux
|
|
#+begin_src sh
|
|
pacman -S texlive-core texlive-bin texlive-science texlive-latexextra
|
|
pacman -S gnuplot
|
|
pacman -S jupyter # required by +jupyter
|
|
#+end_src
|
|
|
|
** NixOS
|
|
#+begin_src nix
|
|
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]))
|
|
];
|
|
#+end_src
|
|
|
|
** TODO Windows
|
|
|
|
* TODO Usage
|
|
#+begin_quote
|
|
/This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
|
|
#+end_quote
|
|
|
|
** 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.
|
|
#+begin_src sh
|
|
emacsclient --eval '(+org-capture/open-frame INITIAL-INPUT KEY)'
|
|
#+end_src
|
|
|
|
** 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 [[https://github.com/Somelauw/evil-org-mode/blob/master/README.org#keybindings][here]].
|
|
|
|
* TODO Configuration
|
|
#+begin_quote
|
|
/This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
|
|
#+end_quote
|
|
|
|
** Changing ~org-directory~
|
|
~org-directory~ must be set /before/ [[doom-package:org]] has loaded:
|
|
#+begin_src emacs-lisp
|
|
;; in $DOOMDIR/config.el
|
|
(setq org-directory "~/new/org/location/")
|
|
#+end_src
|
|
|
|
** Changing ~org-noter-notes-search-path~
|
|
#+begin_src emacs-lisp
|
|
;; in $DOOMDIR/config.el
|
|
(setq org-noter-notes-search-path '("~/notes/path/"))
|
|
#+end_src
|
|
|
|
* Troubleshooting
|
|
[[doom-report:][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 [[https://www.orgroam.com/manual.html#How-to-migrate-from-Org_002droam-v1_003f][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:
|
|
- [[https://github.com/org-roam/org-roam/blob/master/doc/org-roam.org][Org-roam v2 Official Manual]]
|
|
- [[https://github.com/org-roam/org-roam/wiki/Hitchhiker's-Rough-Guide-to-Org-roam-V2][Hitchhiker's Rough Guide to Org roam V2]]
|
|
- [[https://blog.jethro.dev/posts/org_roam_v2/][Releasing Org-roam v2 - Jethro Kuan's blog]]
|
|
- [[https://org-roam.discourse.group/t/org-roam-major-redesign/1198][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:
|
|
1. Enable [[doom-module:+roam2]] flag (and disable [[doom-module:+roam]] if it was previously enabled) in your
|
|
=init.el=.
|
|
2. Ensure your ~org-roam-directory~ points to a directory with your v1 files.
|
|
3. Run ~$ doom sync -u~ in your shell.
|
|
4. 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.
|
|
4. 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
|
|
[[https://github.com/org-roam/org-roam/issues][report]] your issue.
|
|
|
|
* Frequently asked questions
|
|
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
|
|
|
|
* TODO Appendix
|
|
#+begin_quote
|
|
This module has no appendix yet. [[doom-contrib-module:][Write one?]]
|
|
#+end_quote
|