With GitHub Pages and Mailchimp

This is the easiest setup I could think of. I keep my signup page for the Tester’s Digest newsletter in the index file of my GitHub Pages site. The archive of past issues is also kept there, with each issue written and committed as a Markdown file. GitHub Pages is free for public projects. This gives me revision control, no worries about backing up content, high availability, and ease of authoring in Markdown.

Distribution of the newsletter is handled via Mailchimp service, which is also free up to a certain number of subscribers, which this little newsletter would be lucky to ever reach. The Mailchimp signup link is pasted into the index page; unsubscribes and anti-bot defenses are handled by Mailchimp so I don’t need to worry about any of that.

When I compose a new issue of the newsletter, I add a new markdown file to the archive, and link it off the archive index page. Then I create a new “campaign” inside Mailchimp account, paste the markdown as is into the body of the email, and push the big red button. Done!

Then access the local copy of the site at port 4000. Note that good old grip doesn’t render GitHub flavored markdown quite right, so the above approach is preferred. The setup to make it work was simply to make a Gemfile with the right incantation, then run bundle install, that’s it.

What is the newsletter frequency?

Is there an RSS feed?

Why do Tester’s Digest emails have <angle brackets around the URLs> ?

Due to a quirk of GFM (GitHub Flavored Markdown), I have to put the URLs inside angle brackets when writing the markdown files. They render fine on the GH Pages site, but the brackets show up in newsletter emails. There is no way around this, short of hand-editing the brackets out of the markdown when creating a Mailchimp campaign. That would be error prone, and I cannot be bothered. The angle brackets stay.

Is there any click tracking due to using Mailchimp?

Nope. Because I pick plain-text campaign type in Mailchimp, and only leave the required “Track plain-text clicks” setting enabled, the sole tracked link is the Unsubscribe one at the bottom of the email. The links to articles/posts in the newsletter have no tracking on them.

Moreover, I make sure I remove any fields after ? in the URLs before including them into the newsletter, so I don’t pass on the tracking that may have been included by original publisher.

I don’t often wear a hat, but when I do, it’s tinfoil.

This has a side effect of not knowing if my subscribers ever read anything I send out. I can live with the mystery.

How does testersdigest.mehras.net redirect to GitHub Pages?

To set this up, I used these excellent instructions because GitHub’s own doc was a bit opaque.

Any other customizations that were needed?

GH Pages use Jekyll as the static site generator. There are built-in themes you can use to make the site look decent. I went with Dinky so that’s in my _config.yml file.

The default Dinky was creating duplicate “View on GitHub” buttons on my index page, so I copied off _layouts/default.html and commented out the extra button. I also added the EFF badge image in the footer.

I added a favicon.ico PNG file to get that “TD” marker in the browser tab or bookmark. I made the image myself by using Google’s free font library.

The index page for the site is in Markdown because why not, Jekyll transforms it into index.html. It includes the embedded signup form snippet provided by Mailchimp. The form “just works”.

How to get SEO and Slack URL unfurling for posts

I noticed that links to Tester’s Digest issues were not getting a nice little snippet when posted in Slack. Quick investigation showed that this fanciness, called URL unfurling, is based on SEO (Search Engine Optimization) metadata which I didn’t have, hence this newsletter was also not enjoying SEO benefits. Here is how I added metadata tags with Jekyll and Markdown:

Added to Gemfile:

gem 'jekyll-seo-tag'

Added to _config.yml:

gems:
- jekyll-seo-tag

Added right before </head> in the site template _layouts/default.html (without the extra spaces):

{ % seo % }

Then in markdown of each post, I added “front matter” section that is transformed by Jekyll into the meta tags when generating html page:

---
description: What this post is about.
---

Note a gotcha that colon character : is not welcome inside the description.

I tried overriding title in the markdown front matter, but it wasn’t getting picked up, so I stayed with the default site-wide title “Tester’s Digest”. I also tried adding image tag to get a thumbnail logo for the unfurled URLs in slack, that didn’t work either, sticking with the “good enough” solution of description metadata.