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.

Answer 2

Since --url in command line has been deprecated there is another solution.

Let's say your URL path is repo in you http://name.github.io/repo. Now in all links use absolute URLs like

<link rel="stylesheet" href="/repo/css/syntax.css">

Or links

<a href="/repo/license/">License</a>

All you need now is to add --baseurl to command line when you run it locally.

jekyll --server --baseurl /repo/

Answer 3

In the latest version of jekyll (1.1.2) I found it's best to create a separate configuration file from the original. The only difference? The url (or baseurl variable).

The default _config.yml has:

url: myurl.com

The new config (lets call it _preview_config.yml):

url: localhost:4000

This will reassign all your absolute links depending on what configuration you use. Now to run the server with the preview config use:

jekyll serve -w --config _preview_config.yml

A full explanation is on my blog.

Answer 4

To answer your question in short: add baseurl: '/project-name' in _config.yml

For CSS/JS links: {{ site.baseurl }}/css/styles.css

For all other links: {{ site.baseurl }}{{ post.url }}

The official Jeykll GH-Pages answer is here: http://jekyllrb.com/docs/github-pages/

Excerpt:

Project Page URL Structure

Sometimes it’s nice to preview your Jekyll site before you push your gh-pages branch to GitHub. However, the subdirectory-like URL structure GitHub uses for Project Pages complicates the proper resolution of URLs. Here is an approach to utilizing the GitHub Project Page URL structure (username.github.io/project-name/) whilst maintaining the ability to preview your Jekyll site locally.

1. In _config.yml, set the baseurl option to /project-name – note the leading slash and the absence of a trailing slash. ex: baseurl: '/my-proj'

2. 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”).

3. When doing permalinks or internal links, do it like this: {{ site.baseurl }}{{ post.url }} – note that there is no slash between the two variables.

4. 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 at the beginning): ex: 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.

Answer 5

I use jekyll-bootstrap and deploy locally on port 4000, but my github pages url is user.github.com...i think that it depends on how you originally create the repo. Originally I used the auto page builder that github offers which created the repo in a very wizard like manner.

I just followed the steps at:

http://jekyllbootstrap.com/

Hope that helps