Alan D. Salewski (writings)

Left-hand ENTER key

2020-09-22T00:00:00+00:00

(Updated: 2023-05-05 to fix some typos)

Remap “Caps Lock” key as left-hand ENTER

[ This post is relevant primarily to right-handed folks, and to left-handed folks who use a right-handed computer setup (you use the mouse with your right hand). ]

I found myself working on a one-off task that involved a fair amount of copy/paste work in my terminal emulator, building up command lines with little tidbits of data gathered from here and there, without any typing (except to hit the ENTER key to run the command).

I am using X11, so selecting the source text tidbits is enough to “copy” it, and clicking the middle mouse button pastes it in the target window at the location of the cursor. So far, so good. Once the command line was ready I pressed the ENTER key (with my right hand), and then moved on to the next one.

I found that moving my right hand from the mouse to the ENTER key and then back to the mouse again was slowing me down, and the motion was generally irritating.

It occurred to me that it would be nice if there were an ENTER key within reach of my left hand, and that the Caps Lock key would be a good candidate for remapping for that purpose.

TL;DR

To turn your Caps Lock key into an ENTER key, run these two commands in a shell within your X11 session. If you are happy with the result, then add the commands to your ~/.xsession file (or your local system equivalent) to have them take effect the next time you restart X.

    $ xmodmap -e 'clear Lock'

    $ xmodmap -e 'keycode  66 = Return NoSymbol Return'

For best results, read the rest of the article first, though; the Caps Lock key on your keyboard might not be mapped to keycode 66. If that is the case, the above will just disable your Caps Lock key and turn whatever key that is mapped to keycode 66 into an ENTER key. Also described below is an approach to preserving the mapping when keyboards are hotplugged to the system (e.g., USB keyboards).

Background

A typical 104- or 105-key US keyboard has two ENTER keys reachable with your right hand:

one to the right side of the home row, and
one on the right edge of the number pad.

However, there are not any reachable from your left hand.

Since the Caps Lock key is useless anyway, it is a good candidate to re-map as a left-hand ENTER key. Having that allows you to keep your right hand on the mouse and use your left hand to press the ENTER key, when needed.

Gather tools and data

In order to remap the keyboard Caps Lock key, you will need a couple of pieces of information and two programs: xev(1) and xmodmap(1). On Debian-based systems, the xev program is provided by the x11-utils package, and the xmodmap program is provided by the x11-xserver-utils package. You may have one or both of them already, but if not:

    # apt-get -u install x11-utils x11-xserver-utils

The pieces of information needed include the “keycodes” for the “Caps Lock” and “Enter” keys, as well as the mapping (to “keysyms”) in effect for the “Enter” key (so we can copy it for use with the “Caps Lock” key).

Use xev to obtain the keycodes. Here’s what I saw initially for my “Caps Lock” key:

KeyPress event, serial 31, synthetic NO, window 0xd400001,
    root 0x1ab, subw 0x0, time 4049429559, (169,-13), root:(309,938),
    state 0x10, keycode 66 (keysym 0xffe5, Caps_Lock), same_screen YES,
    XLookupString gives 0 bytes: 
    XmbLookupString gives 0 bytes: 
    XFilterEvent returns: False

KeyRelease event, serial 34, synthetic NO, window 0xd400001,
    root 0x1ab, subw 0x0, time 4049429670, (169,-13), root:(309,938),
    state 0x12, keycode 66 (keysym 0xffe5, Caps_Lock), same_screen YES,
    XLookupString gives 0 bytes: 
    XFilterEvent returns: False

So that tells us that our “Caps Lock” key is mapped to keycode 66. A similar query for the “Enter” key told me it was mapped to keycode 36.

Next we will use xmodmap to obtain the keycode to keysyms mapping, and also the current state of the Lock modifier (from the “modifier map”).

Since we will make reference below to clearing the lock modifier, it is useful to note the initial state of it:

    $ xmodmap -pm | grep '^lock'
    lock        Caps_Lock (0x42)

[ The -pm option causes xmodmap to show us the current modifier map. ]

