site.baseurl behaviour specific to GitHub Pages

[MattiSG]

This issue affects

• The site generated by GitHub Pages
• Building sites locally

What did you do (e.g., steps to reproduce)

• Set baseurl to '' in the _config.yml.
• Publish to GitHub Pages.

What did you expect to happen?

• {{ site.baseurl }} to be expanded to nothing.

What happened instead?

• {{ site.baseurl }} was expanded to the name of the built GitHub repo.

Additional information

• Link to the live site (if applicable): https://beta.gouv.fr
• Link to the source repo (if applicable): https://github.com/sgmap/beta.gouv.fr

Context: betagouv/beta.gouv.fr@a8280a4

The problem is that an empty baseurl is overridden on GitHub Pages, but not a non-empty one.
The behaviour is not exactly the same as specifying a --baseurl in the build options, as specifying it like that overrides any config value, even a non-empty one.

For example, before this commit, everything worked fine: {{ site.baseurl }} was set, and expanded, to / with the website still being properly served.

[benbalter]

{{ site.baseurl }} was expanded to the name of the built GitHub repo.

Interesting. For a project site, should it have a baseurl locally? @parkr any strong feelings one way or the other?

[DirtyF]

@MattiSG GitHub Pages is now powered by Jekyll 3.3, so you should be able to rely on relative_url filter rather than baseurl

[parkr]

o you should be able to rely on relative_url filter rather than baseurl

relative_url uses site.baseurl to do its thing, so one is dependent of the other.

For a project site, should it have a baseurl locally?

I guess the expected behaviour here would be:

1. Is there a CNAME? Then set site.url and site.baseurl to respect that CNAME.
2. Is it local? Then set site.url to http://localhost:4000 or whatever url the servlet gives us.

We don't add this value unless when JEKYLL_ENV=production so I'm not sure why this would affect local builds.

[pathawks]

@MattiSG Your repo seems to be missing a CNAME file; how are you serving it at a different domain?

If you added a CNAME file, GitHub could figure out the url and baseurl from that information.

[MattiSG]

Reverse-proxying it so we can serve it over HTTPS from a custom domain.

[clark-pan]

I have a similar use case. I'm using CloudFront as a reverse proxy CDN for the application, with the marketing portions of the site pointing to github pages. Would very much like an option _config.yaml to override this behaviour.

The default behaviour makes perfect sense for the normal usage.

[Morendil]

We've been bitten by this again. The jekyll-relative-links plugin relies on baseurl to transform links it finds in Markdown pages into relative links using the relative_url filter. This means that some of our internal links are being mangled, and we are unable to either set baseurl to the empty string or disable the plugin.

[benbalter]

To confirm, the issue is that Jekyll GitHub Metadata should respect "" as a baseurl?

[Morendil]

