Configuring Jekyll for github PROJECT pages

Question

I am at my wits end here. I\'ve been trying to look at all other example github project pages I could find and even the blogs but none exhibit the problems I am getting. First,

Answer 1

When you have a slash at the front of your permalink, it means that all URLs should be relative to the site root. This is the reason that it's going to http://corroded.github.com/exercises/title-here instead of http://corroded.github.com/projectname/exercises/title-here. Try it without the first slash:

permalink: exercises/:title

The same thing goes for any URLs you create with HTML. If you have:

<a href="/about">

it will always go to the root of the domain (e.g. http://corroded.github.com/about). If you're project is called 'projectname', you can use HTML like

<a href="/projectname/about">

to link directly to pages (e.g. http://corroded.github.com/projectname/about).

Of course, you can also use relative URLs (i.e. URLs without a leading slash) as well. You just have to be aware of where you are in the directory tree.

Answer 2

EDIT: This answer has been added to the Jekyll documentation at http://jekyllrb.com/docs/github-pages/.

---

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.

More conversation about this problem on issue #332.