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 spinningnumbers.org
- How Staticman implements comments and replies
- 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 spinningnumbers.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 calculated waveforms are also created in D3.js. The 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 the images were created in Adobe Illustrator. My current graphic tool of choice is Inkscape based on it favorable cost of $0.
How 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 info into the /_data/comments/* folder. This triggers GitHub Pages to regenerate the affected web files. The new comment is rendered into html at the bottom of the appropriate page by comments.html. The whole process takes 30-60 seconds depending on how busy GitHub servers are at the moment. 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 for one to be created. The mailing list 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 sign-up 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 on-line 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.