Org layer

• Vim inspired key bindings are provided by evil-org-mode
• Nicer bullet via org-superstar-mode
• A pomodoro method integration via org-pomodoro
• Presentation mode via org-present
• Insertion of images via org-download
• Project-specific TODOs via org-project-capture
• Easy insert of URLs from clipboard with org format via org-cliplink
• Rich insert of code (into a source block with highlighting, and a link) from other buffers via org-rich-yank
• Pixel-perfect visual alignment for Org and Markdown tables via valign
• Text transclusion via org-transclusion

To use this configuration layer: in the main Spacemacs configuration file (~/.spacemacs), to the existing dotspacemacs-configuration-layers list add the org entry.

If you would like to enforce dependencies in your TODO hierarchy, this layer has some sane default configurations to try via its org-todo-dependencies-strategy configuration variable.

Setting it to 'naive-auto, will cause an entry to switch to DONE when all its subentries are done, and to TODO otherwise. This does not result in extra prompts for the user, but doesn't work well with more workflow states because of the literal DONE and TODO; it is an excellent place for beginners and minimalists:

(setq-default dotspacemacs-configuration-layers '(
  (org :variables
       org-todo-dependencies-strategy 'naive-auto)))

Setting it to 'semiauto, will cause the user to be prompted to change an entry's state when the state of the subentries imply it: that is, when they are either all done while it is still a todo, or the when they are all still todo's while it is done. This assumes next to nothing about your workflow states (it does not use literal TODO and DONE), but may result in additional, possibly surprising, prompting for the user; and it has no intelligence to attempt to determine the destination state. It is a good thing to try if 'naive-auto does not accomplish what you need:

(setq-default dotspacemacs-configuration-layers '(
  (org :variables
       org-todo-dependencies-strategy 'naive-auto)))

If neither of these suffice for you, org-mode can be configured directly by setting org-enforce-todo-dependencies to t and writing your own function to register on the org-after-todo-statistics-hook. The layer implementation is a good reference.

To enable notifications for agenda events, set the variable org-enable-notifications to t.

(setq-default dotspacemacs-configuration-layers '(
  (org :variables
       org-enable-notifications t
       org-start-notification-daemon-on-startup t)))

This will install and configure the org-wild-notifier package. After install, run the org-wild-notifier-mode to start the org-wild-notifier notification daemon. To start the notification daemon automatically on Spacemacs startup, set the variable org-start-notification-daemon-on-startup to t as shown in the code snippet above.

Check the documentation for how org-wild-notifier can be configured (org-wild-notifier uses the alert package for showing notifications. On GNU/linux and Windows, using alert's notifications style is recommended. Note also this issue). Add your preferred alert style to dotspacemacs/user-config with:

(setq alert-default-style 'notifications)

Press M-S RET to enter a todo headline and then press , d t to add a timestamp to the headline (using , d t requires the diary-file variable to point to an existing file, see Agenda recommendations. You can also use the org-journal-new-scheduled-entry that becomes available by enabling org-journal support). By default, the org-wild-notifier package will scan your org-agenda-files (every minute) for TODO headlines that include a timestamp (configuration options are documented here). The default configuration shows a notification 10 minutes before the event using the alert package. The default behavior can be configured via the org-wild-notifier-alert-time variable. The notification type can be configured via the the alert package its configuration settings. Additional notification times can be added using the :WILD_{NOTIFIERNOTIFYBEFORE}: keyword (note that this additionally requires a SCHEDULED: stamp). Properties can be added with , i p.

Emacs comes with its own diary package included. It is recommended not to use the diary directly. Instead of creating a diary file, create a diary.org file and set the diary-file variable to point to that file. To make the holidays, birthdays etc. from the diary show up in the agenda, add the diary-style expression entries to your diary.org file as shown in the code block of the Calendar/Diary integration section here.

Subsequently, to add appointments to the agenda you could use the following syntax:

* Friday, 04/02/2021
  ** Appointment 1
  <2021-04-02 Fri 10:10>
  ** TODO Appointment 2
  <2021-04-02 Fri 10:11>

or just use the org journal system. Outside org-journal you can still use org-journal-insert-header-at-point to create the date headers. In the source block above, the first appointment will just show up in the agenda. If org-wild-notifier is configured, then the second appointment will also trigger a notification 10 minutes (by default) before its due time (see Agenda notifications).

To install GitHub related extensions like ox-gfm to export to GitHub flavored markdown set the variable org-enable-github-support to t.

(setq-default dotspacemacs-configuration-layers '(
  (org :variables org-enable-github-support t)))

To enable the export to Twitter Bootstrap-formatted HTML - set the variable org-enable-bootstrap-support to t. This would install the ox-twbs extension.

(setq-default dotspacemacs-configuration-layers '(
  (org :variables
       org-enable-bootstrap-support t)))

Org-mode supports the plotting of data within tables through Gnuplot as demonstrated here.

Unfortunately, this is not terribly well supported on Windows, at this stage. To disable the configuration of gnuplot support - add the gnuplot package to your dotspacemacs-excluded-packages variable.

To enable the export of org files as a reveal.js presentation - set the variable org-enable-reveal-js-support to t. This would install the org-re-reveal Emacs extension.

(setq-default dotspacemacs-configuration-layers
 '((org :variables org-enable-reveal-js-support t)))

Then the extension needs to be pointed to the reveal.js itself. So download reveal.js and point org-re-reveal-root to the path, as it described in the manual.

Alternatively, add the following line to each .org file you want to process:

#+REVEAL_ROOT: https://cdn.jsdelivr.net/npm/reveal.js@3.8.0

org-contacts is a handy contacts management system. It can be used to manage (email) addresses (compatible with gnus, mu4e, notmuch etc.), birthdays and more. It is simpler than bbdb/ebdb and probably powerful enough for most users.

To install org-contacts, set the variable org-enable-org-contacts-support to t. Optionally, also set the variable org-contacts-files and add a capture template. The value of the org-contacts-files variable should be a list with filenames to use as contact sources. If set to nil (default) then all your Org files will be used. The first file in the org-contacts-files list can be visited with the keyboard shortcut SPC a o C f.

(org :variables org-enable-org-contacts-support t
     org-contacts-files '("~/Org/contacts.org" "~/Org/file2.org")
     org-capture-templates '(("c" "Contacts" entry (file "~/Org/contacts.org")
                              "* %(org-contacts-template-name)
:PROPERTIES:
:EMAIL: %(org-contacts-template-email)
:END:")))

A more elaborate capture template can be found in the org-contacts.el file.

Contacts can include the :BIRTHDAY: keyword. To include the birthdays in your org-agenda add %%(org-contacts-anniversaries) to one of your contacts files. It is important that this is inserted after a heading an that it has no preceding whitespace. So probably the best way is to add

* Birthdays
%%(org-contacts-anniversaries)

to the beginning or the end of one of your contacts files.

org-journal is a simple journal management system that:

• Keeps a separate journal file for each day inside a directory
• New daily file would always migrate entries with chosen TODO states
• Has journal encryption functionality
• Easily integrates with org-agenda and Emacs calendar, iCalendar, allows scheduling
• Easily integrates with org-capture

To install org-journal - set the variable org-enable-org-journal-support to t.

(setq-default dotspacemacs-configuration-layers '(
  (org :variables
       org-enable-org-journal-support t)))

By default, journal files are stored in ~/Documents/journal/. To override this - set org-journal-dir variable in the dotspacemacs/user-config:

(setq org-journal-dir "~/org/journal/")

To change the journal file name format - alter org-journal-file-format:

(setq org-journal-file-format "%Y-%m-%d")

Warning: setting org-journal-file-format to include a file extension like %Y-%m-%d.org would break the calendar search functionality.

By default, journal files are started with a first level heading (*) followed by the date in the form set by locale. To format journal files differently:

• alter org-journal-date-prefix and org-journal-date-format. For example, to have new journal files created with this header:

  #+TITLE: Tuesday, September 06 2016
  

• define the following in dotspacemacs/user-config:

  (setq org-journal-date-prefix "#+TITLE: ")
  (setq org-journal-date-format "%A, %B %d %Y")
  

The default entry is a second level heading (=** =) followed by a timestamp. If you start your journal files with a Title as shown above you may want to adjust entries to start at the first level heading and you may want to change or omit the timestamp.

(setq org-journal-time-prefix "* ")
(setq org-journal-time-format "")

Any of the org-journal settings can be configured in dotspacemacs/user-config or defined alongside the layer itself.

For example:

(setq-default dotspacemacs-configuration-layers '(
  (org :variables
      org-enable-org-journal-support t
      org-journal-dir "~/org/journal/"
      org-journal-file-format "%Y-%m-%d"
      org-journal-date-prefix "#+TITLE: "
      org-journal-date-format "%A, %B %d %Y"
      org-journal-time-prefix "* "
      org-journal-time-format "")
)

To install the Org exporter ox-hugo that generates Hugo -compatible Markdown plus TOML/YAML front-matter, set the variable org-enable-hugo-support to t.

(setq-default dotspacemacs-configuration-layers '(
  (org :variables
       org-enable-hugo-support t)))

To install Trello support set the variable org-enable-trello-support to t.

(setq-default dotspacemacs-configuration-layers '(
  (org :variables
       org-enable-trello-support t)))

You can tweak the bullets displayed in the org buffer in the function dotspacemacs/user-config of your dotfile by setting the variable org-superstar-headline-bullets-list. By default the list is set to (?◉ ?○ ?✸ ?✿).

(setq org-superstar-headline-bullets-list '(?■ ?◆ ?▲ ?▶))

You can disable the fancy bullets entirely by adding org-superstar to dotspacemacs-excluded-packages.

(dotspacemacs-excluded-packages '(org-superstar))

Set the layer variable org-project-capture-projects-file to the filename where you want to store project-specific TODOs. If this is an absolute path, all todos will be stored in the same file (organized by project), whereas if it is just a single filename, todos will be stored in each project root.

We currently only support org-projectile as backend as it supports more features than the build in project.el alternative.

(setq-default dotspacemacs-configuration-layers
  '((org :variables org-project-capture-projects-file "TODOs.org")))

The TODO files are not added to the agenda automatically. You can do this with the following snippet.

(with-eval-after-load 'org-agenda
  (require 'org-project-capture)
  (mapcar '(lambda (file)
                 (when (file-exists-p file)
                   (push file org-agenda-files)))
          (org-project-capture-projects-file)))

For Emacs 25 or later, to install org-brain set the variable org-enable-org-brain-support to t.

See the org-brain package documentation for more information.

To install org-roam support set the variable org-enable-roam-support to t.

(setq-default dotspacemacs-configuration-layers '(
  (org :variables
       org-enable-roam-support t)))

More information about org-roam package (including manual) can be found at Org-roam website.

To temporarily enable mode line display of org clock, press SPC t m c.

To permanently enable mode line display of org clock, add this snippet to your dotspacemacs/user-config function:

(setq spaceline-org-clock-p t)

To install sticky header support set the variable org-enable-sticky-header to t.

(setq-default dotspacemacs-configuration-layers '(
  (org :variables
       org-enable-sticky-header t)))

To install the Org exporter ox-epub that generates e-book file format epub, set the variable org-enable-epub-support to t.

(setq-default dotspacemacs--configuration-layers
              '((org :variables
                     org-enable-epub-support t)))

To bring Jira and OrgMode together over org-jira set the variable org-enable-jira-support to t.

(setq-default dotspacemacs-configuration-layers '(
  (org :variables
       org-enable-jira-support t
       jiralib-url "https://yourcompany.atlassian.net:443")))

