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:

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

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:

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:

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 :

Personal History

I have always preferred smaller, lighter keyboards, particularly Apple’s built-in laptop keyboards and their “magic” keyboard line. (I am also a total Apple fan, since before they were cool. I had a PowerBook G4 in high school). I thought the often maligned butterfly keys on the 2015/2016 MacBook were just outstanding; though many folks ended up having issues with them. To me, mechanical keyboards, which can require heavy keypresses and which usually have a loud clack sound, were in no way appealing.

For the last 15 years I have been using a Dvorak layout. I use MacOS to do the key mapping (no extra/fancy software) and I 100% touch type when I’m doing Dvorak. macOS offers “Dvorak with QWERTY ⌘”, but I do not use it. If I need to switch to qwerty, I essentially hunt-and-peck as all my muscle memory is gone. I do, however, still use qwerty on my phone keyboard.

I am also a big Emacs fan. My favorite saying about emacs is “some people have a zen garden, I have an emacs configuration.” I have long history of tweaking my key chords and changing / adding shortcuts. Relatedly, I have always re-mapped caps lock to control.

All this to say, changing my keyboard layout and tweaking parts of my workflow are something that I find fun. In the past few years, my MoonLander (and now my Voyager) are really filling this need for me as I have had less time to play with emacs.

Typing Practice

I’m a big fan of doing typing practice. To learn Dvorak, I essentially took a summer off (a summer when I couldn’t find a job during grad school) and spent my time playing typing games with Dvorak. I was able to go all-in on Dvorak, as I didn’t have any other commitments at the time. Thus, I learned to touch type (using the MacOS keyboard viewer to get me started).

In addition to the great typ.ing platform from ZSA, I use keybr.com and Emac’s speed-type package for regular practice. My favorite typing game used to be sunrise typer. It had 10 levels of typing where you had to get faster and more accurate to successfully complete the level and qualify to get to the next level. I’m pretty sure it was a flash-based game, so at some point it was wiped from the internet and I haven’t been able to find it in a long time. (Please reach out if you know of it!)

MoonLander

In early 2023 I fractured my right wrist and was in a cast. Trying to position my arm to type was painful… which was unacceptable as my day job is 100% keyboard-based.

I forget exactly where I heard about ZSA and the MoonLander, (I think it was from a profile on Uses This) but I was really intrigued by their keyboard layout program and the many macros that you could set up. The MoonLander was on my radar and in my list of pretty things that might one day upgrade my home setup.

After about 24 hours of furious research, I settled on getting a MoonLander with white printed keys and Kailh silver switches. My goal was for relatively quiet keys and a light press. (Note that I ended up adding some silencing o-rings, which helped a bit, but my keyboard was still much noisier than I would have liked.) My research was mostly around which switches I would want, since this was my first mechanical keyboard purchase. I didn’t think much about what my layout would be… though that ended up being where all the fun of owning the MoonLander.

When my MoonLander finally arrived, it was so much fun! I tried a couple of different layouts, including a straight Dvorak one. However, I settled on using a qwerty layout and still relying on MacOS to implement the Dvorak mapping. Thanks to the timeline in Oryx, I can look back and see that it took me about a month to get a good layout, which I regularly tweaked for the next year or so. Then, I made essentially no changes for almost 2 years, until I started prep for my voyager keyboard.

Besides messing with the layout, I also added o-rings to my keys to try and silence them more. It made minimal difference. I later bought a cute keycap set and didn’t bother with the o-rings. (A note about my keycap purchase: unfortunately I didn’t pay much attention to the OEM-profile and some of the keys look a bit wonky.) Also, while the MoonLander comes with a nifty travel pack, I have never taken it any where. In fact, I don’t think it had left my desk until the Voyager showed up.

MoonLander Layout

The MoonLander, obviously, has keys in different places than a traditional keyboard. Overall, it has 72 keys, compared to 81 on my MacBook. Additionally, 8 of the MoonLander keys are on the thumb module… further reducing the number of keys I could map to. Upon first seeing the MoonLander I realized I in a bit of trouble. There was an extra column of keys in the middle, and a dearth of side keys. This was going to require more changes than initially expected.

