Clearing Up Confusion Around baseurl -- Again

TL;DR: Use baseurl when you are building a site that doesn’t sit at the root of the domain.

Hey, so there’s been a bit of confusion about what the Jekyll configuration option called baseurl is. Part of the beauty of open-source and of Jekyll is that there’s a lot of flexibility. Unfortunately, much of this flexibility doesn’t apply to baseurl. Here’s a quick distillation of its intentions, and how to use it.

Mimic GitHub Pages

baseurl was originally added back in 2010 to allow “the user to test the website with the internal webserver under the same base url it will be deployed to on a production server”.¹

Example

So let’s say I come up with a cool new project. I want to make documentation for a project I’m working on called “example”, and I’ll be deploying it to GitHub Pages as a repo under the “@jekyll” username. Its documentation will be available at the URL https://jekyll.github.io/example.

In this example, the term “base URL” refers to /example, which I place in my _config.yml as:

baseurl: /example

When I go to develop my website, I run jekyll serve like normal, but this time I go to https://localhost:4000/example/. What this baseurl has done is specified a base path relative to the domain at which the site lives. If you navigate to just https://localhost:4000/, you will see an error message. If you have hooked up all your links correctly, then you will never see a URL in your testing without /example at the beginning of the path.

You might see, for example:

{{ page.path | prepend:site.baseurl }}

Configuring Your Site Properly

1. Set baseurl in your _config.yml to match the production URL without the host (e.g. /example, not https://jekyll.github.io/example).
2. Run jekyll serve and go to https://localhost:4000/your_baseurl/, replacing your_baseurl with whatever you set baseurl to in your _config.yml, and not forgetting the trailing slash.
3. Make sure everything works. Feel free to prepend your urls with site.baseurl.
4. Push up to your host and see that everything works there, too!

Now what the heck is site.url?

site.url is used in conjunction with site.baseurl when you want a link to something with the full URL to it.

Success!

You’ve done it! You’ve successfully used baseurl and the world is wonderful.