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, I am trying to create a project page for my repo. I did this by following the usual tutorials, creating a gh-pages branch in my project repo and pushing.

I managed to do these and template my files. I even managed to use HAML and SASS(they still both get converted to html/css and that's what I push to the repo so no problem there). I just think that I am configuring my jekyll wrong. First, I don't see any configurations in other people's pages that use baseurl or url on config.yml.

The problem with mine is when looping through my posts:

{% for post in site.posts %}
  <a href="{{ post.url }}">{{ post.title }}</a>
{% endfor %}

It always generates the href as href="/post-title"

my _config.yml btw only has this:

permalink: /exercises/:title

The problem with this when I click the link, it always points to http://corroded.github.com/exercises/title-here when it should actually be http://corroded.github.com/projectname/exercises/title-here

I have actually tried hard coding the path by doing:

<a href="http://corroded.github.com{{ post.url }}"> and this works. It goes to the post BUT it shows it as plain text and not as the generated html. I know I am missing something very simple here but I can't seem to find it and I've been wrestling with this the whole weekend.

Oh and I forgot to add: doing this in my localhost, I can access everything at:

http://localhost:4000/ and clicking on links will get me to http://localhost:4000/exercises/title-here and IT WORKS. So I have a pretty good guess that it has something to do with the configuration.

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.