我们经常发布文档更新,此页面的翻译可能仍在进行中。有关最新信息,请访问英文文档。如果此页面上的翻译有问题,请告诉我们
文章版本: Enterprise Server 2.17

使用 Jekyll 在本地设置 GitHub Pages 站点

您可以设置 Jekyll GitHub Pages 站点的本地版本以在本地测试对站点的更改。 我们强烈建议安装 Jekyll 以预览您的站点并帮助对失败的 Jekyll 版本进行故障排除。

GitHub 页面 可用于具有 GitHub Free 的公共仓库,以及具有 GitHub Pro、GitHub Team、GitHub Enterprise Cloud 和 GitHub Enterprise Server 的公共和私有仓库。

本文内容:

Windows 并未正式支持 Jekyll。 更多信息请参阅官方 Jekyll 文档中的“Windows 上的 Jekyll”。

要求

我们建议使用 Bundler 安装和运行 Jekyll。 Bundler 可管理 Ruby gem 依赖项,减少 Jekyll 构建错误和阻止环境相关的漏洞。 要安装 Bundler,您必须安装 Ruby

  1. 打开终端终端Git Bash终端

  2. 检查是否已安装 Ruby 2.1.0 或更高版本:

    $ ruby --version
    > ruby 2.X.X
  3. 如果未安装 Ruby,请安装 Ruby 2.1.0 或更高版本

  4. 安装 Bundler:

    $ gem install bundler
    # 安装 Bundler gem
  5. 如果已有用于 Jekyll 站点的本地仓库,请跳至步骤 2

步骤 1:为您的 Jekyll 站点创建本地仓库

  1. 如果尚未下载 Git,请安装它。 更多信息请参阅“设置 Git”。

  2. 打开终端终端Git Bash终端

  3. 在本地计算机上,初始化用于 Jekyll 站点的新 Git 仓库:

    $ git init JEKYLL-SITE-REPOSITORY-NAME
    > Initialized empty Git repository in /Users/octocat/my-site/.git/
    # 在本地计算机上创建新文件目录,初始化为 Git 仓库
  4. 将目录更改为您创建的新仓库:

    $ cd JEKYLL-SITE-REPOSITORY-NAME
    # 更改工作目录
  5. 如果新的本地仓库用于项目页面站点,请创建新的 gh-pages 分支:

    注:如果您宁愿为项目页面使用 master 分支,可以跳过此步骤。 如果未检出任何分支,则您在本地仓库中进行提交后,您的更改默认将在 master 分支上显示。

    $ git checkout -b gh-pages
    > Switched to a new branch 'gh-pages'
    # Creates a new branch called 'gh-pages', and checks it out

    提示:要了解关于创建用户、组织或项目页面以及使用哪个分支的更多信息,请参阅“用户、组织和项目页面”。要了解关于如何从 master 分支的 /docs 文件夹构建站点源文件的更多信息,请参阅“配置 GitHub Pages 的发布来源”。

步骤 2:使用 Bundler 安装 Jekyll

为跟踪站点的依赖项,Ruby 将使用 Gemfile 的内容来构建您的 Jekyll 站点。

  1. 检查以了解您的本地 Jekyll 站点仓库中是否存在 Gemfile:

    $ ls
    > Gemfile

如果您有 Gemfile,请跳至步骤 4。 如果您没有 Gemfile,请跳至步骤 2。

  1. 如果您没有 Gemfile,打开您喜欢的文本编辑器(例如 Atom),并将以下行添加到新文件:

    source 'https://rubygems.org'
    gem 'github-pages', group: :jekyll_plugins
  2. 将该文件命名为 Gemfile 并将其保存到本地 Jekyll 站点仓库的根目录。 跳至步骤 5 以安装 Jekyll。

  3. 如果您已有 Gemfile,打开您喜欢的文本编辑器(例如 Atom),并将以下行添加到 Gemfile:

    source 'https://rubygems.org'
    gem 'github-pages', group: :jekyll_plugins
  4. 从 GitHub Enterprise Pages gem 安装 Jekyll 和其他依赖项

    $ bundle install
    > Fetching gem metadata from https://rubygems.org/............
    > Fetching version metadata from https://rubygems.org/...
    > Fetching dependency metadata from https://rubygems.org/..
    > Resolving dependencies...

    提示:如果您在尝试使用 Bundler 安装 Jekyll 时看到 Ruby 错误,您可能需要使用包管理器(例如 RVMHomebrew)来管理您的 Ruby 安装。 更多信息请参阅 Jekyll 的疑难解答页面

