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.

Talavera

Use relative URLs instead? – Ardennes

Relative URLs break if e.g. the same layout is used by /index.html and /2012/01/01/happy-new-year/. – Talavera

If you have an assets directory in the root of your project, /assets/whatever.js will work from anywhere. See my answer for more detail. – Ardennes

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.

Nightingale

this --url is deprecated. I do тещ know how to solve. Have the same issue. – Xavier

It disables custom plugins. If you use github pages, all the plugins will be disabled. – Nightingale

Although this might work, I think the intended way to use the --baseurl option is actually like @SergeyRomanov described it in his answer. – Sprayberry

In both answers the option is used in the same way, to specify the base url of the project. This question is about how to handle the use of github pages for project pages both in local and in github. – Nightingale

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/

Xavier

I couldn't find the deprecation of the url command line option in the docs, but I think that this solution is better. Can you provide a reference for this? – Nightingale

You can see that in docs about configuration --url even not mentioned. – Xavier

lifesaver. I've been headdesking all morning and your answer is the only thing that has worked. There needs to be more documentation/simple examples for getting up and running with this. Thank you! – Syphilis

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.

Aldo

+1, except if you use jekyll serve --config _config.yml,_preview_config.yml you can keep your other settings. In this case, _preview_config.yml only contains the url line. – Capitalist

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.

Bertram

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

Incantation

I'm talking about GitHub Project Pages, not GitHub User Pages. – Talavera