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

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/

组合/列表变量

https://jekyllrb.com/docs/collections/

通过collections_dir指定目录, 如果使用这个配置, 那么_posts目录和_drafts目录也要挪到这个目录下

collections_dir: mycollections # 选择指定一个目录来将所有合集和posts存储在同一个位置

通过collections变量定义不同的collection, 如果是使用页面, 对应的要在上面指定的目录下, 创建一个同名但是以_开头的目录, 例如下面的设置, 需要创建一个mycollections/_collection01目录

collections:
  collection01: # 你的collection名称
    output: true 

• 通过collections指定的页面合集, 文件名不需要使用固定格式
  _posts目录是一种特殊的collection, 文件名格式是固定的

如果需要对一个collection中的页面进行分组, 可以通过在collection下的页面头部添加变量进行区分, 具体方法参考 https://stackoverflow.com/questions/37277738/can-i-create-nested-collections-in-jekyll

1. 创建一个目录 _sections 下面放置页面合集
2. 每个页面上添加变量chapter, 分别使用值01, 02, ... 用于区分不同的chapter
3. 创建layout, _layouts/chapter.html, 内容为

---
layout: default
---

<h1>Chapter {{ page.chapter }}</h1>

{% for section in site.sections %}
{% if section.chapter == page.chapter %}
{{ section.output }}
{% endif %}
{% endfor %}

4. 创建页面 chapter01.md, 内容为

---
chapter: 01
layout: chapter
---

5. 在全局设置 _config.yml 中设置 _sections 目录不输出

collections:
  sections:
    output: false
  chapters:
    output: true

数据文件

放置到 _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

变量处理引擎 Liquid

• 日期格式: STRFTIME, 常用的 2022-10-23 12:12:12格式对应的是%Y-%m-%d %H:%M:%S

插件

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

在页面上列出所有标签和标签下的文章 https://talk.jekyllrb.com/t/how-to-list-all-posts-for-any-given-tag/1402/2

根目录下创建文件 tags.html, 或者创建目录和文件 tags/index.html, 使用如下的内容

---
layout: default
---

{% assign sorted_tags = site.tags | sort %}
{% for tag in sorted_tags %}
{% assign vids = tag[1] | sort %}

{% if vids != empty %}

  <h2 id="{{tag[0] | uri_escape | downcase}}">{{tag[0]}}</H2>
     <p>
      {% for p in vids %}
     <a href="{{ p.url }}">{{ p.title }}</a> <span class="entry-date"><time datetime="{{ p.date | date_to_xmlschema }}" itemprop="datePublished">{{ p.date | date: "%B %d, %Y" }}</time></span>
     <br />
      {% endfor %}
    </p>
  
{% endif %}

{% endfor %}

对应的展示效果 http://ephotopros.com/tags/

文章摘要

默认使用的是正文内容的第一段, 可以通过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