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 之外的一個自定義子域名和一個自定義頂端域名一塊兒經過域名重定向（有時也稱爲「域名轉發」）。可是，請注意，這僅僅只用於用戶和組織的頁面，而非項目頁面。