Elsa Gonsiorowski

Emacs Carnival: Org Mode Completions

gonsie@me.com (Elsa Gonsiorowski) — Sat, 28 Feb 2026 00:00:00 +0000

I’m so happy to be joining this month’s emacs carnival! I love the idea behind these carnivals and I think it’s such a good way of building community virtually.

This month’s topic is Emacs completions. I’m going to share a sort of “hack”… a way that I’ve been able to achieve completions within core org mode.

Org Mode Tempo Templates

Org Mode has long supported a template expansion mechanism, some times called “easy templates” or “structured templates”. The default behavior changed dramatically in version 9.2, and is now built on top of the Emacs builtin tempo.el.

Update To get the behavior described here, you must add (require 'org-tempo) to your config.

Essentially, you start a new line with <X (where X is a pre-defined key), then hit TAB to have the template expanded. For example, starting a new line with:

<s

and hitting TAB will expand to:

#+begin_src

#+end_src

Super handy and very easy to remember.

Default templates

The default are not entirely documented, though most are listed on the Structured Templates manual page.

Listed again here for convenience:

Key	Expansion
<a	`#+BEGIN_EXPORT ascii … #+END_EXPORT`
<c	`#+BEGIN_CENTER … #+END_CENTER`
<C	`#+BEGIN_COMMENT … #+END_COMMENT`
<e	`#+BEGIN_EXAMPLE … #+END_EXAMPLE`
<E	`#+BEGIN_EXPORT … #+END_EXPORT`
<h	`#+BEGIN_EXPORT html … #+END_EXPORT`
<l	`#+BEGIN_EXPORT latex … #+END_EXPORT`
<q	`#+BEGIN_QUOTE … #+END_QUOTE`
<s	`#+BEGIN_SRC … #+END_SRC`
<v	`#+BEGIN_VERSE … #+END_VERSE`

In addition to those blocks, there are also some quick tags:

Key	Expansion
<L	`#+latex:`
<H	`#+html:`
<A	`#+ascii:`
<i	`#+index:`
<I	`#+include:` (will interactively find file to include)

You can see that there is sort of a convention, uppercase letters usually insert a tag, whereas lowercase letters are mainly for blocks (though it’s definitely not perfect).

Additional Templates

Some additional templates can be defined by packages. For example, the org-re-reveal package adds:

Key	Expansion
<n	`#+begin_notes ... #+end_notes`

Basic Customization

You can add your own tags and blocks. In fact, there is actually no need for the “keys” to single characters.

Adding Tags

Adding another tag is very easy, seen here:

(add-to-list 'org-tempo-keywords-alist '("N" . "name"))

Which results in this completion:

Key	Expansion
<N	`#+name:`

Create a New Hotkey

I don’t like the <E hotkey for export block, instead I would like that to be <x. That is easily added with:

(add-to-list 'org-tempo-tags '("<x" . tempo-template-org-export))

Create a Completion

You can define your own completion with the tempo-define-template function (see the doc string for full details). It is very flexible! You can specify where the cursor (or “prompt”) ends up after the completion, or you can interactively prompt (via the minibuffer) for additional details. There are more advance features, including auto indentation and dealing with regions.

My Custom Completions

There is no requirement that these templates be simply blocks or tags. I’ve implemented about 5 custom templates, but here are a few that I think would be most useful for others.

Properties Drawer¹

Org headings can have properties, specified by the properties drawer:

:PROPERTIES:

:END:

I add this as <p via this implementation code:

(tempo-define-template "org-properties-block"
                       '(":PROPERTIES:" n
                         (p) n
                         ":END:" n %))
(add-to-list 'org-tempo-tags '("<p" . tempo-template-org-properties-block))

Title Block

This is one that I use most frequently. It’s a title block that I start all my org documents with. It also executes a function call to format-time-string to get today’s date in my preferred format. By having this completion, all of my org documents get a title with a date and I always know when I started working on a document!

My desired result:

#+title:
#+author: Elsa Gonsiorowski
#+date: February 28, 2026

The implementation code:

(tempo-define-template "org-title-block"
                       '("#+title: " (p) n
                         "#+author: Elsa Gonsiorowski" n
                         (concat "#+date: " (format-time-string "%B %e, %Y")) n %))
(add-to-list 'org-tempo-tags '("<t" . tempo-template-org-title-block))

I also implement another completion that is a slightly different title block which I use for starting all my blog posts. It includes the all the options that I want by default.

Finally

In writing this article I stumbled across orgmode documentation page for Completions. I had no idea these M-tab completions existed! (Clearly, since I implemented my own completion for the properties drawer). I’ll definitely be trying these out.

Footnotes

¹ The :properties: keyword can also be added with the M-tab completion on :

Beautifying the Tab Bar

gonsie@me.com (Elsa Gonsiorowski) — Fri, 08 Jul 2022 00:00:00 +0000

Emacs 27.1 introduced a tab bar and I finally got around to trying it out. I found it particularly useful for switching between a few buffers quickly, particularly because I have muscle memory for the Safari tab keybindings (which I set for Emacs tabs).

I must say, the implementation is really nice. Ultimately customizable (a la everything Emacs). It also has some nice interactions with the mouse (if that’s your jam). You can use drag-and-drop to change tab ordering!

Basic Key Bindings

This was the first thing I setup, especially since I knew exactly what I wanted. These mirror Safari’s tab keybindings.

