GitHub Pages 和 Jekyll 筆記
新建一個空倉庫, 名稱為username.github.io, 其中 username 就是你的GitHub賬號名稱
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
此時在倉庫首頁, 能看到一個棕色的小點, 表示有action正在執行, 點選能看到acion的詳情, 等action執行完畢, 就能通過 https://username.github.io 存取網站了.
大部分的 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 不處理以下檔案和目錄
_, ., 或#開頭的檔案或目錄~結尾的檔案或目錄如果需要 Jekyll 處理以上情況的檔案或目錄, 需要在組態檔的 include 中單獨設定.
一個 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/, 當前支援的模板有
完整的設定項參考 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>
預定義的變數
GitHub Pages 預設啟用以下的 Jekyll 外掛, 不能禁用
可以通過 _config.yml 新增新的外掛.
GitHub Pages 中的程式碼高亮和 GitHub 是一樣的, 預設情況下由 Jekyll 處理程式碼高亮, Jekyll 使用的程式碼高亮解析是 Rouge.
Jekyll 的頁面分為不同的型別, 主要有 Page, Posts
Pages 用於做單獨的頁面, 單獨建立, 可以放在任意目錄, 生成時會放到 _site 目錄下
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
...