My guiding principle in creating my layout was to keep things simple and try to keep keys in their general location. I didn’t want to go too crazy with macros and special tapping, mostly to keep the learning curve low for myself. I also didn’t want to be totally at sea if I wasn’t typing on my MoonLander.

Overall, my layout ended up with a bunch of dead keys. Namely, I couldn’t reach the red “launch” keys at all and have never used them. I also rarely used the ‘third’ thumb key on either side. Finally, the extra middle column of keys was almost never used, except in one case noted below.

MoonLander Layout Decisions

See my layout on Oryx

Function Key Row.
Hide behind number row on a layer.

Left-Hand accessory keys: tab, `, and esc.
With MoonLander, these 3 keys are essentially reduced to 2 (due to the missing row of function keys). My solution was to put esc and ` on the same key (esc as tap and ` as hold). I kept tab on the second key, in addition to having it on the thumb module (actually on both, one key on each side).

Left-hand modifiers: ctrl, option, command
I kept these in the same places, in the bottom row, as on the Mac keyboard (with caps lock switched to ctrl), and added a layer switch (though it didn’t really get much use until I started prepping for voyager).

Right-hand accessory keys: [, ], and /
I move these to a single key. Tap for [, hold for ], and double tap for /. Not perfect, and I do sometimes get these wrong, even after years with this layout… but having all this in one spot that is in the relatively correct physical position feels good to me.

Right-hand Return
Moved to thumb module (actually on both, one key on each side).

Right-hand accessory keys: - and =
These I never really found a good spot for. I ended up putting them on the inner column, way far away from where I would have naturally expected them to go. I also really wanted to be using these keys for in-app tab-switching (as in Dvorak those keys are mapped to [ and ] respectively). Thus, these keys ended up with some of the few macros I’ve set up (namely Cmd+Shift+[ and Cmd+Shift+]) and one of my most frequent uses of a layer.

Right-hand arrow keys
Mac keyboards have a very nice arrow key cluster, with admittedly tiny keys. I wanted to keep access to arrow keys, though I have tried to minimize their use (instead relying on Ctrl-n, Ctrl-p, Ctrl-b, Ctrl-f, etc.). I have made some failed attempts to use Vi, but could never quite wrap my head around the hjkl mapping (the left/down/up/right order just doesn’t make sense to me, besides the fact Dvorak throws a wrench into it). Anyways, I decided to use the Vi mapping of left/down/up/right for arrow keys, just to force myself to learn it, and these keys live on the bottom row of the right hand. I do not use my right thumb for any Cmd or Opt combos.

Layers
Overall, other than using a layer for the infrequently used function keys, I didn’t utilize layers much at all in my daily typing. What I instead rely on is built in use of the command and option keys. My left thumb is very much dancing between the thumb module and both the Cmd and Opt keys.

Macros
I have Cmd+Space as hold action for my left-hand space button. This will bring up Alfred (I’ve been an Alfred power user for a decade). I also use it for my Todoist quick-add hotkey (Ctrl+Cmd+Space).

Voyager

Last fall, I made the decision to get a Voyager. I was very excited to have a physically smaller keyboard, one with a more laptop-like feel (and hopefully quieter keys). Moving from MoonLander to Voyager was going to require a more intense condensation of keys, as Voyager has only 52 keys overall. Basically, one whole row is missing when compared with MoonLander!

Before I decided on making a purchase I looked at how others had dealt with the missing row. The default layout suggested by ZSA eliminates the bottom row, namely the command/option/control keys, moving these keys to either the thumbs or in the far outside corners for the pinky to activate… this felt very different from my current setup and was essentially a non-starter for me as I really wanted to keep command and option within reach of my left thumb. But, in keeping the number row at the top, there was no where for these to go (as they would clash with the C/V/B keys on the bottom row of letters).

A revelation came in searching through layouts on oryx. I found a user who had foregone the number row at the top, essentially shifting the home row up one from the default layout. This would leave me room for my row of modifiers along the bottom, but required hiding the number row behind a layer. That, coupled with another layout where each number key added the Shift modifier when doing a hold on the key, solved my biggest concern and I soon after ordered the Voyager.

I bought the Voyager for myself as a Christmas present, so I had a few months to wait before I would actually “receive” it. I started migrating my MoonLander layout to what I would use with my Voyager. This gave me time to practice and tweak my layout, and more slowly transition to the new layout.

Voyager Layout Decisions

See my layout on Oryx.

Number Row
I hid this on a layer behind the QWERTY row. This layer also includes a number keypad layout on the right side. Each number key will type Shift plus that key when held. That is, 1 will type ! when held.

Right-hand Delete Key
This was a tough one and I had a lot of muscle memory of hitting delete in the upper right corner. My only choice seemed to be to move it to one of the thumb keys, and it took some experimentation to figure out which one would work for me. I tried having it on the same key as Enter… but a lot of my typing is in chat-rooms and hitting enter when I wanted to hit delete was very problematic. After noticing that I usually typed the Space key with my right hand, I ended up putting Delete on my left-hand thumb where I had previously had a Space.

Left-hand Tab Key
I decided to move the Esc/` key down a row and remove tab key in that spot. I already had gotten used to having the tab on the thumb module, except for the Cmd+Tab combo (macOS application switcher). With tab on the thumb module, I had no comfortable way to do this key combo. I created a macro such that my thumb-key tab will now do Cmd+Tab when held. This will cycle through open applications on my Mac. It is useful to switch back to the most recently used app. Have I gotten good at stopping when the automatic repeated keypress kicks in, to find the exact app I want? Not really. Instead, I’ll use Alfred.

Right-hand accessory keys: - and =
Again, in Dvoark, these keys are really [ and ]. I’ve moved these to the same layer as my number keypad, in the “h” column. I’ve also put the macros Cmd+Shift+[ and Cmd+Shift+] on separate keys (but same layer), in the pinky-finger column.

Space on the left-side
Sometimes, when my right hand is on the trackpad, I need a way for my left had to hit space. I’ve thus added space to bottom left key.

Opt+Delete
To do delete word, I’ve added an Opt+Delete macro on a layer.

Screenshots
With the number keys hidden behind a layer, there was no good way for me to trigger the macOS screenshot hotkeys, namely Cmd+Shift+3 and Cmd+Shift+4. I’ve remapped those within macOS to be Cmd+Shift+, and Cmd+Shift+.. This gives the same positioning for my fingers (again, I’m using Dvorak layout).

Reflections after 1 month with Voyager

I am so glad that I did the prep. I basically unboxed my Voyager, loaded the configuration that I had been using on my MoonLander and realized there were some extra keys I hadn’t accounted for!

All in all, I still have 3 dead keys. I think it’s the emacs influence, but I am not inclined to have my pinky or any finger have to reach (besides my thumb). As such, the two leftmost keys in the bottom-row (left side) are currently not used (though mapped). I also didn’t quite realize there is now an extra key in the inner column, as that key is missing from the MoonLander. I’ve used a lego to create a switch blocker on the left side, which helps with my thumb positioning.

Unexpected joy: I can still get the long press on the delete! Even though I’ve mapped my hold action to Cmd+Space, doing a double-tap-hold will get me a delete and then a repeated delete action. I miss doing Opt+Delete (delete word), so I mapped that to layer.

In essence, I have a 2 layer setup. I make heavy use of modifier keys (control, command, option), in the way that the operating system expects (aka, Gnu Readline), so I feel like my keyboard-fu is on point. I do have some additional layers for the rarely accessed function keys, plus the ZSA keyboard controls, but my daily drivers in 2 layers. Getting to this point feels like a slow evolution, rather than radically re-learning how to type (which I had already done for Dvorak).

Going back to the MoonLander feels so… clacky, but my layout from one keyboard to the other is essentially identical. I do really really enjoy having a split keyboard, and I don’t think I will ever want to go back.

Conclusion

This is meant to be the kind of keyboard post that I would love to read. I am not very “tuned in” to the mechanical keyboard culture, only reading the monthly ZSA newsletter. I would have really liked to read something like this before. Where someone explains the decisions they had to make for their layout and the why they made a certain choice. The Oryx configuration platform is outstanding. ZSA, I feel, has really created an entry point (and shared community) for people to talk about keyboards, especially for dabblers like myself. Their series of People interviews is quite interesting, and something I was invited to contribute to, years ago, but clearly my todo list got the best of me and I never got around to writing anything.

All that to say, I’m glad I finally got around writing something. Thank you for reading!

Abandoned Posts

Just for the hell of it, here are the half-done blog posts I have hanging around. Let me know if any one in particular sounds interesting to you. Comments on this and all posts go directly to me (and for the time being I have no actual system for publishing them).

• Creating a 2 column layout with emacs-dashboard
• Alternate time systems
• Getting into emacs ansi-term
• Ediff is freaking amazing
• How I debug emacs issues
• Making org-mode presentations beautiful (presenting from within emacs)

New Interests

Anyways, here is a list of some hobbies that are sparking my interest right now.

• Reading books that really capture my attention
• Knitting (if only I had the time/space, but alas, not in this current season of life)
• Trying out modal editing, maybe something like Meow
• Trying a new keyboard and/or layout (I’ve been using Dvorak and Apple keyboards for a like decade ?!?)
• Converting this website to a new tech stack

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.

One of the things that has kept me from posting is that my blog is being indexed by Planet Emacs. I only found out from a comment that someone left, but apparently it’s been in there since March 2020. Now I feel bad for all those non-emacs posts! My solution is create an emacs-only RSS feed for my site.

Note: If you are using GitHub pages to deploy your site, skip to Step 4: Slightly Less Generation.

Step 1: Create the File Generator

Jekyll has the capability to generate whole pages. That is, no .md file exists in the source tree, but a .html file is generated and appears on the site. This requires writing a bit of ruby code (a Jekyll plugin), but a very easy to use template is included in the documentation (linked above).

module GenerateTagRSS
  class TagRSSGenerator < Jekyll::Generator
    safe true

    # loop to generate each feed file
    def generate(site)
      site.tags.each do |tag, posts|
        Jekyll.logger.info "\tGenerating feed for tag: #{tag}"
        # call to TagRSSPage instantiation function
        site.pages << TagRSSPage.new(site, tag, posts)
      end
    end
  end

  # Subclass of `Jekyll::Page` with custom method definitions.
  # TagRSSPage instantiation
  # Definition of what an RSS file looks like
  class TagRSSPage < Jekyll::Page
    def initialize(site, tag, posts)
      @site = site             # the current site instance.
      @base = site.source      # path to the source directory.
      @dir  = 'blorg/feeds'    # the directory the page will reside in.

      @basename = tag          # filename without the extension.
      @ext      = '.xml'       # the extension.
      @name     = tag + '.xml' # basically @basename + @ext.


      # Initialize data hash with a key pointing to all posts under current category.
      # This allows accessing the list in a template via `page.linked_docs`.
      @data = {
        'linked_docs' => posts
      }

      # Look up front matter defaults scoped to type `tags`, if given key
      # doesn't exist in the `data` hash.
      data.default_proc = proc do |_, key|
        site.frontmatter_defaults.find(relative_path, :tag, key)
      end
    end

    # Placeholders that are used in constructing page URL.
    def url_placeholders
      {
        :path       => @dir,
        :basename   => basename,
        :output_ext => output_ext,
      }
    end
  end
end

Now I don’t understand that code entirely, but I have verified that it does work.

Step 2: Template for the Generated Files

The R community has a similar “R topics” RSS aggregator, with an explicit requirement that included feeds are limited to on-topic posts. This post guides you through doing that by hand, for a single Jekyll tag. It provides a basic template for an RSS XML file, (only slightly adapted below).

  <?xml version="1.0" encoding="UTF-8"?>
  <rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
      <channel>
          <title>{{ site.title | xml_escape }}</title>
          <description>{{ site.description | xml_escape }}</description>
          <link>{{ site.url }}{{ site.baseurl }}/</link>
          <atom:link href="{{ page.url | prepend: site.baseurl | prepend: site.url }}" rel="self" type="application/rss+xml"/>
          <pubDate>{{ site.time | date_to_rfc822 }}</pubDate>
          <lastBuildDate>{{ site.time | date_to_rfc822 }}</lastBuildDate>
          <generator>Jekyll v{{ jekyll.version }}</generator>
          {% for post in page.linked_docs %}
              <item>
                  <title>{{ post.title | xml_escape }}</title>
                  <author>{{ site.email | xml_escape }} ({{ site.author | xml_escape }})</author>
                  <description>{{ post.content | xml_escape }}</description>
                  <pubDate>{{ post.date | date_to_rfc822 }}</pubDate>
                  <link>{{ post.url | prepend: site.baseurl | prepend: site.url }}</link>
                  <guid isPermaLink="true">{{ post.url | prepend: site.baseurl | prepend: site.url }}</guid>
                  {% for tag in post.tags %}
                  <category>{{ tag | xml_escape }}</category>
                  {% endfor %}
                  {% for cat in post.categories %}
                  <category>{{ cat | xml_escape }}</category>
                  {% endfor %}
              </item>
          {% endfor %}
      </channel>
  </rss>

Some notes on this snippet:

• This layout file has the .html extension. This is an assumption/requirement of Jekyll, our ruby generator code is what sets the output file extension to .xml.
• The posts which will be included are passed via the page.linked_docs variable.

Of course it’s important to make sure Jekyll knows that the generated files should default to using this layout. That is done in the _config.yml file.

defaults:
  - scope:
      type: tag
    values:
      layout: rss

Step 3: Getting it to Run

By default Jekyll will run any generators it finds in _plugins directory. I included a nice log message in the generation loop, so that I have some indication that each tag is being generated. Locally building my site is complete success!

The one slight issue is that GitHub pages won’t run unsupported plugins, aka the generator we just wrote. So much of this post feels moot. The whole reason I’m still using the Jekyll stack is that GitHub takes care of generating the site for me.

Step 4: Slightly Less Generation

Since I couldn’t get GitHub pages to actually generate the files from whole cloth, I had to do a bit by hand. This is relatively easy, given a list of tags which exist on my site, I simply create the following markdown file for each tag:

---
layout: rss
permalink: /blorg/feeds/emacs.xml
tagname: emacs
---

Then, in the RSS layout (from Step 1), instead of looping over the page.linked_docs variable, I use:

{% for post in site.posts %}
{% if post.tags contains page.tagname %}

(Don’t forget to close your if statement with an {% endif %} just before the end of the loop). This solution requires the manual step of me remembering to create the tag markdown file when I use a new tag, but it works!

Step 5: Profit

The final step is to share these RSS feeds with the world. I’ve created a whole feeds page which implements the following liquid to generate a nice list of topics with a link to each RSS feed (somewhat simplified here):

{% for tag in site.tags %}
  {% capture tagname %}{{ tag | first }}{% endcapture %}
  <a href="/blorg/feeds/{{ tagname }}.xml">{{ tagname }}</a>
{% endfor %}

Of course, you can find all this code in my site’s GitHub repository.

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.

A few of them feature some clever liquid to make updating/expanding easy for others. Here I’ve collected my portfolio of sites, all of which are still live, thanks to github and the power of static sites. Looking over this collection, I mainly see a lot of acronyms…

My Website

• gonsie.com
• Converted to Jekyll site in 2012 (still in use)
• Accent theme by Ankit Sultana (blog)

The only real blog in my portfolio, this site has a bunch of sections and cruft left around from past projects. Recently, I’ve created some post templates which allow me to easily post quotations and photos.

ROSS

• ross.cs.rpi.edu
• Launched 2013 (still in use)
• Polar Bear Theme by Camille Diez

The ROSS (Rensselaer’s Optimistic Simulation System) website hosts much of the user documentation for the simulator I worked on during graduate school. This is/was one of my more successful sites. My idea to build up documentation for ROSS (which was severely lacking) was to require a ‘blog post’ to the website for nearly every pull request. Each blog post contains a jekyll tag, which places that entry in the proper section of the overall documentation table of contents.

XPDES

• xpdes.org
• 2014
• Hyde theme by Mark Otto

The Extreme Parallel Discrete-Event Simulation (PDES) was a consortium of PDES researchers from several institutions. The site had some liquid to group ‘people’ pages by institution; the posts were for meeting agendas. The consortium lasted until 2016.

NYχ

• nychi.tech
• 2016
• Long Haul theme by Brian Maier Jr.

The New York Capitol Hackathon for Inclusivity was a hackathon I help organize in April 2016. We needed a quick website. This site includes some nice liquid for automatically generating the navigation menu from all pages that exist.

IHPCSS

• ihpcss.github.io
• 2018
• Git-Wiki theme (and functionality) by Yehonal

This wiki theme is very cool with tons of functionality. I created this site because there was a lot of information that I wanted to organize for students at the International HPC Summer School. I hoped the wiki feature would allow other to add content, but the site was voted down by the organizing committee and the content migrated to a different system.

HUST

• hust-workshop.github.io
• I joined in 2019 (still in use)
• SinglePaged Theme by Tim O’Brien

The HUST site was initially developed by Chris Bording, but I started co-organizing the workshop (and running the website) in 2019. This single-paged site uses post files to hold the content for each section. Any posts from the current year (as specified by the frontmatter in the index.md) are displayed. This allows us to easily keep the content file from previous years, without them getting in the way.

PSIP

• bssw-psip.github.io
• 2019
• Cayman Theme by Pietro Menna

This really simple site was for a bunch of markdown documentation whcih existed on GitHub for the Productivity and Sustainability Improvement Planning software improvement process. The coolest thing was an interactive Rate Your Project Survey which calculates a cumulative score for items checked off on the page (using javascript).

Jekyll Resume

• gonsie.com/jekyll-resume/resume.html
• 2019
• A jekyll implementation of the One Page Resume by Chris Coyier

I’ve used Chris Coyier’s one page resume since 2012 (slightly before I started using jekyll). In 2019 I created a template jekyll repository which I use to teach students about markdown and static websites. The template renders a resume written in markdown to a nice one page resume website. This site is really a demonstration of my markdown and css skills (rather than jekyll or liquid).

I (many others I know) are “exiting” the pandemic with new babies. If a global catatrophy doesn’t change your whole life, a baby certainly will. Some things become more important (like having a job that supports your new reality) and some things less so (like whatever you thought your 5-year career plan should be).

As my baby exits her first year, I am finding myself returning to a new normal. My hobbies, reading and knitting, have restarted after a long lockdown and pregnancy pause. In an effort to avoid storing my data in someone else’s system, I’ll be adding some reading logs and knitting project posts here.

If you’ve visited my site in the last month or so, you may have noticed a (poorly-stylized) comment box at the bottom of each of my blog posts. I’m working on setting a static-site friendly comment system. The goal is having all the comment data live within the blog repository (i.e., not using a third-party hosted service such as Disqus).

The general idea for the system is:

1. Readers fill out a comment form that is processed through a third-party, which essentially forwards the text to my email. Status: complete, using formsubmit.co.
2. I receive the comments in my email and add those comments to my blog repo. Status: workflow not finalized.
3. Comments appear on the relevant post. Status: not started, requires html/css design plus Jekyll infrastructure/Liquid to make the right ones appear.

Right now, I am able to accept comments. I’ve even received a few useful ones (some helpful folks pointed out that my site was broken in dark mode on some browsers). I am thinking about letting commenters include their GitHub username, that way comments could appear as commits to my blog repository and folks could have their identity linked… but I haven’t worked out all the detail yet.

Anyways, feel free to leave comments, I do get them and read them all! The comments just won’t appear on the site itself, yet.

This year, the ECP annual meeting is a virtual event. One of the platforms they are using is Gather.Town: a virtualized physical conference space. I. love. it.

You control a little avatar and move around a virtual space designed to look like work, or in this case, a meeting space. You enter rooms, you run into people, you get lost, someone corners you with a conversation that turns out to be awesome. I sit in the audience and work on my laptop while there is a talk going on in the background. Maybe it’s the pandemic isolation getting to my head, but I miss this. I never thought moving a little virtual character could make me feel so present. The only thing missing here was a coffee station for people to gather around.

I am already scheduled to use Gather.Town for another event this summer (the International HPC Summer School). I can’t wait to get my hands on helping to design the space. If we weren’t virtual, the event would have been held in Toronto… maybe we can get a layout from some landmark there!

In the mean time, I think I’ll try to create a personal Gather.Town instance… maybe I can convince a few of my more social co-workers (or even colleagues from other companies) to join me.