Post

如何写一个帖子

Posted Updated
By xpluspro
19 min read
如何写一个帖子

如何写一个帖子

在仓库的主文件夹下找到.post这个子文件夹，在这里面创建创建一个名为 YYYY-MM-DD-TITLE.EXTENSION 的新文件。请注意，EXTENSION 必须是 md 或 markdown 之一。如果想节省创建文件的时间，可以考虑使用 Jekyll-post 插件来完成此操作。

在vscode中安装这个插件之后，在资源管理器中右键.post文件夹就会有一个New post的选项，就可以更简单的创建新帖子

具体怎么写的内容可以从https://chirpy.cotes.page/posts/write-a-new-post/#naming-and-path 中获取，以下提供中文版仅做备份

本教程将指导你如何在Chirpy模板中撰写文章。即便你之前使用过Jekyll，也值得一读，因为许多功能需要设置特定的变量。

命名与路径

新建一个文件，命名格式为<YYYY-MM-DD-TITLE.EXTENSION>，并将其放在根目录的_posts文件夹中。请注意，<EXTENSION>必须是md或markdown其中之一。如果你想节省创建文件的时间，可以考虑使用Jekyll-Compose插件来完成此操作。

文章头部信息（Front Matter）

基本上，你需要在文章顶部按如下格式填写文章头部信息：

1
2
3
4
5
6

---
title: TITLE
date: YYYY-MM-DD HH:MM:SS +/-TTTT
categories: [TOP_CATEGORIE, SUB_CATEGORIE]
tags: [TAG]     # TAG名称应始终为小写
---

文章的布局默认设置为post，所以无需在文章头部信息块中添加layout变量。

日期的时区

为了准确记录文章的发布日期，你不仅要在_config.yml中设置timezone，还需要在文章头部信息块的date变量中指定文章的时区。格式为：<+/-TTTT>，例如<+0800>。

分类和标签

每篇文章的categories最多包含两个元素，而tags中的元素数量可以是0到任意多个。例如：

1
2
3
4

---
categories: [动物, 昆虫]
tags: [蜜蜂]
---

作者信息

文章的作者信息通常无需在文章头部信息中填写，默认会从配置文件中的social.name变量和social.links的第一个条目获取。不过，你也可以通过以下方式覆盖默认设置： 在_data/authors.yml中添加作者信息（如果你的网站没有这个文件，可随时创建一个）。

1
2
3
4

<author_id>:
  name: <全名>
  twitter: <作者的推特账号>
  url: <作者的主页>

然后使用author指定单个作者，或使用authors指定多个作者：

1
2
3
4
5

---
author: <author_id>                     # 指定单个作者
# 或者
authors: [<author1_id>, <author2_id>]   # 指定多个作者
---

需要说明的是，author键也可以指定多个作者。 从_data/authors.yml文件读取作者信息的好处是，页面会有twitter:creator元标签，这能丰富Twitter卡片信息，有利于搜索引擎优化（SEO）。

文章描述

默认情况下，文章的开头部分内容会显示在主页的文章列表、“进一步阅读”部分以及RSS订阅的XML文件中。如果你不想显示自动生成的文章描述，可以在文章头部信息中使用description字段进行自定义，如下所示：

1
2
3

---
description: 文章的简短摘要。
---

此外，description的内容也会显示在文章页面的标题下方。

目录

默认情况下，目录（TOC）会显示在文章的右侧面板。如果你想全局关闭目录功能，可以前往_config.yml，将toc变量的值设置为false。如果你只想关闭某篇特定文章的目录，可以在该文章的头部信息中添加以下内容：

1
2
3

---
toc: false
---

评论

评论的全局设置由_config.yml文件中的comments.provider选项定义。一旦为该变量选择了评论系统，所有文章都将启用评论功能。 如果你想关闭某篇特定文章的评论，可以在文章的头部信息中添加以下内容：

1
2
3

---
comments: false
---

媒体

在Chirpy中，我们将图片、音频和视频统称为媒体资源。

URL前缀

有时，我们需要为文章中的多个资源定义重复的URL前缀，这是一项繁琐的任务，不过可以通过设置两个参数来避免。 如果你使用CDN来托管媒体文件，可以在_config.yml中指定cdn。这样，网站头像和文章的媒体资源URL将以CDN域名作为前缀。

1

cdn: https://cdn.com

要为当前文章/页面范围指定资源路径前缀，可以在文章的头部信息中设置media_subpath：

1
2
3

---
media_subpath: /path/to/media/
---

site.cdn和page.media_subpath这两个选项可以单独使用，也可以组合使用，灵活地构建最终的资源URL：[site.cdn/][page.media_subpath/]file.ext

