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 之外的一个自定义子域名和一个自定义顶端域名一块儿经过域名重定向（有时也称为“域名转发”）。可是，请注意，这仅仅只用于用户和组织的页面，而非项目页面。