GitHub Pages 和 Jekyll 笔记 - Milton
source link: https://www.cnblogs.com/milton/p/16817549.html
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 笔记
快速创建(使用默认的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
将内容提交到仓库
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:
![My helpful screenshot](/assets/screenshot.jpg)
或者链接到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 实例参考
Recommend
About Joyk
Aggregate valuable and interesting links.
Joyk means Joy of geeK