GitHub Pages 和 Jekyll 笔记

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/

组合/列表变量

通过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 实例参考

• https://github.com/github/government.github.com
• https://github.com/artsy/artsy.github.io