Spinningnumbers.org is a static web site. I use Staticman v3 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.
- Setting up the Staticman app with Staticman v3
- Staticman implements comments and replies
- Setting up MailGun
- About spinningnumbers.org
- Staticman web site
- Staticman on GitHub
- Staticman app on GitHub
- Eduardo’s personal site on github is a good source of Staticman news.
- 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 email 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 spinningnumbers.org.
- MailGun is an ESP (email service provider) known to Staticman.
- GitHub Pages is the hosting service for spinningnumbers.org.
- Popcorn. Staticman’s demo site (based on Staticman v1).
- Popcorn on github
Setting up the Staticman app with Staticman v3
I recently converted from the v2 public instance of Staticman over to the v3 GitHub app.
- Remove staticmanapp as a collaborator (if it is left over from an earlier install).
- Go to https://github.com/apps/staticman-net and install the application on your repository. Just click on install. Don’t change any settings.
- 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 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 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-“.
Pro tip: Staticman encrypts some stuff. Mailgun encrypts other stuff. Don’t double-encrypt.
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.
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.
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.