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:
或者鏈接到PDF
... you can [get the PDF](/assets/mydoc.pdf) directly.
文章串列
使用以下方式創建文章串列
<ul>
{% for post in site.posts %}
<li>
<a href="https://www.cnblogs.com/milton/archive/2022/10/22/{{ 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="https://www.cnblogs.com/milton/archive/2022/10/22/{{ 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="https://www.cnblogs.com/milton/archive/2022/10/22/{{ 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
轉載請註明出處，本文鏈接：https://www.uj5u.com/qita/518983.html
標籤：其他
上一篇：DNS服務
下一篇：SSH遠程登錄協議