文章

如何在 Chirpy 使用 Markdown 撰写文章

发表于 更新于
Chirpy 主题在多平台上的响应式渲染。
Chirpy 主题在多平台上的响应式渲染。
作者 CashewTeam
21 分钟阅读
如何在 Chirpy 使用 Markdown 撰写文章

简单翻译并改进一下官方的文档，方便我后续用Markdown写文章。
本教程将指导您如何在 Chirpy 模板中撰写文章，即使您以前使用过 Jekyll，也值得阅读，因为许多功能需要特殊的设置。

文件名与路径

创建一个名为 YYYY-MM-DD-TITLE.md的文件，并将其放在根目录的 _posts中 如果您想节省创建文件的时间，请考虑使用插件 Jekyll-Compose 来实现此目的。

前置文本

你需要在文章顶部填写如下的 Front Matter：

1
2
3
4
5
6
7
8
9

---
title: 标题
date: 2024-09-29 14:10:00 +0800
categories: [主分类, 子分类]
tags: [标签]     # TAG 名称应始终为小写，但实测好像不需要
image:
  path: /path/to/image
  alt: 图片描述文本
---

帖子的 layout 已默认设置为 post，因此无需在 Front Matter 中再添加变量 layout。

时区与日期

为了准确记录文章的发布日期，您不仅应该设置 _config.yml 的 timezone，还应该在 前置文本 的 date 变量中提供文章的时区。格式：+/-TTTT，例如 +0800。

类别与标签

每个帖子的categories最多包含两个元素，tags中的元素数量可以是零到无穷大。例如：

1
2
3
4

---
categories: [Animal, Insect]
tags: [bee]
---

作者信息

文章的作者信息通常不需要填写在 Front Matter 中，它们会默认从变量 social.name 和配置文件的 social.links 第一个条目中获取。但你也可以按如下方式覆盖它：

在 _data/authors.yml 中添加作者信息（如果您的网站没有此文件，请毫不犹豫地创建一个）。

1
2
3
4

<author_id>:
  name: <full name>
  twitter: <twitter_of_author>
  url: <homepage_of_author>

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

1
2
3
4
5

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

话虽如此，值author也可以识别多个条目。

从文件 _data/authors.yml 中读取作者信息的好处是，页面会带有元标记 twitter:creator，丰富了 Twitter Cards，有利于搜索引擎优化。

文章概述

默认情况下，文章的第一段话会显示在帖子列表的主页上、Further Reading 部分以及 RSS 源的 XML 中。如果您不想显示帖子的自动生成描述，可以使用_Front Matter_ 中的description字段对其进行自定义，如下所示：

1
2
3

---
description: Short summary of the post.
---

此外，description 文本也将显示在帖子页面的帖子标题下。

目录

默认情况下，目录（TOC）显示在帖子的右侧面板上。如果要全局关闭，请在 _config.yml 并将变量 toc 的值设置为 false。如果要关闭特定帖子的目录，请在帖子的 Front Matter 中添加以下内容：

1
2
3

---
toc: false
---

评论区

评论的全局开关由文件 _config.yml 中的变量 comments.active 定义。为该变量选择评论系统后，将为所有帖子打开评论。

如果您想关闭特定帖子的评论，请在帖子的 Front Matter 中添加以下内容：

1
2
3

---
comments: false
---

置顶文章

您可以将一个或多个帖子固定在主页顶部，固定帖子根据其发布日期以相反的顺序排序。通过以下方式启用：

1
2
3

---
pin: true
---

文章头图

如果您想在帖子顶部添加图像，请提供分辨率为 1200 x 630. 请注意，如果图像长宽比不符合 1.91 : 1，图像将被缩放和裁剪。

了解这些先决条件后，您可以开始设置图像的属性：

1
2
3
4
5

---
image:
  path: /path/to/image
  alt: 图片描述文本
---

注意 [URL前缀] 也可以传递给文章头图，设置好后，属性 path 只需要图像文件名。

为了简单使用，您也可以只使用 image 定义路径。

1
2
3

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

LQIP

