Site root: Github Pages vs. `jekyll --server`

Question

When I run jekyll --server my site is available at http://localhost:4000/, but when I deploy to GitHub Project Pages, it's available at http://username.github.com/projectname/.

This means that I cannot use absolute URLs when referring to stylesheets and other resources. Relative URLs break when the same layout is used by e.g. index.html and 2012/01/01/happy-new-year.html. What is the-accepted/a-good way of adding stylesheets and other resources to a GitHub Project Pages repository?

Cross-posted to GitHub Issues.

Answer 1

This problem arises because the root directory is always the user url (user.github.com), in both user and project pages. I found a solution to this: Configure the url variable in the _config.yml file to the github project page:

safe: true ... url: "http://user.github.io/project-name" 

then, in the layouts, use absolute references, using the site.url variable to do that:

<link rel="stylesheet" href="{{ site.url }}/css/styles.css"> 

and run the server using:

$jekyll --server --url=http://localhost:4000 

The command line option overwrite the setting in the configuration file in local mode. With those settings, I get all the links pointing to the right place, both hosted in github and in local mode.

---

UPDATE: Jekyll 1.0 Since Jekyll reached 1.0, the aforemetioned options server and url and its respective command line options --server and --url have been deprecated. Instructions for the new version:

In the _config.yml file, add the variable baseurl (without trailing slash):

baseurl: "http://user.github.io/project-name" 

In the layouts or pages, use absolute references, using the site.baseurl variable:

<link rel="stylesheet" href="{{ site.baseurl }}/css/styles.css"> 

and then, run the local server (the baseurl option is empty on purpose):

$ jekyll serve --watch --baseurl= 

More details about the changes in the docs.