@benbalter Yes, that would be an out for us. (It may have undesirable side effects I haven't thought of.) Should I create an issue there? This is the relevant line.

[benbalter]

@Morendil that would be the relevant line, but my reading is that it shouldn't inject the baseurl if it is explicitly set as "". Is that still not the case?

[Morendil]

Correct - I'm reproducing this locally with JEKYLL_ENV set to production and Github identifiers in the environment. Despite setting baseurl: "" in _config.yml its value is still reported as /pages/sgmap/beta.gouv.fr.git. We're tracking the Github Pages versions of everything (ruby, gems).

[benbalter]

Opened jekyll/github-metadata#97 with a failing test and more details about what's going on and our constraints.

[benbalter]

Closing in favor of jekyll/github-metadata#97.

[benbalter]

This is now fixed. If you set your baseurl to "" it will be respected.

[bajicdusko]

Hi @benbalter I've just stumbled to baseurl issue when deploying to GitHub pages and I gotta feeling that it's related to this issue.

This is the relevant config I'm using:

url: 'http://bajicdusko.com'
baseurl: '/'

Locally everything is fine, however, when deployed to GitHub Pages, baseurl is changed from / to "". Which break everything.

What should be the proper config in this case. I've added some dummy tags to show the values or githuburl, url and baseurl which proves observation above:

head.html

<meta property="test:githuburl" content="{{ site.github.url }}">
  <meta property="test:url" content="{{ site.url }}">
  <meta property="test:baseurl" content="{{ site.baseurl }}">

Locally:

  <meta property="test:githuburl" content="">
  <meta property="test:url" content="http://localhost:4000">
  <meta property="test:baseurl" content="/">

GitHub

  <meta property="test:githuburl" content="http://bajicdusko.com">
  <meta property="test:url" content="http://bajicdusko.com">
  <meta property="test:baseurl" content="">

As a temporary solution, I've set baseurl: "" and refactored each {{ site.baseurl }} to /{{ site.baseurl }}. Not sure if there is some smarter solution, I'm really new to Jekyll.

[benbalter]

As a temporary solution, I've set baseurl: "" and refactored each {{ site.baseurl }} to /{{ site.baseurl }}. Not sure if there is some smarter solution, I'm really new to Jekyll.

This is the proper solution.

See https://help.github.com/articles/setting-up-your-github-pages-site-locally-with-jekyll/#step-2-install-jekyll-using-bundler for instructions on how to replicate production settings locally.

See http://ben.balter.com/jekyll-style-guide/config/#baseurl (and the linked post) for more information on baseurls. The baseurl should never be /.

[dottorblaster]

Hi @benbalter, I'm really perplexed as this move from "/" to "" for my github pages blog broke the entire production and I didn't see this mentioned in any place.

I'm sure this was my mistake but well, I got my blog crippled for a couple of hours and I was just leaving this here for a rant.

Are you sure that /{{ site.baseurl }} is an elegant solution? Seems like a tiny hack to me, it's not elegant at all. But well, I'm refactoring all of my headers to reflect this change 😂 👌

[benbalter]

@dottorblaster (and those that 👍'd)... would love to learn more about your hosting setup and why this would break a site. Are you proxing from a top-level domain to a subpath on GitHub Pages? If so, how are you acomplishing it? How does the baseurl value break the site? How are you using baseurl? Do you have a CNAME set?

I'm sure this was my mistake but well, I got my blog crippled for a couple of hours

See http://ben.balter.com/jekyll-style-guide/config/#baseurl. Base URL was intended to represent a subpath, not /, but regardless of the intention, it's one of Jekyll most misunderstood/misused features. I'm a big fan of "practicality over purity". Even if on paper that's the right way to do things, we shouldn't break your site if we can avoid it.

Are you sure that /{{ site.baseurl }} is an elegant solution?

I'm not sure when you'd use it. I'd suggest using the relative_url and absolute_url filters, which should take into account the logic (and IIRC, solve for both forms of baseurls).

I'm really perplexed as this move from "/" to "" for my github pages blog broke the entire production and I didn't see this mentioned in any place.

Re-reading https://github.com/jekyll/github-metadata/pull/97/files#diff-165b64b2f6bce98447b6c550f3205ad9L45 and https://github.com/jekyll/github-metadata/pull/97/files#r122748605, I think we may have misread the original logic (and didn't have adequate test coverage for this case).

There's three potential baseurl values with clear intentions:

• nil - No user-supplied baseurl. Good to overwrite.
• "" - User explicitly asked us not to build with a baseurl
• /foo - User explicitly provides a baseurl

/, on the other hand, is ambiguous in that we don't know if the if user really wants no baseurl (what should be ""), or if they they misconfigured their site. Under the assumption that proxying from a subpath to a different domain root was not a common use case, and those users sophisticated to proxy across paths would be more likely to properly configure their domain, we erred on the side of helping users that may have misconfigured their site. If they have a baseurl of / and it's a use page, we'll end up at the same place. If it's a project page, we'll properly correct the baseurl and avoid a more novice user's potential frustration.

I understand now that the metadata change, along with the upstream default change had some unintended consequences. I'd love to learn more about how you're using GitHub Pages and the baseurl value so that we don't violate your expectations, here or in the future.

[Ivoz]

@benbalter an org I worked with has a project on a CNAME'd bare domain.

https://github.com/OpenTechSchool/www.opentechschool.org/

Since ANY subpage will always have a slash prefixing it, I assumed setting baseurl to / would be deduplication. Instead of having that trailing slash after every single written usage of baseurl, it would be in baseurl.

If I have a subpage, instead of writing baseurl + / + subpage I can write baseurl + subpage. or instead of {{ site.baseurl }}/blah I can leave out that /

Now thanks to this change I will be removing the / from being written once in a config file, and be adding it all over site links to fix things. So duplicating / all over the place.

After all, when you visit google.com you don't ask for the the page on path "". You ask for the page on path "/".

[jonhoo]

@benbalter to try to give you a more concrete example of how the story here is hard to figure out. First of all, in my _config.yml I have

permalink: /blog/:title/

Because of this, I need URLs to all use baseurl one way or another, since the source of those links may or may not be inside subdirectories (stylesheets in head for example). While I could maybe make all my URLs correct using the right prepending, I'd rather just set <base href=""> and be done with it.

I have a website that was previously self-hosted at example.com, and I want to move to GitHub pages. However, before flipping the DNS switch, I want to make sure everything is working using user.github.io/example.com. I have no idea how to set baseurl such that it will work correctly:

• when run locally with jekyll server
• when run on user.github.io/example.com
• when (eventually) run directly on example.com

What needs to happen is that baseurl is set to / in the first and last case, and /example.com/ in the second case. The trailing / is because if you use <base href="" />, all relatively URLs are relative to the given URL, and something like /blog relative to /example.com is simply /blog.

I haven't tried the third case yet, but here's what happens in the first two:

• if I set baseurl: "", baseurl is set to "" in both cases, which doesn't work
• if I don't set baseurl, it gets set to "" in the first case and /example.com in the second.
• if I set baseurl: /, baseurl is set to / in the former case, which works, and /example.com in the second, which doesn't work since the trailing / is missing

Notice that the proposed solution of prefixing baseurl with / doesn't work, since //example.com is interpreted as a protocol-relative URL, so it's basically like setting baseurl: https://example.com, which breaks the user.github.io links.

Instead, as far as I can tell, the only correct solution is to not set baseurl and to add

<base href="{{ site.baseurl }}/" />

to the site. I've also now tested that this works with the CNAME set.

I wish this was documented somewhere since (seemingly) this is the kind of setup a decent number of people have. Now that I know how to configure it correctly, it doesn't seem so bad, but the process of figuring out exactly what to put where took a decent amount of trial and error!