Deploying an 11ty Site to GitHub Pages

I am building a new personal site. The idea behind it is pretty simple: it’s a blog that will have a total of 50 pages added to it over 5 years. Not much content and not much complexity.

I debated about just coding the entire site by hand, each and every page. But this seemed like an opportunity to try a static site generator. The last static site generator I used was MovableType back before WordPress was ever a thing.

I’ve heard a bunch of good buzz around 11ty and figured I’d give it a try.

Getting Started with 11ty

11ty was really easy to get started. I ended up forking the blog repo, since I figured it’d have enough stuff in there to get me started. Sure enough, it did.

However, I needed a place for this stuff to live. The rest of Snook.ca sits on a Linode slice and I debated about doing the same. I’d have to set up the Apache configuration and maybe set up automated git hooks to pull in and build the latest version. That seemed like more work than I felt like dealing with.

GitHub Pages

I knew GitHub Pages was a thing, although I’ve never used them. I didn’t even really understand how it works. The project configuration on GitHub let me choose what branch to use but it wasn’t clear which branch I should choose.

I thought maybe if I selected Master, it would just know what to do. Yeah, no.

GitHub Pages takes whatever is on that branch and pushes it live. It doesn’t run any build process from what I can tell. I needed to select the gh-pages branch and then I needed to figure out how to get a build of the site into that branch.

Setting up Travis CI

I noticed a Travis CI build file in the project. I also noticed a Netlify boilerplate. I didn’t put much thought into and figured, let’s go with Travis CI since there’s already a build file there.

I set up an account and then turned on deployment for my 11ty project. I watched it do its first build and then… fail.

Looks like a token issue.

The Personal Token

There’s a $GITHUB_TOKEN variable specified in the .travis.yml file. I know enough not to put any private keys into this file, as that’ll expose it to the world. It says to put the token into Travis.

I went to the settings for the project in Travis and I can see where I set “Environment Variables”. But what am I supposed to specify here?

Turns out, I need to generate a token in GitHub. That’s found under Settings > Developer settings > Personal access tokens.

I gave it a name and gave it repo access. Then I copied that token and went back to Travis to enter a new Environment Variable called GITHUB_TOKEN and pasted the key in there.

My builds were working!

Custom Domain

Unfortunately, every time I did a commit to GitHub, I’d lose the custom domain setting. It would revert back to the default, which is username.github.io/reponame.

Is this a GitHub issue or a Travis issue? Turns out, the latter. If you’re doing a custom domain for this, there are two things you want to adjust:

First, set the domain name in the .travis.yml file under the deploy heading.

deploy:
  fqdn: fifty.snook.ca

This was what was blowing out my custom domain setting.

The second thing that needs to be changed is the path prefix. By default, the build expects the site to be in a subfolder off the root. The default path prefix in the 11ty repo is to the name of the repo, /eleventy-base-blog/. If you rename your fork (like I did), you’ll need to update this.

In my case, since I was using a custom domain, I didn’t want any prefix at all.

script: eleventy --pathprefix="/"

And voila!