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

[firemonkeyio]

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

http://user-name.github.com/project-name

Relative url's fail:

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

resolves to

http://user-name.github.com/

Another example:

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

resolves to

http://user-name.github.com/blog

when I needed:

http://user-name.github.com/project-name/blog

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: http://stackoverflow.com/questions/4305955/can-jekyll-act-over-css-or-js-files)... a "base-url:" is suggested in the wiki here: https://github.com/mojombo/jekyll/wiki/Configuration ... 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?

[firemonkeyio]

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/

[Kwpolska]

Use the HTML base tag and it will work fine.

[halfninja]

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

[fguillen]

+1

[andrewspiers]

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?

[fredgrott]

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..:)

[darthdeus]

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]

I am also interested in a solution...

[bilke]

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

👍

[rachelslurs]

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

[madelinecr]

No solution for this yet?

[jeffreycrow]

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.

[archseer]

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

[parkr]

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.

[archseer]

@parkr The problem here is that if you serve a website via Github Pages, the url looks like http://username.github.com/repo/where 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: http://username.github.com/css/styles.css, while we want `http://username.github.com/repo/css/styles.css... 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.

[oblitum]

@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 username.github.io/project 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>{{ post.date | 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]

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]

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?

[ghost]

So, what is the solution?

[mjswensen]

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.

[aseemk]

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

[mjswensen]

@aseemk No sweat!

[oblitum]

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.

[sethburtonhall]

@mjswensen Thanks for the solution. That worked.

on a different note, what a PITA.

[parkr]

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

[mjswensen]

@parkr Be happy to.

[almgwary]

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

[almgwary]

here example [ https://github.com/almgwary/almgwary_gallary/blob/gh-pages/index.html ]
file are loaded

[whoisjorge]

This simple set up works for me:
<a href="{{ "/sitemap" | relative_url }}">sitemap</a>

It will redirect to http://<absolute&belovedURI>/sitemap