The next thing to find out was what the xmodmap setting for the “Enter” key looked like. That was done by browsing the output of the command:

    $ xmodmap -pke | less

[ The -pke option causes xmodmap to print on stdout the current keymap table, in the form of expressions that can be fed back into to xmodmap. ]

The two lines in that output of interest here were:

    keycode  36 = Return NoSymbol Return

    keycode  66 = Caps_Lock NoSymbol Caps_Lock

The first shows the setting for the “Enter” key, and the second is the initial setting for the “Caps Lock” key.

Let’s do it

To turn our “Caps Lock” key into a left-hand “Enter” key, we need to do two things:

Remove the lock modifier for the “Caps Lock” key.
Re-map the “Caps Lock” key’s keycode to the “keysyms” appropriate for an “Enter” key.

Step (1) is accomplished on the live system by using the command¹:

    $ xmodmap -e 'clear Lock'

[1] Note that a more surgical approach to the above action would be to run the command:

    $ xmodmap -e 'remove Lock = Caps_Lock'

Indeed, that was what I was using initially, but it came with complications.

The first (and easily dealt with) complication is that upon (re)attaching a USB keyboard to the machine, we could not know in advance the state of the lock modifier. We might find that the lock modifier is not applied to any keysym, or maybe it is applied to the 'Return' keysym, or perhaps applied to both 'Caps_Lock' and 'Return' keysyms, or some other variation. Just blindly running the above command would fail if the lock modifier was not currently set for the 'Caps_Lock' keysym.

So to use the more specific command requires first detecting the current state and then taking appropriate action. For example (in bash):

    current_lock_assignment=$(xmodmap -pm | grep -i '^lock[[:space:]]')

    shopt -q -s nocasematch

    if [[ "${current_lock_assignment}" =~ Caps_Lock ]]; then
        xmodmap -e 'remove Lock = Caps_Lock'
    fi

    if [[ "${current_lock_assignment}" =~ Return ]]; then
        xmodmap -e 'remove Lock = Return'
    fi

Depending on other factors in your machine configuration, the above may work for you "as is". If so, it is probably a better approach than the approach I ultimately took because it expresses precisely the desired configuration.

In my environment, however, I have another complication: There is something else in the mix also responding to the "keyboard enabled" events, and it is conflicting with my use of the above. Oddly enough, it only affects me every other time I plug the keyboard in. The observed behavior is that the lock modifier is applied to the 'Return' keysym, and though the "Caps Lock" key still behaves as an "Enter" key, it also still toggles the letter case with each press.

I don't have time at the moment to track down the competing mechanism, but it does not rear its head (in any obvious way) when using the 'clear Lock' expression. So that is what I am going with, at least for now. Also, using 'clear Lock' is not a compromise of any functionality; I did not use lock for anything other than "Caps Lock" (the "Num Lock" key uses a different modifier ('mod2')).

Step (2) is accomplished on the live system by using the command:

    $ xmodmap -e 'keycode  66 = Return NoSymbol Return'

Congratulations, your “Caps Lock” key now functions as an “Enter” key. At this point, your “Caps Lock” should have stopped having any letter case-altering effect, and should have no locking (“toggle”) effect, either. If your keyboard has an LED light that used to turn on when your “Caps Lock” key was in the lock position, you will find that the LED is no longer lit when the “Caps Lock” key is pressed (or even held down).

Make permanent

The above settings are transient as currently configured. If you were to restart X or reboot your machine (or something similar) the old settings would come back when X gets reinitialized. To have the new settings take effect automatically in your next X session, there are two different approaches you might consider:

The first (and simpler) approach would be to add the commands exactly as typed above to your ~/.xsession file (or local system equivalent). If your keyboard is always plugged into the machine (typical for a desktop) then that approach is good enough.
The second, more elaborate, approach would be to take additional steps to allow the settings to take effect not only upon re-initializing X, but also when hotplugging the keyboard.

Make dynamic

If your keyboard is not always plugged into the machine (e.g., a USB keyboard plugged into a laptop machine, sometimes) then you will find that approach (1) above is not adequate. The reason is that, in X11, those keyboard setting overrides would applied only to the devices attached to the system at the time the settings are applied – that is, when initializing X.

