A Website is Born!

6 minute read

I learned a lot while building this website; I hope to share it so that it might be helpful for anyone trying to do the same. I’m sure you’ll notice that I’m far from an expert in the subjects we’re going to explore here; this is my first foray into web development. If you have any corrections, or things I’ve misunderstood, I’d love to hear about it! Just post a comment.

The site is built using Jekyll, using the theme Minimal Mistakes. I host it on Github pages, and purchased and manage my domain through Google Domains. We’ll go through each of these steps in detail. I’ll assume that you have the up-to-date versions of Ruby and Jekyll on your local machine. I’m going through all this in macOS, which may affect some of the shell commands I give, but translating to Windows shouldn’t be too hard.

Making a site with Minimal Mistakes

The website for Minimal Mistakes includes a great quick-start guide; I recommend the Starting with jekyll new section as a place to start. Using this you shoudl be able to establish a base site with some simple demonstration content.

Enabling MathJax

In order to enable MathJax, which renders the mathematical equations you see in my posts, you’ll need to edit the file scripts.html contained in the folder _includes/ to include a line enabling MathJax. However, you’ll want to avoid overwriting the contents of the default scripts.html.

So, we need to find where bundle is storing the Gem for Minimal Mistakes. To find this, do

bundle show minimal-mistakes-jekyll 

If you just want to navigate directly to that directory, do

cd $(bundle show minimal-mistakes-jekyll)

Now you can copy the default scripts.html into your site:

cp _includes/scripts.html /path/to/site/_includes/scripts.html

Open the copied scripts.html in your editor of choice,1 and add the following lines at the end:

 
 
{% if page.mathjax %}
<script type="text/javascript" async
src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-MML-AM_CHTML">
</script> 
{% endif %} 
 

And you’re done!2 Now, you can type $$x_1$$ to see , and so on. The $$...$$ syntax will generate inline math if used inline, and will generate a display equation if used on its own line. So, if one enters

$$ f(a) = \frac{1}{2\pi i} \oint_\gamma \frac{f(z)}{z-a} dz $$

Then the rendered equation appears as so:

Customize Font Sizes

I found the fonts a bit oversized, so I wanted to change the size for the posts. In order to do this, you need to copy the entire folder which contains all the relevant scss files. In order to do this, do

cd $(bundle show minimal-mistakes-jekyll)
cp -r _sass /path/to/site

Now, after much digging through the GitHub issues,3 I found that the file to edit here is _sass/_reset.scss. In my site, the relevant chunk of text looks like

  @include breakpoint($medium) {
    font-size: 13px;
  }

  @include breakpoint($large) {
    font-size: 15px;
  }

  @include breakpoint($x-large) {
    font-size: 18px;
  }

Once this file has been edited, you should see the font size reduced in your page.

Getting it on GitHub Pages

Okay, now we write a bunch of nonsense, find some beautiful pictures at Unsplash to use as headers, and we’re ready to publish the thing on GitHub Pages. I’ll first go through as though we don’t want to use a custom domain, so that the website will be exposed at USERNAME.github.io.

Enabling jekyll-remote-theme

First of all, make sure that you’re using the remote-theme jekyll plugin, which allows you to use any jekyll theme that is GitHub hosted, rather than only the few that are officially supported. This process is outlined on the Minimal Mistakes website, but I’ll go through it here.

First, in your _config.yml file, enable the plugin by including it in the plugins list, via

plugins:
  - jekyll-remote-theme

If you have other plugins you want to use (I use jekyll-feed), then add them to this list as well. Designate the remote_theme variable, but do so after setting the theme, so that you have in your config file

theme: "minimal-mistakes-jekyll"
remote_theme: "mmistakes/minimal-mistakes"

Finally, in your Gemfile, add gem "jekyll-remote-theme".

Push it to the repository

GitHub pages looks for a repository that follows the naming convention USERNAME.github.io. So, for example, since my GitHub username is peterewills, the repository for the source of this site is at https://www.github.com/peterewills/peterewills.github.io.

Once you’ve created such a repository, initialize a git repo on your site by going into path/to/your/site and doing git init. Then, do

git remote add origin https://www.github.com/USERNAME/USERNAME.github.io

and then commit and push. (If you’re unfamiliar with using git, I recommend either of these tutorials.) You’ll get an email that your page build was successful, but you’re “using an unsupported theme.” Don’t worry about this; it happens whenever you use remote-theme.

You now should be able to navigate to USERNAME.github.io and see your page!

Using a Custom Domain

Suppose you’d prefer to use a custom domain, such as mydomain.pizza (this is actually a real, and available, domain name). There are lots of ways to do this; I did it through Google Domains, so I’ll go through those steps.

First, you go to Google Domains, pick out the domain you want, and register it. For this example, we’ll assume you went with mydomain.pizza. You should now see it appear under the My Domains tab on the right side of the page. You should see a domain called mydomain.pizza and a DNS option. This is what we need to edit.

We need to configure the DNS behavior of our domain so that it points at the IP address where GitHub Pages is hosting it. On the DNS page, scroll down to Custom Resource Records. You’ll want to add three custom resource records; two “host” resource records (designated by an A) and one “alias” resource record (designated by CNAME). GitHub pages exposes its sites at IP addresses 192.30.252.153 and 192.30.252.154. So, you’ll want to add both of these as host resource records. You’ll want to add your GitHub Pages url USERNAME.github.io as an alias record. By the time you’ve added the three, your list of resource records should look like the example below.

So, now your url (mydomain.pizza) knows that it is an alias for USERNAME.github.io, but we still have to specify this aliasing on the GitHub end of things.

To do this, simply make a text file called CNAME and include on the first line

mydomain.pizza

This is the entire contents of the text file CNAME. Once this is pushed to the repository USERNAME/USERNAME.github.io, the appropriate settings should automatically update themselves. To check this, go to the respository settings, scroll down to the “GitHub Pages” settings, and look under “Custom domain.” You should see something like the following:

If the DNS record of your Google domain has not yet been updated, then you will see Your site is ready to be published mydomain.pizza on a yellow background. Note that it sometimes takes up to 48 hours for DNS records to update, so be patient.

Conclusion

Once the DNS records have updated, you should be able to see your site at mydomain.pizza. You can check out the repository for my site to see examples of what I’ve gone through here; including my CNAME file, my _include/scripts.html file that enables MathJax, and my _config.yml file. Please let me know, either by email or in the comments, if you have any questions or corrections!

  1. Presumably emacs. 

  2. Some older blog posts discuss the process of adding kramdown as the markdown rendering engine, but this is default behavior for Jekyll 3.x, so there’s no need to do this step. 

  3. Michael, the guy who built Minimal Mistakes, is really wonderful about responding to issues on GitHub, which are really used as a support forum for people using the theme who have no experience in web development (such as myself). 

Updated: