如何在Github Project Pages网站上使用github.io网站中的主题 [英] How to use theme from github.io site for Github Project Pages sites

问题描述

几年来，我一直在我的网站上工作，学到了很多有关JavaScript，CSS的知识，HTML，Bootstrap，Jekyll，Travis-CI和Github页面. (长列表是为什么要花这么长时间的主要因素.)

I've been working on my website on and off for a couple years, learned a ton about JavaScript, CSS, HTML, Bootstrap, Jekyll, Travis-CI, and Github Pages in the process. (Long list is a major factor in why it's taken so long.)

我发现，如果我推送(或让Travis部署到)回购协议的gh-pages分支，它实际上将成为我网站的子域.示例:此处，此处.

I've discovered that if I push to (or have Travis deploy to) the gh-pages branch of a repo, it actually becomes a subdomain of my website. Examples: here, here, here.

这非常棒，但是这些子页面最终感觉像它们不是同一网站的一部分，因为它们没有提供返回首页的方法.我希望他们包括我的导航栏.

This is pretty awesome, but those sub-pages end up feeling like they're not a part of the same website, because they provide no way to get back to the main page. I'd like them to include my navbar.

是否有一种优雅的方法?

Is there an elegant way to do this?

推荐答案

昨天我终于经历并做了我在9月份提出的理论. 结果现在放在这里.这不是一个容易的过程，尽管文档试图提供帮助，因为Jekyll和GitHub页面是一个非常复杂的不透明框，Ruby对我来说并不陌生.但最终归结为几个重要步骤和陷阱:

Yesterday I finally went through and did what I theorized about in September. The result lives here now. This was not an easy process, despite the documentation trying to be helpful, because the intersection of Jekyll and GitHub pages is such a massively complicated opaque box, and ruby was unfamiliar to me. But ultimately it boils down to a few important steps and gotchas:

1. 您将需要红宝石和几个包裹. sudo apt install ruby应该为您提供ruby(解释器)和gem(程序包管理器).

1. You're gonna need ruby and several packages. sudo apt install ruby should give you ruby (interpreter) and gem (package manager).

• Gotcha 1a:基础知识尚待解释，因此请允许我:Ruby代码来自称为gems的程序包，与python程序包非常相似.它们由gem或bundler而不是pip管理，并托管在rubygems.org而不是pypi上.就像在Python世界中，每个人都赞美conda一样，在Ruby世界中的每个人都赞美bundler，它本身就是一颗宝石，您必须gem install，因为它没有包装与gem本身一样的红宝石.我发现捆绑器有故障.当我尝试bundle install github-pages时它挂起(稍后在github-pages中有更多信息).此外，捆绑程序还依赖于更多名为Gemfile s的配置文件，这些配置文件是pip文件可以可以使用的requirements.txt文件的类似物，但不需要可以提取.老实说，谁愿意在一个没有复杂依赖树的小型项目中找到更多杂物?还有谁想不得不bundle exec jekyll serve而不只是jekyll serve?你在开玩笑吧?只需使用gem进行安装，然后跳过Gemfile.就像pip一样，我发现越简单越好.
• Gotcha 1b:如果您sudo apt install jekyll，您会获得旧版本，例如3.1或类似的版本.但是杰基尔是一颗宝石.您可以并且应该使用软件包管理器进行安装. (但实际上不要这样做，因为它是github-pages gem的一部分，并且版本不同意.稍后会对此进行更多介绍.)
• Gotcha 1c:哦，那是什么?您要gem install jekyll(甚至gem install bundler)吗?是的，抱歉，我不能这样做，因为缺少一些东西，这里有很长的打印输出. ... Google，Google ... sudo apt install ruby-dev.哦，对不起，我 still 无法建立.这是一些 other 错误. ... Google，Google ... sudo apt install g++.好的， now 可以正常工作.对于您来说，此过程可能会略有不同.关键是要建立一个红宝石环境.
• Gotcha 1d:哦，那是什么?现在，您希望能够像使用刚刚安装了apt的命令行一样从命令行调用jekyll?好吧，对不起，我是gem，有时我没有在您的路径上放jekyll.如果您遇到这种情况，请注意gem保存gem的位置，在其中找到可执行文件，然后使用sudo ln -s /path/to/jekyll /usr/bin/jekyll
创建符号链接.

• Gotcha 1a: The basics are left unexplained, so allow me: Ruby code comes in packages called gems, which are a lot like python packages. They're managed by gem or bundler rather than pip and hosted on rubygems.org instead of pypi. Much like in the Python world where everyone sings the praises of conda, everyone in the Ruby world sings the praises of bundler, which is itself a gem, one that you have to gem install because it doesn't come packaged with ruby like gem itself. I found bundler to be buggy; it hung when I tried to bundle install github-pages (more on github-pages later). Also, bundler relies on yet more configuration files called Gemfiles, which are the analog of the requirements.txt files pip can but doesn't need to ingest. Honestly who wants more of that clutter lying around for a small project with no complicated dependency tree? And who wants to have to bundle exec jekyll serve instead of just jekyll serve? Are you kidding me? Just use gem to install things, and skip the Gemfile. Much like pip, I find simpler is better.
• Gotcha 1b: If you sudo apt install jekyll, you get an old version, like 3.1 or something. But Jekyll is a gem; you can and should install using the package manager. (But actually don't do this, because it comes as part of the github-pages gem, and the versions don't agree. More on that later.)
• Gotcha 1c: Oh, what's that? You want to gem install jekyll (or even gem install bundler)? Yeah, sorry, I can't do that because there's some stuff missing, and here's a long printout about it. ...Google, Google... sudo apt install ruby-dev. Oh, sorry I still can't build. Here are some other errors. ...Google, Google... sudo apt install g++. Okay now it works. This process might be slightly different for you; point is setting up a ruby environment can be dicey.
• Gotcha 1d: Oh what's that? Now you want to be able to call jekyll from the command line like you could if you just installed it with apt? Well, sorry, I'm gem, and some times I don't put jekyll on your path. If this happens to you, pay attention to where gem saves the gems, go find the executable within, and then create a symlink with sudo ln -s /path/to/jekyll /usr/bin/jekyll

将assets，_includes，_layouts和_sass从站点移至新的存储库.完毕. am您现在有一个远程主题.确实应该那么简单，但是...

Move assets, _includes, _layouts, and _sass from the site to a new repo. Done. Bam. You have a remote theme now. It really should be that easy, but...

• Gotcha 2a:没有人告诉您这是最低可行的产品，因此您必须首先了解什么是远程主题以及它们如何工作.根据佳能的说法，它们是成熟的宝石.当您引用一个网站时，Jekyll需要先获取它，然后才能生成您的网站. The Jekyll文档都是关于如何真正打包您的软件包的指导主题作为宝石，并将其推至rubygems.org，这需要:(1)rubygems帐户，(2)您的主题包含一个深奥的.gemspec文件，其内容没有得到很好的解释.继续阅读为什么这无关紧要.
• Gotcha 2b:您必须了解 GitHub Pages 实际上是如何使用远程主题的.关于这个主题，GitHub很高兴地告诉您关于将remote_theme: user/theme-name添加到利用站点的_config.yml(Jekyll配置)中的信息，但是他们却没有事先告诉您他们是从某个地方还是从某个地方获取宝石.原来他们正在使用另一个名为 jekyll-remote-theme 的宝石来提取原始文件直接从回购中进行编译和上传gem的步骤，并且没有人会理解.gemspec的意思，也不想看到不必要的东西. (万岁).benbalter关于远程主题gem本身的文档是我唯一可以找到此信息的地方.
• Gotcha 2c:请注意，因为页面仍在Jekyll 3.8.6上，您在GitHub Pages上可能没有想要的某些功能，例如在主题的_config.yml 中定义站点数据.结果，我的前置.css包含一些Liquid标签，这些标签在我未分离的网站的一部分中可以正常工作，最终在生成的网站中替换了空字符串标签.我最终在主题中硬编码一些变量.
• Gotcha 2d:其他任何文件夹和文件(不在assets，_includes，_layouts和_sass中)(我有一个名为theme的文件夹，其中包含像我的收藏夹之类的东西.)不能折叠成主题的宝石，也可以通过GitHub采用的jekyll-remote-theme机制进行运输.通过仔细修改.gemspec，您可以将这些文件包含在gem中，但是此方法对jekyll-remote-theme的行为没有影响，因此我最终基本上将所有内容都放在了assets中.
• 投诉2e:现在显然已弃用Ruby Sass? Jekyll持续使用了这么长时间吗?我仍然没有遇到一个看起来有用的例子.

