GitHub Pages

GitHub Pages 是什么

GitHub Pages 是通过我们网站托管和发布的公开网页。

你可以通过 Automatic Page Generator 在线创建和发布 GitHub Pages。如果你更喜欢本地操作，你可以使用 Mac或者 Windows 平台的 GitHub App，或者使用 命令行。

Pages 是通过 HTTP 服务的，不是 HTTPS，所以你不应该使用它处理敏感的事务，像发送密码或者信用卡号码。

警告：GitHub Pages 网站是在互联网上公开的，即使它们所在的库是私有的。如果你有敏感的数据在 Page 库，你应该在发布之前删除它。

用户、组织和项目 Pages

这里有两种基本的 GitHub Pages 类型：用户/组织 Pages 和项目 Pages。它们极其相似，但是有一些很重要的差别。

两种类型的 Pages 都是使用 HTTP 服务，不是 HTTPS。你不应该使用它处理敏感信息，像发送密码或者信用卡号码。

请注意 Pages 发布之后都是公开的，即使它所在的库是私有的。

用户/组织 Pages

用户/组织 Pages 存在于一个特定的 GitHub Pages 文件专有库中。你将使用用户名来命名这个库，比如 atmos/atmos.github.io。

• 你必须使用username.github.io这样的命名体制。
• master分支上的内容将用于构建和发布你的 GitHub Pages 网页。

你只可以使用你自己的用户名创建用户或者组织 Pages 的库。像joe/bob.github.io这样的命名将不能构建用户 Pages 网站。

当用户 Pages 构建完之后，打开http(s)://<username>.github.io就可以正常使用了。

构建你的用户 & 组织 Pages

用户 Pages 的构建可以通过任何经过认证邮件的账户。它也可以使用 部署 keys 来自动化这个过程。

组织 Pages 的构建可以通过任何有 push 权限的成员和有认证邮件的用户。想要自动构建，你可以 设置一个机器用户 作为你的组织的成员。组织 Pages 不支持部署 keys。

项目 Pages

不像用户和组织的 Pages，项目 Pages 是作为一个项目保存在同一个库中。个人账户和组织都可以创建项目 Pages。个人账户的项目 Pages 的 URL将会是这样 http(s)://<username>.github.io/<projectname>，但组织的 URL 是http(s)://<orgname>.github.io/<projectname>。创建项目 Pages 的步骤两者都是相同的。

项目 Pages 与用户和组织 Pages 很相似，但有一些轻微的不同：

• gh-pages分支用来构建和发布项目 Pages 网站。

• 如果没有 自定义的域名，项目 Pages 网站将服务在用户 Pages 网站的子域名下：username.github.io/projectname。

• 用户和组织 Pages 网站的 自定义域名 适用于这个账户托管的所有重定向项目 Pages 的相同域名。使用自定义域名的项目 Pages 网站同样在个人账户的username.github.io/projectname和组织的orgname.github.io/projectname中有效。

• 自定义的 404s 只用在使用了自定义域名的网站。否则，将使用用户 Pages 404。

Pages 中使用 Jekyll

除了支持常规的 HTML 内容之外，GitHub Pages 也支持 Jekyll，一个简单的，博客风格的静态网页生成器。Jekyll 使创建站点范围内的头部和底部变得简单，不需要在每个页面复制它们。它也提供一些其他更深入的模板功能。

使用 Jekyll

当你将内容推送到一个特别命名的分支版本库中运行，每个 GitHub Pages 是通过 Jekyll 处理。对于 User Pages，使用在 username.github.io 库的 master 分支。对于 Project Pages，使用项目中存储库中的 gh-pages 分支。因为一个普通的 HTML 网站也是一个有效的 Jekyll 网站，你不需要做什么特别的事情让您的标准 HTML 文件不变。 Jekyll 完整的文档，涵盖其功能和使用方法。只需启动提交 Jekyll 格式的文件，你就会在任何时间使用 Jekyll。

安装 Jekyll

我们强烈建议您的计算机上安装 Jekyll 预览您的网站，并在发布你的网站之前帮助检测出有问题的 GitHub Pages。

很幸运的是，在你的电脑上安装 Jekyll，并确保你的计算机最匹配 GitHub Pages 设置很容易，多亏了 the GitHub Pages Gem和我们的依赖版本的页面。要安装 Jekyll，你需要做几件事情：

