html - GitHub pages and relative paths

Question

I have created a gh-pages branch for a project that I am working on at GitHub.

I use Sublime text to author the website locally and my problem is that when this is pushed to GitHub, all the links to javascrips, images, and css files are invalid.

For instance, I have this in my head section.

<link href="assets/css/common.css" rel="stylesheet">

This works great locally, but it does not work from GitHub as the links are not resolved using the repository name as part of the URL.

It asks for:

http://[user].github.io/assets/css/common.css

when it should have been asking for:

http://[user].github.io/[repo]/assets/css/common.css.

I could of course put the repo name as part of the URL, but that would prevent my site to work locally during development.

Any idea how to deal with this?

Answer 1

You'll need to use Jekyll.

Copying verbatim from the relevant documentation:

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.

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): 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.

(Apparently someone figured this out only a few months ago.)