#+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, 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.
- +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][org-roam v2]].

** Packages
- [[doom-package:htmlize]]
- [[doom-package:ob-async]]
- [[doom-package:org]]
- [[doom-package:org-cliplink]]
- [[doom-package:org-contrib]]
- [[doom-package:ox-clip]]
- [[doom-package:toc-org]]

*** From Flags
- [[doom-module:+contacts]]
  - [[doom-package:org-contacts]]
- [[doom-module:+dragndrop]]
  - [[doom-package:org-download]]
- [[doom-module:+gnuplot]]
  - [[doom-package:gnuplot]]
  - [[doom-package:gnuplot-mode]]
- [[doom-module:+hugo]]
  - [[doom-package:ox-hugo]]
- [[doom-module:+jupyter]]
  - [[doom-package:jupyter]]
- [[doom-module:+noter]]
  - [[doom-package:org-noter]]
- [[doom-module:+pandoc]]
  - [[doom-package:ox-pandoc]]
- [[doom-module:+passwords]]
  - [[doom-package:org-passwords]]
- [[doom-module:+pomodoro]]
  - [[doom-package:org-pomodoro]]
- [[doom-module:+present]]
  - [[doom-package:centered-window]]
  - [[doom-package:org-tree-slide]]
  - [[doom-package:org-re-reveal]]
- [[doom-module:+pretty]]
  - [[doom-package:org-appear]]
  - [[doom-package:org-modern]]
- [[doom-module:+roam]]
  - [[doom-package:org-roam]]

*** From Modules
- [[doom-module::editor evil]]
  - [[doom-package:evil-org]]
- [[doom-module::lang crystal]]
  - [[doom-package:ob-crystal]]
- [[doom-module::lang go]]
  - [[doom-package:ob-go]]
- [[doom-module::lang nim]]
  - [[doom-package:ob-nim]]
- [[doom-module::lang racket]]
  - [[doom-package:ob-racket]]
- [[doom-module::lang rest]]
  - [[doom-package:ob-restclient]]
- [[doom-module::lang rst]]
  - [[doom-package:ox-rst]]
- [[doom-module::lang rust]]
  - [[doom-package:ob-rust]]
- [[doom-module::lang scala]]
  - [[doom-package:ob-ammonite]]
- [[doom-module::os macos]]
  - [[doom-package:org-mac-link]]
- [[doom-module::tools magit]]
  - [[doom-package:orgit]]
- [[doom-module::tools pdf]]
  - [[doom-package:org-pdftools]]

** 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 the [[doom-module:+roam]] flag) requires Emacs to be
  built with sqlite support.

** 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
#+end_src

For [[doom-module:+jupyter]], install =jupyterlab= or =jupyter-notebook= ([[https://wiki.archlinux.org/title/Jupyter][source]]).

** Debian & Ubuntu
#+begin_src sh
apt-get install texlive dvipng
apt-get install gnuplot
#+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~
- ~kagi:search terms~
- ~org:todo.org~ -> ={org-directory}/%s=
- ~wolfram:sin(x^3)~
- ~wikipedia:Emacs~
- ~youtube:P196hEuA_Xc~ (link only)

** 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
/There are no known problems with this module./ [[doom-report:][Report one?]]

* 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