If you would like to avoid being prompted for your login and password each time you connect, add your authentication credentials to ~/.authinfo.gpg or ~/.authinfo:

machine yourcompany.atlassian.net login you@example.com password yourPassword port 443

To install valign. Which provides: Pixel-perfect visual alignment for Org and Markdown tables. Set the variable org-enable-valign to t:

(setq-default dotspacemacs-configuration-layers
 '((org :variables org-enable-valign t)))

Known problem: Rendering large tables (≥100 lines) is laggy.

org-modern beautifies org files with many visual enhancements. It toggles visibility of some markers, changes faces of common elements and just "modernizes" the visual appearance. To enable it by default, set the org-enable-modern-support to t:

(setq-default dotspacemacs-configuration-layers
 '((org :variables org-enable-modern-support t)))

To toggle its features, either call M-x org-modern-mode or ESC , T m.

To install org-appear, which toggles visibility of emphasis markers, links, subscripts, and superscripts in org mode, set the org-enable-appear-support to t:

(setq-default dotspacemacs-configuration-layers
 '((org :variables org-enable-appear-support t)))

If you set org-appear-trigger to manual and your editing style is vim or hybrid, org-appear is turned on in insert mode but not in normal mode.

To install org-transclusion, which allows you to include a view of another file via a file link or an ID lin, set the org-enable-transclusion-support to t:

(setq-default dotspacemacs-configuration-layers
 '((org :variables org-enable-transclusion-support t)))

To install Verb, an HTTP client based on Org mode, set the org-enable-verb-support variable to t:

(setq-default dotspacemacs-configuration-layers
 '((org :variables org-enable-verb-support t)))

To install Org exporter ox-asciidoc, that generates AsciiDoc documents, set the variable org-enable-asciidoc-support to t.

(setq-default dotspacemacs-configuration-layers
  '((org :variables org-enable-asciidoc-support t)))

A Spacemacs custom layout @Org is defined by the layer and accessible via SPC l o. The startup behavior can be customized with the following layer variables:

• org-persp-startup-org-file Defines the org file buffer that should be opened after startup. Defaults to the first file in org-agenda-files, if org-persp-startup-org-file is set to nil.
• org-persp-startup-with-agenda If non-nil, sets initial buffer to the specified (custom) org-agenda buffer, e.g. (setq org-persp-startup-with-agenda "a") opens org-agenda-list.

Please see the evil-org documentation for additional instructions on customizing evil-org-mode.

Insert state In evil insert-state, use the introspection functions under M-m h d and M-RET to discover key bindings. The following table shows keybindings for some of the most frequently used commands

Normal state

If the layer variable org-want-todo-bindings is true, the following bindings are also available.

Besides the key bindings mentioned here it is recommended to use the auto-completion layer and its yasnippet key bindings in particular.

org-capture-mode and org-src-mode both support the confirm and abort conventions.

org-present must be activated explicitly by typing: SPC SPC org-present

Journal entries are highlighted in the calendar. The following key bindings are available for calendar-mode for navigating and manipulating the journal.

While viewing a journal entry in org-journal-mode the following key bindings are available.

Key binding prefixes:

• SPC a o J (everywhere)
• SPC m m j (in an org-mode buffer)

Key binding prefixes:

• SPC a o r (anywhere)
• SPC m r (in an org-mode buffer)

org-roam buffer