If, for example, a USB keyboard is unplugged and then re-plugged, it will get default settings, not the override settings that we would have applied during X11 initialization.

One solution to this problem is the userspace inputplug(1) daemon, available in the ‘inputplug’ Debian package or from the GitHub repo andrewshadura/inputplug. Because inputplug monitors the system for a particular class of XInput2 events, it can determine when a new device has been (re)added to the system. When such an event is received, it invokes a user-provided program with the event metadata; that gives us a chance to (re)apply our override settings.

[ The approach described below is an adaptation of the technique presented by unix.stackexchange.com user mosvy in an answer in the discussion “Prevent keyboard layout reset when USB keyboard is plugged in”. ]

This approach uses four small pieces acting on concert.

my-keyboard-setup – A script with the above xmodmap commands in it
on-new-kbd – A script invoked by inputplug; calls my-keyboard-setup
~/.xsession (1st) – Modify to call my-keyboard-setup (at X init time)
~/.xsession (2nd) – Modify to launch inputplug daemon (at X init time)

Piece 1 of 4: my-keyboard-setup

The first is a small script that runs the xmodmap commands we have been using above. The reason for putting them in a dedicated script is that it will allow us to trigger the functionality from two different contexts.

    $ mkdir -p ~/bin/

    $ cat - <<EOF > ~/bin/my-keyboard-setup
    > #!/bin/bash -
    > xmodmap -e 'clear Lock'
    > xmodmap -e 'keycode  66 = Return NoSymbol Return'
    > EOF

    $ chmod 0755 ~/bin/my-keyboard-setup

Piece 2 of 4: on-new-kbd

The second is a script intended to be invoked by inputplug that will decide when to invoke the above command (basically, only when a new keyboard has been enabled). There is a more complete version in the on-new-kbd Gist, but the basic idea looks like this:

#!/bin/bash -
declare -r PROG='on-new-kbd'

# When invoked by 'inputplug', four command line parameters will be
# provided:
#
#     event-type device-id device-type device-name
#
# See inputplug(1) for details.

event_type=$1
device_id=$2
device_type=$3
device_name=$4

# Examples:
# =========
#
# Note that we get two different events when we unplug the keyboard, and
# two different events when we plug the keyboard back in.
#
# Unplug events:
#
# -----------------------------------------------
# event_type:  XIDeviceDisabled  XIDeviceDisabled
# device_id:   10   10
# device_type: XISlaveKeyboard XISlaveKeyboard
# device_name: is_unset_or_null 
# -----------------------------------------------
# event_type:  XISlaveRemoved  XISlaveRemoved
# device_id:   10   10
# device_type: is_unset_or_null 
# device_name: is_unset_or_null 
# -----------------------------------------------
#
#
# Plug event:
#
# -----------------------------------------------
# event_type:  XISlaveAdded  XISlaveAdded
# device_id:   10   10
# device_type: XIFloatingSlave XIFloatingSlave
# device_name: Microsoft Natural Keyboard Elite Microsoft Natural Keyboard Elite
# -----------------------------------------------
# event_type:  XIDeviceEnabled  XIDeviceEnabled
# device_id:   10   10
# device_type: XISlaveKeyboard XISlaveKeyboard
# device_name: Microsoft Natural Keyboard Elite Microsoft Natural Keyboard Elite
# -----------------------------------------------

case "${event_type} ${device_type}" in

    'XIDeviceEnabled XISlaveKeyboard') my-keyboard-setup ;;

    *)
        : uninteresting event -- ignore
        ;;
esac

Piece 3 of 4: ~/.xession call to my-keyboard-setup

To have our keyboard mapping overrides take effect during X11 initialization, add a line such as the following to your ~/.xsession file (or equivalent):

    "${HOME}/bin/my-keyboard-setup"

Piece 4 of 4: ~/.xession run inputplug(1) daemon

Also done during X11 initialization, arrange for the inputplug daemon to run and to invoke the on-new-kbd script for device add/remove and enable/disable events. To do so, add a line such as the following to ~/.xsession beneath the line we just added in the previous step:

    /usr/bin/inputplug -c "${HOME}/bin/on-new-kbd"

