Jekyll 笔记

Jekyll 相关资源整理

Jekyll 主题 / Jekyll 插件 /

Windows 安装 Jekyll

Windows 安装 Jekyll 教程

MacOS 安装

MacOS 已集成主要环境可以直接安装

文件夹安装

已安装 Bundler 直接执行 bundle update jekyll 或者bundle update

未安装 Bundler 先安装 gem update jekyll

全局安装

sudo gem install bundler
sudo gem install -n /usr/local/bin/ jekyll

查看当前版本

bash jekyll -v

升级 jekyll

升级前请先查看相关文档：- jeykll 升级：Upgrading - jekyllrb
确认所需的 ruby 版本 ruby -v
知晓版本中的功能变更，一般会有参数修改或者删除一些老的用法。

未安装 bundle ，先安装 bundle

gem update jekyll

已安装 bundle

bundle update jekyll

安装指定版本示例，请勿直接使用

gem install bundler:2.1.4

如果无法安装或者一直报错可以看一下已安装版本和卸载低版本

gem uninstall bundler

再安装最新版本

gem install bundler

参考资料

Jekyll on macOS Global Install

升级 bundler 版本

bundle update --bundler

环境搭建

jekyll new myblog 全新安装

Install the jekyll and bundler gems. 安装 jekyll 和 bundler gems

gem install jekyll bundler

Create a new Jekyll site at ./myblog. 创建一个新的 jekyll 站点，会在当前目录下新建一个文件夹

jekyll new myblog

Change into your new directory. 进入对应文件夹

cd myblog

运行本地服务

bundle exec jekyll serve

clone 安装本地编译并运行

建议先从 gitlab 或者 github clone 或者 fork 一个仓库

初次运行需要先安装

bundle install

已经安装后

bundle exec jekyll server

本地生成静态 HTML 和对应资源文件

bundle exec jekyll build -d _site

ruby3.0 运行 jekyll 报错

无法加载 webrick

------------------------------------------------
      Jekyll 4.2.0   Please append `--trace` to the `serve` command 
      for any additional information or backtrace. 