对于预览图像：

1
2
3
4

---
image:
  lqip: /path/to/lqip-file # or base64 URI
---

您可以在这篇帖子的预览图像中查看LQIP的使用 "Text and Typography".

对于一般图像：

1

![Image description](/path/to/image){: lqip="/path/to/lqip-file" }

标题

示例，仅H2、H3标题会被添加至目录。

H1 — 标题

H2 — 标题

H3 — 标题

H4 — 标题

1
2
3
4

# H1 — 标题
## H2 — 标题
### H3 — 标题
#### H4 — 标题

正文

换行符

1

<br />

文本样式

块引用/斜体

This line shows the 斜体. 第二行 第三行

1
2
3

> This line shows the _斜体_.
  第二行
> 第三行

加粗

1

**加粗**

划除

1

~~划除~~

行内代码

这是一个 行内代码的示例

1

这是一个 `行内代码`的示例<br />

文件路径

这是一个文件路径 /path/to/the/file.extend.

1

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

链接

http://127.0.0.1:4000 标题

1
2

<http://127.0.0.1:4000>
[标题](http://127.0.0.1:4000)

脚注

点击角标将跳转到脚注1，这是另一个脚注2。

1

文本[^footnote]  文本[^fn-nth-2]

列表

有序列表

  1. 第一
  2. 第二
  3. 第三
1
2
3

1. 第一
2. 第二
3. 第三

无序列表

  • Chapter
    • Section
      • Paragraph
  • 第一
1
2
3
4

- Chapter
  - Section
    - Paragraph
* 第一

ToDo 列表

  • 任务
    • 步骤 1
    • 步骤 2
    • 步骤 3
1
2
3
4

- [ ] 任务
  - [x] 步骤 1
  - [x] 步骤 2
  - [ ] 步骤 3

描述列表

Sun
the star around which the earth orbits
Moon
the natural satellite of the earth, visible by reflected light from the sun
1
2
3
4

Sun
: the star around which the earth orbits
Moon
: the natural satellite of the earth, visible by reflected light from the sun

表格

CompanyContactCountry
Alfreds FutterkisteMaria AndersGermany
Island TradingHelen BennettUK
Magazzini Alimentari RiunitiGiovanni RovelliItaly
1
2
3
4
5

| Company                      | Contact          | Country |
| :--------------------------- | :--------------- | ------: |
| Alfreds Futterkiste          | Maria Anders     | Germany |
| Island Trading               | Helen Bennett    |      UK |
| Magazzini Alimentari Riuniti | Giovanni Rovelli |   Italy |

提示文本

有几种类型的提示： tip, info, warning, danger。它们可以通过添加 prompt-{type} 让文本变为提示文本。以下为提示文本示例。

An example showing the 提示 type prompt.

An example showing the 信息 type prompt.

An example showing the 警告 type prompt.

An example showing the 危险 type prompt.

1
2
3
4
5
6
7
8
9
10
11
12

> 提示文本.
> An example showing the `提示` type prompt.
{: .prompt-tip }

> An example showing the `信息` type prompt.
{: .prompt-info }

> An example showing the `警告` type prompt.
{: .prompt-warning }

> An example showing the `危险` type prompt.
{: .prompt-danger }

媒体资源

在 Chirpy 中，我们将图像、音频和视频称为媒体资源（Media）。

URL前缀

有时我们必须为帖子中的多个资源定义重复的URL前缀，这是一项无聊的任务，您可以通过设置两个参数来避免。

  • 如果您使用CDN来托管媒体文件，您可以在_config. yml{：.filepath}中指定CDN。网站头像和帖子的媒体资源URL随后以CDN域名为前缀。

    1

    cdn: https://cdn.com

  • 要指定当前帖子/页面范围的资源路径前缀，在当前文章的 front matter 中设置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

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

大小

为了防止加载图像时页面内容布局发生移动，我们应该为每个图像设置宽度和高度。

1

![Desktop View](/assets/img/sample/mockup.png){: width="700" height="400" }

对于SVG，您必须至少指定其 width (宽度)，否则将无法显示。

从 Chirpy v5.0.0 开始， height 与 width 支持缩写 (height → h, width → w). 以下示例与上述效果相同：

1

![Desktop View](/assets/img/sample/mockup.png){: w="700" h="400" }

位置

默认情况下，图像居中，但您可以使用其中一个类来指定位置 normal, left, and right.

指定位置后，不应添加图片描述。

  • 左对齐

    图像将在下面的示例中保持对齐：

    1

    ![Desktop View](/assets/img/sample/mockup.png){: .normal }

  • 浮在左侧

    1

    ![Desktop View](/assets/img/sample/mockup.png){: .left }

  • 浮在右侧

    1

    ![Desktop View](/assets/img/sample/mockup.png){: .right }

深色/亮色模式

您可以在深色/亮色模式下使图像遵循主题偏好。这需要您准备两张图像，一张用于暗模式，一张用于亮模式，然后为它们分配一个特定的类 (dark or light):

1
2

![Light mode only](/path/to/light-mode.png){: .light }
![Dark mode only](/path/to/dark-mode.png){: .dark }

阴影

程序窗口的截图可以考虑显示阴影效果：

1

![Desktop View](/assets/img/sample/mockup.png){: .shadow }

效果预览

默认（带图片描述）

Desktop View 全屏宽度和中心对齐

左对齐

Desktop View

浮在左侧

Desktop View Praesent maximus aliquam sapien. Sed vel neque in dolor pulvinar auctor. Maecenas pharetra, sem sit amet interdum posuere, tellus lacus eleifend magna, ac lobortis felis ipsum id sapien. Proin ornare rutrum metus, ac convallis diam volutpat sit amet. Phasellus volutpat, elit sit amet tincidunt mollis, felis mi scelerisque mauris, ut facilisis leo magna accumsan sapien. In rutrum vehicula nisl eget tempor. Nullam maximus ullamcorper libero non maximus. Integer ultricies velit id convallis varius. Praesent eu nisl eu urna finibus ultrices id nec ex. Mauris ac mattis quam. Fusce aliquam est nec sapien bibendum, vitae malesuada ligula condimentum.

浮在右侧

Desktop View Praesent maximus aliquam sapien. Sed vel neque in dolor pulvinar auctor. Maecenas pharetra, sem sit amet interdum posuere, tellus lacus eleifend magna, ac lobortis felis ipsum id sapien. Proin ornare rutrum metus, ac convallis diam volutpat sit amet. Phasellus volutpat, elit sit amet tincidunt mollis, felis mi scelerisque mauris, ut facilisis leo magna accumsan sapien. In rutrum vehicula nisl eget tempor. Nullam maximus ullamcorper libero non maximus. Integer ultricies velit id convallis varius. Praesent eu nisl eu urna finibus ultrices id nec ex. Mauris ac mattis quam. Fusce aliquam est nec sapien bibendum, vitae malesuada ligula condimentum.

暗/光模式和阴影

下图将根据主题偏好切换深色/浅色模式，请注意它有阴影。

light mode only dark mode only

视频

社交媒体平台

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

1

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

Platform 是平台名，ID为视频ID。

下表显示了如何在给定的视频URL中获取我们需要的两个参数，您还可以了解当前支持的视频平台。

Video URLPlatformID
https://www.youtube.com/watch?v=H-B46URT4mgyoutubeH-B46URT4mg
https://www.twitch.tv/videos/1634779211twitch1634779211
https://www.bilibili.com/video/BV1Q44y1B7WfbilibiliBV1Q44y1B7Wf
示例：
1

{% include embed/bilibili.html id='BV1X4411Z7rj' %}

视频文件

如果要直接嵌入视频文件，请使用以下语法：

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='Demo video'
  autoplay=true
  loop=true
  muted=true
%}

