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

firemonkeyio opened this Issue May 15, 2011 · 37 comments


None yet

If you're not using a CNAME and hosting your Project Page on GitHub Pages it's served out of a "project-name" subfolder

Relative url's fail:

<a href="/">home</a>

resolves to

Another example:

<a href="/blog">blog</a>

resolves to

when I needed:

The workaround I can think of for this is setting a "base-url:" in the _config.yml then put that in front of all href, src, url paths ... need it in .css and .js files, so they need to run through Jekyll (see: a "base-url:" is suggested in the wiki here: ... but I can't seem to find anything that explains how this should be implemented within your actual files. e.g.

<a href="{{ site.base-url }}/blog">blog</a>

... am I missing something here? Is there a more elegant solution?

Personally I would prefer it to be shorter since you would need to be typing this A LOT
<a href="{{ site.url }}/blog">

Then on a page you have {{ site.url }} == /project-name and {{ page.url }} == /blog/

Use the HTML base tag and it will work fine.

--base-url was added more as an option for the --server, so that WEBrick can serve your local content from the same /project-name as your project page. But you're right that it would make sense if GitHub Pages could pass a relevant --base-url in, just so that {{ site.baseurl }} is set to a useful value.


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?

shareme commented Nov 3, 2011

Its simpler to use the config.yml baseurl line to add it as html base in head of html than you never are editing hrefs ever..:)

Is this still unfixed? Even if I add baseurl to my _config.yml, that might work on GitHub, but it will break the site when I running it locally. Is there any way to overcome this?

bilke commented Dec 6, 2011

I am also interested in a solution...

bilke commented Dec 7, 2011

@7andrew: unfortunately your solution does not work in platform redirect files such as:

    layout: os_redirect
    title: Set Up Git
    description: A quick guide to help you get started with Git
    categories: beginner
    redirect_win: {{site.baseurl}}/win-set-up-git
    redirect_mac: {{site.baseurl}}/mac-set-up-git
    redirect_linux: {{site.baseurl}}/linux-set-up-git
salzig commented Dec 22, 2011


Any solution? I would like to be able to have relative links work in GitHub pages as well as locally.

pacebl commented Aug 29, 2012

No solution for this yet?

What I've done to make paths work both locally and on my ghPage is to create a _config.yml file that I then add to my .gitignore where I define a url variable for my local path. Then I use {{ site.url }} in paths to create full absolute urls. However, since the config file doesn't get uploaded when I push to GitHub, the {{ site.url }} is ignored there and the paths stay relative on my ghPage.

I just tried this and it works, but I am still in process of putting my ghPage together so I've only tried it on my index page and my test post.

This is still a big issue for serving html pages in subfolders and linking them to css in root on Github Pages

parkr commented Feb 18, 2013

According to all of the documentation I have, baseurl is used by jekyll --server to serve Jekyll under an arbitrary base url via WEBrick. It doesn't interact with any of the links in your Jekyll source, nor is that configuration added to the site variable in Jekyll.

@parkr The problem here is that if you serve a website via Github Pages, the url looks like the repo part acts as a subfolder. Let's say you have a multi-level site: there's pages in the root folder, as well as subfolders containing pages (index.textile and documentation/index.textile), and CSS is stored in the /css/ folder. The way you normally set the url's (and the way it works if your run jekyll --server locally) to the CSS assets is like so:

<link href="/css/reset.css" rel="stylesheet" type="text/css">
<link href="/css/styles.css" rel="stylesheet" type="text/css">
<link href="/css/syntax.css" rel="stylesheet" type="text/css">

