Down to the Wire Elements of LabVIEW

Configuring Jekyll for User and Project GitHub Pages

You’ve chosen a Jekyll theme and set it up for your GitHub user page. It looks great and works well.

That theme is your favorite and you want to reuse the tweaks you added, so you apply it to your GitHub project pages, except there’s a small problem: you’re seeing a double-slash in the URL after the repository name, like http://you.github.io/your-project//a-post.html.

Or maybe there’s a much larger problem: many of the in-site links are broken and yield a frustrating and confusing 404.

Jekyll was supposed to be fast and simple. What’s going on? How can you fix it?

Usually, the defect comes from one or both of these:

  1. Your settings – incorrect data in _config.yml
  2. The theme – incorrect usage of Jekyll variables and Liquid tags

Once you tidy your settings and theme, your user and project pages will have normalized URLs and working links. Even better: they will Just Work™ if you use Jekyll locally to preview your sites.

Configuring your site correctly

There is only one rule to follow for _config.yml:

Rule 0a – For a User site, baseurl must be empty

Good baseurl:
Bad baseurl: /

Rule 0b – For a Project site, baseurl must begin with a slash

Good baseurl: /your-repository
Bad baseurl: your-repository
Bad baseurl: your-repository/

Using Jekyll and Liquid correctly

There are thee rules to follow:

Rule 1 – Always concatenate Jekyll and Liquid tags

Good href="{{ site.baseurl }}{{ post.url }}"
Bad href="{{ site.baseurl }}/{{ post.url }}"

This removes the double-slash from your site’s URLs.

Good href="{{ site.baseurl }}{{ post.url }}"
Bad href="{{ post.url }}"

This fixes almost all of the in-site links. The next rule covers the remainder.

Otherwise, feed readers and other aggregators, which rely on absolute URLs, won’t be able to send subscribers to your pages.

Rule 3 – Always use a trailing slash after {{ site.baseurl }}

Good href="{{ site.baseurl }}/" title="Home"
Bad href="{{ site.baseurl }}" title="Home"
Good href="{{ site.baseurl }}/public/favicon.ico"
Bad href="{{ site.baseurl }}public/favicon.ico"

This fixes links to resources.

A few simple grep searches from your repository’s root will show you what you need to fix, and where.

grep -r href=\" . | grep 'href=\"{{ *site\.b*a*s*e*url *}}/{' | grep -vE _posts\|_site

If there are any hits, apply Rule 1 to your theme.

grep -r href=\" . | grep -v 'href=\"{{ *site\.b*a*s*e*url *}}' | grep -vE _posts\|_site

The only hits should be to external resources and pages. If there are any that point into your site, you need to apply Rule 2 to your theme.

grep -r href=\" . | grep 'href=\"{{ *site\.baseurl *}}[^/{]' | grep -vE _posts\|_site

If there are any hits, apply Rule 3 to your theme.

Why are these the rules to follow?

Two reasons:

  1. It’s the way HTTP URLs work
  2. It’s the way Jekyll works

HTTP URL structure

HTTP supports two kinds of links: absolute and relative. Absolute links have the full and complete URL, while relative links have a variety of flavors. The one that matters for us is the one that starts with a leading slash. When a browser is on a web page, it can assume that the target of a link with a leading slash is on the same host.

For example, assume a page at http://host.com/folder/page.html wants to link to http://host.com/folder/other.html, then these are equivalent href links:

  • <a href="http://host.com/folder/other.html">Go</a>
  • <a href="/folder/other.html">Go</a>

The browser will navigate to the same page when you click on either link.

Jekyll’s rendering behavior

Jekyll adopted this style of in-site linking, and so it uses leading-slash relative links whenever it populates variables like page.url (for more information, see my previous post about exploring Jekyll variables). So, when providing your own URL data, like site.baseurl, it’s important that you use the same pattern. See Jekyll’s documentation for GitHub Pages if you want a second (and identical) opinion.

While there is much more behind HTTP uniform resource locators than the simplification below, here are the basic building blocks, with a slightly different delineation so that they match Jekyll variable names.

User Page

 http://you.github.io/a-post.html 

  •  site.url 
  •  page.url 
Violation Result
Rule 0
bare slash
http://you.github.io//a-post.html
Rule 1
slash between tags
http://you.github.io//a-post.html
Rule 2
missing site.baseurl
href="/a-post.html" (!)
Rule 3
no slash after tag
href="" title="Home" (x)
Rule 3
no slash after tag
href="/public/favicon.ico" (!)

Notes:

  • ! – This result is still correct, but only for a User page. This is a false positive and many theme authors incorrectly assume that this “correct” result is also correct for Project pages.
  • x – This is an abnormal relative URL, and browsers will navigate to the current page.

Project Page

 http://you.github.io/your-project/a-post.html 

  •  site.url 
  •  site.baseurl 
  •  page.url 
Violation Result
Rule 0
no leading-slash
http://you.github.ioyour-project/a-post.html (404)
Rule 0
trailing-slash
http://you.github.ioyour-project//a-post.html (404)
Rule 1
slash between tags
http://you.github.io/your-project//a-post.html
Rule 2
missing site.baseurl
href="/a-post.html" (404)
Rule 3
no slash after tag
href="/your-project" title="Home" (404)
Rule 3
no slash after tag
href="/your-projectpublic/favicon.ico" (404)

No comments

You today