Summary

At this point you should have a working left-hand ENTER key that is both permanent and dynamic. Enjoy!

initialysm (definition)

2020-09-17T00:00:00+00:00

initialysm: (noun)

[portmanteau of initially + initialism
syllables: ini·tial·ysm
pronunciation: i-ˈni-shə-ˌli-zəm (pronounced identically to "initialism")]

A word interpreted as an initialism that predates its own expansion; such a word that was born backwards. As in, "Initially it was just the initials, but later each letter was made to stand-in for a word for mnemonic effect."

Like a backronym, but is always pronounced as a series of letters.

Etymology
The word initialysm was coined in order to explain the name of the aagg program, a command line program for use on Unix-like systems.

The name of the program is pronounced "a a gee gee", with the individual letters standing for the expansion phrase "AWS-a-go-go".

The program was initially named by finding a small number of characters that combined to form an easy to type, grep-friendly sequence on a standard QWERTY keyboard. Later, when it came time to document the program for use by others, the expansion phrase was retrofitted as a mnemonic device.

Debian 9.x “stretch” APT pinning change

2017-06-25T00:00:00+00:00

Last week (on 2017-06-17), Debian GNU/Linux 9.x (codenamed “stretch”) was released. While preparing to update one of my systems I came across the following statement in section 5.3.2.2 of the release notes (“New requirements for APT repository”):

5.3.2.2. New APT pinning engine

APT 1.1 introduced a new pinning engine that now matches the description in the manual page.

The old engine assigned one pin priority per package; the new one assigns pin priorities per version. It then picks the version with the highest pin that is not a downgrade or that has a pin > 1000.

This changes the effect of some pins, especially negative ones. Previously, pinning a version to -1 effectively prevented the package from being installed (the package pin was -1); it now only prevents the version of this package from being installed.

I run my Debian systems without systemd, and my initial reading of the above text gave me pause because I use APT pinning to prevent systemd from becoming my init system. My initial reading of the above left me with the misunderstanding that I would need to apply a different mechanism to keep my current init setup ('/sbin/init' provided by sysvinit-core package).

The default init system on Debian (since Debian 8.x, codenamed “jessie”) has been systemd, in which '/sbin/init' is provided by the systemd-sysv package. This continues to be the case with Debian 9.x.

My existing setups use a customized set of APT preferences which, among other things, contains the file:

    /etc/apt/preferences.d/LOCAL-avoid-systemd.pref

whose meat is:

    Package: systemd-sysv
    Pin: release o=Debian
    Pin-Priority: -1

The effect of the 'Pin-Priority' of -1 is to prevent APT from ever installing the 'systemd-sysv' package. And indeed, this is how the mechanism continues to work in Debian 9.x “stretch”. I did not realize this without closer study, however.

After spending more time than I care to admit searching for and reading related info on the ‘Net, I came to realize that the statement in the release notes above applies very specifically to how APT treats pinning of versions. The above APT configuration, in contrast, is based on the separate concept of release origin.

The above config file snippet applies the -1 pin priority to any 'systemd-sysv' package in which the “Release file” declares the origin as “Debian” (the release o=Debian bit). It does not contain any bits related to the package version.

In retrospect, this is all rather obvious, and I’m embarrassed to think how much time I spent researching it. It was also quite helpful to read the motivation for the release notes blurb, which is contained in bug #852967, against the ‘release-notes’ pseudo-package.

Other than mucking around with my 'sources.list' file (and related), I tend to go many years between having to think about my APT configuration at all – so it is easy to become hazy on the details. Hence my focus on the -1 pin priority but glossing over the specific language in the release notes of “pinning a version” (which it is now clear that I am not doing).

I hope the above saves somebody from the need to research the same concerns I had.

Terraform HOWTO: delete a non-empty AWS S3 bucket

2017-04-30T00:00:00+00:00

The Amazon AWS S3 service provides a number of different ways to delete a non-empty S3 bucket; some of the approaches involve “emptying” the bucket prior to deleting it. The process can also vary a bit depending on whether or not the bucket has versioning enabled.

