Html GitHub 页面和相对路径

GitHub pages and relative paths

提问by seesharper

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

我gh-pages为我在 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.

我使用 Sublime 文本在本地创作网站，我的问题是，当它被推送到 GitHub 时，所有指向 javascrips、图像和 css 文件的链接都无效。

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.

这在本地工作得很好，但它在 GitHub 上不起作用，因为链接没有使用存储库名称作为 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.

我当然可以将 repo 名称作为 URL 的一部分，但这会阻止我的站点在开发过程中在本地工作。

Any idea how to deal with this?

知道如何处理这个问题吗？

采纳答案by Ivan Zuzak

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

您使用的是哪个浏览器？你确定会发生这种情况吗？因为它不应该。如果在链接中包含相对 URL，它将相对于包含该链接的文档的 URL 进行解析。换句话说，当你包括

<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.csswill 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.cssas you claim.

在位于 的 HTML 文档中http://www.foo.com/bar/doc.html， 链接assets/css/common.css将通过将其附加到 HTML 文档的 URL 前缀而不是路径的最后部分（没有doc.html）来解析，即链接将解析为http://www.foo.com/bar/assets/css/common.css，而不是http://www.foo.com/assets/css/common.css您声称的。

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.

例如，查看 Twitter Bootstrap 网页的来源：http: //twitter.github.io/bootstrap/。请注意顶部的样式链接，指定为<link href="assets/css/bootstrap.css" rel="stylesheet">。该链接正确解析为http://twitter.github.io/bootstrap/assets/css/bootstrap.css，即它确实包含存储库名称。

回答by Anubhav C

You'll need to use Jekyll.

你需要使用 Jekyll。

Copying verbatim from the relevant documentation:

从相关文档中逐字复制：

Sometimes it's nice to preview your Jekyll site before you push your gh-pagesbranch 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 baseurloption 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 --baseurloption, so that you can view everything at localhost:4000normally (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-pagesbranch all the URLs will start with /project-nameand resolve properly.

有时，在将gh-pages分支推送到 GitHub之前预览您的 Jekyll 站点会很好 。但是，GitHub 用于项目页面的类似子目录的 URL 结构使 URL 的正确解析变得复杂。这是一种利用 GitHub 项目页面 URL 结构 ( username.github.io/project-name/) 同时保持在本地预览 Jekyll 站点的能力的方法。

1. 在 中_config.yml，将baseurl选项设置为/project-name– 注意前导斜杠和尾随斜杠的缺失。

2. 引用 JS 或 CSS 文件时，请这样做：{{ site.baseurl}}/path/to/css.css– 注意变量后面的斜杠（就在“path”之前）。

3. 在做永久链接或内部链接时，这样做：{{ site.baseurl }}{{ post.url }}- 注意两个变量之间没有斜线。

4. 最后，如果您想在使用 提交/部署之前预览您的站点jekyll serve，请确保将一个空字符串传递给该--baseurl选项，以便您可以localhost:4000正常查看所有内容 （开头没有 /project-name）： jekyll serve --baseurl ''

通过这种方式，您可以从 localhost 上的站点根目录在本地预览您的站点，但是当 GitHub 从gh-pages分支生成您的页面时，所有 URL 都将开始/project-name并正确解析。

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

（显然有人在几个月前才发现这一点。）

回答by Affilnost

You could just put

你可以把

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

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

<head>标签内部，它解决了问题。

You could also improve this solution by setting:

您还可以通过设置来改进此解决方案：

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

and then set site.baseurlto empty string for the local testing.

然后设置site.baseurl为空字符串进行本地测试。

回答by VonC

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:

在 2016 年 12 月，也就是 3 年半之后，这应该不再是一个问题。
请参阅Ben Balter发布的“ GitHub 页面的相对链接” ：

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

一段时间以来，您在 GitHub.com 上创作 Markdown 时已经能够使用相对链接。

(that is from January 2013)

（即从 2013 年 1 月开始）

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:

现在，当通过GitHub Pages发布时，这些链接将继续有效。

如果您的存储库中有一个 Markdown 文件docs/page.md，并且您想从该文件链接到docs/another-page.md，您可以使用以下标记来实现：

[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.htmlto match the target page's published URL.

Under the hood, we're using the open source Jekyll Relative Linksplugin, 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.

当您在 GitHub.com 上查看源文件时，相对链接将继续工作，就像以前一样，但是现在，当您使用 GitHub Pages 发布该文件时，该链接将被静默转换docs/another-page.html以匹配目标页面的发布 URL .

在幕后，我们正在使用开源Jekyll 相对链接插件，该插件默认为所有构建激活。

GitHub Pages 上的相对链接还考虑permalink: /docs/page/了文件 YAML 前端内容中的自定义永久链接（例如），并在适当的情况下预先添加项目页面的基本 URL，确保链接在任何上下文中继续有效。

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

并且不要忘记，自 2016 年 8 月以来，您可以直接从master分支（并不总是gh-pages分支）发布您的页面

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

自2016年12 月以来，您甚至不需要Jekyll或index.md。简单的降价文件就足够了。

回答by Andrey Mikhaylov - lolmaus

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.

似乎 Github Pages 不是很灵敏。虽然它使新文件立即可用，但由于缓存或其他原因，修改后的文件不会立即出现。

After waiting 15 minutes or so, everything is fine.

等待 15 分钟左右后，一切正常。

回答by Jason Haslam

The best option is now the relative_urlfilter:

现在最好的选择是relative_url过滤器：

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

回答by mulllhausen

Another option is to create a new repo specifically for the github.io webpages. If you name the repo as [user].github.ioon github then it will be published at https://[user].github.ioand 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.

另一种选择是专门为 github.io 网页创建一个新的存储库。如果您将 repo 命名为[user].github.ioon github，那么它将发布在https://[user].github.io，您可以完全避免在 URL 路径中包含 repo 名称。显然，缺点是每个 github 用户只能拥有 1 个这样的 repo，所以它可能不适合您的需求，我不确定。