alpha-org is a powerful configuration for org-mode, similar to how Spacemacs and Doom are configurations for Emacs as a whole.
Theming is not included as part of this configuration; this is just an example showing doom-nord.
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.
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"))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.
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 iluInsert link to URL at point or on clipboard withorg-web-tools.
- Timestamps
M-SPC itInsert current, inactive timestamp.M-SPC iTInsert current, active timestamp.
- Links
- Headings
M-SPC haGo to heading in agenda files.M-SPC hbGo to heading in current buffer.M-SPC hpGo to parent of current heading.M-SPC hrGo to a recent heading.M-SPC hvGo to a visible heading.
- Refiling
M-SPC rvRefile current heading to any currently visible heading.
- View
M-SPC vsView default sidebars (org-sidebar-toggle).M-SPC vtView tree sidebar (org-sidebar-tree-toggle).
A step-by-step guide showing the use of some features would probably be helpful. Here’s a start:
- Install the
alpha-orgpackage. - Open this
README.orgfile. - Press
M-SPC vtto show the tree sidebar, and again to hide it. - Press
M-SPC vsto show the item sidebar, and again to hide it. - Select the tree sidebar window and press
<S-tab>to globally cycle the tree’s outline visibility. Press<tab>or clickmouse-2to cycle individual trees. - Click on a heading (which one?) with
mouse-1in the tree sidebar to show that entry’s contents. - Press
M-SPC vtto show the tree sidebar for just that entry. - In the tree sidebar, click and drag the on a heading to show more of its contents. Try clicking and dragging with both
mouse-1andmouse-2.
These packages must already be installed:
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 <adam@alphapapa.net>
;; 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)Code and packages that aren’t directly Org-related.
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"))Can I use a variable for this prefix key?
MAYBE hercules
Code and packages that are directly Org-related.
;;;; Configuration
;; This section includes configuration code for options and packages built-in to Org.(use-package org
:custom (org-ellipsis "⋯"))(use-package org
:custom
(org-list-demote-modify-bullet '(("+" . "-") ("-" . "+"))))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 "^\**")))))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)These packages are included and configured by default. Each package links to its configuration code later in this file.
;;;; Packages(use-package org-sidebar
:general
(alpha-org/general-def
"vs" #'org-sidebar-toggle
"vt" #'org-sidebar-tree-toggle)
:custom (org-sidebar-tree-side 'left))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.
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))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))(use-package org-web-tools
:general
(alpha-org/general-def
"ilu" #'org-web-tools-link-for-url))(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))(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))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.
(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)))))))My own function that works a bit better than the built-in one.
My function that fixes blank lines between entries.
Should demo this too.
(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
(provide 'alpha-org)
;;; alpha-org.el ends here
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.
e.g. to hide text from added entries (unless I can figure another way around that).
Suggested in a comment on Reddit. I think I noted it in org-sidebar’s notes file.
Maybe something like auto-dim-other-buffers.
Seems like a natural way to update it, even if not optimal.
Show how scrolling down past the heading still shows it in the header line.
Like this script.
File-local configuration.