A behind the scenes look at running 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.

---

Originally posted on michaelsoolee.com.

Thanks for taking the time to read this article! I'd love to stay in contact and send you tips on programming and design, working from home and making side projects through my newsletter. Click here to sign up.

Comments

[Ben Halpern]

This is quintessential JAMstack. Thoughts on this as a trending approach for web development?

[Michael Lee 🍕]

Hey hey @ben ! Thanks for the question. There's been a lot of thoughts regarding JAMstack that I've considered for my projects.

Before it was JAM, I got hooked on Jekyll because static was so appealing for me. Wordpress' click a button and have a site up in minutes was so appealing a few years back with a lot of hosting providers but you ran into a lot of issues like updates, praying that plugins didn't break on upgrades, DB corruptions and so on. With Jekyll, you could fall back on HTML, CSS and JS and create "dynamic" static sites which let you focus on the building instead of the managing. This was important for me, for example for my site. Although my writings date 2013 on my site, I've been writing on the web for much longer. So where is the archive pre 2013? Gone because it got lost in a DB somewhere. Exhausted by always having to maintain a system instead of creating content, when I stumbled on Jekyll, I was sold.

Fast track to 2018 and there is a lot to be excited about with static and the JAMstack scene. I've written about some of my excitement back in 2016 for Forestry. But with the entry of companies like Forestry and Netlify, I find it easier, cheaper and faster to get up and running with a static site. Some thing like Forestry allows you to adopt Hugo or Jekyll as a CMS where multiple authors can be supported. Which I think was a huge roadblock for bigger entities to adopt static. Netlify provides hosting, CDN, SSL and build and deployment which is phenomenal. It integrates well with BitBucket and GitHub. They also have some killer features such as forms that you can collect submissions from with just normal markup. Or lambda functions from within Netlify.

Really you can get creative with the JAMstack as long as you know the benefits and the limitations. But with services coming about these days, I can see a lot of the limitations disappearing. One use case is e-commerce for static or commenting. Or in Spell It Out's case, a lot of the steps are still manual to me. Which I don't mind since I like to curate the quality of the content, but there is a limit. I think I could eventually get to a point of automation for a lot, if not all my problems, but just haven't had the brain power to do so.

But would love to see more examples of projects that are successfully using the JAMstack. As a creative, static sites and the JAMstack has really allowed me to hash out my ideas quickly instead of worrying about frameworks, databases and servers.

[Ali Spittel]

I love it b/c you can host your site for free in a lot of cases. That's my #1 reason for using JAMstack.