When the “aws” provider is used, the Terraform program acts as a client to the AWS service, so has a number of available approaches it can take when deleting S3 buckets.

When managing your infrastructure using Terraform, one common way to get rid of an infrastructure resource (cause it to be destroyed) is to simply remove it from your Terraform configuration (either by commenting-out it’s configuration block or by deleting it from the configuration file entirely).

Non-empty S3 buckets throw a monkeywrench into that process. The data stored as S3 objects within the bucket can be considered as separate (possibly precious!) artitfacts, so a little extra convincing is needed to let Terraform know that you really do want it to delete an S3 bucket resource and any data objects it contains.

If you simply get rid of the configuration block for the bucket, the terraform plan command will succeed in telling you that it would remove the bucket (as you might expect):

    $ terraform plan
    Refreshing Terraform state in-memory prior to plan...
    The refreshed state will be used to calculate this plan, but will not be
    persisted to local or remote state storage.

    aws_s3_bucket.your_tf_s3_bucket_resource_name: Refreshing state... (ID: your-bucket-name)
    The Terraform execution plan has been generated and is shown below.
    Resources are shown in alphabetical order for quick scanning. Green resources
    will be created (or destroyed and then created if an existing resource
    exists), yellow resources are being changed in-place, and red resources
    will be destroyed. Cyan entries are data sources to be read.

    Note: You didn't specify an "-out" parameter to save this plan, so when
    "apply" is called, Terraform can't guarantee this is what will execute.

    - aws_s3_bucket.your_tf_s3_bucket_resource_name


    Plan: 0 to add, 0 to change, 1 to destroy.

However, if you were then run terraform apply you might be surprised by the error:

    $ terraform apply
    aws_s3_bucket.your_tf_s3_bucket_resource_name: Refreshing state... (ID: your-bucket-name)
    aws_s3_bucket.your_tf_s3_bucket_resource_name: Destroying... (ID: your-bucket-name)
    Error applying plan:

    1 error(s) occurred:

    * aws_s3_bucket.your_tf_s3_bucket_resource_name (destroy): 1 error(s) occurred:

    * aws_s3_bucket.your_tf_s3_bucket_resource_name: Error deleting S3 Bucket: BucketNotEmpty: The bucket you tried to delete is not empty. You must delete all versions in the bucket.
            status code: 409, request id: <request-id-value>, host id: <host-id-value> "your-bucket-name"

    Terraform does not automatically rollback in the face of errors.
    Instead, your Terraform state file has been partially updated with
    any resources that successfully completed. Please address the error
    above and apply again to incrementally change your infrastructure.

Despite the “delete all versions in the bucket” language of the error message, the above error will appear regardless of whether or not the bucket has versioning enabled.

The Solution

Terraform will happily delete all of the objects in the bucket for you, but you have to explicitly tell it to do so, and you have to know how to ask.

Let’s say you have the following as your S3 bucket configuration block in your Terraform configuration file:

    resource "aws_s3_bucket" "my_s3_bucket_resource" {

        bucket = "my-bucket-name"

        acl    = "private"

        versioning {
            enabled = true
        }

        tags {
            Name        = "whatev-name"
            Environment = "whatev-env"
        }

        lifecycle {

            # Any Terraform plan that includes a destroy of this resource will
            # result in an error message.
            #
            prevent_destroy = true
        }
    }

You’ll want to do two things to allow the above S3 bucket to be deleted:

Comment-out (or remove) the 'prevent_destroy' setting
Add a 'force_destroy' setting

Here’s our new version:

    resource "aws_s3_bucket" "my_s3_bucket_resource" {

        bucket = "my-bucket-name"

        force_destroy = true

        acl    = "private"

        versioning {
            enabled = true
        }

        tags {
            Name        = "whatev-name"
            Environment = "whatev-env"
        }

    #     lifecycle {
    #
    #         # Any Terraform plan that includes a destroy of this resource will
    #         # result in an error message.
    #         #
    #         prevent_destroy = true
    #     }
    }

