alpha-org

alpha-org is a powerful configuration for org-mode, similar to how Spacemacs and Doom are configurations for Emacs as a whole.

Screenshots

Theming is not included as part of this configuration; this is just an example showing doom-nord.

Usage

This can be used as a package which you install, or, since each feature is configured in its own use-package block, you may copy parts into your own config.

Installation

The easiest way to install the whole thing is with quelpa-use-package (which may be installed from MELPA), like so:

(require 'quelpa-use-package)
(use-package alpha-org
  :quelpa (alpha-org :fetcher github :repo "alphapapa/alpha-org"))

Sandbox

The script emacs-sandbox.sh can be used to try this configuration in a sandbox, separately from your existing Emacs configuration, like this:

$ emacs-sandbox.sh README.org

After Emacs opens this file, follow the instructions in the Installation section above, or load the alpha-org.el library, e.g. with M-x load-file RET alpha-org.el RET.

Key Bindings

To best demonstrate the power of this configuration, it’s necessary to bind some keys by default (because using M-x to access everything is relatively cumbersome). While this config isn’t designed to work with EVIL, similar to Spacemacs and Doom, all keys bound by this config are under a prefix key, which is M-SPC by default.

• Inserting
  • Links
    • M-SPC ilu Insert link to URL at point or on clipboard with org-web-tools.
  • Timestamps
    • M-SPC it Insert current, inactive timestamp.
    • M-SPC iT Insert current, active timestamp.
• Headings
  • M-SPC ha Go to heading in agenda files.
  • M-SPC hb Go to heading in current buffer.
  • M-SPC hp Go to parent of current heading.
  • M-SPC hr Go to a recent heading.
  • M-SPC hv Go to a visible heading.
• Refiling
  • M-SPC rv Refile current heading to any currently visible heading.
• View
  • M-SPC vs View default sidebars (org-sidebar-toggle).
  • M-SPC vt View tree sidebar (org-sidebar-tree-toggle).

DOING Tutorial / Demo

A step-by-step guide showing the use of some features would probably be helpful. Here’s a start:

1. Install the alpha-org package.
2. Open this README.org file.
3. Press M-SPC vt to show the tree sidebar, and again to hide it.
4. Press M-SPC vs to show the item sidebar, and again to hide it.
5. Select the tree sidebar window and press <S-tab> to globally cycle the tree’s outline visibility. Press <tab> or click mouse-2 to cycle individual trees.
6. Click on a heading (which one?) with mouse-1 in the tree sidebar to show that entry’s contents.
7. Press M-SPC vt to show the tree sidebar for just that entry.
8. In the tree sidebar, click and drag the on a heading to show more of its contents. Try clicking and dragging with both mouse-1 and mouse-2.

Requirements

These packages must already be installed:

• use-package

Code

Header

This header is tangled to alpha-org.el, declaring package dependencies so that they can be installed automatically.

;;; alpha-org.el --- A powerful Org configuration           -*- lexical-binding: t; -*-

;; Author: Adam Porter <[email protected]>
;; Keywords: outlines

;; Package-Requires: ((emacs "26.3") (use-package) (general) (avy) (which-key) (org-bullets) (org-make-toc) (org-sidebar) (org-sticky-header))

;;; License:

;; Copyright (C) 2019  Adam Porter

;; This program is free software; you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation, either version 3 of the License, or
;; (at your option) any later version.

;; This program is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;; GNU General Public License for more details.

;; You should have received a copy of the GNU General Public License
;; along with this program.  If not, see <https://www.gnu.org/licenses/>.

;;; Commentary:

;; `alpha-org' is a powerful configuration for `org-mode', similar to
;; how Spacemacs and Doom are configurations for Emacs as a whole.

;;; Code:

;;;; Requirements

(require 'use-package)

(require 'cl-lib)
(require 'subr-x)

Non-Org

Code and packages that aren’t directly Org-related.

General

General is used to ease configuration of key bindings.

(use-package general
  :config
  (global-unset-key (kbd "M-SPC"))
  (general-create-definer alpha-org/general-def
    :prefix "M-SPC"))

Prefix key variable?

Can I use a variable for this prefix key?

which-key

MAYBE Hydra

MAYBE hercules

Org

Code and packages that are directly Org-related.

Configuration

;;;; Configuration

;;  This section includes configuration code for options and packages built-in to Org.

Appearance

(use-package org
  :custom (org-ellipsis "⋯"))

Lists

(use-package org
  :custom
  (org-list-demote-modify-bullet '(("+" . "-") ("-" . "+"))))

Speed commands

Speed commands provide one-key bindings to quickly navigate and manipulate outlines.

(use-package org
  :custom
  (org-use-speed-commands (lambda ()
                            (and (looking-at org-outline-regexp)
                                 (looking-back "^\**")))))

Link to Org documentation for speed command keys

org-indent-mode

This mode displays text indented to match its heading’s indentation. Text is not actually indented in the buffer.

(add-hook 'org-mode-hook 'org-indent-mode)

Comparison screenshot

Packages

These packages are included and configured by default. Each package links to its configuration code later in this file.

;;;; Packages

Contents

Agenda [0/1]

org-super-agenda

Appearance / UI [0/2]

DOING org-sidebar

(use-package org-sidebar
  :general
  (alpha-org/general-def
   "vs" #'org-sidebar-toggle
   "vt" #'org-sidebar-tree-toggle)
  :custom (org-sidebar-tree-side 'left))

yequake

The yequake-org-capture function is used to provide a quick capturing UI with drop-down Emacs windows that disappear automatically when a capture is finalized or canceled.

org-bullets

This mode replaces heading stars with visually appealing ones. Its settings can be customized in the org-bullets group.

(use-package org-bullets
  :hook (org-mode . org-bullets-mode))

Screenshot

org-sticky-header

This package displays in the header-line the Org heading for the node that’s at the top of the window. This way, if the heading for the text at the top of the window is beyond the top of the window, you don’t forget which heading the text belongs to. The display can be customized to show just the heading, the full outline path, or the full outline path in reverse.

(use-package org-sticky-header
  :hook (org-mode . org-sticky-header-mode))

Screenshot

Capture

org-web-tools

(use-package org-web-tools
  :general
  (alpha-org/general-def
    "ilu" #'org-web-tools-link-for-url))

Headings

org-recent-headings

(use-package org-recent-headings
  :general
  (alpha-org/general-def
    "hr" #'org-recent-headings-helm)
  :config
  (org-recent-headings-mode)
  :custom
  (org-recent-headings-reverse-paths t)
  (org-recent-headings-candidate-number-limit 100))

org-bookmark-heading

helm-org

(use-package helm-org
  :general
  (alpha-org/general-def
    "ha" #'helm-org-agenda-files-headings
    "hb" #'helm-org-in-buffer-headings
    "hp" #'helm-org-parent-headings)
  :custom
  (helm-org-format-outline-path t))

Miscellaneous

org-make-toc

This package automates customizeable tables of contents in Org files.

(use-package org-make-toc
  :hook (org-mode . org-make-toc-mode))

MAYBE unpackaged

Not sure if I should use it or move its Org-related code into this.

DOING Avy

(use-package avy
  :general
  (alpha-org/general-def
    "hv" #'alpha-org/goto-visible-heading
    "rv" #'alpha-org/refile-to-visible)

  :config
  (defun alpha-org/refile-to-visible ()
    "Refile current heading as first child of visible heading selected with Avy."
    ;; Inspired by `org-teleport':
    ;; http://kitchingroup.cheme.cmu.edu/blog/2016/03/18/Org-teleport-headlines/
    (interactive)
    ;; NOTE: Use `when-let' so that if avy is aborted with "C-g",
    ;; `org-refile' won't be called with a nil refile location.
    (when-let ((marker (alpha-org/avy-marker)))
      (let* ((filename (buffer-file-name (or (buffer-base-buffer
                                              (marker-buffer marker))
                                             (marker-buffer marker))))
             (heading (org-with-point-at marker
                        (org-get-heading 'no-tags 'no-todo)))
             ;; NOTE: I guess this won't work with target buffers
             ;; whose filename is nil, but I doubt I'll ever want to
             ;; do that.
             (rfloc (list heading filename nil marker))
             (org-after-refile-insert-hook (cons #'org-reveal org-after-refile-insert-hook)))
        (org-refile nil nil rfloc))))

  (defun alpha-org/goto-visible-heading ()
    "Go to visible heading selected with Avy."
    (interactive)
    (when-let* ((marker (alpha-org/avy-marker)))
      (with-current-buffer (marker-buffer marker)
        (goto-char marker))))

  (defun alpha-org/avy-marker ()
    "Return marker at Org heading selected with Avy."
    (save-excursion
      (when-let* ((org-reverse-note-order t)
                  (pos (avy-with avy-goto-line
                         (avy-jump (rx bol (1+ "*") (1+ blank))))))
        (when (integerp (car pos))
          ;; If avy is aborted with "C-g", it returns
          ;; `t', so we know it was NOT aborted when it
          ;; returns an int.  If it doesn't return an
          ;; int, we return nil.
          (copy-marker (car pos)))))))

Searching [0/5]

org-ql

Other Code

Tree-to-indirect-buffer command

My own function that works a bit better than the built-in one.

Demo it

Agenda for subtree command

Demo it

Outline tidying

My function that fixes blank lines between entries.

org-return-dwim

Should demo this too.

Refile within buffer

(defun ap/org-refile-within-buffer ()
  "Call `org-refile' with `org-refile-targets' set to current buffer's headings."
  ;; This works now, but it doesn't fontify the headings/paths like
  ;; Helm does, so it's faster but doesn't look as nice
  (interactive)
  (let ((org-refile-use-cache nil)
        (org-refile-use-outline-path t)
        (org-refile-targets (list (cons (list (buffer-file-name (or (buffer-base-buffer (current-buffer))
                                                                    (current-buffer))))
                                        (cons :maxlevel 20)))))
    (call-interactively 'org-refile)))

Footer

;;;; Footer

(provide 'alpha-org)

;;; alpha-org.el ends here

Ideas

MAYBE Organize code by features rather than packages

Users are more interested in features than what packages implement them. Even if a package were mentioned in more than one use-package form, it would still be helpful, because users could copy features rather than whole packages into their own configs.

Update tree sidebar with idle timer

e.g. to hide text from added entries (unless I can figure another way around that).

MAYBE Use font-locking to hide entry content in tree sidebar

Suggested in a comment on Reddit. I think I noted it in org-sidebar’s notes file.

Dim background of sidebar windows

Maybe something like auto-dim-other-buffers.

Hook to update sidebar item buffers when file is saved

Seems like a natural way to update it, even if not optimal.

With prefix, insert timestamps with calendar prompt

mouse-2 on headings in non-tree buffers to cycle visibility

MAYBE Jump to characters/words with Avy

Include sandbox script for testing and demonstration

Demo org-return-dwim

Demo org-sticky-header

Show how scrolling down past the heading still shows it in the header line.

MAYBE Scripted GIF screencast

Like this script.

Notes

Discussions

{RFC, WIP} alpha-org (a configuration like Spacemacs or Doom, but just for Org) : orgmode

File Configuration

File-local configuration.