音频

如果要直接嵌入音频文件，请使用以下语法：

1

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

Where URL is a URL to an audio file e.g. /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='Demo audio'
%}

代码

行内代码

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 %} 与此主题不兼容。

行号

默认情况下，所有语言，除了 plaintext, console, terminal 将显示行号。当您想隐藏代码块的行号时，添加类 nolineno

1
2
3
4

```shell
echo 'No more line numbers!'
```
{: .nolineno }

指定文件名

您可能已经注意到代码语言将显示在代码块的顶部。如果要将其替换为文件名，可以添加属性file来实现：

1
2
3
4

```shell
# content
```
{: file="path/to/file" }

Liquid 代码

如果要显示Liquid 代码段（视频和音频使用Liquid 代码），请用 {% raw %} 和 {% endraw %} 将 Liquid 代码括起来：

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 或更高版本） 添加到帖子的 YAML 块。

数学公式

我们使用MathJax生成数学公式。出于网站性能原因，默认情况下不会加载数学功能。但它可以通过以下方式启用：

1
2
3

---
math: true
---

启用数学公式后，您可以使用以下语法添加数学方程：

  • Block math should be added with $$ math $$ with mandatory blank lines before and after $$
    • Inserting equation numbering should be added with $$\begin{equation} math \end{equation}$$
    • Referencing equation numbering should be done with \label{eq:label_name} in the equation block and \eqref{eq:label_name} inline with text (see example below)
  • Inline math (in lines) should be added with $$ math $$ without any blank line before or after $$
  • Inline math (in lists) should be added with \$$ math $$
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