步骤 3(可选):生成 Jekyll 站点文件

要在本地构建您的 Jekyll 站点、预览您的站点更改和对构建错误进行故障排除,您必须在本地计算机上有 Jekyll 站点文件。 如果您克隆了 Jekyll 站点仓库,则本地计算机可能已有 Jekyll 站点文件。 如果尚未下载 Jekyll 站点,则可为本地仓库中的基本 Jekyll 模板站点生成 Jekyll 站点文件。

如果想要在 GitHub 上使用现有的 Jekyll 站点仓库作为 Jekyll 站点的起始模板,请将 GitHub 上的 Jekyll 站点仓库复刻并克隆到您的本地计算机。 更多信息请参阅“复刻仓库”。

注:从 Jekyll 3.2 开始,默认的 Jekyll 站点包含一个 Gemfile,可将 Jekyll 锁定为您构建时使用的 Gem 版本。 要将其锁定为 GitHub Pages 使用的版本,您将在下面的步骤中取消注释 gem "github-pages", group: :jekyll_plugins 行。

  1. 如果您的本地计算机上没有 Jekyll 站点,请在新目录中创建 Jekyll 模板站点:

    $ bundle exec jekyll _3.3.0_ new NEW-JEKYLL-SITE-REPOSITORY-NAME
    > New jekyll site installed in /Users/octocat/NEW-JEKYLL-SITE-REPOSITORY-NAME.
  2. 导航到新的站点目录:

    $ cd NEW-JEKYLL-SITE-REPOSITORY-NAME
  3. 编辑您的 Gemfile 并删除以下行:

    $ "jekyll", "3.3.0"
  4. 在 Gemfile 中,删除以下行开头的 #

    $ gem "github-pages", group: :jekyll_plugins
  5. 将您的站点目录初始化为 Git 仓库。

    $ git init
    > Initialized empty Git repository in /Users/octocat/name-of-your-directory
  6. 将 GitHub Enterprise 上的远程仓库连接到 GitHub 页面 站点的本地仓库。

    $ git remote add origin https://github.com/username-or-organization-name/your-remote-repository-name
  7. 要编辑 Jekyll 模板站点,请在文本编辑器中打开新的 Jekyll 站点文件。 进行更改,然后在文本编辑器中进行保存。 您可以在计算机上本地预览这些更改,而无需使用 Git 通过运行 Jekyll 命令构建站点来提交您的更改。

  8. 添加或暂存您的更改。

    $ git add .
  9. 提交您的更改及注释。

    $ git commit -m "updated site"
  10. 要在 GitHub 页面 站点上发布您的更改,推送更改到 GitHub Enterprise 上的远程仓库。

    $ git push -u origin master

有关使用此 Git 工作流的更多详细,请参阅“学习 Git 和 GitHub Enterprise 的良好资源”或查看此 Git 备忘清单

步骤 4:构建本地 Jekyll 站点

  1. 导航到本地 Jekyll 站点仓库的根目录

  2. 在本地运行您的 Jekyll 站点:

    $ bundle exec jekyll serve
    > Configuration file: /Users/octocat/my-site/_config.yml
    >            Source: /Users/octocat/my-site
    >       Destination: /Users/octocat/my-site/_site
    > Incremental build: disabled. Enable with --incremental
    >      Generating...
    >                    done in 0.309 seconds.
    > Auto-regeneration: enabled for '/Users/octocat/my-site'
    > Configuration file: /Users/octocat/my-site/_config.yml
    >    Server address: http://127.0.0.1:4000/
    >  Server running... press ctrl-c to stop.
  3. 在您的 Web 浏览器中预览本地 Jekyll 站点,网址为:http://localhost:4000

使用 GitHub Pages gem 保持您的站点最新

Jekyll 是一个活跃的开源项目,会经常更新。 随着 GitHub Enterprise Pages 服务器的更新,您计算机上的软件可能会过时,导致站点在本地显示为与 您的 GitHub Enterprise Server 实例 上发布时不同的外观。

  1. 打开终端终端Git Bash终端

  2. 运行此更新命令:

    • 如果您遵循了我们的安装建议并且已安装 Bundler,则运行 bundle update github-pages 或仅运行 bundle update,您的所有 gem 都将更新为最新版本。
    • 如果未安装 Bundler,则运行 gem update github-pages

后续步骤:配置 Jekyll

要进一步配置页面站点,请参阅“配置 Jekyll”。要设置项目页面站点,请参阅有关项目页面 URL 的 Jekyll 官方文档

进一步阅读

问问别人

找不到要找的内容?

联系我们