Now you can see the plan for destroying that bucket (and its dependencies) with the command:

    $ terraform plan -destroy -target=aws_s3_bucket.my_s3_bucket_resource

And then to actually have the bucket, its content, and its dependencies destroyed:

    $ terraform destroy -target=aws_s3_bucket.my_s3_bucket_resource
    [Terraform will prompt you to confirm, warning that there is no 'undo' for the action]

Here’s what it looks like in action:

    $ terraform destroy -target=aws_s3_bucket.my_s3_bucket_resource
    Do you really want to destroy?
      Terraform will delete the following infrastructure:
            aws_s3_bucket.my_s3_bucket_resource
      There is no undo. Only 'yes' will be accepted to confirm

      Enter a value: yes

    aws_s3_bucket.my_s3_bucket_resource: Refreshing state... (ID: my-bucket-name)
    aws_s3_bucket.my_s3_bucket_resource: Destroying... (ID: my-bucket-name)
    aws_s3_bucket.my_s3_bucket_resource: Destruction complete

Destroy complete! Resources: 1 destroyed.

Q: What would happen if we did not comment-out `'prevent_destroy'`?

You may be wondering what would happen if we did not comment-out the 'lifecycle' setting prevent_destroy = true while having force_destroy = true set at the same time. The answer is that Terraform would do what you would want it to do: it would refuse to delete the S3 bucket:

    $ terraform plan -destroy -target=aws_s3_bucket.my_s3_bucket_resource
    Refreshing Terraform state in-memory prior to plan...
    The refreshed state will be used to calculate this plan, but will not be
    persisted to local or remote state storage.

    aws_s3_bucket.my_s3_bucket_resource: Refreshing state... (ID: my-bucket-name)
    Error running plan: 1 error(s) occurred:

    * aws_s3_bucket.my_s3_bucket_resource: aws_s3_bucket.my_s3_bucket_resource: the plan would destroy this resource, but it currently has lifecycle.prevent_destroy set to true. To avoid this error and continue with the plan, either disable lifecycle.prevent_destroy or adjust the scope of the plan using the -target flag.

Terraform version: 0.9.4 (released 2017-04-26)

