![](/style/images/good.png)
![](/style/images/bad.png)
Github Pages 背后的 Jekyll | cf020031308.github.io
source link: https://cf020031308.github.io/wiki/jekyll-behind-github-pages?
Go to the source link to view the article. You can view the picture content, updated content and better typesetting reading experience. If the link is broken, please click the button below to view the snapshot at that time.
Github Pages 背后的 Jekyll
在代码仓库 settings 中开通 Github Pages 后,该仓库目标位置(gh-pages
分支、/
或 /docs/
)的 markdown 文件会在 Github 的服务器上被 Jekyll 渲染为同名的 html 文件,以提供网页服务。
关于 Github Pages 和 Jekyll 的关系,官方文档是个不错的开始。
本文研究以下需求所涉及的知识:
- 改善 SEO 并增加页面功能
- 尽可能少地在仓库里增加代码文件
- 尽可能少地依赖 Github 与 Jekyll
Jekyll 项目结构
一个较简单的 Jekyll 项目的文件结构如下:
.
├── _config.yml
├── _posts
│ └── 2020-03-14-jekyll-behind-github-pages.md
├── about.md
├── readme.md
├── _layouts
│ ├── default.html
│ ├── post.html
│ └── page.html
└── _includes
├── footer.html
└── header.html
- 配置文件:
/_config.yml
- post:格式为
/_posts/YYYY-mm-dd-title.md
的文件,将被渲染为网页/YYYY/mm/dd/title.html
- 索引页:任一目录中都会依次查找使用
index.md
或readme.md
用以生成index.html
。比如/foo/readme.md
对应网页的路径为/foo/index.html
,甚至访问/foo
也可以 - 其它页:如
about.md
。Github Pages 会将所有非下划线开头的路径中的 markdown 文件转为对应名字的网页。 - 网页模板:使用 Liquid 编写的模板文件(就是带 {
% if true %
} {{ var | filter }
} {% endif %
} 一类标记的 html 或 markdown)- layout:
/_layouts/
里是 layout 模板。markdown 文件的内容会嵌入到以下 layout中作为最终的网页:/index.md
或/readme.md
依次尝试home.html
、page.html
和default.html
- post 会依次尝试
post.html
和default.html
- 其它 markdown 文件依次尝试
page.html
和default.html
- 组件:
/_includes/
通常是 layout 中抽取出的公共部分,在 layout 中通过如 {%include footer.html %
} 引入
- layout:
网页模板中的变量
page: Markdown 的元信息
虽然 Jekyll 要求 markdown 文档开头要有 Front Matter(即首尾各一行 ---
的 yaml 片段),如:
---
title: "My Real Title"
my_diy_var: "my_diy_value"
---
# My Fake Title
blah blah
等价于如下 yaml 对象:
title: "My Real Title"
my_diy_var: "my_diy_value"
content: "<h1> My Fake Title </h1> <p> blah blah </p>"
该对象在 layout 中名为 page
,于是可以这样用:<h1> {
{ page.title }} </h1>{
{ page.content }}
但实际上,在 Github Pages 中可以没有 Front Matter,title 等字段可以从文档中推断出来。
注:其它文件如 html、sass 等开头也可以加 Front Matter,但意义不大。
site: 网站元信息与数据文件
另一个 layout 中可用的重要变量是 site
,内容如下:
_config.yml
中的字段,例如site.twitter_username
- 下划线开头的一级目录(
/_*/
)中的元信息或数据文件,例如/_data/
中的 markdown/yaml/json/csv/tsv 可以用site.data
遍历/_authors/roy.json
可以用site.authors.roy
得到
- 所属代码仓库的基本信息,如
site.title
默认是代码仓库的名字
使用现成的 Jekyll 主题
我之前的用法是不做任何主题的定制,除了自己写的简陋索引页外只有 markdown 文档,详情参见 Code Less, Talk More。
也可以在仓库 settings 中选择 官方支持的主题,比如选 minima。这等价于在 _config.yml
中配置 theme: minima
或者可以在网上找个自己满意的 Jekyll 主题,比如 minimal-mistakes,就下载到本地或在 _config.yml
中配置 remote-theme: mmistakes/minimal-mistakes
本地使用 Jekyll
Jekyll 是一个 ruby 包,安装需要使用 ruby 自带的包管理器 gem。
# 在 MacOS 用 brew 安装 ruby
brew install ruby
echo 'export PATH="/usr/local/opt/ruby/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
# 用 gem 安装 jekyll 与官方建议的 bundler
# 但因 MacOS 系统限制需要用 -n 绑定执行程序的路径,否则安装后找不到可执行文件
gem install -n /usr/local/opt/ruby/bin jekyll bundler
# 在当前路径下初始化一个项目
jekyll new blogtest
# 在本地安装依赖并运行服务
cd blogtest
bundle install
jekyll serve
初始项目本身比较简单,_config.yml
中看到使用的主题是 minima。
可以使用 bundle info minima
找到本地的 minima 代码,或者在 minima 的 Github 仓库 下载,以此为起点学习或做点定制开发。
Recommend
About Joyk
Aggregate valuable and interesting links.
Joyk means Joy of geeK