这篇文章将告诉你如何基于 Chirpy 来写文章，即便你以前使用过 Jekyll 也值得一读，因为许多功能都需要设置特定的变量。
1️⃣ 新建文章
在根目录的 _posts 文件夹中，创建一个新的文件并以 YYYY-MM-DD-TITLE.EXTENSION 这种格式命名。
其中的 EXTENSION 必须是 md 或者 markdown。
如果你想快速新建文章，可以考虑使用插件：Jekyll-Compose。
2️⃣ 顶部格式块
一、基本格式
每一篇文章，都需要在顶部写 顶部格式块，最基本的结构如下：
1
2
3
4
5
6
---
title: TITLE
date: YYYY-MM-DD HH:MM:SS +/-TTTT
categories: [TOP_CATEGORIE, SUB_CATEGORIE]
tags: [TAG] # TAG names should always be lowercase
---
文章的 layout 默认设置为
post，因此在 顶部格式块 中不需要添加 layout 变量。
二、日期的时区
为了准确记录文章的发布日期，在 _config.yml 设置 timezone 的同时，还得在 顶部格式块 的 date 变量中写上文章的时区。格式：+/-TTTT，例如：+0800。
三、分类和标签
顶部格式块 的 categories 变量最多包含两个元素，而 tags 变量包含的元素数量可以是0个，也可以任意个。例如：
1
2
3
4
---
categories: [Animal, Insect]
tags: [bee]
---
四、作者信息
文章的作者信息一般不需要在 顶部格式块 中再写一遍，默认会从配置文件的 social.name 以及 social.links 的第一个对象中获取。
但是你也可以通过以下操作进行覆盖：
1、在 _data/authors.yml 文件中按照以下格式填写作者信息，文件如果不存在则可以新建一个。
1
2
3
4
<author_id>:
name: <full name>
twitter: <twitter_of_author>
url: <homepage_of_author>
2、如果你想在指定的文章添加一个对象的话，请将 author 变量添加到 顶部格式块，如果想添加多个对象的话，则使用 authors 变量。当然，author 变量也是可以识别多个对象。
1
2
3
4
5
---
author: <author_id> # for single entry
# or
authors: [<author1_id>, <author2_id>] # for multiple entries
---
从
_data/authors.yml文件中读取作者信息的好处是页面将携带上标签twitter:creator，即完善了 Twitter Cards，这将有利于 SEO。
3️⃣ 目录
默认情况下，目录显示在文章的右侧面板上。
如果你想全局关闭它，需要在 _config.yml 文件中将 toc 变量设置为 false。
如果你想在指定的文章关闭它，需要把如下参数添加到 顶部格式块：
1
2
3
---
toc: false
---
4️⃣ 评论
默认情况下，评论功能由 _config.yml 文件中的 comments.active 变量控制。
当你为这个变量选择了一个评论系统后，全部文章都将开启评论功能。
如果你想在指定的文章关闭它，需要把如下参数添加到 顶部格式块：
1
2
3
---
comments: false
---
5️⃣ 数学展示能力
出于对站点性能的考虑，文章默认不加载数学展示能力。
如果你想在指定的文章使用它，需要把如下参数添加到 顶部格式块：
1
2
3
---
math: true
---
6️⃣ 流程图、时序图、甘特图
Mermaid 是一个很好用的图表生成工具。
如果你想在指定的文章使用它，需要把如下参数添加到 顶部格式块：
1
2
3
---
mermaid: true
---
然后你可以像 Markdown 一样使用它：用 ```mermaid 和 ``` 把图形代码括起来。
7️⃣ 图片
一、图片说明
将斜体文字添加到图片的下一行，相应的文字将成为图片的说明并出现在图片的底部：
1
2
_图片说明_
二、图片大小
为了防止页面内容布局在加载图片时移动，我们应该设置每个图片的宽度和高度。
1
{: width="700" height="400" }
对于 SVG，你必须至少指定其宽度，否则它将不会渲染出来。
从 Chirpy v5.0.0 开始，height 和 width 支持缩写（height → h, width → w）。以下示例跟上面的效果相同：
1
{: w="700" h="400" }
三、图片位置
默认情况下，图片是居中展示的，但是你也可以使用 normal、left 或 right 指定图片的位置，分别对应：左对齐、左浮动和右浮动。
指定图片位置后，图片说明就不能添加上了。
normal
1
{: .normal }
left
1
{: .left }
right
1
{: .right }
四、暗黑模式/明亮模式
你可以使图片在暗黑模式/明亮模式下根据主题切换，这需要准备两个图片，一个用于暗黑模式，一个用于明亮模式，然后为它们分别指定 dark 或 light：
1
2
{: .light }
{: .dark }
五、阴影
程序的截图可以考虑加上显示阴影效果：
1
{: .shadow }
六、CDN 配置
如果你的图片设置了通过 CDN 加载，可以在 _config.yml 中的 img_cdn 变量中配置上 CDN URL，则可以不需要再在图片路径前写 CDN URL ：
1
img_cdn: https://cdn.com
使用 img_cdn 变量后，所有以 / 开头的图片路径（包括站点头像、文章）前都会自动加上 CDN URL。
使用图片时如下所示：
1
自动在图片路径前添加 CDN 前缀 https://cdn.com，最终解析结果如下：
1
<img src="https://cdn.com/path/to/flower.png" alt="The flower">
七、图片路径
当文章包含许多图片时，重复定义图片的路径将是一项繁琐的事情。为了解决这个问题，可以把如下参数添加到 顶部格式块：
1
2
3
---
img_path: /img/path/
---
然后，Markdown 的图片源可以直接写入文件名：
1
输出结果将会是：
1
<img src="/img/path/flower.png" alt="The flower">
八、文章预览图片
如果你想在文章顶部添加图片，最佳分辨率为 1200 x 630。如果图片宽高比不符合 1.91 : 1，图片将会被缩放和裁剪。
了解这些前提条件后，你可以开始在 顶部格式块 设置当前文章预览图片的属性：
1
2
3
4
5
---
image:
path: /path/to/image
alt: image alternative text
---
注意，img_path 也可以传递给预览图片，也就是说，在设置好后，属性 path 只需要填写图片文件名。
为了简单使用，你也可以只用 image 变量。
1
2
3
---
image: /path/to/image
---
九、图片占位加载
文章图片可以设置占位加载的功能，可以理解成图片的 loading 过渡。
1、文章预览图片的占位加载
如果你想在指定的文章使用它，需要把如下参数添加到 顶部格式块：
1
2
3
4
---
image:
lqip: /path/to/lqip-file # or base64 URI
---
你可以在当前文章 文字和排版 的预览图像中查看效果。
2、文章普通图片的占位加载
1
{: lqip="/path/to/lqip-file" }
8️⃣ 置顶文章
你可以将一个或多个文章固定到首页的顶部，固定文章会根据其发布日期的倒序排序。
如果你想在指定的文章使用它，需要把如下参数添加到 顶部格式块:
1
2
3
---
pin: true
---
9️⃣ 提示
有四种类型的提示：tip、info、warning 和 danger。
可以通过设置 prompt-{type} 来使用它们。
例如，info 类型的提示如下所示：
1
2
> Example line for prompt.
{: .prompt-info }
1️⃣0️⃣ 计算机语言语法
一、行内代码
1
`inline code part`
二、文件路径高亮
1
`/path/to/a/file.extend`{: .filepath}
三、代码块
Markdown 的 ``` 符号可以轻松创建代码块，如下所示：
1
2
3
```
This is a plaintext code snippet.
```
四、特定的代码语言
使用 ```{language} 可以得到一个带有语法高亮显示的代码块：
1
2
3
```yaml
key: value
```
Jekyll 自带的
{% highlight %}语法跟当前主题不兼容。
1、行序号
默认情况下，除 plaintext、console 和 terminal 以外的所有语言都会显示行号。如果你要隐藏代码块的行号，可以设置 nolineno ：
1
2
3
4
```shell
echo '没有行序号!'
```
{: .nolineno }
2、特定的文件名称
你可能已经注意到，代码语言将显示在代码块的顶部。如果要将其替换为文件名，可以设置 file 并附上值：
1
2
3
4
```shell
# content
```
{: file="path/to/file" }
3、展示 Liquid 代码
如果要展示 Liquid 代码段，请在 liquid 代码两边加上 {% raw %} 和 {% endraw %}：
1
2
3
4
5
6
7
{% raw %}
```liquid
{% if product.title contains 'Pack' %}
This product's title contains the word Pack.
{% endif %}
```
{% endraw %}
或者把参数 render_with_liquid: false 添加到指定的文章的 顶部格式块，需要 Jekyll 4.0 或更高的版本。
1️⃣1️⃣ 视频
你可以使用以下语法嵌入视频：
1
{% include embed/{Platform}.html id='{ID}' %}
其中 Platform 需要用小写的平台名称替换，而 ID 则是各自平台的视频对应的 ID。
下表显示了如何在给定的视频 URL 中获取我们需要的两个参数以及当前支持的视频平台。
| Video URL | Platform | ID |
|---|---|---|
| https://www.youtube.com/watch?v=H-B46URT4mg | youtube | H-B46URT4mg |
| https://www.twitch.tv/videos/1634779211 | twitch | 1634779211 |
1️⃣2️⃣ 更多
访问 Jekyll Docs: Posts 可了解更多有关 Jekyll 文章的相关信息。