(global-set-key (kbd "s-{") 'tab-bar-switch-to-prev-tab)
(global-set-key (kbd "s-}") 'tab-bar-switch-to-next-tab)
(global-set-key (kbd "s-t") 'tab-bar-new-tab)
(global-set-key (kbd "s-w") 'tab-bar-close-tab)

The s- prefix key is the “command ⌘” key on a Mac.

I think s-w is set to kill-emacs or delete-frame something similar by default. I personally never want that to happen so I’ve had those functions and keybinding disabled for years now. I also had s-{ and s-} bound to switch between frames (other-frame), but I usually use the Emacs GUI in full screen mode, so using these for tabs makes more sense. At least for right now.

Settings

Of course, the tab bar comes with a bunch of customizable settings. I’m using:

(when (< 26 emacs-major-version)
 (tab-bar-mode 1)                           ;; enable tab bar
 (setq tab-bar-show 1)                      ;; hide bar if <= 1 tabs open
 (setq tab-bar-close-button-show nil)       ;; hide tab close / X button
 (setq tab-bar-new-tab-choice "*dashboard*");; buffer to show in new tabs
 (setq tab-bar-tab-hints t)                 ;; show tab numbers
  (setq tab-bar-format '(tab-bar-format-tabs tab-bar-separator)))
                                            ;; elements to include in bar

The when clause wrapping these settings ensures my configuration is maximally compatible with all modern Emacs versions. I figured out these settings through a combination of looking at the *Customize* menu for Tab Bar and reading the help documentation for each variable.

One setting I really like (but am not using right now), is the ability to have a “Menu” button in the tab bar. This is achieved by adding tab-bar-format-menu-bar at the beginning of the tab-bar-format value list.

Theme

I worked really hard on my modeline and I can reuse all that styling! This is the snippet from my personal dusk theme¹:

;; modeline settings
'(mode-line ((t (:underline nil :overline nil :box (:line-width 8 :color "#353644" :style nil) :foreground "white" :background "#353644"))))
'(mode-line-buffer-id ((t (:weight bold))))
'(mode-line-emphasis ((t (:weight bold))))
'(mode-line-highlight ((((class color) (min-colors 88)) (:box (:line-width 2 :color "grey40" :style released-button))) (t (:inherit (highlight)))))
'(mode-line-inactive ((t (:weight light :underline nil :overline nil :box (:line-width 8 :color "#565063" :style nil) :foreground "white" :background "#565063" :inherit (mode-line)))))
;; tab bar settings
'(tab-bar ((t (:inherit mode-line))))
'(tab-bar-tab ((t (:inherit mode-line :foreground "white"))))
'(tab-bar-tab-inactive ((t (:inherit mode-line-inactive :foreground "black"))))

Binding the Tab Hint Numbers

I have a pretty wonky keybinding setup, where I create my own minor mode key map and use that by default (as recommended by this stackexchange post). Here I use (setq mac-command-modifier 'super).

The tab bar documentation indicates that to enable pressing ⌘-1 (or s-1 as Emacs sees it) to switch to tab number 1 I would need:

(setq tab-bar-select-tab-modifiers "super")

But this didn’t work for me. Instead, I bound each super-number combination (s-1 through s-0) to tab-bar-select-tab and it works!

Final Comments

As I mentioned above, the tab bar implementation is really nice. This reflects the high standards that the Emacs community and developers have, especially for anything that becomes built in. I was able to do all of this implementation and blogging while flying back from a semi-vacation in Greece (where I spent a lot of time improving my blog, if you didn’t notice). An editor with completely built-in documentation and an interface for configuring / customizing is really, really pleasant. Not needing the internet to do something productive feels increasingly rare.

Footnotes

¹ Back when I wrote about package cl being deprecated, I noted that the way I define my theme was outdated. I finally got around to modernizing it, but never wrote about the process. I’m not sure a blog post would be useful, since I’m guessing most readers use existing theme packages. I did start with the customize-create-theme function, which made the process of porting my old color-theme definition to the modern customize format trivial.

You can view my theme in my dotfiles GitHub repo.

Package cl is deprecated

gonsie@me.com (Elsa Gonsiorowski) — Wed, 22 Dec 2021 00:00:00 +0000

Package cl is deprecated

I’ve been ignoring this startup message for maybe a year now (since the release of Emacs 27). After recently updating all my packages (and completely breaking my emacs setup) I decided to go through all the startup messages and start fixing things.

The Fix

Searching around the fix is straight forward. Instead of requiring cl the correct name is now cl-lib.

(require 'cl-lib)

I knew of one place where I had used cl (I used the return-from function to do an early exit from a while loop), but after making the change, I was still getting the startup message. Unfortunately that meant the startup message was coming from one of the many packages I had installed, how would I ever find it?

Finding `cl` requirements

Luckily, we have the emacs stackexchange, with this handy snippet:

(require 'loadhist)
(file-dependents (feature-file 'cl))

Showing the one place with a cl requirement:

Users/gonsie/.config/emacs/elisp/color-theme-6.6.0/color-theme.el

Unfortunately this is in one of the packages I’ve been hand carrying around for over 10 years (longer than my dotfiles repo has existed). It’s finally time to update the implementation of my preferred color theme, but that is a post for another day.

Don't be afraid of eshell

gonsie@me.com (Elsa Gonsiorowski) — Wed, 31 Jul 2019 00:00:00 +0000

One of the reasons I decided to switch to emacs was the ability to embed a terminal window directly within my editor. Before last week, I never got the embedded terminal working and never really gave eshell much of a try. Initially, I tried to setup my regular shell (fish), but that never quite worked correctly. I also learned the power of dired and haven’t had the need to use the command line quite as much. Then, last week, I found myself editing and re-compiling code in a tight loop. I wanted access to the terminal, to trigger compilation, without leaving emacs. I created a quick-and-dirty eshell setup… and then wondered why I hadn’t done this sooner.

What is eshell?

Emacs shell, or eshell, presents bash-like command line interface built directly on emacs. It tries to be the best of two worlds:

An elisp REPL wherein elisp commands can be directly executed
A command line interface similar to bash

By understanding that eshell is presenting emacs in a terminal/shell sort of way, I can choose if I want to execute a command the elisp or bash way. More details can be found on the eshell page in the emacs manual.

Bare Minimum

First things first: to launch an eshell terminal, run M-x eshell.

Next, there are 2 things I need to have a basic, functioning shell environment:

Have the correct PATH
Have my most used aliases

Path

The PATH variable used by eshell is exposed through the addpath command. Without any arguments, addpath simply prints out the directories currently in PATH. When called with one or more arguments, addpath will append these paths to your PATH. There is no need to include the current PATH contents, as addpath always appends.

Aliases

Eshell has a number of built in commands, which are similar to the bash builtins. The most useful command is alias, which can be used to create any commands that you are used to using in your regular shell. The first step for me was to figure out which aliases I use most often and add them to eshell.

First, I needed the ls alternative that I use. Luckily, there is an ls provided by eshell (shown by running which ls). It takes the same arguments as my Mac’s builtin version.

Next, I needed a way to open an emacs buffer with a specific file. I use the command em to launch a new emacs session within my terminal window (emacs -nw). The alias for eshell is slightly different, since I am already running an emacs session. I simply want to start editing a particular file. Thus, the alias makes a call to the emacs function find-file.

My alias file (~/.emacs.d/eshell/alias) looks like this:

alias la ls -AFGhl $1
alias em find-file $1

Next Steps

The bare minimum takes care of my most frequent use case. Now, I can compile code without switching away from emacs!

The next step for me is to add the aliases to dotfiles and continue to improve my eshell setup. A quick web search lead me to a literate config for eshell in howardabrams/dot-files. There are several settings here that I will have to add for myself.

Sending Email from Org Mode

gonsie@me.com (Elsa Gonsiorowski) — Wed, 01 May 2019 00:00:00 +0000

Every so often, I need to generate a bunch of form emails. Often, I’m sending the same email to multiple groups of people and I want use variables, such as $first_name, in the text. While I’m sure there a number of online services which could achieve this for me, I really don’t need to set up a fancy campaign or use tracking. Plus, I’m wary of submitting others’ emails to a third party.

Of course, I’ve used Emacs to do this, using org mode and AppleScript.

Overview

To approach this task I start with a single org file. Getting AppleScript executing from an org block is trickier than I would like. Instead, I write the script whole cloth in my org file and tangle it out to a separate .scpt file. I store the data in my file as a table. I then use a bash block, which takes the data through :var, to loop over running the script.

AppleScript for Email

I’ve never formally learned AppleScript, but some searching on StackOverFlow and trial-and-error can get you pretty far. Mac OS X has a built in editor found in /Applications/Utilities/Script Editor. Once you’ve opened the editor, you can browse the dictionary with File > Open Dictionary.... This dictionary lists all the classes and commands for different applications. The AppleScript language itself looks like natural language and is relatively easy to understand… especially once someone else has properly constructed the program.

For my email-sender script, I store the AppleScript source is as a block. This block is tangled (C-c C-v C-t) to a .scpt file. The first half of this script sets some variables, including the body of the email message. The second half creates the message and sets a “to” recipient (could also set a “cc” recipient).

#+NAME: script
#+BEGIN_SRC apples :tangle email.scpt
on run argv
   set varName  to item 1 of argv
   set varEmail to item 2 of argv
   set varBody  to "Hello " & varName & ",

Blah blah blah. Lor ipsum, etc.

Sincerely,
Elsa"

   tell application "Mail"
        set theMessage to make new outgoing message with properties {subject: "Email", content: varBody, visible:true}
        tell theMessage
             make new to recipient with properties {name:varName, address:varEmail}
             #send
        end tell
   end tell
end run
#+END_SRC

Note that I’ve commented out the send command and set the message property visible: true. This means that the draft emails appear in the Mail GUI, but do not get automatically sent. This allows me to do trial runs before spamming my recipients.

Filling the Variables

Once I have the script and email body written, I know what variables I’ll need to fill in. The next step is to put all the data into a named org table. I usually do this data formatting by hand since I’m bringing together data items from many different sources.

#+NAME: data
|    Name    |      Email      |
|------------|-----------------|
| Mx. Person | person@test.com |

Since I tangle the email sending AppleScript program, I need to run it from the command line. I call the script once for each row in the data table using a bash loop and variable arrays. Then, I use C-c C-c to run the bash loop and generate the emails.

#+BEGIN_SRC bash :var name=data[,0] email=data[,1]
for i in `seq 0 0`; do
osascript email.scpt "${name[$i]}" "${email[$i]}"
done
#+END_SRC

Note that I do not calculate the total number of data items / rows. That would take way too much bash magic for this simple example. Also, if you want to test the variables with an echo statement, use :results output as an argument to the org block.

Hitting Send

I usually choose to manually hit send on each individual email once I’m satisfied with the script.

I keep all of these org commands in a single notes.org file so that I can remember how to recreate the emails (usually a year later when it’s time to send them again). For example, this notes.org file sends introduction emails for a mentoring program I organized with Women in HPC.

Emacs Delete vs. Kill

gonsie@me.com (Elsa Gonsiorowski) — Wed, 04 Jul 2018 00:00:00 +0000

One thing that has always vexed me is the Emacs kill ring. It’s great that it makes a list of things you’ve killed, but often I just want delete things quickly without saving it. So I need to change the default settings to enable both killing and deleting words and lines.

Basic nomenclature (for this blog post at least);

kill means removing text and putting it in the kill ring
delete means removing text and not putting it in the kill ring

Understanding Key Bindings

The default behavior of Emacs can depend on the underlying operating system. This is because key presses are first translated by the OS, then passed (if they don’t trigger an OS function) to the application, e.g., Emacs. This can be further complicated by the keyboard setup and, further still, by an Emacs instance running inside of a Terminal.

To figure out the name that Emacs itself has for each key, use C-h k KEY or M-x describe-key KEY. This internal name will come in handy when rebinding these keys.

For extended keyboards, there are often two “delete” keys, one which performs a backspace and one which does a forward delete. The forward delete is often found on the “keypad” or number pad and is thus called kp-delete by Emacs.

Mac Keyboards

Mac keyboards have the following modifier keys: Shift, Control, Option (Alt), and Command. While Shift and Control are already mapped for Emacs (known as S and C respectively), the Option and Command keys are not mapped. I use Option/Alt as a meta (M) key and Command as a super (s) key.

(setq mac-command-modifier 'super) ;; command -> s
(setq mac-option-modifier 'meta)   ;; option/alt -> M

Default Commands

By default, the delete key removes a single letter (backwards). In Emacs keybindings, this is sometimes denoted as backspace (in addition to sometimes being called delete). M-delete (ALT-delete on a Mac keyboard) will remove a whole word, but place it in the kill ring. Killing a line is simple: C-k, but this kills a line forwards.

Putting the most recently killed word or line back is C-y, called yanking. Yanking previous items in the ring is achieved with M-y, which will cycle through the ring.

Combinations

There is a 3 dimensional problem to solve here, with 16 possible combinations (14 unique operations):

Removal direction (backwards or forwards)
Removal type (kill or delete)
Removal size (character, word, visual line, whole line)

Direction

I use the Mac internal for marking the direction as backwards or forwards. Even on laptop keyboards, I can use Fn-delete to get the forwards deletion.

The whole line removal does not have a direction, but must be bound to both delete and kp-delete.

Removal Type

The un-modified delete key-press should trigger a character delete. Using the meta (M) modifier triggers a word removal. Using the control (C) modifier triggers a line removal.

Saving Items to the Kill Ring

I use the Shift (S) modifier to explicitly trigger adding the removed text to the kill ring.

Binding the Keys

The following table tracks all the combinations which must be implemented. The implementation looks like:

(global-set-key (kbd "<<keybinding>>") '<<function>>)

Direction	Type	Save	Key Binding	Function
Backwards	Char	No	`<delete>`	None needed
	~~Char~~	~~Yes~~		Not implemented
	Word	No	`<M-delete>`	`backward-delete-word` *
	Word	Yes	`<M-S-backspace>`	`backward-kill-word`
	Line	No	`<C-backspace>`	`backward-delete-line` *
	Line	Yes	`<C-S-backspace>`	`backward-kill-line` *
Forwards	Char	No	`<kp-delete>`	`delete-forward-char`
	~~Char~~	~~Yes~~		Not implemented
	Word	No	`<M-kp-delete>`	`delete-word` *
	Word	Yes	`<M-S-kp-delete>`	`kill-word`
	Line	No	`<C-kp-delete>`	`delete-line` *
	Line	Yes	`<C-S-kp-delete>`	`kill-line`
Both	Line	No	`<s-backspace>` and `<s-kp-delete>`	`delete-current-line` *
Both	Line	Yes	`<s-S-backspace>` and `<s-S-kp-delete>`	`kill-whole-line`

The functions marked with a * must be implemented.

;; from https://stackoverflow.com/a/12990359/1160876
(defun backward-delete-word (arg)
  "Delete characters backward until encountering the beginning of a word.
With argument ARG, do this that many times."
  (interactive "p")
  (delete-region (point) (progn (backward-word arg) (point))))

(defun delete-word (arg)
  "Delete characters forwards until encountering the beginning of a word.
With argument ARG, do this that many times."
  (interactive "p")
  (delete-region (point) (progn (forward-word arg) (point))))

(defun backward-delete-line (arg)
  "Delete (not kill) the current line, backwards from cursor.
With argument ARG, do this that many times."
  (interactive "p")
  (delete-region (point) (progn (beginning-of-visual-line arg) (point))))

(defun delete-line (arg)
  "Delete (not kill) the current line, forwards from cursor.
With argument ARG, do this that many times."
  (interactive "p")
  (delete-region (point) (progn (end-of-visual-line arg) (point))))

(defun backward-kill-line (arg)
  "Kill the current line, backwards from cursor.
With argument ARG, do this that many times."
  (interactive "p")
  (kill-region (point) (progn (beginning-of-visual-line arg) (point))))

;; from https://stackoverflow.com/a/35711240/1160876
(defun delete-current-line (arg)
  "Delete (not kill) the current line."
  (interactive "p")
  (save-excursion
    (delete-region
     (progn (forward-visible-line 0) (point))
     (progn (forward-visible-line arg) (point)))))

Summary

I am very happy with how cleanly these keybindings map to functionality. Let’s see if I can actually put these to use!

Developing ox-jekyll

gonsie@me.com (Elsa Gonsiorowski) — Sat, 12 May 2018 00:00:00 +0000

In a previous post, I surveyed existing org and jekyll integration workflows. This survey found two common approaches, one that is Jekyll-centric and one that uses Org-publish (Emacs-centric). Unfortunately, neither fit with my workflow and I decided to develop my own Org exporter.

I finally have some functioning code, so I figured I should share details about the project and the development process. You can find the project on GitHub.

Starting Point

In my survey I found some useful resources:

The Worg Documentation on Org Export Engine;
An existing ox-jekyll in org-octopress.

Great artists steal.

I want everything that org-octopress is doing with it’s jekyll exporter, I just want it built on markdown instead of HTML.

So, I’ve copied ox-jekyll.el and replaced “html” with “md”. After fixing a few function names, it works!

Most importantly, the front matter is in the right spot (with and without a table of contents). The next step is to make this work with the particulars of my publishing workflow.

My Publishing Workflow Details

There are a number of things I want my exporter to accomplish. Many of which are particular to my workflow.

I use a single org file per post.
Upon export, the date (YYYY-MM-DD) should get added to the file name.
Subtree level matches export heading level (this is just how I design my site’s CSS)
Code snippets should be easy to export with appropriate syntax. This is where many markdown converters differ, but jekyll currently wraps code blocks with { % highlight LANG %} / { % endhighlight %}. [Ignore the extra space before the %]
Jekyll front matter should be added above org-inserted table of contents. The manual HTML source block is just hideous.
It should be easy to move the generated file to a separate location (I think this addressed in the org-publish workflow).
Org-y way to add tags to the post.
Safe export of title (colon character mucks things up for Jekyll).
Fix up links and export connected images. This one is really a nice to have, not necessary.
TOC should be an ordered list (with the option to make it unordered) WTF is the HTML exporter doing making it an unordered list with numbers in the text.

Many of these are solved with code from org-octopress, particularly the yaml front matter.

Implementing Features

Here are some notes on my implementation.

Thinking about the Table of Contents

I had been including a table of contents at the top of each of my posts. I didn’t actually label it with “table of contents” and I prefer an un-numbered list. This seems to be very contrary to what the org-exporter likes to do. It pretty much does not allow for any fine-grained control of how the table of contents appears.

While I was able to get the code to do what I wanted, it ended up being way too much of a hack. In the end, I’ve decided that I don’t want a table of contents at all. Really, it will be up to the markdown / jekyll / liquid parser to create a TOC if necessary. This makes it easy to apply separate HTML styles to the TOC (to put it in a sidebar or something).

Preserving the Headline Level

I would like :headline-offset (as described here) to work on a file level. This allows me to make sure the contents of my post match up the CSS on the web site (the content’s final destination). This is definitely a more markdown-y way to do things rather than the org way.

Unfortunately, the :headline-offset option is only supported per subtree. I can hack it with a simple function that adds an “offset by 0” property to each subtree:

(defun org-jekyll-headline-offset (headline contents info)
  "proper headline offset"
  (let* ((info (plist-put info :headline-offset 0)))
    (org-md-headline headline contents info)))

I add it to the derived backend :translate-alist like so:

(org-export-define-derived-backend 'jekyll 'md
  ;; ...
  :translate-alist
  '((headline . org-jekyll-headline-offset)
  ;; ...

Now, this function is called each time a headline is translated by the export engine and my headline level is directly translated to markdown.

Setting the Date

I have a strange workflow where I want the #+DATE: tag to be the day I started working on a post and the date in the filename to be the day I hit publish. For my exporter, I can use the option date: to trigger this behavior. The date: option takes precedence over the variable org-export-with-date.

While I would like my code to support putting the #+DATE: property into the filename, this seems impossible with the export engine. The date property is stored in the info plist which I don’t have access to at file naming time.

Instead, I’ve implemented this functionality:

The date: option controls if the value of the #+DATE property is put into the Jekyll front matter.
I’ve added a new option to the exporter: org-jekyll-use-today-date. If t, the exporter will prepend the filename with today’s date.

Results

I’m quite happy with my exporter, I even used it to export this post! I still need to figure out how to use the org-publish workflow, but for now I can successfully export my blog posts.

As with most of my projects, you can find it on GitHub. Please feel free to file an issue and share any feed back you have.

Org Export Hooks

gonsie@me.com (Elsa Gonsiorowski) — Thu, 22 Mar 2018 00:00:00 +0000

In my quest for a simplified, org-based publishing scheme, I would like to add some information to a file when I export it. Namely, I would like to add some metadata within the file, something like:

    #+property: exported: 2018-01-30

Let’s see if I can prototype this functionality through Org-mode!

Hooks and Useful Functions

I can think of some functions and/or variables I will need:

StackOverflow: org-export-preprocess-final-hook
Org mode timestamp format
Interesting functions from C-h f org-insert-TAB:
- org-insert-comment
- org-insert-time-stamp
- end-of-buffer which references (goto-char (point-max))

Let’s put them together into an elisp snippet.

    (add-hook 'org-export-preprocess-final-hook
      (save-excursion
        (goto-char (point-max))
        (insert "\n#+property: exported: ")
        (org-insert-time-stamp (current-time))
        (insert "\n")))

I think that does the thing that I want. Ideally the property would go near (but not at) the top of my document, but that seems overly hard for the moment. Notice that executing the block puts the #+property at the end of the document. That is the behavior we want, BUT it should not be happening when executing the block rather it should happen on export. Also, this function will keep inserting more text, rather than update an existing property.

That seems like a rather hacky way to set properties. There must be something included with org. Let’s try the org-set-property function.

    (save-excursion
      (goto-char (point-min))
      (org-set-property "exported:" (format-time-string (car org-time-stamp-formats) (current-time))))

Gross. Without going to the beginning of the file, it just adds a property drawer to the current subtree. Going to the beginning of the file just inserts the timestamp with the error: “Before first headline in position 1”.

StackExchange to the Rescue

This StackExchange Question leads me in the direction of the powerful org-element-parse-buffer. Actually, there is one solution which includes a rather elegant set of org-global-prop functions that I want to properly package up and attribute¹. Let’s try them out:

    (org-global-prop-set "exported:" (format-time-string (car org-time-stamp-formats) (current-time)))

That function works! What about as a hook?

    (add-hook 'org-export-before-parsing-hook
      '(org-global-prop-set "exported:" (format-time-string (car org-time-stamp-formats) (current-time))))

Ugh, hooks are dead. Reading through the official org documenatation, it seems like each hook operates on a copy of the current buffer, not what I want.

Hooking on to Something

That’s fine, I can hack in another way. Let’s just rebind the keys that do the exporting to a new function which will do the export property update.

    ;; add exported: property with date to org files when exporting
    (defun my/org-export-dispatch ()
      "updateds the exported: property before opening the dispatch"
      (org-global-prop-set "exported:" (format-time-string (car org-time-stamp-formats) (current-time)))
      (org-export-dispatch))

    (add-hook 'org
              '(local-set-key (kbd "C-c C-e") 'my/org-export-dispatch))

Not perfect (the spaces/newlines after the property are globbed) but good enough for now. Someday I’ll have to work on integrating this functionality into the publishing process (rather than this hack), but hey, it works.

Footnotes

¹ I found the author, Tobias Zawada, and put the code on GitHub.

Org and Jekyll: A Survey

gonsie@me.com (Elsa Gonsiorowski) — Wed, 07 Feb 2018 00:00:00 +0000

My Current Process
Survey of Related Work
Future Work
Conclusions

I am getting more into Org mode and I’ve started to use it in my blogging process. I host my blog on GitHub pages with Jekyll. I would like to keep my posts in markdown and not push HTML direct to _site. At first I thought I needed to build my own org exporter for Jekyll, but I’ve realized there a number of solutions (and blog posts about those solutions) already out there.

This post is a survey of existing approaches to blogging with Org and Jekyll.

My Current Process

My current process includes several non-optimal “fix up” steps that I would like to eliminate. Ideally, the Emacs publish transformation would spit-out the markdown exactly as I want it. A bonus would be to take advantage of the Org publish workflow (rather than just an export of the document). Then, I would be able to make any copy edits directly on the Org draft and the publish/deploy process could happen at the push of a button.

Before codifying my workflow, I’ve surveyed the work of others. I have found a number of blog posts that discuss each author’s experience with and workflow for blogging with Org mode and Jekyll.

There are three categories of approaches:

Support a Jekyll-centric workflow by developing a Jekyll plugin / converter.
Support an Org and Emacs-centric workflow by building on the org-publish functionality. This approach transforms the Org content directly to HTML.
Support the Org-publish workflow by transitioning away from Jekyll altogether (i.e., using a different platform).

Jekyll-centric Approaches

Jekyll-centric approaches often attempt to make Org syntax a first-class citizen in Jekyll. However, none of these tools have been adapted by the Jekyll community and thus remain outside of Jekyll itself. This means that org-based blogs are not able to take advantage of automatic publishing by GitHub Pages.

An Org-Mode Jekyll Plugin by Joel’s Journal

This post takes a literate programming approach to developing the Jekyll plugin for understanding org documents. This post is great review of what is happening under the hood (including details on the I/O streams, which can be complex).
eggcaker/jekyll-org on GitHub

Yet another Jekyll plugin. Maybe I’m missing something as to why this approach is so attractive.
tjaartvdwalt/jekyll-org-mode-converter on GitHub

The ReadMe in this project is the equivalent of blog post. It covers some other, existing projects and again uses the Jekyll converter/plugin approach.

Org-publish Approaches

There are many “hacks” that smash together Jekyll and Org. Unfortunately, it seems that neither Jekyll nor Org are used in all their glory. Each workflow contains a bunch of new elisp for getting everything to work.

“Official” Guidance: Using org to Blog with Jekyll on Worg

Worg provides some guidance for blogging with Org. This is the unofficial starting place for many Org bloggers and describes several Org-centric workflows.
Using org-mode to blog with Jekyll by Martin Foot

This post expands on the Worg guidance for generating HTML for Jekyll. It uses the HTML blocks to export the Jekyll front matter. It includes the elisp snippets to set up proper project publishing. As such, it’s a great starting place for new bloggers.
Using org-mode with Jekyll by Levlaz

This post again starts from the Worg guidance (and a bad experience with Google Docs). He includes the elisp org-publish snippet which moves the draft out of _org and into _posts.
Org-jekyll by Juan Reyero

The first line of the posts mentions that author is no longer using this method. I really appreciate having this information up front!

The post uses org-publish to export subtrees from a single org document as individual posts.

Other Platform Approaches

It is important to recognize that there are some other approaches. Some users have transitioned away from Jekyll completely, while new platforms have appeared to enable to blogging.

Blogging with Org mode by Superloopy.io

Approach:
- Originally tried upstreaming a Jekyll plugin.
- Moved away from Jekyll altogether, now using org-publish
Superloopy’s post has a lot of great ideas and discussion of the task.

First, I completely agree that setting up the Jekyll tech stack is a huge pain. That is somewhat mitigated by the fact that GitHub will automatically publish them with Jekyll for you. Also, it is disappointing that the gem/jekyll-plugin was ignored.

The post also describes a way to lower the barriers to blogging through a capture template (which looks fantastic). The post also includes code for publishing direct from org and converting existing jekyll-markdown posts back to org.
yoshinari-nomura/org-octopress on GitHub

The org-octopress package contains exporters for octopress and jekyll. These exporters have a number of features I will want:
- support for automatically adding yaml frontmatter
- setting the layout in the frontmatter (with a default value)
- some filename and date functionality
This package still exports to HTML, rather than the markdown that I want. But, if I can easily get it into my workflow, it might make sense to use this rather than developing a new tool.

Future Work

At the start of this survey I thought that an ox-jekyll solution would already exist. On the contrary, I haven’t found one that builds on top of markdown and native Jekyll parsing.

I will have to develop my own. This exporter will have to fit neatly in existing workflows (if I want to make it useful to others). I have a number of assumptions about the setup of projects and org files that I will have to be careful about or document clearly.

Conclusions

I’ve learned a lot from this review, including some useful takeaways for my own blogging purposes:

I should make sure my blog has a header. I’ve been working on this post offline and with the relevant web pages already open. If I were looking at a post on my own blog, I would have no context/meta-information on the page.
Starting the post with any update about its contents is such a courtesy to the reader. I must do this for my own posts.

One key take away: there are a ton of people using Emacs and Org to blog (and write and do work). The influence of literate programming means that many of these people write blog posts about their workflow. As a result of this project, I’ve added about 5 blogs to my RSS feed.

Configuring for Emacs 22 and 25

gonsie@me.com (Elsa Gonsiorowski) — Sat, 03 Feb 2018 00:00:00 +0000

Old Initialization File Setup
New Scheme
Tips
Conclusion

I work in high performance computing (HPC). This means I work on some of biggest and best supercomputers in the world. It also means that I work on some biggest and best supercomputers from 5 or 10 years ago.

Recently, I found myself on a machine with Emacs 22. This post documents some of the changes I had to make to my Emacs configuration files to ensure that they could be used for any Emacs version I was likely to come across.

Old Initialization File Setup

Ever since I’ve restarted using Emacs (from SublimeText), I’ve been using a few configuration files. I wanted my .emacs to be pretty generic and high level. This would call an init.el file which had a bunch of settings and packages. I also put a bunch of machine-specific configurations in a .emacs-custom.el file.

Looking at Emacs 22, I don’t think there is any support for package.el. I could roll with an old version, but after a quick search I could only find a snapshot for Emacs 23. In reality, I don’t need full Emacs package support, I just want to ensure my basic settings are on (I love my colors and hate auto-save files).

New Scheme

The new scheme has four files, three of which are called from the root .emacs file.

`.emacs`

This file contains all vanilla Emacs 22 settings. Some packages, such as autopair or org, have at one point been included in the Emacs distribution, but are not guaranteed. That said, the settings in this file should be safe for all versions of Emacs.

`.emacs-custom.el`

This file contains any machine-specific settings (such as the ispell path) or customize settings. Note that you have to manually touch this file when getting set up on a new machine or Emacs will complain.

`init.el`

This file contains everything to do with packages. It has the set-up for MELPA and then use-package for everything else. I actually really like how clean and single purpose this file turned out to be.

`theme.el`

This file contains all the settings for my color theme. This file must be correct (i.e., not throwing errors) for all versions of Emacs as well. Any package-specific colors must be properly protected in case the package isn’t loaded.

For my particular setup, I am only able to achieve this because I include the color-theme package/elisp files with my dotfiles distribution. Colors are notoriously tricky, so I’ve got something that works and I’m not changing it.

Tips

Here are a few snippets I used to make everything work.

Checking The Emacs Version

The init.el should only be called from Emacs 25 or greater. My init.el would probably work for Emacs 24 as well, but I’ll leave it for now.

(when (< 24 emacs-major-version)
  (load "~/.config/emacs/init.el"))

Checking for a Package

Some package specific colors can only be set if the package is loaded. I suppose this could be done through use-package, but I have org outside of that for now.

(when (require 'org nil 'noerror)
  (set-face-attribute 'org-table t :foreground "#536fd6"))

Package Initialization

Since my packages are all loaded in the init.el file (and the file is only loaded for specific Emacs versions), I put the MELPA setup and (package-initialize) calls in there. This causes package.el to complain and automatically put a call to (package-initalize) in the .emacs file. Thus, to use a setup like this, I needed to add a comment at the beginning of my .emacs file.

;; package.el will check for this comment; it's actually called from init.el
;; (package-initialize)

Conclusion

I think this new scheme is quite slick. I get my favorite colors and settings no matter what machine I’m working on. Plus, there are no complaints/warnings/errors when I start up Emacs.

Part 2: Counting Words

gonsie@me.com (Elsa Gonsiorowski) — Wed, 10 Jan 2018 00:00:00 +0000

This post is part of a series.

Part 1: Using Org to Develop E-lisp Snippets
(You are here) Part 2: Counting Words

Exploring Existing Functionality
Marking and Counting
Jaunting
Count All the Things!

I often use an separate (Org) file to develop written content, especially when I am filling out an application that has essay questions. The answers often have a word-count or character-count limit. Let’s use Emacs and Org to count words!

Exploring Existing Functionality

First, I use builtin documentation (and tab completion) to compile some useful functions. Actually, I flailed a lot and bugged my friend who knows a bunch about Emacs and Org.

The count-words function is obviously a good place to start. The documentation indicates that functions works on either a region or buffer and that it acts differently if called from lisp (rather than interactively). I don’t know anything about regions, but the Emacs Lisp documentation for “The Region” mentions two more useful functions: region-beginning and region-end.

Looking through all the Org functions, two stick out: org-mark-subtree and org-babel-mark-block. These functions create a region on a specified chunk of Org content.

Finally, I’ll need to go to the Org location to mark the region. There are a few functions that look good for that: org-goto (though that seems to be very interactive) and org-id-goto. Also, I come across org-babel-goto-named-src-block. I already know how to name a source block. For the other go-tos, making an Org ID is easy enough: org-id-get-create. (Note, although org-id-new looks promising, I eventually learn that it doesn’t do what I want).

Marking and Counting

I need to create an Org section for each answer that I want to word count. I can either use a header/node/subtree or a source block (of text). In the first case, I’ll add a unique ID to the header (by invoking the org-id-get-create) so I can use the org-id-goto. In the source block case, I can simply give it a name.

** Describe Blah (100 words)
:PROPERTIES:
:ID:       460D55A4-7C61-485C-8778-075406BAE8A4
:END:

My answer is that blah.

#+NAME: question1
#+BEGIN_SRC text
Blah blah blah.
#+END_SRC

The snippet for counting words in a subtree looks something like:

#+NAME: subtree-method
#+BEGIN_SRC elisp
(org-id-goto "460D55A4-7C61-485C-8778-075406BAE8A4")
(org-mark-subtree)
(count-words (region-beginning) (region-end))
;; note that this snippet does not work
#+END_SRC

Unfortunately, the first snippet doesn’t work. Instead, it shows the error “Wrong type argument: markerp nil”.

Let’s try the source block way:

#+NAME: src-block-method
#+BEGIN_SRC elisp
(org-babel-goto-named-src-block "question1")
(org-babel-mark-block)
(count-words (region-beginning) (region-end))
#+END_SRC

Huzzah! This one works. Strangely, the result appears below the question block, not where I would expect it (below the code snippet).

Jaunting

My friend (who actually reads books) shows me an awesome Emacs lisp function⁶:

save-excursion: Save point, and current buffer; execute BODY; restore those things.

Turns out, this function is all over a bunch of e-lisp code. Let’s try it! First, the subtree version of counting words:

#+NAME: subtree-method
#+BEGIN_SRC elisp
(save-excursion
  (org-id-goto "460D55A4-7C61-485C-8778-075406BAE8A4")
  (org-mark-subtree)
  (count-words (region-beginning) (region-end)))
#+END_SRC

Low and behold! It suddenly works. Plus, the results appear below the current code block. Using save-excursion also fixes the source block method, making the results block appear near it.

One remaining issue with the subtree method is that it counts the Org properties drawer in the word count.

Count All the Things!

Finally, our word counting snippet should work on a bunch of subtrees or blocks. Let’s pass some input to the snippets. Also, we should pretty print the results. Finally, I’ve included the code to count the characters as well. The source block method ends up looking like:

#+NAME: questions
- question1
- question2
- question3

#+BEGIN_SRC elisp :var blks=questions  :results output
(save-excursion
  (while blks
    (setq b (car (car blks)))
    (setq blks (cdr blks))
    (org-babel-goto-named-src-block b)
    (org-babel-mark-block)
    (princ b)
    (princ "\t")
    (princ (count-words (region-beginning) (region-end)))
    (princ " words\t")
    (princ (- (region-end) (region-beginning)))
    (princ " chars\n")))
#+END_SRC

#+RESULTS:
: question1	3 words	16 chars
: question2	3 words	16 chars
: question3	3 words	16 chars

The same can be done for the subtree method, but with IDs as the input.

Footnotes

⁶ Documentation for Emacs Lisp save-excursion

Part 1: Using Org to Develop Elisp

gonsie@me.com (Elsa Gonsiorowski) — Wed, 10 Jan 2018 00:00:00 +0000

This post is part of a series.

(You are here) Part 1: Using Org to Develop E-lisp snippets
Part 2: Counting Words

Useful Commands
The Power of Introspection
Starting with Org Blocks

One of the powers of Org mode is the ability to run blocks of code and collect the output. This allows you to capture code, context for writing the code (as actual text), and results in a single document. This blog-post will describe how I’ve started to learn Emacs lisp using org and Emacs itself.

Useful Commands

In Emacs, there are many ways to trigger the same actions. I find that memorizing chords is terribly difficult (if I have any memorized its through muscle memory rather than my brain knowing what I’m typing). Here is a short table of commands I’ve needed to get at the documentation builtin to Emacs. Usually I run these via M-x FUNCTION, which allows me to get at tab-completion if I don’t remember the exact name.

Chord	Function	Out Come
`C-h f FUNCTION`	`describe-function`	show doc page for function
`C-k F FUNCTION`	`Info-goto-emacs-command-node`	show manual page for function
`C-h k KEY`	`describe-key`	show doc page for a chord
`C-h K KEY`	`Info-goto-emacs-key-command-node`	show manual page for chord
`C-h C-f`	`view-emacs-FAQ`	show GNU Emacs FAQ
`C-h i`	`info`	Bring up info documentation browser to the last info page you were looking at
`C-h i m elisp RET`		Shortcut to ELisp documentation
`C-h i d`		Top level info directory
`C-c C-c`	`org-ctrl-c-ctrl-c`	Great function name. Does a bunch of things, namely running the source code block
`C-c '`	`org-edit-special`	Edit block/table in a separate buffer popup

Helpful web pages:

Orgmode Source Code Editing
Org Easy Templates
Org Source Block Header Arguments
GNU Manual on Lisp in Emacs and the page on save-excursion

The Power of Introspection

I do not learn through text books. Often, I find that they have all this extra narrative, when all I really want is the equation or detailed function documentation. This does make it somewhat difficult for me to learn new programming languages as I’m not going to sit down a read a book. This is where an IDE can really help.

In psychology, the process of introspection relies exclusively on observation of one’s mental state. Introspection is closely related to human self-reflection and is contrasted with external observation¹.

In programming, introspection is the ability to look at the code itself, as a program is running. Emacs allows this (in a sense) through the describe-function and describe-key functions. Users can view both documentation and even the source code itself². Using the describe-function function, along with tab completion, you can guess at functions that may exists and start to build e-lisp snippets.

Built-in documentation isn’t technically introspection, but it is nice. To bring up the “Emacs Lisp” manual, type C-h i m elisp RET.

Despite my dislike of narrative, I now present a basic walk-through for getting started with Org mode code blocks.

Starting with Org Blocks

Now that we know how to bring up documentation without leaving Emacs, lets code! I’m sure we could create a new elisp file / project, but who has time? I would rather do my day job and learn a little new elisp when the opportunity arises. This means I’m already working on something while writing in Org-mode.

Basics: Running and Results

Org source blocks contain snippets of code that can be executed. First, make sure executing e-lisp code through Org babel in enabled (usually in your init.el or .emacs file):

(org-babel-do-load-languages
  'org-babel-load-languages
  '((emacs-lisp . t)))

Let’s start with a very basic Emacs lisp snippet. Typing <s TAB will automatically create a source code block (this is called a template³).

#+NAME: calc
#+BEGIN_SRC elisp
(- 10 2)
#+END_SRC

Placing the cursor within the block at hitting C-c C-c triggers the run (type y to allow the snippet to run on your computer). The results appear in the document.

#+RESULTS: calc
        : 8

String Manipulations

Elisp isn’t my go-to calculator, but it is a handy way to run simple calculations. Let’s get more complicated with some quick text parsing. Here I create 2 lists of items, then print all the permutations through an Org block.

#+NAME: letters
- A
- B
- C

#+NAME: numbers
- 1
- 2

#+NAME: str-permute
#+BEGIN_SRC elisp :var s1=letters s2=numbers :results output
(while s1
  (setq x (car s1))
  (setq s1 (cdr s1))
  (setq tmp s2)
  (while tmp
    (setq y (car tmp))
    (setq tmp (cdr tmp))
    (princ (car x))
    (princ (car y))
    (princ "\n")))
#+END_SRC

#+RESULTS: str-permute
: A1
: A2
: B1
: B2
: C1
: C2

A few notes about this example:

To edit the e-lisp code in an “Emacs-Lisp” mode buffer, move the cursor in to the source block and type C-c '. This ensures proper indentation and other major mode niceness. Note that this can work for any major mode⁴, including text.
Notice the :results output header argument on the code block⁵. There are a bunch of arguments, but the results one always messes me up. In this case, I want to print the output as the snippet executes, not the return value of the snippet.
Do not forget to cdr your while loop variable. Should you forget, use C-g to kill the execution.
Emacs print functions are weird and the documentation is obtuse… I just use princ. Unfortunately there is no easy to princ many items in a single, variable argument command (and I don’t want figure out how to build strings).

Footnotes

¹ Introspection. Wikipedia, The Free Encyclopedia. Accessed Jan. 4, 2018.

² Okay, this isn’t technically programmatic introspection, more like “built-in documentation.” On the other hand, Emacs is somewhat unique in how users can interact with the documentation and the underlying code.

³ Documentation for Org Easy Templates

⁴ Documentation for Org source blocks

⁵ Documentation for Org source block header arguments

Part 0: Word Count Goals

gonsie@me.com (Elsa Gonsiorowski) — Wed, 10 Jan 2018 00:00:00 +0000

An Excursion into E-Lisp and Org

I have had some recent success with learning Emacs lisp through Org-mode. I’ve decided to write about for others looking to get started with elisp.

I plan to eventually write a third post describing the process of publishing a package.

Converting from Sublime Text to Emacs

gonsie@me.com (Elsa Gonsiorowski) — Sat, 09 Dec 2017 00:00:00 +0000

Motivation
Prerequisites
The Basics
The Best from Sublime Text
Things That Never Really Worked in ST
Org-mode
Conclusion

Motivation

Until recently, Sublime Text (ST) has been my go-to code editor, especially when working on projects. The multi-cursor capabilities completely changed my life and I can't imagine living without them. Other than that, ST makes everything else pretty easy: simple package management, straight forward project navigation, easy synchronization across systems.

For the past couple of months, I have been working closely with someone who is an expert in Emacs and uses org-mode throughout his workday. The power of tangling and exporting from a single document makes so much sense, I just have to try it. I've always been a member of Team Emacs and I even created my first GitHub read-me in org syntax. But, without someone's door to knock on, I didn't truly understand the full power of org-mode and it didn't stick.

In this post I attempt to document my transition from Sublime Text 3 to Emacs. The main motivation is for full org-mode support. While there are some packages for ST that provide some org-mode syntax, full functionality is lacking. Thus, I want to take everything I've learned (all the productivity enhancing features) in ST and replicate it with Emacs.

Throughout this post, I continually come to the same conclusion: Emacs has support for the weird thing I want to do. Truly, this XKCD comic is real.

Setup: I use a Mac (technically 2, one at home and one at work) with the latest Emacs installed via Homebrew. Based on this post from Aaron Bieber, I have been mainly using Emacs through the GUI program.

Prerequisites

I'm sure there are several resources for those who are just getting started with Emacs. I will cover just the basics that you should know before reading the rest of this post.

Assumptions

You should know the basics of Emacs, meaning:

Understand chords, such as C-x C-c.
Get help with C-h ?
Quit (usually used for a chord gone-wrong) with C-g
Understand how to check your Emacs environment
- M-x describe-key
- M-x describe-variable
- M-x describe-function (run this before trying C-x M-c butterfly).
Understand buffers and windows
- Switch between open windows with C-x o
- Remove this window with C-x 0
- Split this window in half horizontally, C-x 2, or vertically C-x 3.
- Switch to another buffer with C-x b

Knowing these things should get you pretty far… and prevent you from breaking too many things. For the rest, just google it!

Package Management

Emacs supports many package managers, but the most popular one is MELPA. Check the MELPA website for the latest installation instructions. Once MELPA is configured, you can manually install packages with:

M-x package-install RET package-name

On top of MELPA, I use the use-package package to organize all of the packages I need. This works especially well for syncing between multiple machines.

Another solution could be req-package. This is built on top of use-package, but I haven't tried it yet.

Color Theme

Setting the terminal color scheme is actually a very hard thing to do. Mainly the conflict arises from where the colors should actually be specified: in the back-end or front-end. Should Emacs dictate what "red" looks like, or should the terminal program? Plus, getting the same color scheme in the GUI and terminal can be tricky.

Here is my code for initializing the Emacs color theme. It has a useful snippet is to set background color for GUI Emacs (which should not be done when in the Terminal).

(eval-after-load "color-theme"
  '(progn
     (color-theme-initialize)
     (color-theme-dusk)
     (when (display-graphic-p)
       ;; settings for GUI emacs
       (add-to-list 'default-frame-alist '(background-color . "#282B35"))
       (add-to-list 'default-frame-alist '(foreground-color . "White"))
       (set-frame-font "Inconsolata 18" nil t))))

I will cover my particular color theme in more detail in a separate post.

The Basics

There are a few basic things needed for setting up Emacs (or any editor). If you already have a great Emacs configuration going, just skip ahead.

Syncing Between Machines

For years I have been syncing ST settings and packages with Dropbox. This worked well until I started working for a company where arbitrary cloud services are frowned upon. While a cloud solution could work equally as well with Emacs, I would like my new setup to better support remote machines.

For my regular UNIX settings (bash profiles and so forth) I use a dot-files git repo. This repo gets cloned to any new machine and includes instructions for getting setup. It also includes a synch.sh script which does two things:

For new installations, any existing dot-files that would be over written are saved to a special folder. Then, all of my dot-files are installed and symlinked to my home directory.
For existing installations, the synch script will diff the files in the repo to those installed. Thus, any changes I've made locally can be added back to the repo and committed and shared.

For Emacs specifically, this is where use-package comes in. Use-package will auto-magically handle installing packages when I startup on a new machine. For now, I have a setup with 3 separate Emacs-related dot files:

.emacs: This file is bare bones. It sets up MELPA and and includes instructions for setting up a new machine (such as installing use-package). It also makes the calls to load the other 2 files.
init.el: This is the file where all my settings live. It doesn't necessarily need to be separate from the .emacs file, but for now, it is. All of my use-package declarations live in this file.
.emacs-custom.el: This file is where all of my M-x customize settings go. Many of these variable are machine specific, e.g., which packages are installed and where org files exist.

This setup is a work in progress and may be more convoluted than necessary.

Trim Spaces

I absolutely hate extra white space and a newline at the end of a file is a must. Here are the Emacs settings:

(add-hook 'before-save-hook 'delete-trailing-whitespace)
(setq require-final-newline t)

Which does the equivalent of these ST options:

"trim_trailing_white_space_on_save": true
"ensure_newline_at_eof_on_save": true

Closing Parenthesis Insertion

The autopair package is built-in to Emacs and will insert the closing parenthesis. It isn't the smartest (such as inserting markup on a selected word in org-mode), but it works for now. Additionally, since I assume it is always on, there is no need to show it on my mode line (which I'll get into later). Also, since I'm now using Emacs and I find myself editing more and more lisp, I've turned on a mode which shows the matching open or close parenthesis if one is selected.

;; autopair
(autopair-global-mode)
(diminish 'autpair-mode)
(show-paren-mode 1)

Large Files

One of the greatest things about ST is its handling of large files. In Emacs, I can at least set the threshold for warning me about the large file:

;; warn when opening files bigger than 100MB
(setq large-file-warning-threshold 100000000)

Adding Language Syntax

Emacs has built-in support for many coding languages, but sometimes you'll need to ensure that the right mode is triggered for the correct filenames and/or extensions. Here are two examples for turning on CMake file support.

In this first example, it assumes that cmake-mode has been installed manually:

;; CMake
(setq auto-mode-alist
      (append
       '(("CMakeLists\\.txt\\'" . cmake-mode))
       '(("\\.cmake\\'" . cmake-mode))
       auto-mode-alist))

In this second example, use-package syntax is used for lazy-loading. This means we don't have to remember to package-install cmake-mode. It also means that the cmake-mode package is not installed until I open a CMake file.

;; CMake
(use-package cmake-mode
  :mode ("\\.cmake\\'"
         "CMakeLists\\.txt\\'")
  :config (use-package cmake-font-lock))

Here is another example, but for Rust:

;; rust
(use-package rust-mode
  :mode ("\\.rs\\'" . rust-mode))

The Best from Sublime Text

There are so many things that Sublime Text just gets right, some things I never knew I needed until they were at my finger tips.

Project View

One of the features from ST that I have come to expect is the project sidebar. Having a file browser is key to orienting myself within the project.

For this, I use Neotree (some documentation found here). Its look and feel can be customized, but I haven't experimented with that yet. I stuck with the suggested keybinding of <f8>. To customize it for Mac, I had to change the default system command to the open program.

;; neotree
(use-package neotree
  :bind ([f8] . neotree-toggle)
  :config (setq neo-default-system-application "open"))

Neotree supports a bunch of functionality in its buffer, including "quicklook" and "add file here". The one thing that is missing is the equivalent of the dired-do-shell-command. This would allow me to place the cursor at a file and trigger some command-line input. Keybindings which matched (or were similar) to dired's would be nice, but at least neotree supports the ? key.

Multiple Cursors

The arguably best thing about ST is the multiple cursors. Once you know about it, there are some many small things I open in ST just to use it.

Emacs does have its very own multiple-cursors package. Unfortunately, there are several issues with getting the right keybindings working on a Mac. Thus, I've dedicated the <f2> and <f3> keys for this. I've also used ESC ESC as the quit-this-mode command (similar to what would work in ST):

;; multiple-cursors
(use-package multiple-cursors
  :bind (("<f2>" . mc/mark-previous-like-this)
         ("<f3>" . mc/mark-next-like-this)
         ("C-c <f2>" . mc/mark-all-like-this)
         ("<ESC> <ESC>" . mc/keyboard-quit))
  :ensure t)

As you get started with multiple-cursors mode, it will ask you several questions to make sure you really intend to something at all cursors. The answer is usually yes. Sometimes things get mucked up and multiple cursors will behave weird in a particular mode. As documented here, the solution is remove the ~/.emacs.d/.mc-lists.el file.

Project-Wide Search

After some preliminary exploration, I still haven't been able to get a good cross-file search going. The built-in M-x grep does some nice things, but isn't very reliable. I will investigate this further in a future post.

Spell Check

My spelling is atrocious, so spell checking is a must. ST on Mac can turn on the system wide spell checker (with additional functionality to remember/ignore words). Unfortunately, getting spell checking on Emacs is much more complicated.

The default spelling program in Emacs is ispell, or interactive spell. To actually install the ispell dictionary on a Mac you must use homebrew and tell Emacs where to find the program.

I define the ispell program variable in my custom file since location is machine specific.

(setq ispell-program-name "/usr/local/bin/aspell")
(setq ispell-list-command "--list")

The only missing element is an always-on spell checker. Another Emacs package, Flyspell, does the trick. Now I just need to enable flyspell-mode by default for text-type buffers:

(dolist (hook '(text-mode-hook))
  (add-hook hook (lambda () (flyspell-mode 1))))
(dolist (hook '(change-log-mode-hook log-edit-mode-hook))
  (add-hook hook (lambda () (flyspell-mode -1))))

Things That Never Really Worked in ST

Now there are a couple of things that I could never really get working with ST. This includes deep git integration and opening a shell. Of course, Emacs supports these things! Over time, you'll slowly come to the opinion that you should never have to leave Emacs.

Git

Emacs git support is done through magit. This is an amazing project which gives you full git control without leaving Emacs. Magit works through a series of popups, meaning you only need to know one keybinding. Once you are in a magit popup, you can figure out how to do things with the ? key.

;; MAGIT
(use-package magit
  :bind ("C-x g" . magit-status)
  :ensure t)

Shell Integration

Unsurprisingly, Emacs offers deep shell integration. This post on Mastering Emacs Shells goes into the nitty-gritty details. There may be some settings needed to get M-x shell working properly with fish. However, M-x ansi-term seems do everything needed, just be careful that you don't startup Emacs inside your Emacs.

For very simple shell one-liners, there is always dired mode. The command ! allows you to run a shell command on the selected file. This works great for generating dot output from a graphviz file. I would really like a shortcut for opening the selected file from the system, but ! open works for now.

Org-mode

The absolutely best thing about Emacs is org-mode. There is way too much to cover here, so I'll talk about why you should consider org-mode and provide links to checkout. Case-in-point, this entire post was created with org mode. Unlike the other packages, I manually install org-mode when setting up a new computer.

Basics Syntax & Outlining

Org-mode is a lot like markdown, at its core it is a syntax for markup of plain text. Here is the basic markup:

Effect	Code
italic	`/italic/`
bold	`bold`
~~strike through~~	`+strike through+`
underlined	`_underlined_`
`code`	`~code~`
`verbatim`	`=verbatim=`
<h1>Heading 1</h1>	`* Heading 1`
<h2>Heading 2</h2>	`** Heading 2`
Link Text	`C-c C-l` or `[[http://gonsie.com][Link Text]]`

Also (as seen above), org supports spreadsheets (aka really smart tables). This support includes extra whitespace so that the tables always look aligned.

Org-mode does section folding with each heading. Hitting TAB will cycle through the visibility of the children.

Org-mode also supports blocks, such as code blocks, quotes, examples, and more:

#+BEGIN_SRC rust
fn sample_code () -> u32 {
    10
}
#+END_SRC

Renders to:

fn sample_code () -> u32 {
    10
}

#+BEGIN_QUOTE
Everybody lies
 -- Dr. House
#+END_QUOTE

Renders to:

Everybody lies – Dr. House

As you'll learn, the standard way to add markup/options/metadata within an org document is the #+SETTING marker at the beginning of a line. This is the way that org is able to support complex exporting to latex documents.

Literate Programming

Literate programming is the idea that a single document should include the thought process used to create code as well as the code itself. This works for R scripts, where the author is trying to tell a story about the data while presenting and including the data itself.

Export

Each org document can be exported, or converted, to a document in a different language. Export options include LaTeX, Beamer, Markdown, HTML, and more. The exporter pane is brought up with C-c C-e.

Tangle

All the pieces come together with tangling. Tangling takes a piece of code which is written your document and executes it. Then, it can even embed result directly in the document itself.

Here are two examples of org-mode source code blocks. To generate the RESULTS blocks, one would type C-c C-c within a source block.

Example 1: Shell Command

#+BEGIN_SRC bash
hostname
#+END_SRC

#+RESULTS:
Eris.local

Example 2: Generate and Embed an Image

#+BEGIN_SRC dot :file images/example_dot.png :cmdline -Kdot -Tpng
digraph g {
rankdir = LR;
a -> b;
}
#+END_SRC

#+RESULTS:

I'll just let that seep in. The possibilities are truly endless.

Agendas

One great feature of org-mode is its ability to track to do items. Getting this system setup and organized can be somewhat of a bear, so I'll avoid getting overly detailed. Instead, I encourage you to start with a bare bones setup and see what works for you. If you do decide that org-mode agenda can fit into your daily workflow, I encourage you to look around at what others have done.

First, you'll need to turn on the org-mode agenda functions with some keybindings. The defaults are:

;; org-mode agenda recommended keybindings
(global-set-key "\C-cl" 'org-store-link)
(global-set-key "\C-ca" 'org-agenda)
(global-set-key "\C-cc" 'org-capture)
(global-set-key "\C-cb" 'org-iswitchb)

Next, you'll need an easy way to keep track of any TODO item you create. The easiest way I've found is this on-save hook (from Frederick Giasson). Through this hook, every org file is automatically "filed" and any to do items inside will be found by the org-mode agenda builder.

;; Add Org files to the agenda when we save them
(defun to-agenda-on-save-org-mode-file()
  (when (string= (message "%s" major-mode) "org-mode")
    (org-agenda-file-to-front)))

(add-hook 'after-save-hook 'to-agenda-on-save-org-mode-file)

This does mean that when files are deleted or moved the org agenda complains.

Conclusion

I've been down the Emacs rabbit hole about 2 months now. It has been fun and I'm excited to continue to modify my setup and play with new packages. You can find my setup on GitHub.

In my brief exploration I've found a number of extremely helpful individuals:

Sacha Chua: Sacha is incredibly inspiring and a prolific contributor to the Emacs community. She writes a weekly roundup of Emacs and Org news.
Frederick Giasson: He had the tip for automatically filing org files on save.
Pragmatic Emacs This blog has a number of tips for using Emacs in academia and with LaTeX.
Aaron Bieber He had blog post on using GUI Emacs, which convinced me to try it.

Elsa Gonsiorowski

Emacs Carnival: Org Mode Completions

Org Mode Tempo Templates

Default templates

Additional Templates

Basic Customization

Adding Tags

Create a New Hotkey

Create a Completion

My Custom Completions

Properties Drawer1

Title Block

Finally

Footnotes

Beautifying the Tab Bar

Basic Key Bindings

Settings

Theme

Binding the Tab Hint Numbers

Final Comments

Footnotes

Package cl is deprecated

The Fix

Finding cl requirements

Don't be afraid of eshell

What is eshell?

Bare Minimum

Path

Aliases

Next Steps

Sending Email from Org Mode

Overview

AppleScript for Email

Filling the Variables

Hitting Send

Emacs Delete vs. Kill

Understanding Key Bindings

Mac Keyboards

Default Commands

Combinations

Direction

Removal Type

Saving Items to the Kill Ring

Binding the Keys

Summary

Developing ox-jekyll

Starting Point

My Publishing Workflow Details

Implementing Features

Thinking about the Table of Contents

Preserving the Headline Level

Setting the Date

Results

Org Export Hooks

Hooks and Useful Functions

StackExchange to the Rescue

Hooking on to Something

Footnotes

Org and Jekyll: A Survey

My Current Process

Survey of Related Work

Jekyll-centric Approaches

Org-publish Approaches

Other Platform Approaches

Future Work

Conclusions

Configuring for Emacs 22 and 25

Old Initialization File Setup

New Scheme

.emacs

.emacs-custom.el

init.el

theme.el

Tips

Checking The Emacs Version

Checking for a Package

Package Initialization

Conclusion

Part 2: Counting Words

Exploring Existing Functionality

Properties Drawer¹

Finding `cl` requirements

`.emacs`

`.emacs-custom.el`

`init.el`

`theme.el`