------------------------------------------------
/Users/username/.rvm/gems/ruby-2.7.0/gems/jekyll-4.2.0/lib/jekyll/commands/serve/servlet.rb:3:in `require': cannot load such file -- webrick (LoadError)

执行命令，给 Gemfile 文件添加 webrick 配置

bundle add webrick

执行成功后会在 Gemfile 文件尾端增加一行 gem "webrick", "~> 1.7"（2021-01-18）解决方法：https://github.com/jekyll/jekyll/issues/8523

说明

/_site 静态文件生成目录，一般 .gitignore 文件中要注明这个目录 /photo 不含下划线的文件夹中的文件都会处理成 page 或者直接复制到生成目录 /index.html 主页文件，也可以用 index.md

YEAR-MONTH-DAY-title.md 文章命名规范

exclude: [DIR, FILE, ...] 忽略文件，不会被 jekyll 处理（这些目录文件不会生成，无法访问） include: [DIR, FILE, ...] 强制处理，如 .htaccess（如果该文件被忽略，会强行生成） timezone: TIMEZONE 时区 encoding : utf-8 编码 permalink: /:categories/:year/:month/:day/:title.html 文章 URL 定制

paginate: 5 分页数 paginate_path: "blog/page:num/" 分页 URL 路径

模板

Jekyll Cheat Sheet 参数表（含代码示例）：https://cloudcannon.com/community/jekyll-cheat-sheet/
Liquid User Guide For J1 Theme: https://jekyll.one/pages/public/manuals/liquid/user_guide/

输出全部页面（页面导航）

site.pages 全部页面，整个jekyll 的全部页面
site.url 假设 url 是一个 collections，那只会调用该 collections 的全部页面链接

{% for my_page in site.pages %}
  {% if my_page.title %}
  <a class="page-link" href="{{ my_page.url | prepend: site.baseurl }}">{{ my_page.title }}</a>
  {% endif %}
{% endfor %}

按分类输出该各分类下所有内容

{% for category in site.categories %}
<h2>{{ category | first }}</h2>
</span>{{ category | last | size }}</span>
<ul class="arc-list">
    {% for post in category.last %}
        <li>{{ post.date | date:"%d/%m/%Y"}}<a href="{{ post.url }}">{{ post.title }}</a></li>
    {% endfor %}
</ul>
{% endfor %}

仅输出全部分类（不含链接）

{% for category in site.categories %}
<h2>{{ category | first }}</h2>
<span>{{ category | last | size }}</span>
{% endfor %}

输出全部标签（标签云）

href 的值结合自己 jekyll 实际设定调整

{% for tag in site.tags %}
    {% assign count = tag | last | size %}
    {% assign fontsize = count | times: 4 %}
    {% if count  > 2 %}
    <a class="post-tags-item" href="/tag/{{ tag | first }}/" title="{{ tag | first }}" data-count="{{ count }}" style="font-size: {% if fontsize > 24 %}24{% else %}{{ fontsize }}{% endif %}px">{{ tag | first }}</a>
    {% endif %}
{% endfor %}

注释掉页面代码或内容 {% comment %}

使用 {% comment %} 注释掉的模板代码或内容，在生成的时候不会输出，所以在html网页源代码中看到这部分内容。（这个功能一般称之为代码注释或者代码评论。）

{% comment %}
要被注释的内容
{% endcomment %}

slug

如果页面没有配置，默认使用文件名（:title）

引入模板文件

head.html 也可以是 style.css 样式文件或者更多“文本类型”文件。

{% include head.html %}

include 验证支持的文件格式

html
css
md

通过 front matter 或 _data 使用 include 和 include_relative

通过 front matter 或 _data 中的 csv 或 yml 读取配置

通过 front matter 配置 include_relative

---
css_link: page.css
---

{% include_relative {{page.css_link}} %}

通过 _data 中的 csv 或 yml 配置 include

product.yml

pic: 
url: images/001.jpg

front matter

---
css_link: pic
---

{% assign product = site.data.[page.project_name] %}
{% include {{product.url}} %}

md文件避免执行liquid代码片段导致报错

当我们在文字中分享liquid代码片段时，jekyll生成的时候可能会报错，按以下方式处理

{% raw %}
``` 
// 原来代码片段 （包括开头结尾的 ```）
``` 
{% endraw %}

查看参考：https://github.com/jekyll/jekyll/edit/master/docs/_docs/datafiles.md

YAML 使用技巧

单独调用 YAML 指定的一个参数的值

_data/test.yml 内容

name:
  id1: john
  id2: lola

test.html 内容

<p>ID1 的 name: {{site.data.test.name.id1}}</p>
<p>ID2 的 name: {{site.data.test.name.id2}}</p>

include 语句或 include 文件中使用页面变量

---
title: My page
my_variable: footer_company_a.html
---

{% if page.my_variable %}
  {% include {{ page.my_variable }} %}
{% endif %}

include 参数传递到包括的结构

假设 _includes/note.html 包含此段代码。

在页面引用 note.html 时配置 content ，{{ include.content }} 内容会被填充为指定内容。

<div class="header">
<h2>Note:</h2>
{{ include.content }}
</div>

{% include note.html content="This is my sample note." %}

配置多个参数,假设 _includes/header_logo.html 包含此段代码。

<figure>
   <a href="{{ include.url }}">
   <img src="{{ include.file }}" style="max-width: {{ include.max-width }};"
      alt="{{ include.alt }}"/>
   </a>
   <figcaption>{{ include.caption }}</figcaption>
</figure>

{% include header_logo.html url="https://1px.run"
max-width="200px" file="logo.png" alt="Jekyll logo"
caption="This is the Jekyll logo." %}

include 参数传递变量而不是字符串

{% capture download_note %}
The latest version of {{ site.product_name }} is now available.
{% endcapture %}

省略参数内容前后的引号，因为它不再是字符串而是变量。

{% include note.html content=download_note %}

assign 创建变量重复使用

{% assign text_read = "已读" %}
{{ text_read }}

capture 指定内容重复使用

{% capture text_read %}已读{% endcapture %}

{{ text_read }}

{{ text_read }}编译后显示已读，支持单行也支持多行

include_relative 引用当前文件目录下的文件相对路径链接

假设这个代码片段存在 page/home.html，会引用 page/tpl/footer.html 该个路径文件。

{% include_relative tpl/footer.html %}

include 相关文档

通过文章、页面头信息访问yml数据中指定内容

可以用于语言设定 _data/language.yml

en:
    name: English
    doname: en
cn:
    name: 中文
    doname: cn

language_cn.html 页面内容

---
title: 中文语言
language: cn
---

{% assign language = site.data.language[page.language] %}
<a rel="language"
  href="https://{{ language.doname }}.1px.run"
  title="{{ language.name }}">
    {{ language.name }}
</a>

yml数据中全部内容

language_all.html 页面内容

---
title: 全语言
---
<ul>
{% for language in site.data.sago.update_popups_language %}
{% assign update = language[1] %}
  <li>
    <a rel="language"
      href="https://{{ language.doname }}.1px.run"
      title="{{ language.name }}">
        {{ language.name }}
    </a>
  </li>
{% endfor %}
</ul>

操作符

基本判断运算

操作符	说明
`==`	等于
`!=`	不等于
`>`	大于
`<`	小于
`>=`	大于等于
`<=`	小于等于
`or`	或者
`and`	和，并且
`contains`	字符串包含
`startswith`	字符串开头
`endswith`	字符串结尾

操作符一个 if 判断多个运算条件

{% if item.tag != 'error' and item.sort != 'note' %}
 tag 不包括 error 和 note 的内容
{% endif %}

使用 else 实现不包含 not contains

{% if item.tag contains 'error' %}
{% else %}
  tag 不包括 error 的内容
{% endif %}

使用 unless 实现不包含 not contains

(未验证)

{% if item.tag %}
  {% unless item.tag contains "error"
    tag 不包括 error 的内容
  {% unless item.tag contains "error"
    tag 不包括 error 的内容
  {% endunless %}
{% endif %}

数据类型

类型	值或说明	演示
空值	`null`	–
Boolean	`true`、`false`	`{% assign foo = true %}`
Number	–	`{% assign my_int = 30 %}` `{% assign my_float = 88.76 %}`
String	引号包裹字符串	`{% assign my_string = "Hello Atop!" %}`
Nil	类似 `undefined`	–
Array	索引取值	`{{ site.users[0] }} {{ site.users[1] }}`
Array	遍历操作	`{% for user in site.users %} {{ user }} {% endfor %}`

条件判断

值的判断

{% if post.wrong == null %}
  - 无数据
{% elsif post.wrong == 'on' %}
  ON
{% else %}
  {{ post.wrong }}
{% endif %}

读取 YAML（YML 或 JSON 或 CSV）数据时通过类型筛选参考文档（jekyllrb）

<ul>
{% for item in site.data.help %}
  {% if item.category == 'coins' %}
  <li>
    {{ item.title }}
  </li>
  {% endif %}
{% endfor %}
</ul>

读取 YAML（YML 或 JSON 或 CSV）数据时排序参考文档（jekyllrb）

{% assign doclist = site.data.samplelist.docs | sort: 'title'  %}
<ol>
{% for item in doclist %}
    <li><a href="{{ item.url }}">{{ item.title }}</a></li>
{% endfor %}
</ol>

更多条件判断案例：
- https://www.scube.co/guide/liquid-cheatsheet/
- https://shopify.dev/docs/api/liquid/basics

判断参数不存在时使用制定值

当 menu_name 不存在时，使用 title

作用和判断相似，代码更简短。

{{ item_page.menu_name | default: item_page.title }}

以上代码等同于以下判断逻辑

{% if item_page.menu_name %}
  {{ item_page.menu_name }}
{% else %}
  {{ item_page.title }}
{% endif %}

排序

排序方式	演示代码
升序	`{% assign event = site.data.event_list \| sort: "date" %}`
降序	`{% assign event = site.data.event_list \| sort: "date" \| reverse %}`
两个排序方式？	`{{ site.pages \| sort: "title", "last" }}`

strip_html 删除字符串中html标记

输入

{{ "Have <em>you</em> read <strong>Ulysses</strong>?" | strip_html }}

输出

Have you read Ulysses?

newline_to_br 换行符转为html代码`<br>`

newline_to_br 让内容输出时按换行符进行换行

{% capture string_with_newlines %}
Hello
there
{% endcapture %}

{{ string_with_newlines | newline_to_br }}

输出效果

<br />
Hello<br />
there<br />

strip_newlines 删除字符串中换行符

从字符串中删除任何换行符（换行符）。

输入

{% capture string_with_newlines %}
Hello
there
{% endcapture %}

{{ string_with_newlines | strip_newlines }}

输出

Hellothere

remove 移除字符串中指定内容

输入

{{ "I strained to see the train through the rain" | remove: "rain" }}

输出

I sted to see the t through the

remove_first 移除字符串中指定内容只操作一次

输入

{{ "I strained to see the train through the rain" | remove_first: "rain" }}

输出

I sted to see the train through the rain

prepend 指定内容前插入内容

在字符串前面插入内容

输入

{{ "apples, oranges, and bananas" | prepend: "Some fruit: " }}

输出

Some fruit: apples, oranges, and bananas
prepend can also accept a variable as its argument.

输入

{% assign url = "example.com" %}
{{ "/index.html" | prepend: url }}

Output

example.com/index.html

replace 替换内容中指定的内容

替换指定内容

输入

{{ "Take my protein pills and put my helmet on" | replace: "my", "your" }}

输出

Take your protein pills and put your helmet on

replace_first 只替换一次内容中的指定内容

替换指定内容，但是只执行一次

输入

{{ "Take my protein pills and put my helmet on" | replace_first: "my", "your" }}

输出

Take your protein pills and put my helmet on

reverse 反转数值或字符串中内容

反转数组中项目的顺序。reverse不能反转字符串。

输入

{% assign my_array = "apples, oranges, peaches, plums" | split: ", " %}

{{ my_array | reverse | join: ", " }}

输出

plums, peaches, oranges, apples

虽然reverse不能直接在字符串上使用，但您可以将字符串拆分为数组，反转数组，然后通过将过滤器链接在一起重新加入。

输入

{{ "Ground control to Major Tom." | split: "" | reverse | join: "" }}

输出

.moT rojaM ot lortnoc dnuorG

last 提取数值或字符串中最后的内容

返回数组的最后一项。

输入

{{ "Ground control to Major Tom." | split: " " | last }}

输出

Tom.

输入

{% assign my_array = "zebra, octopus, giraffe, tiger" | split: ", " %}

{{ my_array.last }}

输出

tiger

last当您需要在标签内使用过滤器时，可以使用点表示法：

{% if my_array.last == "tiger" %}
  There goes a tiger!
{% endif %}

url_decode 将 URL 编码字符转为字符串

解码已编码为 URL 或由url_encode.

输入

{{ "%27Stop%21%27+said+Fred" | url_decode }}

输出

'Stop!' said Fred

url_encode 将字符串转为 URL 编码字符

将字符串中的任何 URL 不安全字符转换为百分比编码字符。

输入

{{ "john@liquid.com" | url_encode }}

输出

john%40liquid.com

请注意，这url_encode会将空格变成+符号而不是百分比编码的字符。

输入

{{ "Tetsuro Takara" | url_encode }}

输出

Tetsuro+Takara

upcase 将字符串中的英文字母转为大写

使字符串中的每个字符大写。它对已经全部大写的字符串没有影响。

输入

{{ "Parker Moore" | upcase }}

输出

PARKER MOORE

downcase 将字符串中英文字母转为小写

输入

{{ "Parker Moore" | downcase }}

输出

parker moore

truncatewords 按单词截断字符串内容并添加自定义省略符号

将字符串缩短为作为参数传递的字数。如果指定的单词数小于字符串中的单词数，则将省略号 (…) 附加到字符串。

输入

{{ "Ground control to Major Tom." | truncatewords: 3 }}

输出

Ground control to...

truncate 按字符串字符截断

输入

{{ "Ground control to Major Tom." | truncate: 20 }}

输出

Ground control to...

数值计算

加法

{{ 183.357 | plus: 12 }}

195.357

minus 减法

{{ 183.357 | minus: 12 }}

171.357

times 乘法

---
number1: 5
number3: 10
---
{{ 5 | times: 10 }}
{{ page.number1 | times: page.number2 }}

两者结果均为50

divided_by 除法

默认四舍五入输入

{{ 20 | divided_by: 7 }}

输出

这是一个浮点数：

输入

{{ 20 | divided_by: 7.0 }}

输出

2.857142857142857

生成相对路径链接或者绝对路径链接

相对路径链接

{{ "/assets/style.css" | relative_url }}

/my-baseurl/assets/style.css

绝对路径链接

{{ "/assets/style.css" | absolute_url }}

http://example.com/my-baseurl/assets/style.css

自定义省略号

truncatewords接受一个可选的第二个参数，该参数指定要附加到截断字符串的字符序列。默认情况下，这是一个省略号 (…)，但您可以指定不同的序列。

输入

{{ "Ground control to Major Tom." | truncatewords: 3, "--" }}

输出

Ground control to--

自定义日期格式

https://shopify.github.io/liquid/filters/date/

将时间戳转换为另一种日期格式。此语法的格式与 strftime. 输入使用与 Ruby 相同的格式Time.parse。

输入

{{ article.published_at | date: "%a, %b %d, %y" }}

输出

Fri, Jul 17, 15

输入

{{ article.published_at | date: "%Y" }}

输出

date如果字符串包含格式正确的日期，则适用于字符串。

输入

{{ "March 14, 2016" | date: "%b %d, %y" }}

输出

Mar 14, 16

要获取当前时间，请将特殊单词”now”（或”today”）传递给date。

输入

This page was last updated at {{ "now" | date: "%Y-%m-%d %H:%M" }}.

输出

This page was last updated at 2024-03-11 16:24.

请注意，该值将是上次从模板生成页面的当前时间，而不是当涉及缓存或静态站点生成时将页面呈现给用户的时间。

date_to_string 将日期转为短格式

{{ site.time | date_to_string }}

07 Nov 2008

以美国序数形式将日期转为字符串

将日期格式化为序数、美国、短格式。

{{ site.time | date_to_string: "ordinal", "US" }}

Nov 7th, 2008

无法比较数据或计算输出内容

假设我只输出 view 数据大于等于 500 的内容。

正确操作方式：

{% assign view = item.view | plus: 0 %}
{% if view >= 500 %}
  内容
{% endif %}

错误举例：

由于无法进行子变量比较，所以如果子变量大于小于的数字计算会报错，提示不能用字符串计算

{% if item.view >= 500 %}
  内容
{% endif %}

Liquid 报错提示

 Liquid Exception: Liquid error (line 128): comparison of String with 500 failed in project/lanshu/home.html

参考：Liquid error: comparison of String with ‘number’

collections 功能（集合）

使用演示

_config.yml 配置

collections:
  url:
    output: true
    permalink: /:collection/:name/ #生成的链接形式
defaults:
  - scope:
      path: ""
      type: "url" # 指定一个类型
    values: # 页面头部信息，比如 layout、tag 等，也可以添加模板的自定义字段
      layout: touch # 该类型使用的模板 layout
      page_width: 960px # 自定义字段

_layouts/url.html 模板

---
layout: default
---
<div class="page">
  <h1 class="mt-4 publication-title">{{ page.title }}</h1>
  <div class="publication-authors">{{ page.authors }}</div>
  <div class="publication-info">{{ page.publication }}, {{ page.year}}</div>
  <div class="publication-teaser">
    <img
      src="/images/publication-pages/{{ page.slug }}.jpg"
      alt="project teaser"
    />
  </div>
  {{ content }}
  <h2 id="downloads">Downloads</h2>
  <p>
    <a href="/download/{{ page.slug }}.pdf"
      ><i class="far fa-file-pdf"></i> PDF</a
    >&nbsp;&nbsp; {% if page.slides %}
    <a href="/download/{{ page.slug }}_slides.pdf"
      ><i class="far fa-file-pdf"></i> Slides</a
    >&nbsp;&nbsp; {% endif %}
    <a href="/download/{{ page.slug }}.bib"
      ><i class="far fa-file-alt"></i> BibTex</a
    >&nbsp;&nbsp; {% if page.doi %}
    <a href="{{ page.doi }}"><i class="fas fa-external-link-alt"></i> DOI</a
    >&nbsp;&nbsp; {% endif %}
  </p>
</div>

列表页

---
layout: 
title: Url
permalink: /url/
---
<h1 class="mt-4">Publications</h1>
{% assign publications = site.url | sort: "year" | reverse %}
{% for pub in publications %}
<div class="pubitem">
  <div class="pubtitle">{{ pub.title }}</div>
  <div class="pubauthors">{{ pub.authors }}</div>
  <div class="pubinfo">{{ pub.publication }}, {{ pub.year}}</div>
  <a href="{{pub.url}}"><i class="fas fa-link"></i> Project Page</a>
</div>
{% endfor %}

内容页 _url/mypub19.md

文件存放路径 _url/mypub19.md （文件夹名称必须使用_开头）

---
title: A New Method for Fancy Research
authors: John Doe and Mary Jane
publication: Journal of Fancy Research
year: 2019
doi: http://dx.doi.org/XX.XXX/
---
8888

内容页 _url/mypub18.md

---
title: 什么
authors: 这个
publication: 什么情况
year: 2019
doi: http://dx.doi.org/XX.XXX/
---
6666

通过页内 front matter 的 YAML 列表输出在页面列表中

front matter 部分

---
list:
  - title: Happy
    description: are you happy?
  - title: Apple
    description: i like your apple tree.
  - title: Nice Day
    description: hello world.
---

内容部分

<div class="list-grid">
{% for my_log in page.list %}
  <div class="item">
    <p>{{ my_log.title }}</p>
    <p>Description: {{ my_log.description }}</p>
  </div>
{% endfor %}
</div>

标签功能实现，自动生成标签页面

列表页分页说明

分页功能
- 分页的路径是固定的如第2页：blog/page2/index.html，但是不会生成page1这个文件夹
- 使用了 permalink 就不能使用分页功能
- 分页功能只支持 html 文件
- 不支持对分类、标签页分页

文章摘要调用和手动切割摘要的分隔符

在列表调用文章摘要内容：post.excerpt

在配置文件自定义切割摘要的分隔符：excerpt_separator: 

模板构建

Jekyll 中的配置和模板语法方法比较详细，包含官方 API 举例。
关于for循环：Jekyll：按通用属性对_data子文件夹中的文件进行排序

参考内容

48 个你需要知道的 Jekyll 使用技巧 https://crispgm.com/page/48-tips-for-jekyll-you-should-know.html

静态博客目录生成方案选择 https://weiweitop.fun/2020/03/18/%E9%9D%99%E6%80%81%E5%8D%9A%E5%AE%A2%E7%9B%AE%E5%BD%95%E7%94%9F%E6%88%90%E6%96%B9%E6%A1%88%E9%80%89%E6%8B%A9/

48 个你需要知道的 Jekyll 使用技巧 https://crispgm.com/page/48-tips-for-jekyll-you-should-know.html

jekyll - 如何使用Liquid列出目录中的文件？ - Stack Overrun https://stackoverrun.com/cn/q/4750500

让 html 模板可以识别和解析 Markdown

{% capture markdown_content %}

## 天气预报

- [天气预报 天气网](https://m.weather.com.cn/)
- [天气预报 weather.com](https://weather.com/weather/today/)
- [天气网 The Weather Network](https://www.theweathernetwork.com/)

{% endcapture %}

{{ markdown_content | markdownify }}

Liquid

查看相关内容

让 jekyll 支持解析 .txt 中的 Markdown

新建 markdownify.html 文件，存于 _layouts 文件夹： _layouts/markdownify.html

文件内容如下，请将 layout 替换你常用的模板，比如layout: page

---
layout: page
---
{{ content | markdownify }}

在 .txt 格式的Markdown文件使用 markdownify.html 模板
permalink 后面必须加上 .html 不然生成的是 txt 文件，如果使用类似 /page/ 目录路径就要这样写 /page/index.html
保存后构建或者运行服务，访问 http://127.0.0.1:4000/txtdomo/ 查看效果（请替换自己的域名和端口）

---
layout: markdownify
title: Markdown 预览
permalink: /txtdomo/index.html
---

# {{ page.title }}

## 你的页面内容

- 终于可以支持 .txt 后缀的Markdown文件渲染了
- 这是一个简单的示例

这个方式除了可以支持 .txt 还可以支持其他后缀。

因为部分软件无法识别 .md 所以会把文件夹命名为 .md.txt ，在电脑端使用 vscode的时候会做格式匹配，在手机上，txt格式基本都能支持

内容特殊用法

给 H1-H5 标签添加 ID 锚点 name

添加锚点方法

## 关于我们
{: #about}

生成 HTML 的结果

<h2 id="about">关于我们</h2>

给 p 和其他 HTML 块标签添加自定义 Class

{: .bg-blue}
这个段落添加自定义 Class .bg-blue（样式：蓝色背景）

Markdown 解析后的代码结构

<p class="bg-blue">
这个段落添加自定义 Class .bg-blue（样式：蓝色背景）
</p>


### 引用文件路径自动获取文件的固定连接（permalink）

这个方法的好处在于，如果你修改了某个文件的固定连接 permalink ，之前链接到这个文件的页面都需要手动修改链接，而使用这个方法生成 HTML 时会自动使用最新的 permalink 。

````markdown
<a href="{% link _docs/index.md %}">文档</a>
``

## 让链接从新窗口打开

在链接后面增加`{:target="_blank"}`即可

```markdown
[https://1px.run](https://1px.run){:target="_blank"}

生成的 HTML

<a href="https://1px.run" target="_blank">https://1px.run</a>

数据文件

数据文件和模板结合，复用或者数据模块化

页面代码（模板）

通过 docs_variables_table 模板渲染 data.jekyll_variables 数据文件中的 site 内容（对数据进行分类，然后按类别读取并嵌套模板）。以下示例摘自 jekyll/docs。

{% include docs_variables_table.html scope=site.data.jekyll_variables.site %}

引用模板 _include/docs_variables_table.html

<table>
  <thead>
    <tr>
      <th>Variable</th>
      <th>Description</th>
    </tr>
  </thead>
  <tbody>
  {% for var in include.scope -%}
    <tr>
      <td><p><code>{{ var.name }}</code></p></td>
      <td><p>{{- var.description -}}</p></td>
    </tr>
  {% endfor -%}
  </tbody>
</table>

数据文件 _data/jekyll_variables

global:
  - name: site
    description:  整个站点的信息和配置
site:
  - name: site.time
    description: 运行 jekyll 命令时的时间
page:
  - name: page.title
    description: 页面标题。

模板优化

获取文字字数和阅读所需时间

<div class="post-meta">
    <span>本文共 {{ page.content | strip_html | strip_newlines | remove: " " | size }} 字 <b>·</b> 阅读大约需要 {{ page.content | strip_html | strip_newlines | remove: " " | size | divided_by: 350 | plus: 1 }} 分钟</span>
</div>

Jekyll 笔记

Jekyll 相关资源整理

Windows 安装 Jekyll

MacOS 安装

文件夹安装

全局安装

查看当前版本

升级 jekyll

参考资料

升级 bundler 版本

环境搭建

jekyll new myblog 全新安装

clone 安装 本地编译并运行

本地生成静态 HTML 和对应资源文件

ruby3.0 运行 jekyll 报错

说明

模板

输出全部页面（页面导航）

按分类输出该各分类下所有内容

仅输出全部分类（不含链接）

输出全部标签（标签云）

注释掉页面代码或内容 {% comment %}

slug

引入模板文件

include 验证支持的文件格式

通过 front matter 或 _data 使用 include 和 include_relative

通过 front matter 配置 include_relative

通过 _data 中的 csv 或 yml 配置 include

md文件避免执行liquid代码片段导致报错

YAML 使用技巧

单独调用 YAML 指定的一个参数的值

include 语句或 include 文件中使用页面变量

include 参数传递到包括的结构

include 参数传递变量而不是字符串

assign 创建变量重复使用

capture 指定内容重复使用

include_relative 引用当前文件目录下的文件 相对路径链接

include 相关文档

通过文章、页面头信息访问yml数据中指定内容

yml数据中全部内容

操作符

操作符 一个 if 判断多个运算条件

使用 else 实现不包含 not contains

使用 unless 实现不包含 not contains

数据类型

条件判断

判断参数不存在时使用制定值

排序

strip_html 删除字符串中html标记

newline_to_br 换行符转为html代码<br>

strip_newlines 删除字符串中换行符

remove 移除字符串中指定内容

remove_first 移除字符串中指定内容只操作一次

prepend 指定内容前插入内容

replace 替换内容中指定的内容

replace_first 只替换一次内容中的指定内容

reverse 反转数值或字符串中内容

last 提取数值或字符串中最后的内容

url_decode 将 URL 编码字符转为字符串

url_encode 将字符串转为 URL 编码字符

upcase 将字符串中的英文字母转为大写

downcase 将字符串中 英文字母转为小写

truncatewords 按单词截断字符串内容并添加自定义省略符号

truncate 按字符串字符截断

数值计算

加法

minus 减法

times 乘法

divided_by 除法

生成相对路径链接或者绝对路径链接

自定义省略号

自定义日期格式

date_to_string 将日期转为短格式

无法比较数据或计算输出内容

collections 功能 （集合）

通过页内 front matter 的 YAML 列表输出在页面列表中

标签功能实现，自动生成标签页面

列表页分页说明

文章摘要调用和手动切割摘要的分隔符

模板构建

clone 安装本地编译并运行

include_relative 引用当前文件目录下的文件相对路径链接

操作符一个 if 判断多个运算条件

newline_to_br 换行符转为html代码`<br>`

downcase 将字符串中英文字母转为小写

collections 功能（集合）