• Gotcha 2a: No one tells you that's the minimum viable product, so you have to start by understanding what remote themes are and how they work. According to canon, they're full-blown gems. When you reference one, Jekyll needs to go and fetch it before it can generate your site. The Jekyll documentation is all about coaching you on how to truly package up your theme as a gem and push it up to rubygems.org, which requires: (1) a rubygems account, (2) for your theme to contain an abstruse .gemspec file, the contents of which are not well explained. Keep reading for why this is irrelevant.
• Gotcha 2b: You have to understand how GitHub Pages actually uses remote themes. On this topic GitHub is happy to tell you about adding remote_theme: user/theme-name to the leveraging site's _config.yml (Jekyll config), but they neglect to tell you upfront whether they're pulling in a gem from somewhere or what. Turns out they're using yet another gem called jekyll-remote-theme to pull the raw files directly from a repo, making the step of compiling and uploading a gem and having a .gemspec no one understands or wants to look at unnecessary. (Hooray.) benbalter's documentation for the remote theme gem itself is the only place I could find this information.
• Gotcha 2c: Beware that because 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 hard-coding some variables in the theme.
• Gotcha 2d: Any other folders and files--not among assets, _includes, _layouts, and _sass--(I had one named theme containing stuff like my favicon.) don't get folded in to a theme gem or transported via the jekyll-remote-theme mechanism employed by GitHub. By carefully amending the .gemspec, you can include those files in a gem, but this method has no effect on the behavior of jekyll-remote-theme, so I ended up basically putting everything in assets.
• Complaint 2e: Ruby Sass is apparently deprecated now? Why has Jekyll continued to use it for so long? I've still not encountered an example where it seems useful.

在要在主题中呈现项目页面的每个回购的gh-pages分支的根目录中放置一个包含remote_theme: yourname/yourtheme的_config.yml.没有Gemfile，没有废话.只需等待它部署.

Put a _config.yml containing remote_theme: yourname/yourtheme in the root directory of the gh-pages branch of every repo for which you want the Project Pages rendered in your theme. No Gemfile, no nonsense. Just wait for it to deploy.

• Gotcha 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说:当您在GitHub上对发布源进行更改时，GitHub Pages将尝试构建您的网站.如果构建失败，您将在您的主要电子邮件地址收到一封电子邮件.您还将收到通过电子邮件发送有关构建警告的邮件.您可以在站点存储库的设置"标签中的GitHub上看到站点的构建失败(但没有构建警告)."我确实收到一封电子邮件，指出"/_layouts/default.html中第15行的标签include_cached不是可识别的Liquid标签."，但我不记得这是用于哪个版本的，也找不到记录在其中的故障.存储库设置在任何地方.
• Gotcha 3b:如果更新主题，则不会重建使用该主题的Pages网站以反映主题更改.您必须手动将站点重新推到分支站点才能触发站点重建.对于我与Travis-CI集成的回购协议，这非常容易，因为我可以在列表中重新运行最新的版本，最终将结果推送到gh-pages分支，从而导致Pages服务器进行重建.但是对于其他站点，我必须进行一些合法的更改或推送一个空的提交.

