<commit_before>---
layout: article
title:  "Staticman and Mailgun"
author: <NAME>
comments: true
---

Spinningnumbers.org is a static web site. I use [Staticman v2](https://staticman.net) 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
{:.no_toc}

* Will be replaced with the ToC
{:toc}

----

## Resources

[Staticman](http://staticman.org). I don't run my own Staticman server, I use the public instance of Staticman. 
[Staticman on github](https://github.com/eduardoboucas/staticman). Watch this repository to follow along with Staticman's development and issues.   

[Eduardo's personal site on github](https://github.com/eduardoboucas/eduardoboucas.github.io) is a good resource for Staticman news and developments.  

[<NAME>'s personal site](https://mademistakes.com/articles/improving-jekyll-static-comments/) - 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](https://github.com/mmistakes/made-mistakes-jekyll). This was my primary inspiration for implementing Staticman, comments, and mail for spinninnumbers.org.

[MailGun](https://www.mailgun.com/). This is an ESP (email service provider) known to Staticman. I set up my own account. 

[GitHub Pages](https://pages.github.com/) is the hosting service for spinningnumbers.org.

[Popcorn](http://popcorn.staticman.net/). Staticman's demo site (based on Staticman v1).    
[Popcorn's repository on github](https://github.com/eduardoboucas/popcorn)  

## Encryption

Staticman encrypts some stuff. 
Mailgun encrypts other stuff. 
Don't double-encrypt.  

## About spinninnumbers.org

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

This site is in a repository at [GitHub](https://github.com/willymcallister/spinningnumbers) and is hosted by [GitHub Pages](https://pages.github.com/). When GitHub Pages detects a changed file in the repository, it triggers [Jekyll](https://jekyllrb.com/) to rebuild the site. I'm using the default '[minima](https://github.com/jekyll/minima)' theme with a few additions to the stylesheet, assets/main.scss. 

The articles are written in Jekyll's [Kramdown](https://kramdown.gettalong.org/documentation.html) superset of markdown. 

Equations are rendered by [$\KaTeX$](https://khan.github.io/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](http://d3js.org). The source code for animations is [here](https://github.com/willymcallister/spinningnumbers/tree/master/_articles/d3).

Graphs and calcluated waveforms are also created in D3.js. The source code for static graphs is [here](https://github.com/willymcallister/spinningnumbers/tree/master/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](https://inkscape.org/) based on it favorable cost of \$0.

This is a static site. Comments are implemented with [Staticman](https://staticman.net/), with protection from robots provided by [reCAPTCHA](https://www.google.com/recaptcha/intro/). 

## 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 <EMAIL>. 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-". 

## 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.<commit_msg>update a link, fix typos<commit_after>---
layout: article
title:  "Staticman and Mailgun"
author: <NAME>
comments: true
---

Spinningnumbers.org is a static web site. I use [Staticman v2](https://staticman.net) 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
{:.no_toc}

* Will be replaced with the ToC
{:toc}

----

## Resources

[Staticman](http://staticman.org). I don't run my own Staticman server, I use the public instance of Staticman. 
[Staticman on github](https://github.com/eduardoboucas/staticman). Watch this repository to follow along with Staticman's development and issues.   

[Eduardo's personal site on github](https://github.com/eduardoboucas/eduardoboucas.github.io) is a good resource for Staticman news and developments.  

[<NAME>'s personal site](https://mademistakes.com/articles/improving-jekyll-static-comments/) - 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](https://github.com/mmistakes/made-mistakes-jekyll). This was my primary inspiration for implementing Staticman, comments, and mail for spinningnumbers.org.

[MailGun](https://www.mailgun.com/). This is an ESP (email service provider) known to Staticman. I set up my own account. 

[GitHub Pages](https://pages.github.com/) is the hosting service for spinningnumbers.org.

[Popcorn](http://popcorn.staticman.net/). Staticman's demo site (based on Staticman v1).    
[Popcorn's repository on github](https://github.com/eduardoboucas/popcorn)  

## Encryption

Staticman encrypts some stuff. 
Mailgun encrypts other stuff. 
Don't double-encrypt.  

## About spinningnumbers.org

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

This site is in a repository at [GitHub](https://github.com/willymcallister/spinningnumbers) and is hosted by [GitHub Pages](https://pages.github.com/). When GitHub Pages detects a changed file in the repository, it triggers [Jekyll](https://jekyllrb.com/) to rebuild the site. I'm using the default '[minima](https://github.com/jekyll/minima)' theme with a few additions to the stylesheet, assets/main.scss. 

The articles are written in Jekyll's [Kramdown](https://kramdown.gettalong.org/documentation.html) superset of markdown. 

Equations are rendered by [$\KaTeX$](https://khan.github.io/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](http://d3js.org). The source code for animations is [here](https://github.com/willymcallister/spinningnumbers/tree/master/_articles/d3).

Graphs and calculated waveforms are also created in D3.js. The source code for static graphs is on github under [/assets/d3](https://github.com/willymcallister/willymcallister.github.io/tree/master/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](https://inkscape.org/) based on it favorable cost of \$0.

This is a static site. Comments are implemented with [Staticman](https://staticman.net/), with protection from robots provided by [reCAPTCHA](https://www.google.com/recaptcha/intro/). 

## 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 <EMAIL>. 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-". 

## 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.
{'fraction_non_alphanumeric': 0.0763651521467278, 'fraction_numerical': 0.003251354731137974, 'mean_word_length': 4.291574768416409, 'pattern_counts': {'":': 0, '<': 9, '<?xml version=': 0, '>': 9, 'https://': 40, 'lorem ipsum': 0, 'www.': 4, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3789648', 'n_tokens_mistral': 3430, 'n_tokens_neox': 3155, 'n_words': 1608}