如何将 github.io 站点的主题用于 Github 项目页面站点
How to use theme from github.io site for Github Project Pages sites
我断断续续地为 my website 工作了几年，学到了很多关于 JavaScript、CSS、HTML、[=25= 的知识]、Jekyll、Travis-CI 和 Github 页面。 （长列表是导致它花费这么长时间的一个主要因素。）
我发现如果我推送（或让 Travis 部署到）存储库的 gh-pages 分支，它实际上会成为我网站的子域。示例：here, here, here.
这非常棒，但这些子页面最终感觉它们不是同一网站的一部分，因为它们无法返回主页。我希望他们包括我的导航栏。
有没有优雅的方法来做到这一点？
我还没有实现这个，所以我会做更多，但我想我已经找到了规范的解决方案并想为自己记录下来。
所有 Github 页面站点都有一个主题。您可以：
- 转到设置 -> 选项 -> 向下滚动到 Github 页面和 select a theme from the theme chooser。这是 lame，因为只有几个默认选项，您无法自己自定义主题以反映您站点的特性。现成的主题也不允许您使用其他站点的导航栏。
- 或者您可以将
_config.yml 文件添加到您的项目中，github 将在生成您的 Github 页面站点时尝试阅读并遵循该文件。您可以在其中指定 theme，几个白名单选项（有限列表）之一，或 remote_theme，它可以由任何人创建。这很棒，因为您可以指定自己的主题。
这意味着在 User Pages Site and all my Project Pages Sites 中拥有一致的导航栏和主题以及所有内容的方法是将我的主题从用户页面站点梳理到它自己的 repo 中，然后从配置中的所有其他站点引用它文件。
听起来很繁琐，但确实有助于提高可重用性。
我可能还需要在每个项目的顶层指定 index.md，以取代自述文件作为主页，并确保包含 <head> 内容和导航栏等内容。
昨天我终于完成了. The result lives here now. This was not an easy process, despite the documentation trying to be helpful，因为Jekyll和GitHub页面的交集是一个非常复杂的不透明框，而ruby对我来说很陌生。但最终归结为几个重要步骤和问题：
您将需要 ruby 和几个软件包。 sudo apt install ruby 应该给你 ruby （解释器）和 gem （包管理器）。
- 陷阱 1a：基础知识无法解释，请允许我：Ruby 代码来自名为 gems 的包，这与 python 包非常相似。它们由
gem 或 bundler 而不是 pip 管理，托管在 rubygems.org 而不是 pypi。就像Python世界里人人歌颂conda一样，Ruby世界里人人歌颂bundler，这本身就是一个gem ，您必须 gem install 的一个，因为它不像 gem 本身那样与 ruby 一起打包。我发现捆绑器有问题；当我尝试 bundle install github-pages 时它挂了（稍后会详细介绍 github-pages）。此外，bundler 依赖于更多名为 Gemfiles 的配置文件，它们类似于 requirements.txt 文件 pip can 但 [= =112=]需要 摄取。老实说，对于一个没有复杂依赖树的小项目，谁想要更多的混乱？谁想要 bundle exec jekyll serve 而不仅仅是 jekyll serve？你在跟我开玩笑吗？只需使用 gem 来安装东西，并跳过 Gemfile。很像 pip，我觉得越简单越好。
- 陷阱 1b：如果您
sudo apt install jekyll，您得到的是旧版本，例如 3.1 或其他版本。但是 Jekyll 是一个 gem;您可以而且应该使用包管理器进行安装。 （但实际上不要这样做，因为它是 github-pages gem 的一部分，并且版本不一致。稍后会详细介绍。）
- 问题 1c：哦，那是什么？你想
gem install jekyll（甚至gem install bundler）？是的，抱歉，我不能那样做，因为缺少一些东西，这里有一份关于它的长打印输出。 ...Google, Google... sudo apt install ruby-dev。哦，对不起，我仍然无法构建。这里有一些 other 错误。 ...Google, Google... sudo apt install g++。好的现在 可以了。这个过程对您来说可能略有不同；要点是设置一个 ruby 环境可以是冒险的。
- 问题 1d：哦，那是什么？现在您希望能够从命令行调用
jekyll，就像您刚刚使用 apt 安装它一样？好吧，抱歉，我是 gem，有时我不会把 jekyll 放在你的路径上。如果您遇到这种情况，请注意 gem 保存 gem 的位置，找到其中的可执行文件，然后使用 sudo ln -s /path/to/jekyll /usr/bin/jekyll 创建符号链接
将 assets、_includes、_layouts 和 _sass 从站点移动到新的存储库。完毕。砰。你现在有一个远程主题。真的应该那么简单，但是...
- 陷阱 2a：没有人告诉您这是最低限度的可行产品，因此您必须首先了解什么是远程主题及其工作原理。根据佳能，它们是成熟的 gems。当你引用一个时，Jekyll 需要去获取它才能生成你的站点。 The Jekyll documentation 就是指导您如何真正将主题打包为 gem 并将其推到
rubygems.org，这需要：(1) rubygems account, (2) 你的主题包含一个深奥的.gemspec文件，里面的内容没有很好的解释。继续阅读为什么这无关紧要。
- 陷阱 2b：您必须了解 GitHub Pages 实际上是如何使用远程主题的。关于这个话题，GitHub 很乐意告诉您如何将
remote_theme: user/theme-name 添加到利用站点的 _config.yml（Jekyll 配置）中，但他们忽略了提前告诉您他们是否正在引入 gem 来自某处或什么。事实证明，他们正在使用另一个名为 jekyll-remote-theme 的 gem 直接从存储库中提取原始文件，进行编译和上传 gem 并获得 .gemspec没有人理解或不想看不必要的东西。 （万岁。）benbalter 的远程主题文档 gem 本身是我唯一能找到此信息的地方。
- 陷阱 2c：请注意，因为主题中有 Pages is still on Jekyll 3.8.6, you don't have certain functionality on GitHub Pages that you might want, like being able to define site data in the theme's
_config.yml. As a result, my front-matter-prepended .css containing a few Liquid tags that worked just fine as part of my unseparated site ended up with emptystring tag substitutions in the generated site. I ended up 。
- 陷阱 2d：任何其他文件夹和文件——不在
assets、_includes、_layouts 和 _sass 之间——（我有一个名为 theme 包含像我的网站图标这样的东西。）不要折叠到主题 gem 或通过 GitHub 使用的 jekyll-remote-theme 机制传输。通过仔细修改 .gemspec，您可以将这些文件包含在 gem 中，但是这种方法对 jekyll-remote-theme 的行为没有影响，所以我最终基本上将所有内容都放在 [=44] 中=].
- 投诉2e：Ruby Sass is apparently deprecated now?为什么Jekyll一直在使用它这么久？我还没有遇到一个看起来有用的例子。
将包含 remote_theme: yourname/yourtheme 的 _config.yml 放入每个要在主题中呈现项目页面的存储库的 gh-pages 分支的根目录中。没有 Gemfile，没有废话。只需等待它部署。
- 陷阱 3a：Jekyll 会专门 查找
_layouts 中的 page.html 文件以呈现 readme 内容。如果你有一个 page.html，那么你可以使用 Liquid 标签将你的头部、导航栏和其他 _includes 内容添加到其中，没问题。如果你碰巧忘记了这个文件或者认为 Jekyll 可以使用 post.html 来代替，那么你就错了，主题没有应用。不确定 default.html 是否可以作为故障转移。无论如何，使用 Jekyll 的 GitHub 页面是 super 脆弱的，老实说，我很幸运能够发现这一点而没有被它阻止，因为 (1) 我还没有看过任何 GitHub 文档来准确描述调用哪些命令来生成项目页面，(2) 您看不到远程编译过程的终端输出**，以及 (3)，因为您看不到知道 GitHub 在做什么，没有办法在本地复制它来查看警告或错误打印输出——也就是说 if Jekyll 甚至会警告你。
**如果真的有办法在某个地方查看这个，请告诉我。 GitHub says："When you push changes to your publishing source on GitHub, GitHub Pages will attempt to build your site. If the build fails, you'll receive an email at your primary email address. You'll also receive emails for build warnings. You can see build failures (but not build warnings) for your site on GitHub in the Settings tab of your site's repository." 我确实收到了一封电子邮件，说明 "The tag include_cached on line 15 in /_layouts/default.html is not a recognized Liquid tag."，但我不记得这是针对哪个版本的，而且我在回购设置中的任何地方都找不到记录的失败。
- 陷阱 3b：如果您更新主题，使用该主题的页面站点不会重建以反映主题更改。您必须手动重新推送到构建站点的分支以触发站点重建。这对于我与 Travis-CI 集成的 repos 来说非常容易，因为我可以沿着列表重新运行最近的构建，最终推送到
gh-pages 分支，这反过来会导致 Pages服务器重建。但是对于其他站点，我必须进行一些合法的更改或推送一个空提交。
将 plugins: - jekyll-remote-theme 和 remote_theme: yourname/yourtheme 添加到您的用户页面站点中的 _config.yml。
- 陷阱 4a：本地执行令人困惑。 benbalter's readme 非常好，但使用部分仍然假定您使用的是
bundler。如果不是，那么 gem install github-pages 就像安装任何其他 gem 一样。这个 gem 确实是一个巨大的其他 gem 页面服务器列表 运行 生成您的静态站点，包括相同版本的 jekyll 和 jekyll-remote-theme。您将需要这些，以便您可以在本地捕获所有微妙的版本或显示错误，并且不会在云中出现意外。最后，尽管实际部署似乎没有必要，但对于本地执行，您必须确保将 jekyll-remote-theme 作为插件列在您的利用站点的 _config.yml 中。否则 jekyll serve 错误。
- 陷阱 4b：使用远程主题的本地执行被破坏--或 at least it is for Jekyll 4.0.0。它适用于 GitHub Pages 服务器使用的 Jekyll 3，这就是它部署良好的原因。如果您使用
gem install jekyll 而不是 github-pages 列表获取 Jekyll，您可能会像我一样遇到错误。
所以事后看来这基本上并不难，但到达那里是一个令人沮丧的惨败，盲目飞行只有过于冗长、令人失望的不完整地图来指导你。我希望 GitHub 能向您展示在某些终端中站点编译和部署的整个过程，就像 Travis-CI 对构建所做的那样。我希望 Jekyll 没有那么复杂。有太多的功能，太多的东西默默地失败了。
我希望这项研究可以帮助其他人。
我断断续续地为 my website 工作了几年，学到了很多关于 JavaScript、CSS、HTML、[=25= 的知识]、Jekyll、Travis-CI 和 Github 页面。 （长列表是导致它花费这么长时间的一个主要因素。）
我发现如果我推送（或让 Travis 部署到）存储库的 gh-pages 分支，它实际上会成为我网站的子域。示例：here, here, here.
这非常棒，但这些子页面最终感觉它们不是同一网站的一部分，因为它们无法返回主页。我希望他们包括我的导航栏。
有没有优雅的方法来做到这一点？
我还没有实现这个，所以我会做更多，但我想我已经找到了规范的解决方案并想为自己记录下来。
所有 Github 页面站点都有一个主题。您可以：
- 转到设置 -> 选项 -> 向下滚动到 Github 页面和 select a theme from the theme chooser。这是 lame，因为只有几个默认选项，您无法自己自定义主题以反映您站点的特性。现成的主题也不允许您使用其他站点的导航栏。
- 或者您可以将
_config.yml文件添加到您的项目中，github 将在生成您的 Github 页面站点时尝试阅读并遵循该文件。您可以在其中指定theme，几个白名单选项（有限列表）之一，或remote_theme，它可以由任何人创建。这很棒，因为您可以指定自己的主题。
这意味着在 User Pages Site and all my Project Pages Sites 中拥有一致的导航栏和主题以及所有内容的方法是将我的主题从用户页面站点梳理到它自己的 repo 中，然后从配置中的所有其他站点引用它文件。
听起来很繁琐，但确实有助于提高可重用性。
我可能还需要在每个项目的顶层指定 index.md，以取代自述文件作为主页，并确保包含 <head> 内容和导航栏等内容。
昨天我终于完成了
您将需要 ruby 和几个软件包。
sudo apt install ruby应该给你ruby（解释器）和gem（包管理器）。- 陷阱 1a：基础知识无法解释，请允许我：Ruby 代码来自名为 gems 的包，这与 python 包非常相似。它们由
gem或bundler而不是pip管理，托管在rubygems.org而不是pypi。就像Python世界里人人歌颂conda一样，Ruby世界里人人歌颂bundler，这本身就是一个gem ，您必须gem install的一个，因为它不像gem本身那样与 ruby 一起打包。我发现捆绑器有问题；当我尝试bundle install github-pages时它挂了（稍后会详细介绍github-pages）。此外，bundler 依赖于更多名为Gemfiles 的配置文件，它们类似于requirements.txt文件pipcan 但 [= =112=]需要 摄取。老实说，对于一个没有复杂依赖树的小项目，谁想要更多的混乱？谁想要bundle exec jekyll serve而不仅仅是jekyll serve？你在跟我开玩笑吗？只需使用gem来安装东西，并跳过Gemfile。很像pip，我觉得越简单越好。 - 陷阱 1b：如果您
sudo apt install jekyll，您得到的是旧版本，例如 3.1 或其他版本。但是 Jekyll 是一个 gem;您可以而且应该使用包管理器进行安装。 （但实际上不要这样做，因为它是github-pagesgem 的一部分，并且版本不一致。稍后会详细介绍。） - 问题 1c：哦，那是什么？你想
gem install jekyll（甚至gem install bundler）？是的，抱歉，我不能那样做，因为缺少一些东西，这里有一份关于它的长打印输出。 ...Google, Google...sudo apt install ruby-dev。哦，对不起，我仍然无法构建。这里有一些 other 错误。 ...Google, Google...sudo apt install g++。好的现在 可以了。这个过程对您来说可能略有不同；要点是设置一个 ruby 环境可以是冒险的。 - 问题 1d：哦，那是什么？现在您希望能够从命令行调用
jekyll，就像您刚刚使用apt安装它一样？好吧，抱歉，我是gem，有时我不会把jekyll放在你的路径上。如果您遇到这种情况，请注意gem保存 gem 的位置，找到其中的可执行文件，然后使用sudo ln -s /path/to/jekyll /usr/bin/jekyll 创建符号链接
- 陷阱 1a：基础知识无法解释，请允许我：Ruby 代码来自名为 gems 的包，这与 python 包非常相似。它们由
将
assets、_includes、_layouts和_sass从站点移动到新的存储库。完毕。砰。你现在有一个远程主题。真的应该那么简单，但是...- 陷阱 2a：没有人告诉您这是最低限度的可行产品，因此您必须首先了解什么是远程主题及其工作原理。根据佳能，它们是成熟的 gems。当你引用一个时，Jekyll 需要去获取它才能生成你的站点。 The Jekyll documentation 就是指导您如何真正将主题打包为 gem 并将其推到
rubygems.org，这需要：(1) rubygems account, (2) 你的主题包含一个深奥的.gemspec文件，里面的内容没有很好的解释。继续阅读为什么这无关紧要。 - 陷阱 2b：您必须了解 GitHub Pages 实际上是如何使用远程主题的。关于这个话题，GitHub 很乐意告诉您如何将
remote_theme: user/theme-name添加到利用站点的_config.yml（Jekyll 配置）中，但他们忽略了提前告诉您他们是否正在引入 gem 来自某处或什么。事实证明，他们正在使用另一个名为jekyll-remote-theme的 gem 直接从存储库中提取原始文件，进行编译和上传 gem 并获得.gemspec没有人理解或不想看不必要的东西。 （万岁。）benbalter 的远程主题文档 gem 本身是我唯一能找到此信息的地方。 - 陷阱 2c：请注意，因为主题中有 Pages is still on Jekyll 3.8.6, you don't have certain functionality on GitHub Pages that you might want, like being able to define site data in the theme's
_config.yml. As a result, my front-matter-prepended.csscontaining a few Liquid tags that worked just fine as part of my unseparated site ended up with emptystring tag substitutions in the generated site. I ended up - 陷阱 2d：任何其他文件夹和文件——不在
assets、_includes、_layouts和_sass之间——（我有一个名为theme包含像我的网站图标这样的东西。）不要折叠到主题 gem 或通过 GitHub 使用的jekyll-remote-theme机制传输。通过仔细修改.gemspec，您可以将这些文件包含在 gem 中，但是这种方法对jekyll-remote-theme的行为没有影响，所以我最终基本上将所有内容都放在 [=44] 中=]. - 投诉2e：Ruby Sass is apparently deprecated now?为什么Jekyll一直在使用它这么久？我还没有遇到一个看起来有用的例子。
- 陷阱 2a：没有人告诉您这是最低限度的可行产品，因此您必须首先了解什么是远程主题及其工作原理。根据佳能，它们是成熟的 gems。当你引用一个时，Jekyll 需要去获取它才能生成你的站点。 The Jekyll documentation 就是指导您如何真正将主题打包为 gem 并将其推到
将包含
remote_theme: yourname/yourtheme的_config.yml放入每个要在主题中呈现项目页面的存储库的gh-pages分支的根目录中。没有 Gemfile，没有废话。只需等待它部署。- 陷阱 3a：Jekyll 会专门 查找
_layouts中的page.html文件以呈现readme内容。如果你有一个page.html，那么你可以使用 Liquid 标签将你的头部、导航栏和其他_includes内容添加到其中，没问题。如果你碰巧忘记了这个文件或者认为 Jekyll 可以使用post.html来代替，那么你就错了，主题没有应用。不确定default.html是否可以作为故障转移。无论如何，使用 Jekyll 的 GitHub 页面是 super 脆弱的，老实说，我很幸运能够发现这一点而没有被它阻止，因为 (1) 我还没有看过任何 GitHub 文档来准确描述调用哪些命令来生成项目页面，(2) 您看不到远程编译过程的终端输出**，以及 (3)，因为您看不到知道 GitHub 在做什么，没有办法在本地复制它来查看警告或错误打印输出——也就是说 if Jekyll 甚至会警告你。
**如果真的有办法在某个地方查看这个，请告诉我。 GitHub says："When you push changes to your publishing source on GitHub, GitHub Pages will attempt to build your site. If the build fails, you'll receive an email at your primary email address. You'll also receive emails for build warnings. You can see build failures (but not build warnings) for your site on GitHub in the Settings tab of your site's repository." 我确实收到了一封电子邮件，说明 "The taginclude_cachedon line 15 in/_layouts/default.htmlis not a recognized Liquid tag."，但我不记得这是针对哪个版本的，而且我在回购设置中的任何地方都找不到记录的失败。 - 陷阱 3b：如果您更新主题，使用该主题的页面站点不会重建以反映主题更改。您必须手动重新推送到构建站点的分支以触发站点重建。这对于我与 Travis-CI 集成的 repos 来说非常容易，因为我可以沿着列表重新运行最近的构建，最终推送到
gh-pages分支，这反过来会导致 Pages服务器重建。但是对于其他站点，我必须进行一些合法的更改或推送一个空提交。
- 陷阱 3a：Jekyll 会专门 查找
将
plugins: - jekyll-remote-theme和remote_theme: yourname/yourtheme添加到您的用户页面站点中的_config.yml。- 陷阱 4a：本地执行令人困惑。 benbalter's readme 非常好，但使用部分仍然假定您使用的是
bundler。如果不是，那么gem install github-pages就像安装任何其他 gem 一样。这个 gem 确实是一个巨大的其他 gem 页面服务器列表 运行 生成您的静态站点，包括相同版本的jekyll和jekyll-remote-theme。您将需要这些，以便您可以在本地捕获所有微妙的版本或显示错误，并且不会在云中出现意外。最后，尽管实际部署似乎没有必要，但对于本地执行，您必须确保将jekyll-remote-theme作为插件列在您的利用站点的_config.yml中。否则jekyll serve错误。 - 陷阱 4b：使用远程主题的本地执行被破坏--或 at least it is for Jekyll 4.0.0。它适用于 GitHub Pages 服务器使用的 Jekyll 3，这就是它部署良好的原因。如果您使用
gem install jekyll而不是github-pages列表获取 Jekyll，您可能会像我一样遇到错误。
- 陷阱 4a：本地执行令人困惑。 benbalter's readme 非常好，但使用部分仍然假定您使用的是
所以事后看来这基本上并不难，但到达那里是一个令人沮丧的惨败，盲目飞行只有过于冗长、令人失望的不完整地图来指导你。我希望 GitHub 能向您展示在某些终端中站点编译和部署的整个过程，就像 Travis-CI 对构建所做的那样。我希望 Jekyll 没有那么复杂。有太多的功能，太多的东西默默地失败了。
我希望这项研究可以帮助其他人。