pages-gem 发布版本: v182

GitHub页面Ruby Gem

一个简单的Ruby Gem引导依赖关系,用于设置和维护与GitHub Pages同步的本地Jekyll环境。

Gem Version Build Status

用法

可以选择传统的使用pages-gem或容器化方法的方法,其中使用Docker容器来提供预安装了大多数依赖项的环境。

常规

*重要提示:在执行下一步骤之前,请确保您已在终端中运行“gem update bundler”,以确保您拥有Bundler> v1.14。​​

1.将以下内容添加到项目的Gemfile中:

gem 'github-pages', group: :jekyll_plugins

2.运行bundle install

注意:您不需要单独安装Jekyll。一旦安装了github-pages gem,您可以使用jekyll build来构建您的网站,或者使用jekyll serve预览您的网站。有关在本地安装Jekyll的更多信息,请参阅GitHub帮助文档事项

搬运工人

如果安装了Docker,可以通过简单地产生Docker容器来避免在环境中设置其他工具。

1.从pages-gem目录的根目录下运行make image来建立一个图像,标记为gh-pages 2.运行以下任一操作启动服务器实例: *GITE-PATH_TO_YOUR_PROJECT make服务器从gh-pages存储库的根目录(Makefile所在的位置)或者

  • SITE = PATH_TO_YOUR_PROJECT docker run --rm -p 4000:4000 -vrealpath $ {SITE}:/ src / site gh-pages` from any directory *当[func.sh](contrib / func.sh)已经源于您的终端会话时,任何目录下的github-pages $ PATH_TO_YOUR_PROJECT或 *当[func.sh](contrib / func.sh)已被输入到终端会话中时,将从Jekyll站点的目录中github-pages`进行预览。

注意:github-pages功能可以通过获取func.sh来启用。这可以通过追加来完成

  source $PATH_TO_THIS_DIRECTORY/contrib/func.sh

到启动终端会话时加载的脚本(通常在bash上是〜/ .bashrc或在zsh上是〜/ .zshrc):

未定义 在Jekyll站点的目录中运行github-pages会产生4000端口上的服务器。通过运行github-pages $ PATH $ PORT,你可以明确地提供一条到Jekyll站点和一个端口的路径。这种方法是作为步骤2中第一个选项提到的“make server”或“docker run”调用的用户友好选择提供的。

github-pages函数参数的排序是基于这样的假设:它更可能需要指定自定义路径而不是自定义端口。

命令行用法

GitHub Pages gem还附带有几个命令行工具,包含在github-pages命令中。

列出依赖版本

$ bundle exec github-pages versions
+---------------------------+---------+
| Gem                       | Version |
+---------------------------+---------+
| jekyll                    | x.x.x   |
| kramdown                  | x.x.x   |
| liquid                    | x.x.x   |
| ....                      | ....    |
+---------------------------+---------+

请注意,您还可以传递--gemfile标志以获取以有效的Gemfile依赖性格式列出的依赖项。您还可以在pages.github.com/versions上看到活动依赖项版本的列表。

健康检查

检查您的GitHub页面网站的常见DNS配置问题。

$ github-pages health-check
Checking domain foo.invalid...
Uh oh. Looks like something's fishy: A record points to deprecated IP address

有关更多信息,请参阅GitHub页面运行状况检查文档。

绕过插件白名单

如果您想在本地运行未在GitHub页面上使用的Jekyll插件,您可以通过在jeppyll buildjekyll serve命令前添加'DISABLE_WHITELIST = true来实现。这将允许您的网站使用您网站的gems`配置标志中列出的任何插件。但请注意,只有在本地预览您的Jekyll网站时才能使用此选项。

更新

要更新到最新版本的Jekyll和相关的依赖项,只需运行gem update github-pages,或者如果你已经通过Bundler安装了bundle update github-pages

项目目标

GitHub Pages gem的目标是帮助GitHub Pages用户引导并维护与GitHub页面构建环境最匹配的Jekyll构建环境。 GitHub Pages gem依赖于用户计算机和构建服务器之间共享的显式需求,以确保用户本地构建的结果始终也是服务器构建的结果。

其他工具,如与GitHub API集成以使GitHub Pages站点更容易管理的工具不是主要目标,但可能在项目范围内。

什么是版本

GitHub Pages gem寻求版本环境的两个版本:

红宝石

与Jekyll一起执行的Ruby版本。虽然Jekyll本身可能与以前或未来版本的Ruby兼容,但不同的执行环境会产生不同的结果。例如,Ruby 1.8.7解析YAML的方式不同于1.9.3,而Kramdown在处理1.9.3之前的mailto链接时遇到了问题。为了确保本地构建的结果始终与发布时的结构相同,尽管没有已知的不兼容性,但Ruby本身与Gem一起版本化是非常重要的。

2.依赖性

这包括Markdown处理器以及任何其他版本不一致的Jekyll依赖项,这些依赖项可能会产生意想不到的结果。传统上,由于已知的突变,Maruku,Kramdown,RedCloth,liquid,rdiscount和redcarpet已被严格维护。

更新日志

查看所有版本

释放

要发布此gem的新版本,请运行master分支中的script / release

执照

根据MIT许可证分发。