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?

This happends to me. Did you manage to find out the reason of this? — Andrey Mikhaylov - lolmaus, Aug 27 '13 at 10:02
Note: in Dec. 2016, GitHub pages has changed considerably. See [my answer below](http://stackoverflow.com/a/41127983/6309) — VonC, Dec 13 '16 at 18:21
The problem with relative links in github pages is still there in 2022. — Timo, Jun 30 '22 at 17:31

score 82 · Answer 1 · edited Jan 18 '16 at 03:16

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.

In _config.yml, set the baseurl option to /project-name – note the leading slash and the absence of a trailing slash.

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

Yea, this one should be the accepted answer. Seems a bit convoluted for a common Jekyll use case - I wonder if there's a reason they don't use site.baseurl by default? — Kevin Qi, May 23 '14 at 04:27
While this is several years old and the documentation has changed, this solution worked for me over what was recommended in the Jekyll docs of using `{{ site.github.url }}` — Kyle Shevlin, Oct 30 '16 at 17:38

score 14 · Accepted Answer · answered May 01 '13 at 20:10

Which browser are you using? Are you sure that this happens? Because it shouldn't. If you include a relative URL in a link, it will get resolved relative to the URL of the document that contains the link. In other words, when you include

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

in an HTML document at http://www.foo.com/bar/doc.html, the link to assets/css/common.css will get resolved by appending it to the prefix of the URL of the HTML document without the last part of the path (without doc.html), i.e. the link will resolve to http://www.foo.com/bar/assets/css/common.css, not to http://www.foo.com/assets/css/common.css as you claim.

For example, view the source of the Twitter Bootstrap webpage: http://twitter.github.io/bootstrap/. Notice the style links at the top, specified as <link href="assets/css/bootstrap.css" rel="stylesheet">. That link correctly resolves to http://twitter.github.io/bootstrap/assets/css/bootstrap.css, i.e. it does include the repo name.

how do you handle `href="/"` ? – Akabab Apr 05 '18 at 13:28 — Akabab, Apr 05 '18 at 13:28

score 12 · Answer 3 · edited Jan 05 '21 at 03:05

12

You could just put this

<base href="/[repo]/">

inside of the <head> tag, and it solves the problem.

You could also improve this solution by setting:

<base href="{{site.baseurl}}" />

and then set site.baseurl to empty string for the local testing.

edited Jan 05 '21 at 03:05

Community

1
1

answered Apr 20 '18 at 14:53

Affilnost

309
3
7

1

If you don't want to fool around with Jekyll and all that, this is the best solution – Pro Q May 08 '19 at 04:14
thanks! but can you give some reference? especially about this `site.baseurl`? i mean, can i access this `site` from console? – Patrick Martinus Jan 15 '22 at 17:09
works on pages, but not on localhost I think. – Timo Jun 30 '22 at 18:24
I still want to find a way to use localhost and pages for the same code but not using Jekyll. Your first solution is for remote. – Timo Jun 30 '22 at 18:36

score 5 · Answer 4 · answered Dec 13 '16 at 18:21

This should not be an issue anymore in Dec. 2016, 3 and an half years later.
See "Relative links for GitHub pages", published by Ben Balter:

You've been able to use relative links when authoring Markdown on GitHub.com for a while.

(that is from January 2013)

Now, those links will continue to work when published via GitHub Pages.

If you have a Markdown file in your repository at docs/page.md, and you want to link from that file to docs/another-page.md, you can do so with the following markup:

[a relative link](another-page.md)

When you view the source file on GitHub.com, the relative link will continue to work, as it has before, but now, when you publish that file using GitHub Pages, the link will be silently translated to docs/another-page.html to match the target page's published URL.

Under the hood, we're using the open source Jekyll Relative Links plugin, which is activated by default for all builds.

Relative links on GitHub Pages also take into account custom permalinks (e.g., permalink: /docs/page/) in a file's YAML front matter, as well as prepend project pages' base URL as appropriate, ensuring links continue to work in any context.

And don't forget that since August 2016, you can publish your pages right from the master branch (not always the gh-pages branch)

And since Dec. 2016, you don't even need Jekyll or index.md. Simple markdown files are enough.

There is much good information in your answer - thank you. But after reading through all of the linked articles, I remain at a loss to understand why the relative links in a `html table` in my .md file are not converted to .html during the github pages process. I.e. inside my .md file is an html table containing relative links to other .md files in my repo. The table renders properly on github.com, but in github pages the relative links remain as .md files. [Why?](https://stackoverflow.com/questions/55671021/github-pages-fails-to-convert-md-in-table-to-html) — , Apr 14 '19 at 11:45
@Seamus I never saw that kind of conversion within html elements (like table). I assumed the relative link was converted only when used a pure markdown page, not in a mixed of markdown and HTML elements. — VonC, Apr 14 '19 at 11:51
Apparently that is the case. But it seems I am forced to choose between an ugly lopsided table, and links that are not converted properly. Any suggestions/[answers](https://stackoverflow.com/questions/55671021/github-pages-fails-to-convert-md-in-table-to-html)? — , Apr 14 '19 at 11:56

score 4 · Answer 5 · edited Jun 08 '16 at 23:52

4

It seems that Github Pages is not very responsive. Though it makes new files available immediately, modified files would not appear immediately due to caching or something.

After waiting 15 minutes or so, everything is fine.

edited Jun 08 '16 at 23:52

zurebe-pieter

3,246
21
38

answered Aug 27 '13 at 10:06

Andrey Mikhaylov - lolmaus

23,107
6
84
133

THis was the case for me as well – Jake Oct 14 '18 at 03:29
@AndreyMikhaylov-lolmaus: It seems upvotes are not very responsive either :) – Apr 14 '19 at 11:48

score 1 · Answer 6 · answered Oct 29 '17 at 11:54

Another option is to create a new repo specifically for the github.io webpages. If you name the repo as [user].github.io on github then it will be published at https://[user].github.io and you can avoid having the repo name in the URL path completely. Obviously the downside is that you can only have 1 repo like this per github user, so it may not suit your needs, I'm not sure.

score 1 · Answer 7 · answered Dec 07 '18 at 05:36

1

The best option is now the relative_url filter:

<link href="{{ '/assets/css/common.css' | relative_url }}" rel="stylesheet">

answered Dec 07 '18 at 05:36

Jason Haslam

2,617
13
19

1

I think the filter relative-Url is a Jekyll example, but you should mention it. – Timo Jun 30 '22 at 18:28

GitHub pages and relative paths

7 Answers7

Linked