This article is obsolete. See instead Staticman at Heroku.

Spinningnumbers.org is a static web site. I use Staticman v2 as a service to make it seem like my static site is responsive to comments and discussion.

Staticman allows users to enter their email address to subscribe to a post and be notified if new comments appear.

Contents

Resources

Setting up the Staticman app with Staticman v3

I recently converted from the v2 public instance of Staticman over to the v3 GitHub app.

  1. Remove staticmanapp as a collaborator (if it is left over from an earlier install).
  2. Go to https://github.com/apps/staticman-net and install the application on your repository. Just click on install. Don’t change any settings.
  3. Submit a comment to the new v3 endpoint, https://api.staticman.net/v3/entry/github/[USERNAME]/[REPOSITORY]/[BRANCH]. This line goes in _config.yml as the staticmanUrl variable.

Staticman implements comments and replies

The site has a comment form (_includes/comment_form.html). When the user fills out the form and clicks Submit the form is sent over the web to Staticman. Staticman receives the comment info, processes it, and submits a comment file to GitHub as a Pull Request (PR) to the spinningnumbers.org repository.

I have it set up without moderation (staticman.yml: moderation: false), so GitHub immediately accepts the PR. The PR puts the comment into the /_data/comments/* folder. This triggers GitHub Pages to regenerate the affected web files. The new comment is rendered at the bottom of the appropriate page by comments.html. The whole process takes 30-60 seconds. When the user refreshes her browser, the new comment appears.

At the same time Staticman is sending the PR to GitHub, it sends a request to my MailGun account to add the comment author’s email address to a mailing list for this particular article. If the mailing list doesn’t exist, Staticman asks MailGun to create one. The mailing list has an encoded name, like affa4704f06fda2245c5ed9d54932d35@mg.spinningnumbers.org. The addition of new comment triggers an email sent to the entire mailing list, so everybody who has subscribed gets to see it.

Setting up MailGun

Sign up for a MailGun account at https://app.mailgun.com/new/signup/.

It is free until you exceed 10,000 emails per month. Even though it is free, you should still enter a credit card number and get on the Unity Plan. MailGun won’t charge if you stay under 10K emails. The credit card number enables some features you want, like the ability to send an email to an address that is not in your Authorized Recipients list (limit 5).

Tell MailGun about your domain:
Click on Add your domain. Enter your personal domain name with “mg.” on the front.

Tell your ISP about MailGun:
You have to add some lines to your domain records where your domain is hosted.

MailGun API keys: You will be issued two API keys, one secret, one public. They are listed in several places in your MailGun account pages. The secret key starts with “key-“. The public key starts with “pubkey-“.

Encryption

Pro tip: Staticman encrypts some stuff. Mailgun encrypts other stuff. Don’t double-encrypt.

About spinningnumbers.org

The spinningnumbers.org domain name is hosted at justhost.com.

This site is in a repository at GitHub and is hosted by GitHub Pages. When GitHub Pages detects a changed file in the repository, it triggers Jekyll to rebuild the site. I’m using the default ‘minima’ theme with a few tweaks to the stylesheet, assets/main.scss. The most important modification is to allow the text to get a little bigger when a mobile phone is turned to landscape orientation.

The articles are written in Jekyll’s Kramdown superset of markdown.

Equations are rendered by $\KaTeX$, the super-fast math typesetting library from Khan Academy. The KaTeX equation renderer runs after the page loads. See the line in _layouts/default.html where it includes katex.html.

Animated images are created with D3.js. The source code for animations is here.

Graphs and calculated waveforms (like sines or exponentials) are also created in D3.js. The html source code for static graphs is on github under /assets/d3.

Wherever possible, I use the .svg graphic format for images because they look great on different screen sizes. A lot of images were created in Adobe Illustrator. My current graphic tool of choice is Inkscape based on it favorable cost of $0.

This is a static site. Comments are implemented with Staticman, with protection from robots provided by reCAPTCHA.

Playground

If you are setting up your own system, feel free to practice here. Add comments to this page to see how it works and the timing of regenerating the site when a new comment comes in. This site is moderated, so it takes a while for your comment to appear (I have to approve it).