<!-- Block math, keep all blank lines -->

$$
LaTeX_math_expression
$$

<!-- Equation numbering, keep all blank lines  -->

$$
\begin{equation}
  LaTeX_math_expression
  \label{eq:label_name}
\end{equation}
$$

Can be referenced as \eqref{eq:label_name}.

<!-- Inline math in lines, NO blank lines -->

"Lorem ipsum dolor sit amet, $$ LaTeX_math_expression $$ consectetur adipiscing elit."

<!-- Inline math in lists, escape the first `$` -->

1. \$$ LaTeX_math_expression $$
2. \$$ LaTeX_math_expression $$
3. \$$ LaTeX_math_expression $$

从v7.0.0开始，MathJax的配置选项已移至文件 assets/js/data/mathjax.js，您可以根据需要更改选项，例如添加 extensions.
如果您通过以下方式构建网站 chirpy-starter，将该文件从gem安装目录（使用命令bundle info--path jekyll-they-chirpy检查）复制到存储库中的同一目录。

The mathematics powered by MathJax:

\(\begin{equation} \sum_{n=1}^\infty 1/n^2 = \frac{\pi^2}{6} \label{eq:series} \end{equation}\) We can reference the equation as \eqref{eq:series}. When $a \ne 0$, there are two solutions to $ax^2 + bx + c = 0$ and they are \(x = {-b \pm \sqrt{b^2-4ac} \over 2a}\)

示例代码：

1
2
3
4
5
6
7
8
9

$$
\begin{equation}
  \sum_{n=1}^\infty 1/n^2 = \frac{\pi^2}{6}
  \label{eq:series}
\end{equation}
$$
We can reference the equation as \eqref{eq:series}.
When $a \ne 0$, there are two solutions to $ax^2 + bx + c = 0$ and they are
$$ x = {-b \pm \sqrt{b^2-4ac} \over 2a} $$

Mermaid

Mermaid 是一个很棒的图表生成工具。要在您的帖子中启用它，请将以下内容添加到YAML块中：

1
2
3

---
mermaid: true
---

然后你可以像其他 Markdown 语言一样使用它：
```mermaid
```
示例：

 gantt
  title  Adding GANTT diagram functionality to mermaid
  apple :a, 2017-07-20, 1w
  banana :crit, b, 2017-07-23, 1d
  cherry :active, c, after b a, 1d

代码

了解更多

翻译：Con幺幺、豆包、Google。

有关Jekyll帖子的更多知识，请访问 Jekyll Docs: Posts.
原文1
原文2

Reverse Footnote

  1. The footnote source ↩︎

  2. The 2nd footnote source ↩︎

网络, 建站
jekyll Markdown
本文由作者按照 CC BY 4.0 进行授权