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執行完畢, 就能通過 //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 支援的模板, 可以在這裡查看 //pages.github.com/themes/, 當前支援的模板有
- Architect
- Cayman
- Dinky
- Hacker
- Leap day
- Merlot
- Midnight
- Minima
- Minimal
- Modernist
- Slate
- Tactile
- Time machine
設置全局變數
完整的配置項參考 //jekyllrb.com/docs/configuration/
組合/列表變數
通過collections變數定義 //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="//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="//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
...
