快速创建(使用默认的Jekyll引擎)
1. 新建仓库
新建一个空仓库, 名称为username.github.io, 其中 username 就是你的GitHub账号名称
2. 增加文件
Clone到本地, 在里面建两个文件 _config.yml 和 index.md
_config.yml 是 Jekyll 的配置文件
theme: jekyll-theme-minimal
title: My Homepage
description: For daily notes
index.md 是站点的首页
# Test Page
It's a test page
## Header 2
content
3. 提交
将内容提交到仓库
git add -A
git commit -m "update"
git push
4. 等待发布
此时在仓库首页, 能看到一个棕色的小点, 表示有action正在执行, 点击能看到acion的详情, 等action执行完毕, 就能通过 https://username.github.io 访问网站了.
GitHub Pages 上的Jekyll
大部分的 Jekyll 选项都可以通过 _config.yml 配置使用, 配置项参考, 但是有一些在 GitHub Pages 中是固定的, 不可更改
lsi: false
safe: true
source: [your repo's top level directory]
incremental: false
highlighter: rouge
gist:
noscript: false
kramdown:
math_engine: mathjax
syntax_highlighter: rouge
默认设置下, Jekyll 不处理以下文件和目录
目录 /node_modules
目录 /vendor
以_, ., 或#开头的文件或目录
以~结尾的文件或目录
在配置文件的 exclude 中设置的文件或目录
如果需要 Jekyll 处理以上情况的文件或目录, 需要在配置文件的 include 中单独设置.
Jekyll使用
整体目录结构
一个 Jekyll 网站整体的目录结构如下
├── _config.yml
├── _data
│ └── members.yml
├── _drafts
│ ├── begin-with-the-crazy-ideas.md
│ └── on-simplicity-in-technology.md
├── _includes
│ ├── footer.html
│ └── header.html
├── _layouts
│ ├── default.html
│ └── post.html
├── _posts
│ ├── 2007-10-29-why-every-programmer-should-play-nethack.md
│ └── 2009-04-26-barcamp-boston-4-roundup.md
├── _sass
│ ├── _base.scss
│ └── _layout.scss
├── _site
├── .jekyll-cache
│ └── Jekyll
│ └── Cache
│ └── [...]
├── .jekyll-metadata
└── index.html # can also be an 'index.md' with valid front matter
设置模板
通过指定模板, 可以使 Jekyll 生成不同式样的页面, GitHub Pages 支持的模板, 可以在这里查看 https://pages.github.com/themes/, 当前支持的模板有
Architect
Cayman
Dinky
Hacker
Leap day
Merlot
Midnight
Minima
Minimal
Modernist
Slate
Tactile
Time machine
设置全局变量
完整的配置项参考 https://jekyllrb.com/docs/configuration/
组合/列表变量
通过collections变量定义 https://jekyllrb.com/docs/collections/
数据文件
放置到 _data 目录, 支持 YAML, JSON, CSV 和 TSV 文件(扩展名为 .yml, .yaml, .json, .tsv, 和 .csv).
例如 _data/members.yml
- name: Eric Mill
github: konklone
- name: Parker Moore
github: parkr
- name: Liu Fengyun
github: liufengyun
或者_data/members.csv
name,github
Eric Mill,konklone
Parker Moore,parkr
Liu Fengyun,liufengyun
通过site.data.members引用数据中的值, 例如
<ul>
{% for member in site.data.members %}
<li>
<a href="https://github.com/{{ member.github }}">
{{ member.name }}
</a>
</li>
{% endfor %}
</ul>
_data 目录支持子目录, 对应的在引用变量中要增加子目录名作为变量路径, 例如
文件 _data/orgs/jekyll.yml
username: jekyll
name: Jekyll
members:
- name: Tom Preston-Werner
github: mojombo
- name: Parker Moore
github: parkr
_data/orgs/doeorg.yml
username: doeorg
name: Doe Org
members:
- name: John Doe
github: jdoe
上面的数据可以通过site.data.orgs进行引用, 例如
<ul>
{% for org_hash in site.data.orgs %}
{% assign org = org_hash[1] %}
<li>
<a href="https://github.com/{{ org.username }}">
{{ org.name }}
</a>
({{ org.members | size }} members)
</li>
{% endfor %}
</ul>
静态文件
在 _config.yml 中定义一个路径下的全部文件, 属性增加image = true
defaults:
- scope:
path: "assets/img"
values:
image: true
然后可以在变量中进行过滤
{% assign image_files = site.static_files | where: "image", true %}
{% for myimage in image_files %}
{{ myimage.path }}
{% endfor %}
设置页面变量
在任何 Jekyll 处理的页面文件的最开始(如果是UTF-8, 需要确认没有BOM), 以三横线开始和结束的一段YAML代码用于设置当前页面的页面变量, 例如
---
layout: post
title: Blogging Like a Hacker
---
这里可以引用之前定义的变量, 也可以定义新的值, 例如
---
food: Pizza
---
<h1>{{ page.food }}</h1>
预定义的变量
全局变量: layout, permalink, published
帖子变量: date, category, categories, tags
插件
GitHub Pages 默认启用以下的 Jekyll 插件, 不能禁用
jekyll-coffeescript
jekyll-default-layout
jekyll-gist
jekyll-github-metadata
jekyll-optional-front-matter
jekyll-paginate
jekyll-readme-index
jekyll-titles-from-headings
jekyll-relative-links
可以通过 _config.yml 添加新的插件.
代码高亮
GitHub Pages 中的代码高亮和 GitHub 是一样的, 默认情况下由 Jekyll 处理代码高亮, Jekyll 使用的代码高亮解析是 Rouge.
页面类型
Jekyll 的页面分为不同的类型, 主要有 Page, Posts
Pages
Pages 用于做单独的页面, 单独创建, 可以放在任意目录, 生成时会放到 _site 目录下
Posts
Posts 用于日常的文章发表, 创建时放到 _posts 目录下, 文件名需要使用如下固定的格式
YEAR-MONTH-DAY-title.MARKUP
例如
2011-12-31-new-years-eve-is-awesome.md
2012-09-12-how-to-write-a-blog.md
每个文章的固定格式如下, 前面的front matter可以为空
---
layout: post
title: "Welcome to Jekyll!"
---
# Welcome
**Hello world**, this is my first Jekyll blog post.
I hope you like it!
静态文件
静态文件例如图片, ZIP, PDF, 可以都放置在 assets 目录下, 再从文章中连接, 例如
... which is shown in the screenshot below:
或者链接到PDF
... you can [get the PDF](/assets/mydoc.pdf) directly.
文章列表
使用以下方式创建文章列表
<ul>
{% for post in site.posts %}
<li>
<a href="{{ post.url }}">{{ post.title }}</a>
</li>
{% endfor %}
</ul>
分类和标签
Tag 和 Category 都有单数复数的区分, 如果是单数, 后面的整个值都作为一个标签或分类, 如果是复数, 则按空格分隔
tag: classic hollywood会被当成标签"classic hollywood", 如果是tags: classic hollywood, 则会被当成标签 "classic"和"hollywood".
使用tag或category创建文章目录, 可以使用下面的形式, 注意site.tags和site.categories的for循环中, 每个标签或分类会产生两个单元, 一个单元是名称, 另一个单元才是文章列表
{% for tag in site.tags %}
<h3>{{ tag[0] }}</h3>
<ul>
{% for post in tag[1] %}
<li><a href="{{ post.url }}">{{ post.title }}</a></li>
{% endfor %}
</ul>
{% endfor %}
分类与标签的区别在与, 分类可以直接由文章的目录路径来定义, 在_post 目录上层的目录, 都会被当成分类, 例如如果文章位于路径 movies/horror/_posts/2019-05-21-bride-of-chucky.markdown, 那么 movies 和 horror a自动成为这个文章的分类.
当文章中使用 front matter 定义了类别, 会在列表中添加这篇文章. 取决于 front matter 中是否定义了分类, 例如 category: classic hollywood, 或 categories: classic hollywood, 帖子就会相应地产生这样的链接 movies/horror/classic%20hollywood/2019/05/21/bride-of-chucky.html 或 movies/horror/classic/hollywood/2019/05/21/bride-of-chucky.html
文章摘要
通过excerpt_separator定义, 例如
---
excerpt_separator: <!--more-->
---
Excerpt with multiple paragraphs
Here's another paragraph in the excerpt.
<!--more-->
Out-of-excerpt
在列表中引用摘要
<ul>
{% for post in site.posts %}
<li>
<a href="{{ post.url }}">{{ post.title }}</a>
{{ post.excerpt }}
</li>
{% endfor %}
</ul>
草稿
草稿可以放到 _drafts 目录下
.
├── _drafts
│ └── a-draft-post.md
...
Jekyll 实例参考
https://github.com/github/government.github.com
https://github.com/artsy/artsy.github.io
