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.
- About spinninnumbers.org
- Overview: how Staticman creates comments and uses MailGun
- Setting up MailGun
Eduardo’s personal site on github is a good resource for Staticman news and developments.
Michael Rose’s personal site - This is a good tutorial on upgrading to Staticman v2 and implementing nested comments. Michael’s site uses jekyll and has nested comments with mail replies, but is not generated by GitHub Pages.
Michael’s personal site source on github. This was my primary inspiration for implementing Staticman, comments, and mail for spinninnumbers.org.
MailGun. This is an ESP (email service provider) known to Staticman. I set up my own account.
GitHub Pages is the hosting service for spinningnumbers.org.
Staticman encrypts some stuff. Mailgun encrypts other stuff. Don’t double-encrypt.
The spinningnumbers.org domain name is hosted at ehost.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 additions to the stylesheet, assets/main.scss.
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.
Graphs and calcluated waveforms are also created in D3.js. The source code for static graphs is here.
Wherever possible, I use the .svg graphic format for images because they look great on different screen sizes. A lot of the images were created in Adobe Illustrator. My current graphic tool of choice is Inkscape based on it favorable cost of $0.
Overview: how Staticman creates comments and uses MailGun
My 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 and submits it to GitHub as a Pull Request (PR) for the spinninnumbers.org respository. I have it set up to immediately accept the PR (in staticman.yml: moderation: false). The PR puts the comment and author info into spinningnumbers/_data/comments/* folder. This file change triggers GitHub Pages to regenerate the changed parts of the spinninnumbers web files. When the use refreshes her browser page, the 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 mailinglist does’t exist, Staticman asks for one to be created. The mailinglist will have an encoded name, like firstname.lastname@example.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 an account at MailGun. The signup page is https://app.mailgun.com/new/signup/.
The account 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 yourself on the Unity Plan. MailGun won’t charge it if you stay under 10K emails. Entering a credit card number enables some features you want, like the ability to send an email to an address that is has not been entered into 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.
Your MailGun API keys: You will be issued two API keys, one secret, one public. They are listed in several places in your online account pages. The secret key starts with “key-“. The public key starts with “pubkey-“.
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.