• Gotcha 3a: Jekyll looks specifically for a page.html file inside _layouts to render readme contents. If you have a page.html, then you can add your head, navbar and other _includes stuff to it with Liquid tags no problem. If you happened to forget this file or think Jekyll could use post.html instead, well then you'd be wrong, and the theme isn't applied. Not sure whether default.html would work as a failover. In any case, GitHub pages with Jekyll is super brittle, and I'm honestly lucky to have discovered this without being blocked by it, because (1) I haven't seen any GitHub documentation to describe exactly which commands are being called to generate Project Pages, (2) you can't see the terminal output for the remote compilation process**, and (3), because you don't know what GitHub is doing, there is no way to replicate it locally to see warnings or error printouts--that is if Jekyll even warns you about this.
  **If there actually is a way to view this somewhere, please tell me. 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." I did receive an email stating "The tag include_cached on line 15 in /_layouts/default.html is not a recognized Liquid tag.", but I don't remember which build this was for, and I can't find the failure recorded in the repo Settings anywhere.
• Gotcha 3b: If you update the theme, Pages sites which use the theme aren't rebuilt to reflect the theme changes. You have to manually repush to the branch a site is built from to trigger a site rebuild. This is pretty easy for repos I've integrated with Travis-CI, because I can just go down the list rerunning the most recent builds, which culminate in pushes to gh-pages branches, which in turn cause Pages servers to rebuild. But for other sites, I have to either make some legitimate change or push an empty commit.

在用户页面站点的_config.yml中添加plugins: - jekyll-remote-theme和remote_theme: yourname/yourtheme.

Add plugins: - jekyll-remote-theme and remote_theme: yourname/yourtheme to the _config.yml in your User Pages site.

• Gotcha 4a:本地执行令人困惑. benbalter的自述文件很好，但是用法"部分仍然假定您使用的是.如果不是，那么gem install github-pages就像您将安装任何其他gem一样.该gem实际上是其他大量的Pages服务器实际运行以生成您的静态站点所用的gem，包括相同版本的jekyll和jekyll-remote-theme.您将需要这些，以便可以捕获所有细微的版本或在本地显示错误，并且在云中不会感到惊讶.最后，尽管似乎不需要实际部署，但对于本地执行，您必须确保在使用站点的_config.yml中将jekyll-remote-theme作为插件列出.否则会出现jekyll serve错误.
• Gotcha 4b:具有远程主题的本地执行已损坏-或 at至少是针对Jekyll 4.0.0 .对于Jekyll 3来说，它工作正常，这是GitHub Pages服务器使用的东西，这就是为什么它可以很好地部署的原因.如果您使用gem install jekyll而不是github-pages列表获取Jekyll，则可能会像我一样遇到错误.

• Gotcha 4a: Local execution is confusing. benbalter's readme is pretty good, but the Usage section still assumes you're using bundler. If you're not, then gem install github-pages like you'd install any other gem. This gem is really a huge list of other gems Pages servers actually run to generate your static site, including the same versions of jekyll and jekyll-remote-theme. You'll want these so you can catch all subtle version or display bugs locally and have no surprises in the cloud. Finally, despite it not seeming to be necessary for actual deployment, for local execution you have to make sure to list jekyll-remote-theme as a plugin in your leveraging site's _config.yml. Otherwise jekyll serve errors.
• Gotcha 4b: Local execution with a remote theme is broken--or at least it is for Jekyll 4.0.0. It works fine for Jekyll 3, which is what GitHub Pages servers use, which is why it deploys fine. If you get Jekyll with gem install jekyll rather than from the github-pages list, you might get errors as I did.

因此事后看来，这基本上并不难，但是要实现盲目飞行的惨败只是用过于冗长，令人失望的不完整地图来指导您.我希望GitHub可以在某个终端中向您展示站点编译和部署的整个过程，就像Travis-CI所做的那样.我希望Jekyll不会那么复杂.功能太多，无数次失败都会消失.

So basically it's not hard in hindsight, but getting there is a frustrating fiasco of flying blind with only overly verbose, disappointingly incomplete maps to guide you. I wish GitHub would show you the whole process of site compilation and deployment in some terminal, like Travis-CI does for builds. And I wish Jekyll weren't so complicated. There are too many features, and too many things fail silently.

我希望这项研究可以对其他人有所帮助.

I hope this research can help somebody else.

这篇关于如何在Github Project Pages网站上使用github.io网站中的主题的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！