1. Ruby - Jekyll 需要 Ruby 语言。如果你有一个苹果电脑，你很可能已经有 Ruby。如果你打开​​终端应用程序，然后运行命令ruby --version，可以证实这一点。你的 Ruby 版本至少应该是 2.0.0。如果你已经有了，你就已经完成这一步。跳至步骤 ＃2。否则，请按照以下说明安装 Ruby。

2. Bundler - 捆绑器的软件包管理器。它使 Ruby 软件版本像 Jekyll 一样。如果你将要在本地建设的 GitHub Pages，它能令你容易得多。如果你还没有安装 Bundler，你可以通过运行命令 gem install bundler 安装它。

3. Jekyll - 主要做的事。你将要创建一个名为 Gemfile 的文件在你的网站的库中并添加行 gem 'github-pages 。在此之后，只需运行命令，bundle install 就可以了。如果你决定跳过步骤＃2，你仍然可以使用命令 gem install github-pages 安装 Jekyll，但你可能会碰到了命令行的麻烦。这里有一个 Gemfile 的例子，你可以使用（放置在存储库的根目录）：

source 'https://rubygems.org'
gem 'github-pages'

运行 Jekyll

为了以符合 GitHub Pages 构建服务器的方式运行 Jekyll，需要通过 Bundler 运行 Jekyll。在库的根目录使用命令 bundle exec jekyll serve（在切换到项目库的 gh-pages 分支之后），然后应该能在 http://localhost:4000 访问你的网站。

保持 Jekyll 是最新的

Jekyll 是一个动态开源项目，它会频繁地更新。当 GitHub Pages 服务器更新了，在你电脑上的软件就会过时，导致你的网站出现本地和发布在 GitHub 的样子不一致。保持 Jekyll 的更新，你可以输入命令bundle（或者如果你选择跳开第二步，运行gem update github-pages）。

配置 Jekyll

你可以通过创建一个 _config.yml 来配置 Jekyll 大部分属性。

默认值

以下的默认值是 GitHub 设置的，你可以自由地重写 _config.yml 文件：

highlighter: pygments
github: [Repository metadata]

配置重写

我们可以重写下面的 _config.yml 中你不可以配置的值：

safe: true
lsi: false
source: your top-level directory

记住，如果你改变了 source 的设置，你的页面可能不能正确地建立。 GitHub Pages 把源文件作为最高级别的库目录来考虑。

Frontmatter 是必须的

Jekyll 需要 Markdown 文件有一个 front-matter 定义在所有文件之上。Front-matter 只是一系列的元数据，由三个破折号划定：

---
title: This is my title
layout: post
---

Here is my page.

如果你喜欢，你可以选择从你的文件中删除 Front-matter，但是你仍然需要这三个破折号：

---
---

Here is my page.

如果你的文件在 _posts 目录中，你可完全删除这些破折号。 

问题解决

如果你的 Jekyll 网站在你 push 它到 GitHub 后没有表现为合适的形式，在本地运行 Jekyll 对你检查错误很有用。为了做到这件事，你将会希望使用 Jekyll 的相同版本和其它依赖。

为了保证你的本地开发环境是使用 Jekyll 的相同版本和 GutHub 网站的依赖，一旦 Jekyll 安装了，你可以定期地运行命令gem update github-pages（或者bundle update github-pages如果使用Bundler）。

如果你 Jekyll 网页正在出现问题，请确定你没有使用和其它项目相同名字的分类，这个会引起路径冲突。例如，你有一个博客站点叫“简历”在你的用户网页库中，和一个项目名叫“简历”也有一个 gh-pages 的分支，它们会引起双方的冲突。

关闭 Jekyll

你可以通过在页面库的根目录下创建一个名为 .nojekyll 的文件并将其 push 到 GitHub 来完全退出 Jekyll。只有当您的站点使用以下划线开头的目录，这才是必要的。Jekyll 把这些当作特殊的目录，并且不将它们复制到最终目的地。

贡献

如果你希望 Jekyll 拥有某些功能，请自由地 fork，并发送一个 pull 请求。我们很高兴接受到用户的意见。

关于GitHub Pages的自定义域名

有两种自定义域名可用于重定向GitHub页数：子域名和顶端域名（apex domains）。

子域名

