From 73f942cf7d6bb36c0ac02fcf04006429fcd55ada Mon Sep 17 00:00:00 2001 From: Matt Swensen Date: Wed, 10 Jul 2013 13:53:34 +0200 Subject: [PATCH] Adding details to GitHub Pages deployment docs regarding relative URLs. Fixes #1291. --- site/docs/github-pages.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/site/docs/github-pages.md b/site/docs/github-pages.md index 73a6a646..79d7f5fb 100644 --- a/site/docs/github-pages.md +++ b/site/docs/github-pages.md @@ -54,6 +54,31 @@ actual software project for Jekyll, however the Jekyll website (that you’re looking at right now) is contained in the [gh-pages branch](https://github.com/mojombo/jekyll/tree/gh-pages) of the same repository. +### 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. +2. When referencing JS or CSS files, do it like this: + `{% raw %}{{ site.baseurl}}/path/to/css.css{% endraw %}` -- note the slash + immediately following the variable (just before "path"). +3. When doing permalinks or internal links, do it like this: + `{% raw %}{{ site.baseurl }}{{ post.url }}{% endraw %}` -- 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. +
GitHub Pages Documentation, Help, and Support