Behind the scenes look at Spell It Out

For a little over 10 months now, I’ve been running a site that spells out acronyms used and found in the technology industry called Spell It Out.

Spell It Out in its current version is nothing more than a static site. Meaning a static site generator called Jekyll is used to put the whole thing together and then hosted on a server. That server being Netlify.

In the 10 months that I’ve been managing this project, I’ve created various scripts to handle different parts of my workflow. Before I get into my workflow, it’ll be helpful to share a little bit about the different parts of Spell It Out.

The site

As mentioned before, Spell It Out is generated using a static site generator called Jekyll. The reason why I chose to use Jekyll was that I wanted to get the idea for the site quickly out of my head and hosted for a site. Really the important thing for me was quickly capturing all the acronyms I was picking up on an almost daily basis.

The Jekyll project is setup so that every entry is added as a “post” to the Jekyll project structure.

Every time I come across a new acronym, all I do is add a new entry to my Git repo hosted on BitBucket and it gets added to the site. This happens automatically because I use Netlify to host the site. Netlify will watch for new commits. When a new commit is made, Netlify then kicks off a build process that will compile my Jekyll site. Once compiled, it syncs it to their CDN and it is available on the web for all to use.

I also use Algolia, a third party service that provides search capabilities. At the time of writing this article, I’m over 530 acronyms on Spell It Out. Which means having search is nice to quickly see if the acronym in question is spelt out on my site.

Workflows

Adding a new acronym to the site

In my project folder, I have a set of JavaScript files which are used to run various tasks. One of those is to create new entries in my Jekyll project structure.

node scripts/new.js "SIO" "Spell It Out"

The new script takes two parameters, the first being the acronym itself and then the second is the spelt out version of the acronym. What this produces is a markdown file with this front matter.

---
layout: post
title:  "SIO"
spelt_out: "Spell It Out"
date:   2018-10-11 23:00:00
---

The reason I created this file is, Jekyll by default doesn’t provide any command line options to generate post files for you. Plus I’ve got very specific front matter that are used for the project so with this script I could tweak the file generation to my needs.

From there, I will make a commit via Git which then kicks off the Netlify workflow for building and pushing out the updates to my site.

Syncing the latest index with Algolia

Once a new acronym is added, Algolia needs to be updated. This is done using a Node package called Algolia Atomic. All the package needs is a JSON file with all the acronyms to index and update the search indices.

In order to generate the needed JSON file, I’ve got a file in my project folder that just iterates through all the posts and structures a JSON file. The code for this looks like:

---
---
{% if jekyll.environment == "development" %}
{% assign sorted = site.posts | sort: 'date' | reverse %}
[
{% for post in sorted %}
  {
    "title": "{{ post.title }}",
    "url": "{{ post.url }}",
    "spelt_out": "{{ post.spelt_out }}",
    "objectID": "{{ post.path }}"
  }{% unless forloop.last %},{% endunless %}
{% endfor %}
]
{% endif %}

I only want this JSON file to be generated in a development environment because I don’t care to share this JSON on my site. For this reason the only way the file will output anything useful is by using this Jekyll command:

JEKYLL_ENV=development jekyll build

From there I run my atomic algolia script and my Algolia account will be updated with the latest acronyms.

Generating social images

Aside from updating Algolia, the JSON file generated is also used to generate social media images. Specifically for Twitter.

I’ve got a custom HTML “theme” set up that PhantomJS uses to generate images for use on Twitter. The JSON file is used to determine which acronyms were already generated into images and only the new ones are generated. All the images go into a single folder which then gets used to sync with AWS.

Syncing social media images

Once the social media images are generated I used AWS’ CLI to sync the images folder. This is nice because it’s like rsync and only uploads new image files.

aws s3 sync images/ s3://bucket-name

Tweeting an acronym

Although I wish I’d spend the time to automate this a little more, on a daily basis I try to run a script that tweets a spelt out acronym on the Spell It Out Twitter account @spellitout_xyz.

What the script does is goes through the generated JSON and chooses a random acronym. With the data from the JSON file, it can then retrieve the related image from S3. Once the image is retrieved, the image is uploaded to Twitter and then a tweet is generated that looks like:

Putting it altogether

While orchestrating all the steps in my various workflows takes only a few minutes to manage my project, it has become tedious. Seeing that once acronyms are added to the repo all the steps that follow are all the same, I’ve put together a bash script to run everything for me.

#!/bin/bash

JEKYLL_ENV='development' jekyll build

cd scripts

node algolia.js

node social.js

aws s3 sync images/ s3://bucket-name

cd ..

While not fully automatic, writing this bash script has shaved minutes off my workflow because it automates all the workflows I’ve described above. Plus it feels magical to run a single command and see everything firing off in front of you.