一个子域名通过您的DNS提供商来配置CNAME记录。

我们因为以下这些原因强烈建议您使用自定义子域名：

• 它把我们内容分发网络的好处带给你的GitHub Pages。
• 它不会受到GitHub服务底层IP地址变化影响。
• Pages将加载得更加快，因为拒绝服务保护可以更有效地实施。

顶端域名

一个顶端域名通过你的DNS供应商配置一个A，ALLAS或者ANAME，和经常被分配给一个或更多的IP地址。

注意：一些DNS供应商支持配置顶端域名的ALIAS或者ANAME记录，但是没有专门的工业标准。一些DNS供应商（如DNSimple）允许顶端域名配置ALIAS或者ANAME指向其它域。

对于你的GitHub Pages，我们推荐使用一个自定义的子域名，而不是一个顶端域名。

GitHub Pages怎样使用自定义域名

GitHub Pages种类	GitHub的主机位置	页面是怎么重定向的	自定义域名例子
用户页面	username.github.io	自动重定向至已经设定好的自定义域名	user.example.com
组织页面	orgname.github.io	自动重定向至已经设定好的自定义域名	org.example.com
用户账号拥有的项目Pages	username.github.io/projectname	自动重定向到一个由用户指定的，用户网站自定义域名的子目录（user.example.com/projectname），以及所有自定义域名	project.example.com
组织拥有的项目Pages	orgname.github.io/projectname	自动重定向到一个由组织指定的，项目页面自定义域名的子目录（org.example.com/projectname），以及所有自定义域名	project.example.com

 

设置GitHub Pages的自定义域名

你可以为用户，组织和项目页面配置一个自定义域名。

新建和上传一个CNAME文件

为了重定向你的GitHub Pages，你必须新建和上传一个CNAME文件。这个文件包含你的库根目录的自定义域名。

通过你的DNS提供商配置自定义子域名

如果你的自定义域名是一个子域名，你必须通过你的DNS提供商配置CNAME记录。

通过你的DNS提供商配置自定义顶端域名

如果你的自定义域名是一个顶端域名，你必须配置ALIAS，ANAME或通过DNA提供商配置A记录。

在 DNS 提供者上配置 CNAME 记录的技巧

要设置一个自定义子域名，你必须要在你的 DNS 提供者上配置一个 CNAME 记录，这可能会或可能不会和你的网络主机提供者相同。

要获取更多自定义子域名的信息，可详见“关于 GitHub 网页站点的自定义域.”。

提示：你可以仅仅只为 GitHub Pages 配置一个自定义域名或者一个自定义顶端域名，除非你使用了一个 www 的子域名。

在 DNS 提供者上配置自定义子域名

与你的 DNS 提供者一起，创建一个 CNAME 记录指的是从该域到 username.github.io。DNS 的变化会占用一整天去扩散蔓延。

不要在 GitHub Pages 中使用通配符 DNS 记录（例如 *.example.com ）！一个通配符 DNS 记录可以让任何人在其中一个子域名中登录到 GitHub Pages。

为确保你的 CNAME 记录设置正确，使用 dig 命令：

$ dig www.example.com +nostats +nocomments +nocmd  
;www.example.com.                     IN      A
www.example.com.              3592    IN      CNAME   username.github.io.
username.github.io.           43192   IN      CNAME   github.map.fastly.net.
github.map.fastly.net.        22      IN      A       199.27.76.133

配置一个 www 子域名

如果你配置一个顶端域名（例如 example.com ）和一个匹配的 www 子域名（例如 www.example.com ），GitHub 服务器会自动地创建双重定向。

例如：

• 如果你的 CNAME 文件包含 example.com，那么 www.example.com 会定向到 example.com。
• 如果你的 CNAME 文件包含 www.example.com，那么 example.com 会定向到 www.example.com。

你可以使用除了 www 以外的一个自定义子域名和一个自定义顶端域名来通过域名重定向（有时候也叫“域名转发”）。但是，请注意，这只能用于用户和组织的 Pages，而不是项目的 Pages。

添加CNAME文件到你的存储库中

如果你正在使用一个自定义域名去重定向你的GitHub Pages，你必须创建和提交一个包含自定义域名的CNAME文件到你的GitHub Pages存储库中。