this makes sense, the browser will look for files under the root/css/, i.e. localhost/css/styles.css But, with Github Pages, what happens is this:, while we want ` we could make the links relative

<link href="css/reset.css" rel="stylesheet" type="text/css">

which makes the site work for documents in the root, but still breaks for any subfolders.

@parkr parkr closed this Mar 17, 2013
oblitum commented May 26, 2013

@parkr I'm suffering from this issue too, just as @archSeer described. I've a custom domain properly setup at my older user GitHub page. Now I'm trying out a Jekyll project page, first I've checked that was being redirected to customdomain/project and things were messed up in this fresh Jekyll page because baseurl wasn't configured for such, so everything was referring to customdomain/, then the solution I've found was to change baseurl to /project and fix source files, for example:

<!-- Custom CSS -->
<link rel="stylesheet" href="{{site.baseurl}}/css/main.css">

instead of previous

<!-- Custom CSS -->
<link rel="stylesheet" href="/css/main.css">

but still, this solved things partially, at the index page there's:

{% for post in site.posts %}
  <li><span>{{ | date_to_string }}</span> &raquo; <a href="{{ post.url }}">{{ post.title }}</a></li>
{% endfor %}

When I load the page, {{ post.url }} get expanded to customdomain/post-page instead of customdoman/project/post-page.

So, how do I config a simple GitHub Pages hosted Jekyll new project site that get all this fixed?

oblitum commented May 26, 2013

I got {{ post.url }} fixed by chaging it to {{ site.baseurl }}{{ post.url }}, now it seems the only issue lasting is that locally, jekyll serve doesn't work after all changes, and I can't browse it for tests.

Even then, I'm not sure it was the proper way to fix this.

oblitum commented May 26, 2013

ok, I figured it out for serving locally, I must put the ending slash: http://localhost:4000/project/ (I was doing http://localhost:4000/project).

So, everything is working, the only thing that I find cumbersome now is that I must put {{ site.baseurl }} before everything. Why baseurl configuration solely is not enough to configure / project wide?

xavimat commented May 30, 2013

So, what is the solution?


I finally figured out the trick, if you're looking for a solution with the standard URL for GitHub Pages ( 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.

aseemk commented Jun 5, 2013

Excellent solution, @mjswensen. Thorough and helpful. Thanks.


@aseemk No sweat!

oblitum commented Jun 5, 2013

I doesn't seems different from what I've gone through, except that I never need to use --baseurl '', just jekyll serve works for me. Also, I'm starting up from jekyll-bootstrap themes that have links already done right as @mjswensen described.

@redfrost redfrost referenced this issue in redfrost/Stacks Jul 1, 2013

Jekyll URL problem when creating pages #8

@mjswensen Thanks for the solution. That worked.

on a different note, what a PITA.

parkr commented Jul 9, 2013

@mjswensen Would you want to write that up and submit a PR to the docs site for us?


@parkr Be happy to.

@adamsiem adamsiem added a commit to patrickjmorris/cleanwebny that referenced this issue Apr 12, 2014
@adamsiem adamsiem Eliminate base url and {{ site.baseurl }}
This is needed for the CSS, JS and other file references to work when
using a CNAME to point to (
jekyll/jekyll#332 )
@erictheise erictheise added a commit to erictheise/mctad.js that referenced this issue Jun 23, 2014
@erictheise erictheise using baseurl per jekyll/jekyll#332 9fdf593
@hayd hayd referenced this issue in jekyll/jekyll-redirect-from Aug 10, 2014

Generated link is wrong when baseurl option is used #15

Thank you @mjswensen, you help me a lot! (-;


@willianribeiro Glad to help!

@danrademacher danrademacher pushed a commit to danrademacher/rimfireweb that referenced this issue Aug 18, 2014
Dan Rademacher Adding config.yml
Trying to solve the base URL issue, and the solution is shown here,
jekyll/jekyll#332 (comment)
@lord63 lord63 referenced this issue in tankywoo/simiki Aug 29, 2014

Use site.url instead of site.root #28


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

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

parkr commented Jan 29, 2015

Jekyll is not going to go into your code and change all your links. That's just asking for trouble. If anything, we can provide a liquid tag. But that said, you're asking for some voodoo in the above thay Jekyll can't provide. Using true relative URL's (e.g. ../another-page) would be the best answer.


Yes, this is want I want! I would like my index.html to link to my main css file as css/main.css and my page pages/bob.html should link to the same file as ../css/main.css. This does not appear to be a feature.

I am reading the documentation on relative_permalink but I do not think it will do this for me. Also, now I am looking into an ugly liquid hack, which I will post back here. Thanks for following up.


@fulldecent , would following the pattern outlined in the Project Page URL Structure docs, committing baseurl: '/' in your _config.yml, and then passing --baseurl '' when you compile for the domain not be a viable solution?


@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.

@SungMatt SungMatt added a commit to SungMatt/UsingWavesToFindExoplanets that referenced this issue Mar 8, 2015
@SungMatt SungMatt Added _Config.yml
Conforms to Jekyll, allows internal links to be made in the form of `{{ site.baseurl }}/path/to/css.css`

(As referenced from here and jekyll/jekyll#332
@iominh iominh added a commit to iominh/bootstrap-jekyll that referenced this issue Apr 19, 2015
@iominh iominh set baseurl for github pages deployment: jekyll/jekyll#332 (comment) 2eca492
@jameslaneconkling jameslaneconkling referenced this issue in loggingroads/logging-roads Apr 30, 2015

Fix baseurls for DNS #2

mashdot commented May 22, 2015

Just to point out what is working for me now, since I found this page whilst looking for a solution.

I am using a custom domain on my github project, and Rakefile to publish my _site to the gh-pages branch.

So if my project repo is:

My baseurl: '/example' to allow for local testing, stripping it with jekyll serve -tw --baseurl.

I simply amended my rake task with "baseurl" => "" to strip it when generating the site.

# "rake publish" to compile and publish
desc "Generate site files"
task :generate do{
                                          "source"      => ".",
                                          "destination" => "_site",
                                          "baseurl"     => ""

desc "Generate and publish site to gh-pages"
task :publish => [:generate] do
  Dir.mktmpdir do |tmp|
    cp_r "_site/.", tmp
    Dir.chdir tmp
    system "git init"
    system "git add ."
    message = "Site updated at #{}"
    system "git commit -m #{message.inspect}"
    system "git remote add origin{GITHUB_REPONAME}.git"
    system "git push origin master:refs/heads/gh-pages --force"

This allows me to use {{ site.baseurl }} to test the site locally, and publish to my custom domain with relative links. I simply hardcode in {{ site.url }} for header meta tag absolute links etc.

@thibautdavoult thibautdavoult pushed a commit to thibautdavoult/blog that referenced this issue May 25, 2015
Thibaut Davoult mjswensen baseurl fix 2fa88f2
@benjvi benjvi added a commit to benjvi/ that referenced this issue Jun 13, 2015
@benjvi benjvi URLs borken, try using baseurl f62cbc7
@DirtyF DirtyF added a commit to sudweb/2016 that referenced this issue Dec 24, 2015
@DirtyF DirtyF Fix baseurl problem e91159e
@MaxMontoro MaxMontoro added a commit to MaxMontoro/blog that referenced this issue May 28, 2016
@MaxMontoro MaxMontoro /blog/ prefix added to avatar image
Temporary fix for issue jekyll/jekyll#332

it work with me when index.html file is in the root directory

here example [ ]
file are loaded

@tomelam tomelam added a commit to Mashweb/zen that referenced this issue Aug 30, 2016
@tomelam tomelam This:
led me to this (almost didn't notice it!):
jekyll/jekyll#332 (comment)

This works on localhost. Now I'll see if it works on
@susanjrobertson susanjrobertson referenced this issue in bocoup/opendesignkit Sep 9, 2016

Perform QA on site #132

22 of 28 tasks complete
@spencerwmiles spencerwmiles added a commit to spencerwmiles/26thScouts that referenced this issue Oct 12, 2016
@spencerwmiles spencerwmiles Updated URLs on Index to include Path to /26thScouts/
-- jekyll issue discussed here
@i2000s i2000s added a commit to i2000s/en that referenced this issue Nov 22, 2016
@i2000s i2000s Add site.baseurl to subrepo page templates according to –jekyll/jekyl… 6290e4a
@boykoc boykoc pushed a commit to boykoc/should-i-start-a-startup that referenced this issue Jan 15, 2017
cody Bug: Fix urls based on issue 332 fix. jekyll/jekyll#332. 28ad034
@kratsg kratsg added a commit to deafchi/ that referenced this issue Jan 25, 2017
@kratsg kratsg see jekyll/jekyll#332 c3afe57
@browtayl browtayl referenced this issue in capstone-coal/ Mar 6, 2017

Website Rewrite #10

@11011110 11011110 added a commit to 11011110/blog that referenced this issue Apr 11, 2017
@11011110 11011110 Is this the fix for the prev/next navigation bar failure? Taken from …
…andrewspiers comment on jekyll/jekyll#332, but unable to test locally
@bbgvisualjournalist bbgvisualjournalist added a commit to bbgvisualjournalist/circumventing-censorship that referenced this issue Apr 17, 2017
@bbgvisualjournalist bbgvisualjournalist Trying to fix nav using baseurl via jekyll/jekyll#332 (comment) 5ffe223
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment