In addition to supporting regular HTML content, GitHub Pages support Jekyll, a simple, blog-aware static site generator. Jekyll makes it easy to create site-wide headers and footers without having to copy them across every page. It also offers some other advanced templating features.

為了支持HTML內(nèi)容何恶，GitHub Pages支持了Jekyll框架，Jekyll是一個(gè)簡(jiǎn)單的博客類靜態(tài)網(wǎng)站生成器敌买。Jekyll能夠簡(jiǎn)單地在各個(gè)頁面中使用全局的headers和footers锅铅。同時(shí)Jekyll也能提供一些其他的模版特性特笋。

Using Jekyll——使用Jekyll

Every GitHub Page is run through Jekyll when you push content to a specially named branch within your repository. For User Pages, use the master branch in your username.github.io repository. For Project Pages, use the gh-pages branch in your project's repository. Because a normal HTML site is also a valid Jekyll site, you don't have to do anything special to keep your standard HTML files unchanged. Jekyll has thorough documentation that covers its features and usage. Simply start committing Jekyll formatted files and you'll be using Jekyll in no time.

當(dāng)你向一個(gè)特殊命名的遠(yuǎn)程倉庫推送內(nèi)容后穴肘，GitHub Page就能夠通過Jekyll來運(yùn)行。對(duì)于用戶頁面道宅，可以在名為username.github.io的倉庫中設(shè)置master分支嗓袱。對(duì)于項(xiàng)目頁面籍救，在項(xiàng)目倉庫中設(shè)置gh-pages分支。因?yàn)橐粋€(gè)普通的HTML網(wǎng)頁也是一個(gè)Jekyll框架網(wǎng)頁索抓，所以你無需對(duì)你的標(biāo)準(zhǔn)HTML文件做任何改動(dòng)钧忽。Jekyll有專門描述其特性和使用方法的文檔。你可以輕輕松松使用Jekyll框架來實(shí)現(xiàn)你的網(wǎng)站逼肯。

Installing Jekyll——安裝Jekyll

We highly recommend installing Jekyll on your computer to preview your site and help diagnose troubled builds before publishing your site on GitHub Pages.

Luckily, installing Jekyll on your computer, and ensuring your computer most closely matches the GitHub Pages settings is easy, thanks to the GitHub Pages Gem and our dependency versions page. To install Jekyll, you'll need a few things:

我們強(qiáng)烈推薦你在你的電腦上安裝Jekyll來預(yù)覽你的網(wǎng)站耸黑，同時(shí)這也能幫助你在GitHub Pages上發(fā)布網(wǎng)站之前，診斷因?yàn)椴渴鹗《l(fā)的錯(cuò)誤篮幢。非常幸運(yùn)地大刊，在電腦上安裝Jekyll和相關(guān)設(shè)置非常的簡(jiǎn)單易懂。安裝Jekyll的步驟如下：

• Ruby - Jekyll requires the Ruby language. If you have a Mac, you've most likely already got Ruby. If you open up the Terminal application, and run the command ruby --version you can confirm this. Your Ruby version should begin with 1.9.3 or 2.0.0. If you've got that, you're all set. Skip to step #2. Otherwise, follow these instructions to install Ruby.

• Bundler - Bundler is a package manager that makes versioning Ruby software like Jekyll a lot easier if you're going to be building GitHub Pages sites locally. If you don't already have Bundler installed, you can install it by running the command gem install bundler.

• Jekyll - The main event. You'll want to create a file in your site's repository called Gemfile and add the line gem 'github-pages'. After that, simply run the command, bundle install and you're good to go. If you decided to skip step #2, you can still install Jekyll with the command gem install github-pages, but you may run into trouble down the line. Here’s an example of a Gemfile you can use (placed in the root directory of your repository):

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

• Ruby: Jekyll要求電腦上已經(jīng)安裝了Ruby語言三椿。如果你使用的是Mac缺菌，那么你的電腦中已經(jīng)預(yù)裝了Ruby。你可以打開終端輸入ruby --version來查看Ruby的版本信息搜锰。Ruby的版本號(hào)必須介于1.9.3到2.0.0之間伴郁。如果你已經(jīng)確認(rèn)這些信息都是正確的，那么第一步就已經(jīng)完成了蛋叼，接下來可以執(zhí)行第二步焊傅。否則，按要求安裝Ruby狈涮。

• Bundler: Bundler是一個(gè)Ruby應(yīng)用的包管理軟件狐胎。如果你沒有安裝Bundler，請(qǐng)?jiān)诿钚兄休斎?code>gem install bundler歌馍。

• Jekyll: 在你的網(wǎng)站倉庫的根目錄下創(chuàng)建一個(gè)名為Gemfile的文件握巢，在文件中寫下gem 'github-pages'。然后松却，在命令行中輸入bundle install就會(huì)安裝Jekyll和所有相關(guān)的依賴包暴浦。如果你跳過了第二步溅话，你仍能夠安裝Jekyll，在命令行中輸入gem install github-pages肉渴，但你可能會(huì)遇到一些問題公荧，此時(shí)你要修改Gemfile文件。如下：

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

Running Jekyll——運(yùn)行Jekyll

To run Jekyll in a way that matches the GitHub Pages build server, run Jekyll with Bundler. Use the command bundle exec jekyll serve in the root of your repository (after switching to the gh-pages branch for project repositories), and your site should be available athttp://localhost:4000. For a full list of Jekyll commands, see the Jekyll documentation.

為了模擬GitHub Pages使用Jekyll部署服務(wù)器的過程同规，我們使用Bundler運(yùn)行Jekyll。具體操作：在網(wǎng)頁倉庫根目錄下命令行輸入bundle exec jekyll serve（如果是項(xiàng)目倉庫窟社，需要切換到gh-pages分支）券勺。然后你就可以在瀏覽器中訪問http://localhost:4000來看到你在本地生成的網(wǎng)頁。所有的Jekyll命令請(qǐng)見Jekyll文檔灿里。

Keeping Jekyll up to date——更新Jekyll

Jekyll is an active open source project, and is updated frequently. As the GitHub Pages server is updated, the software on your computer may become out of date, resulting in your site appearing different locally from how it looks when published on GitHub. To keep Jekyll up to date, you can run the command bundle update (or if you opted out of step 2, run gem update github-pages).

Jekyll是一個(gè)非彻亓叮活躍的開源項(xiàng)目，它更新得非常頻繁匣吊。當(dāng)GitHub Pages服務(wù)器更新后儒拂，你電腦上的Jekyll可能就過時(shí)了，這會(huì)導(dǎo)致你的網(wǎng)站在GitHub上顯示的模樣和在本地模擬的模樣不同色鸳。所以社痛，請(qǐng)保證你的Jekyll是最新版本，你可以在命令行中輸入bundle update來更新Jekyll（如果你跳過了安裝的第二步命雀，請(qǐng)輸入gem update github-pages）蒜哀。

Configuring Jekyll——配置Jekyll

You can configure most Jekyll settings by creating a _config.yml file.

你可以通過創(chuàng)建和修改_config.yml文件來完成大部分的Jekyll設(shè)置。

Defaults——默認(rèn)設(shè)置

The following defaults are set by GitHub, which you are free to override in your _config.yml file:

下面_config.yml文件中的默認(rèn)設(shè)置是來自GitHub的吏砂，你可以自由地修改撵儿。

highlighter: pygments
github: [Repository metadata]

For the content of the repository metadata object, see repository metadata on GitHub Pages.

倉庫內(nèi)的元數(shù)據(jù)內(nèi)容請(qǐng)見repository metadata on GitHub Pages。

Configuration Overrides

We override the following _config.yml values, which you are unable to configure:

我們可以修改_config.yml文件中的值（一般不需要修改）：

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

Keep in mind that if you change the source setting, your pages may not build correctly. GitHub Pages only considers source files in the top-level directory of a repository.

如果你更改了source設(shè)置狐血，你的頁面可能會(huì)部署失敗淀歇。GitHub Pages只會(huì)考慮倉庫中頂級(jí)目錄下的source文件。

Frontmatter is required——格式

Jekyll requires that Markdown files have front-matter defined at the top of every file. Front-matter is just a set of metadata, delineated by three dashes:

Jekyll要求每一個(gè)Markdown文件在頭部進(jìn)行定義匈织，主要是設(shè)置元數(shù)據(jù)浪默。通過---與正文分隔。

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

Here is my page.

If you like, you can choose to omit front-matter from your file, but you'll still need to make the triple-dashes:

你可以省略你的頭部定義报亩，但你仍需要---來分隔浴鸿。

---
---

Here is my page.

If your file is within the _posts directory, you can omit the dashes entirely.

For more information, check out the Jekyll docs.

如果你的文件在_posts目錄下，你能夠省略---弦追。更多的信息請(qǐng)見Jekyll文檔岳链。

Troubleshooting——解決問題

If your Jekyll site is not rendering properly after you push it to GitHub, it's useful to run Jekyll locally so you can see any parsing errors. In order to do this, you'll want to use the same versions of Jekyll and other dependencies that we use.

如果你推送commit到GitHub后，你的Jekyll網(wǎng)站沒有正常顯示劲件，那么你可以在本地運(yùn)行Jekyll來找到錯(cuò)誤的原因掸哑。但前提是约急，你必須使用與GitHub Pages相同的Jekyll和依賴包版本。

To ensure your local development environment is using the same version of Jekyll and its dependencies as GitHub Pages, you can periodically run the command gem update github-pages (or bundle update github-pages if using Bundler) once Jekyll is installed. For more information, see the GitHub Pages Gem repository.

為保證你的本地開發(fā)環(huán)境所使用的Jekyll和依賴包與GitHub Pages相同苗分，你可以定期地在命令行中輸入gem update github-pages（如果安裝了Bundler厌蔽，輸入bundle update github-pages）。更多信息詳見GitHub Pages Gem repository摔癣。

If your page isn't building after you push to GitHub, see "Troubleshooting GitHub Pages build failures".

如果你的網(wǎng)頁不能正常顯示奴饮。請(qǐng)見"Troubleshooting GitHub Pages build failures"。

If you are having issues with your Jekyll Pages, make sure you are not using categories that are named the same as another project, as this could cause path conflicts. For example: if you have a blog post named 'resume' in your User Page repository and a project named 'resume' with a gh-pages branch, they will conflict with each other.

如果你的Jekyll頁面有問題择浊，請(qǐng)確保沒有重名的情況發(fā)生戴卜，否則會(huì)造成路徑?jīng)_突。例如：在你的個(gè)人用戶網(wǎng)站倉庫中有一篇名為‘resume’的博文琢岩，同時(shí)恰好又有一個(gè)名為‘resume’的項(xiàng)目下有gh-pages分支投剥。

Turning Jekyll off——關(guān)閉Jekyll

You can completely opt out of Jekyll processing by creating a file named .nojekyll in the root of your Page repository and pushing that file to GitHub. This should only be necessary if your site uses directories that begin with an underscore, as Jekyll sees these as special directories and does not copy them to the final destination.

如果你不想使用這個(gè)Jekyll頁面，你可以在你的個(gè)人用戶頁面?zhèn)}庫的根目錄下創(chuàng)建一個(gè)名為.nojekyll的文件担孔，同時(shí)將這個(gè)改動(dòng)推送到遠(yuǎn)程倉庫江锨。那么就可以隱藏這個(gè)網(wǎng)站了。

Contributing——貢獻(xiàn)

If there's a feature you wish that Jekyll had, feel free to fork it and send a pull request. We're happy to accept user contributions.

如果你希望Jekyll有一些其他特性糕篇，請(qǐng)fork后pull request你的改動(dòng)啄育。我們很高興能接受用戶的貢獻(xiàn)。