图片

图片说明

在图片的下一行添加斜体文字，它就会成为图片说明，并显示在图片底部：

1
2
3

![图片描述](/path/to/image)

*图片说明*

图片尺寸

为防止图片加载时页面内容布局发生变化，我们应该为每张图片设置宽度和高度。

1

![桌面视图](/assets/img/sample/mockup.png){: width="700" height="400" }

对于SVG图片，你至少需要指定其宽度，否则它将无法渲染。 从Chirpy v5.0.0版本开始，height和width支持缩写形式（height → h，width → w ）。以下示例与上述代码效果相同：

1

![桌面视图](/assets/img/sample/mockup.png){: w="700" h="400" }

图片位置

默认情况下，图片是居中显示的，但你可以使用normal、left和right这几个类来指定图片位置。 一旦指定了图片位置，就不应再添加图片说明。

  • 正常位置：
    1

    ![桌面视图](/assets/img/sample/mockup.png){: .normal }
  • 左对齐：
    1

    ![桌面视图](/assets/img/sample/mockup.png){: .left }
  • 右对齐：
    1

    ![桌面视图](/assets/img/sample/mockup.png){: .right }

    暗黑/明亮模式

    你可以让图片根据暗黑/明亮模式的主题偏好进行显示。这需要你准备两张图片，一张用于暗黑模式，一张用于明亮模式，然后为它们分别指定特定的类（dark或light）：

    1
2

    ![仅在明亮模式显示](/path/to/light-mode.png){: .light }
![仅在暗黑模式显示](/path/to/dark-mode.png){: .dark }

    阴影效果

    程序窗口的截图可以添加阴影效果：

    1

    ![桌面视图](/assets/img/sample/mockup.png){: .shadow }

    预览图片

    如果你想在文章顶部添加一张图片，请提供分辨率为1200 x 630的图片。请注意，如果图片的宽高比不符合1.91 : 1，图片将被缩放和裁剪。 了解这些前提条件后，你就可以开始设置图片的属性了：

    1
2
3
4
5

    ---
image:
path: /path/to/image
alt: 图片替代文本
---

    请注意，media_subpath也可以应用于预览图片，也就是说，如果已经设置了media_subpath，path属性只需填写图片文件名即可。 为了简化使用，你也可以直接使用image来定义图片路径：

    1
2
3

    ---
image: /path/to/image
---

    LQIP（低质量图像占位符）

  • 对于预览图片：
    1
2
3
4

    ---
image:
lqip: /path/to/lqip-file # 或base64编码的URI
---

    你可以在“文本与排版”这篇文章的预览图片中观察LQIP效果。

  • 对于普通图片：
    1

    ![图片描述](/path/to/image){: lqip="/path/to/lqip-file" }

视频

社交媒体平台视频

你可以使用以下语法嵌入来自社交媒体平台的视频：

1

{% include embed/{Platform}.html id='{ID}' %}

其中，<Platform>是平台名称的小写形式，<ID>是视频ID。 以下表格展示了如何从给定的视频URL中获取所需的两个参数，同时你也可以了解到当前支持的视频平台。 | 视频URL | 平台 | ID | | ——————————————- | ———- | ————– | | https://www.youtube.com/watch?v=H-B46URT4mg | youtube | H-B46URT4mg | | https://www.twitch.tv/videos/1634779211 | twitch | 1634779211 | | https://www.bilibili.com/video/BV1Q44y1B7Wf | bilibili | BV1Q44y1B7Wf |

视频文件

如果你想直接嵌入视频文件，可以使用以下语法：

1

{% include embed/video.html src='{URL}' %}

其中，<URL>是视频文件的URL，例如/path/to/sample/video.mp4。 你还可以为嵌入的视频文件指定其他属性。以下是允许的完整属性列表：

  • poster='/path/to/poster.png' —— 视频下载时显示的海报图片
  • title='Text' —— 视频下方显示的标题，样式与图片标题相同
  • autoplay=true —— 视频一旦准备好就自动播放
  • loop=true —— 视频播放到结尾时自动回到开头
  • muted=true —— 音频初始时静音
  • types —— 指定其他视频格式的扩展名，用|分隔。确保这些文件与主视频文件在同一目录下。 以下是使用上述所有属性的示例：
    1
2
3
4
5
6
7
8
9
10

    {%
include embed/video.html
src='/path/to/video.mp4'
types='ogg|mov'
poster='poster.png'
title='演示视频'
autoplay=true
loop=true
muted=true
%}

音频

如果你想直接嵌入音频文件，可以使用以下语法：

1

{% include embed/audio.html src='{URL}' %}

其中，<URL>是音频文件的URL，例如/path/to/audio.mp3。 你还可以为嵌入的音频文件指定其他属性。以下是允许的完整属性列表：

  • title='Text' —— 音频下方显示的标题，样式与图片标题相同
  • types —— 指定其他音频格式的扩展名，用|分隔。确保这些文件与主音频文件在同一目录下。 以下是使用上述所有属性的示例：
    1
2
3
4
5
6

    {%
include embed/audio.html
src='/path/to/audio.mp3'
types='ogg|wav|aac'
title='演示音频'
%}

置顶文章

你可以将一篇或多篇文章置顶在主页顶部，置顶文章会根据发布日期倒序排列。在文章头部信息中添加以下内容即可启用置顶功能：

1
2
3

---
pin: true
---

提示框

提示框有几种类型：tip（提示）、info（信息）、warning（警告）和danger（危险）。在blockquote标签中添加prompt-{type}类，即可生成相应类型的提示框。例如，定义一个info类型的提示框如下：

1
2

> 提示框示例内容。
{: .prompt-info }

语法

行内代码

1

`行内代码部分`

文件路径高亮

1

`/path/to/a/file.extend`{: .filepath}

代码块

使用Markdown符号````即可轻松创建代码块，如下所示：

1

这是一个纯文本代码片段。
  
1

指定语言
使用````{language}```，你将得到一个带有语法高亮的代码块：
  
1
2

```yaml
key: value

  
1
2
3
4
5
6
7

Jekyll标签`{% highlight %}`与本主题不兼容。

### 行号
默认情况下，除了`plaintext`、`console`和`terminal`这几种语言，其他语言的代码块都会显示行号。如果你想隐藏某个代码块的行号，可以为其添加`nolineno`类：
```markdown
```shell
echo '不再显示行号！'

  
1
2
3
4
5

### 指定文件名
你可能已经注意到，代码块顶部会显示代码语言。如果你想用文件名替换它，可以添加`file`属性来实现：
```markdown
```shell
# 内容

  
1
2
3
4
5
6
7
8

### Liquid代码
如果你想显示Liquid代码片段，可以用`{% raw %}`和`{% endraw %}`将Liquid代码括起来：
```liquid
{% raw %}
```liquid
{% if product.title contains 'Pack' %}
  该产品的标题包含“Pack”这个词。
{% endif %}

{% endraw %}
  
1
2
3
4
5
6
7
8

或者在文章的YAML块中添加`render_with_liquid: false`（需要Jekyll 4.0或更高版本）。

### 数学公式
我们使用MathJax来生成数学公式。出于网站性能考虑，数学公式功能默认不会加载。但可以通过以下方式启用：
```yaml
---
math: true
---

启用数学公式功能后，你可以使用以下语法添加数学公式：
  • 块级公式应使用$$ math $$添加，且在$$前后必须有空白行
  • 插入公式编号应使用$$\begin{equation} math \end{equation}$$
  • 引用公式编号时，在公式块中使用\label{eq:label_name}，在文本中使用\eqref{eq:label_name}（见以下示例）
  • 行内公式（在段落中）应使用$$ math $$添加，且$$前后不能有空白行
  • 行内公式（在列表中）应使用\$$ math $$添加
  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

<!-- 块级公式，保留所有空白行 -->
$$
LaTeX数学表达式
$$

<!-- 公式编号，保留所有空白行  -->
$$
\begin{equation}
  LaTeX数学表达式
  \label{eq:label_name}
\end{equation}
$$
可引用为\eqref{eq:label_name}。

<!-- 行内公式（在段落中），无空白行 -->
“Lorem ipsum dolor sit amet, $$ LaTeX数学表达式 $$ consectetur adipiscing elit.”

<!-- 行内公式（在列表中），转义第一个`$` -->
1. \$$ LaTeX数学表达式 $$
2. \$$ LaTeX数学表达式 $$
3. \$$ LaTeX数学表达式 $$

从v7.0.0版本开始，MathJax的配置选项已移至assets/js/data/mathjax.js文件，你可以根据需要更改这些选项，例如添加扩展。 如果你是通过chirpy-starter构建网站，可以使用bundle info --path jekyll-theme-chirpy命令查看gem安装目录，然后将该文件复制到你仓库的相同目录下。
Mermaid图表
Mermaid是一个很棒的图表生成工具。要在文章中启用它，可在YAML块中添加以下内容：
  
1
2
3

---
mermaid: true
---

然后你就可以像使用其他Markdown语言一样使用它：用mermaid```和将图表代码括起来。
 This post is licensed under  CC BY 4.0  by the author.