1. 在GitHub，导航到你的页面存储库。
2. 在“分支”菜单中，切换到你存储库的页面分支：
   • 对于用户和组织的页面站点来说，Pages分支是master。
   • 对于项目页面站点来说，Pages分支是gh-pages。
3. 添加一个新文件，命名为CNAME（全部大写！），放在Pages分支的根目录下。
4. 在新文件中，添加一行，指定自定义域名的空子域名。例如，使用blog.example.com而不是 https://blog.example.com。请注意，在CNAME文件中只网求允许有一个域名。
5. 输入提交的消息，或接受默认消息。
6. 在提交消息的对话框底部，点击确认合并。

确认自定义域名配置正确

1. 在你的存储库右边侧边栏，点击。

2. 在“GitHub Pages”底部，你会看到你的CNAME文件的自定义域名。

下一步：配置DNS的设置项

在你已经创建和提交你的CNAME文件到GitHub之后，在你的DNS提供者上做以下项之一：

• 如果的你自定义域的英文一个子域名（推荐），配置一个CNAME记录。
• 如果的你自定义域的英文一个顶端域名，配置一个ALIAS，ANAME，或者A记录。

真实的CNAME文件例子

atmos.github.io repository有一个域名为www.atmos.org的 CNAME文件。

• 用户页面站点atmos.github.io定向到www.atmos.org。
• 项目页面站点atmos.github.io/warden-github定向到www.atmos.org。

注意项目页面站点如何继承其所有者的用户页面站点的域。

表情符号存储库有一个域名为emoji.muan.co的 CNAME文件。它归 muan所有，muan的用户页面存储库有一个域名为muan.co的 CNAME文件。

• 项目页面站点muan.github.io/emoji定向到muan.co/emoji，这对于emoji.muan.co也同样适用。

• 在你的 DNS 提供者上配置 A 记录的技巧

  要设置一个自定义顶点域名，你必须要在你的 DNS 提供者上配置一个 ALIAS，ANAME ，或者 A 记录，这可能会或者可能不会和你的网络主机提供者相同。

  警告：不要在你的 DNS 提供者上为你的自定义顶点域名创建一个 CNAME 记录！这样做可能会导致与其他服务，如电子邮件，在该域的问题。

  要获取更多的自定义顶点域信息，详见“关于 GitHub 页面站点的自定义顶点域名”

  提示：你可以仅仅只为 GitHub Pages 站点配置一个自定义子域名或者一个自定义顶点域名，除非你使用一个 www 子域名。

  在你的 DNS 上配置一个 A 记录

  在你的 DNS 提供者上，创建 A 记录来解决以下的IP地址：

  • 192.30.252.153
  • 192.30.252.154

  为了确保你的 A 记录设置正确，使用 dig 命令：

  $ dig example.com +nostats +nocomments +nocmd
  ;example.com
  example.com.   73  IN  A 192.30.252.153
  example.com.   73  IN  A 192.30.252.154

  在你的 DNS 提供者上配置一个 ALIAS 或者一个 ANAME 记录

  如果你的 DNS 提供者支持 ALIAS 记录（例如是 DNSimple ）或者 ANAME 记录（例如是 DNS Made Easy ），你可以选择创建一个 ALIAS 记录或者一个 ANAME 记录来代替 username.github.io。

  注意：一些 DNS 提供者允许顶点域名配置一个 ALIAS 记录指向其他的域名。

  为了确保你的 ALIAS 或者 ANAME 记录设置正确，使用 dig 命令：

  $ dig example.com +nostats +nocomments +nocmd
  example.com.     3600    IN A     199.27.XX.XXX

  在这里显示的 IP 地址必须要和 dig username.github.io 所显示的最终的 IP 地址相匹配。

  配置一个 www 子域名

  如果你配置一个顶点域名（例如 example.com ）和一个匹配的 www 子域名（例如 www.example.com ），GitHub 服务器会自动的创建两重定向。

  例如：

  • 如果你的 CNAME 文件包含 example.com，那么 www.example.com 会定向到 example.com。

  • 如果你的 CNAME 文件包含 www.example.com，那么 example.com 会定向到 www.example.com。

  你可以使用除 www 以外的一个自定义子域名和一个自定义顶端域名一起通过域名重定向（有时也称为“域名转发”）。但是，请注意，这仅仅只用于用户和组织的页面，而非项目页面。