The examples in this post all used terraform-0.9.4 (released 2017-04-26), but are likely to work just fine with both earlier and later versions. The earliest version expected to work (not tested!) is terraform-0.5.3 (the version that introduced the 'force_destroy’ parameter for AWS S3 bucket resources).

Additional Reading

The rationale for Terraform not blindly deleting S3 objects was discussed in hashicorp/terraform#1977; the discussion there includes the need for some sort of “force” option.

The 'force_destroy' option was implemented in hashicorp/terraform#2007.

The ‘force_destroy’ option is also documented in the Terraform under the “aws” provider.

Al’s GitHub Pages with Jekyll cheatsheet

2016-06-18T00:00:00+00:00

(Updated: 2020-05-05 to add notes on creating the orphan ‘gh-pages’ branch)

Preliminaries

Create an “orphan” git branch named ‘gh-pages’

GitHub Pages will allow you to publish your project’s site from a few different “sources”. Here we are concerned only with one of those approaches: an “orphan” git branch named 'gh-pages' within the repo.

The name 'gh-pages' is not optional; it is treated specially by GitHub Pages. You cannot choose an arbitrary branch name from which to publish your project’s site; the branch must be called 'gh-pages'.

Note that your project’s settings page in the GitHub web site will only show the 'gh-pages' branch as an option in the GitHub Pages “Source” drop-down if the branch already exists in your project’s repository.

For the purposes of publishing your project’s site on GitHub Pages, you’ll want the 'gh-pages' branch to be an “orphan”. That is, you want it to have a history that is entirely disconnected from the other existing branches in your repository. To achieve that, we are going to use the --orphan option to git-checkout(1):

    $ git checkout --orphan gh-pages
    Switched to a new branch 'gh-pages'

At this point, a git status would show that all of the repo’s files that were being tracked on the branch source point are now staged in the index; git does this in anticipation of the user wanting to create a new, clean go-forward history for the “as is” state of the files. That is not our use case, however; we are going to use an entirely different set of files on our new branch, so we can just clear out the git index:

    $ git rm -fr .
    
    $ git status
    On branch gh-pages

    No commits yet

    nothing to commit (create/copy files and use "git add" to track)

Now you have a clean 'gh-pages' branch with no commits. Read on to see how we want to populate it, starting with a file named 'Gemfile'.

In your brand new working directory for a site you intend to generate with Jekyll and host with GitHub Pages, you will want to have some tooling available locally to allow you to veiw the Jekyll-based site generation prior to pubishing it on GitHub Pages.

The Jekyll software is written in Ruby, and (as is true of most Ruby software) is released in the form of a “gem”.

    $ cat - <<EOF > Gemfile
    source 'http://rubygems.org'
    gem 'github-pages', group: :jekyll-plugins
    EOF

This will install (into the 'local-ruby-gems' subdir) the dependencies specified in the 'Gemfile' (see Gemfile(5)), along with all of their dependencies.

    $ bundle install --path=./local-ruby-gems --verbose


    $ cat - <<EOF > _config.yml
    title: my-project-name by Alan D. Salewski
    description: blah blah blah

    markdown: kramdown

    kramdown:
        input:     GFM  # Enable GitHub Flavored Markdown (fensed code blocks)
        hard-wrap: false

    highlighter: rouge

    exclude:
        - local-ruby-gems/    # avoid processing jekyll itself; see also https://github.com/jekyll/jekyll/issues/2938
    EOF

Regular usage

Prior to publishing: edit -> review -> commit cycle

Once you have your tooling setup in your project’s git working directory, you will basically just edit the Markdown files of individual articles in the '_drafts' subdirectory. The edit -> review -> commit cycle works almost the same as any other software project, with commits happening wherever makes sense for the particular article content.

The “review” phase mainly involves just rereading the article content and making adjustments as necessary. Before committing, however, you should view the Jekyll-rendered form of the article in your web browser. To do that, you could just 'git push' to GitHub Pages and hope for the best, but since you’ve gone through the trouble of setting up your local Jekyll-based tooling you should launch the local web server built into Jekyll for previewing your changes.

This will generate the static site and render it the way it will be published when you 'git push ...' your changes up to GitHub:

    $ bundle exec jekyll serve --watch
    Configuration file: /path/to/project/_config.yml
    Configuration file: /path/to/project/_config.yml
                Source: /path/to/project
           Destination: /path/to/project/_site
     Incremental build: disabled. Enable with --incremental
          Generating...
                        done in 0.389 seconds.
     Auto-regeneration: enabled for '/path/to/project'
    Configuration file: /path/to/project/_config.yml
        Server address: http://127.0.0.1:4000/
      Server running... press ctrl-c to stop.

The following variation of the same command (adds the '--drafts' option) will generate the static site and render it with all of your unpublished drafts integrated into the site:

    $ bundle exec jekyll serve --watch --drafts
    Configuration file: /path/to/project/_config.yml
    Configuration file: /path/to/project/_config.yml
                Source: /path/to/project
           Destination: /path/to/project/_site
     Incremental build: disabled. Enable with --incremental
          Generating...
                        done in 0.639 seconds.
     Auto-regeneration: enabled for '/path/to/project'
    Configuration file: /path/to/project/_config.yml
        Server address: http://127.0.0.1:4000/
      Server running... press ctrl-c to stop.

In addition to the normal posts (everything beneath the '_posts' subdir), the above command also includes everything beneath the '_drafts/' subdir.

Q: Should I check the Gemfile in?

(Concerned that it might have an adverse effect if interpreted by the remote GitHub site builder.)

A: Yes, empirical testing shows that the remote site builder does not break.

Publishing

Once you are happy with the content of an article, you can cause GitHub Pages to render it by moving it from the '_drafts/' subdir to the '_posts/writings/' subdir, with a publication date embedded in the file name:

    $ git mv _drafts/my-article.md _posts/writings/YYYY-MM-DD-my-article.md

Push your locally committed changes to GitHub to have them rendered by GitHub Pages:

    $ git push --follow-tags origin master
    ...