Setting up GitHub Pages to use GitHub Actions so you can use the latest version of Jekyll and non-whitelisted Jekyll extensions is easy if you know what you’re doing. I didn’t know what I was doing. Here’s how I remedied that.

target=”_blank”

I wanted links on this blog to open in a new tab automatically. Jekyll uses kramdown (which has Span IALs) as its default Markdown processor, so I could have added {:target="_blank"} (with appropriate rel attributes) to links by hand, but after writing one post this way, that was clearly an unsustainable amount of work.

Jekyll Target Blank

Through a now-forgotten series of Google queries I came upon Jekyll Target Blank. With the necessary updates to this blog’s Gemfile and _config.yml made, when I ran the site locally, all links that point to external URLs opened in new tabs. So, I pushed to GitHub, and… it stopped working. This is how I learned about GitHub’s whitelist of Jekyll extensions, Jekyll Target Blank is not a member.

GitHub Actions

Back to Google. My queries were fruitless, but digging around in the closed Issues on Jekyll Target Blank’s GitHub page turned this up. Eventually, I made my way to a solution in Jekyll’s official docs. This was pretty helpful, but some of the included information is inaccurate (or, more likely, out of date) and expects familiarity with creating a workflow in GitHub Actions, a familiarity I did not have.

GITHUB_TOKEN

After slapping together a workflow file based on what I saw in the Jekyll docs (and, eventually, the jekyll-action GitHub Action docs), I ran into my next stumbling block:

refusing to allow a Personal Access Token to create or update workflow `.github/workflows/github-pages.yml` without `workflow` scope github_token

I won’t go into all the details, but after far too much time generating Personal Access Tokens and creating secrets before altogether scrapping the repository that holds this blog, I learned (I think from a StackOverflow post I’ve now lost) that the easiest way to create a workflow is to do it through the repo’s web interface. Under the Actions tab there’s a New Workflow button. Clicking that takes you to a page with a link that says set up a workflow yourself. Clicking that takes you to page with a relatively intuitive interface for creating a workflow and that has a search tool for the GitHub Actions Marketplace built in.

As it turns out, the GITHUB_TOKEN that both the Jekyll docs and the jekyll-action docs referenced is built in. The Jekyll docs want you to create such a token. This is wrong: GitHub does not want you to create tokens that start with GITHUB_, plus the work is already done for you. The jekyll-action docs call GITHUB_TOKEN “the out-of-the-box secret” but to me as a beginner, this was unclear. Now I know.

Branches

The Jekyll docs say “The Action we’re using here will create (or reset an existing) gh-pages branch on every successful deploy.” This is inaccurate. I fought with this for a while before realizing that jekyll-action was creating a master branch containing the built version of this site. And would you believe it? When the jekyll-action docs say

Remember that GitHub is serving your built static site, not its sources. So when configuring GitHub Pages in your project settings, use gh-pages branch as a Source for GitHub Pages. If you are setting up username.github.io repository, you’ll have to use master branch, so sources can be located in another orphaned branch in the repo (which you can safely mark as default after the first publication). In addition to that default behaviour, you can configure the branch this plugin pushes into with the target_branch-option. Keep in mind to set the source branch accordingly at the GitHub Pages Settings page.

that’s what they meant.

It works!

Through a combination of the Jekyll docs and the jekyll-action docs, I finally got it all to work. You can see the final version of my workflow here. Of note is the line that says target_branch: 'gh-pages'. This is what I ended up renaming the master branch to. Once I did this, I deleted the unused branch and set the GitHub Pages source to gh_pages. I was pleased to discover that I did not have to create this branch before using it in the workflow. The workflow did it for me.

Takeaways

Software manuals are concise, direct, and not always beginner friendly. The information I needed was all right there, but I didn’t yet have the vocabulary for what I was dealing with. Next time, I’ll know to use the web interface for creating a new workflow in GitHub Actions and I’ll have a somewhat better understanding of the GITHUB_TOKEN. But for now, I’m just happy that my external links open in new tabs.