jekyll: baseurl / base-url: GitHub Pages Project Pages - Relative Links Fail

I finally figured out the trick, if you’re looking for a solution with the standard URL for GitHub Pages (username.github.io/project-name/). Here’s what to do:

In _config.yml, set the baseurl option to /project-name – note the leading slash and the absence of a trailing slash.

Now you’ll need to change the way you do links in your templates and posts, in the following two ways:

When referencing JS or CSS files, do it like this: {{ site.baseurl }}/path/to/css.css – note the slash immediately following the variable (just before “path”).

When doing permalinks or internal links, do it like this: {{ site.baseurl }}{{ post.url }} – note that there is no slash between the two variables.

Finally, if you’d like to preview your site before committing/deploying using jekyll serve, be sure to pass an empty string to the --baseurl option, so that you can view everything at localhost:4000 normally (without /project-name getting in there to muck everything up): jekyll serve --baseurl ''

This way you can preview your site locally from the site root on localhost, but when GitHub generates your pages from the gh-pages branch all the URLs will start with /project-name and resolve properly.

Use the HTML base tag and it will work fine.

This sucks. I would much rather have a solution that allows the built files to be hosted from either of:

• https://fulldecent.github.io/monitortech.org/
• http://monitortech.org/

Using the same files. And the only way to do that is relative URLs.

My links to posts currently look like <a href="{{site.baseurl}}{{post.url}}">{{post.title}}</a> which seems inelegant and took a while to figure out.

Also why is it base-url at the command line and baseurl in the config file?

@mjswensen Because I want the same compiled pages to be usable when hosted via gh-pages or via a custom domain. Also, relative urls work with command-line based link checkers.

If anyone else needs this, here is the code that works:

{% assign relative-baseurl = "" %}
{% assign canon = page.url | append: "page.html" | split: "/" %}
{% for item in canon offset:2 %}
  {% assign relative-baseurl = relative-baseurl | append:"../" %}
{% endfor %}
{{ relative-baseurl }}

FYI, the canonicalization in line 2 allows /dir/ and /dir/index.html to be treated the same, both resulting in relative-baseurl equalling ../

I believe relative URLs are a reasonable feature to expect from a static website generator.