文章

官方文档中英双译

发表于 更新于
作者 宿浩 20 分钟阅读

#官方文档

本教程将指导您如何在 Chirpy 模板中编写帖子，即使您以前使用过Jekyll，也值得一读，因为许多功能都需要设置特定的变量。

This tutorial will guide you how to write a post in the Chirpy template, and it’s worth reading even if you’ve used Jekyll before, as many features require specific variables to be set.

Naming and Path ：命名和路径

创建一个名为YYYY-MM-DD-TITLE.EXTENSION的新文件，并将其放在根目录的_posts中。请注意，EXTENSION必须是md和markdown之一。如果你想节省创建文件的时间，请考虑使用插件Jekyll-Compose 来实现这一点。

Create a new file named YYYY-MM-DD-TITLE.EXTENSION and put it in the _posts of the root directory. Please note that the EXTENSION must be one of md and markdown. If you want to save time of creating files, please consider using the plugin Jekyll-Compose to accomplish this.

Front Matter ：前言

基本上，你需要在帖子顶部填写下面的Front Matter ：

Basically, you need to fill the Front Matter as below at the top of the post:

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
---

默认情况下，posts的布局已设置为post，因此无需在Front Matter块中添加可变布局。

The posts’ layout has been set to post by default, so there is no need to add the variable layout in the Front Matter block.

Timezone of Date ：日期时区

为了准确记录帖子的发布日期，您不仅应该设置_config.yml的timezone，还应该在其Front Matter块的可变日期中提供帖子的时区。格式：+/-TTTT，例如+0800。

In order to accurately record the release date of a post, you should not only set up the timezone of _config.yml but also provide the post’s timezone in variable date of its Front Matter block. Format: +/-TTTT, e.g. +0800.

Categories and Tags ：分类及标签

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

The categories of each post are designed to contain up to two elements, and the number of elements in tags can be zero to infinity. For instance:

1
2
3
4

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

Author Information ：作者信息

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

The author information of the post usually does not need to be filled in the Front Matter , they will be obtained from variables social.name and the first entry of social.links of the configuration file by default. But you can also override it as follows:

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

Adding author information in _data/authors.yml (If your website doesn’t have this file, don’t hesitate to create one).

1
2
3
4

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

然后使用author指定单个条目，或使用authors指定多个条目：

And then use author to specify a single entry or authors to specify multiple entries:

1
2
3
4
5

---
author: <author_id>                     # for single entry
# or
authors: [<author1_id>, <author2_id>]   # for multiple entries
---

话虽如此，关键作者还可以识别多个条目。

Having said that, the key author can also identify multiple entries.

从文件_data/authors.yml中读取作者信息的好处是，页面将具有元标签twitter:creator这丰富了Twitter Cards ，有利于SEO。

The benefit of reading the author information from the file _data/authors.yml is that the page will have the meta tag twitter:creator, which enriches the Twitter Cards and is good for SEO.

Table of Contents ：目录

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

By default, the Table of Contents (TOC) is displayed on the right panel of the post. If you want to turn it off globally, go to _config.yml and set the value of variable toc to false. If you want to turn off TOC for a specific post, add the following to the post’s Front Matter:

1
2
3

---
toc: false
---

Comments ：评论

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

The global switch of comments is defined by variable comments.active in the file _config.yml. After selecting a comment system for this variable, comments will be turned on for all posts.

如果你想关闭特定帖子的评论，请将以下内容添加到帖子的前言中：

If you want to close the comment for a specific post, add the following to the Front Matter of the post:

1
2
3

---
comments: false
---

Mathematics ：数学公式

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

For website performance reasons, the mathematical feature won’t be loaded by default. But it can be enabled by:

1
2
3

---
math: true
---

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

After enabling the mathematical feature, you can add math equations with the following syntax:

（翻译不明白，暂时也用不上，//TODO了昂）

  • Block math should be added with $$ math $$ with mandatory blank lines before and after $$
  • 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

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

$$
LaTeX_math_expression
$$

<!-- 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 $$

Mermaid ：美人鱼？

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

Mermaid is a great diagram generation tool. To enable it on your post, add the following to the YAML block:

1
2
3

---
mermaid: true
---

然后，您可以像使用其他标记语言一样使用它：用```mermaid和```包围图形代码。

Then you can use it like other markdown languages: surround the graph code with ```mermaid and ```.

Images ：图片

Caption ：说明文字

在图像的下一行添加斜体，然后它将成为标题并出现在图像的底部：

Add italics to the next line of an image, then it will become the caption and appear at the bottom of the image:

1
2

![img-description](/path/to/image)
_Image Caption_

Size ：大小

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

In order to prevent the page content layout from shifting when the image is loaded, we should set the width and height for each image.

1

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

对于SVG，您至少必须指定其宽度，否则将不会对其进行渲染。（蓝色框框）

For an SVG, you have to at least specify its width, otherwise it won’t be rendered.

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

Starting from Chirpy v5.0.0, height and width support abbreviations (height → h, width → w). The following example has the same effect as the above:

1

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

Position ：位置

默认情况下，图像居中，但可以使用normal、left和right类之一指定位置。

一旦指定了位置，就不应该添加图像标题。

By default, the image is centered, but you can specify the position by using one of the classes normal, left, and right.

Once the position is specified, the image caption should not be added.

  • Normal position ：正常位置

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

    Image will be left aligned in below sample:

    1

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

  • Float to the left ：向左浮动

    1

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

  • Float to the right ：向右浮动

    1

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

Dark/Light mode ：暗/亮模式

您可以在暗/亮模式下使图像遵循主题偏好。这需要您准备两个图像，一个用于暗模式，另一个用于亮模式，然后为它们指定一个特定类别(dark 或 light)：

You can make images follow theme preferences in dark/light mode. This requires you to prepare two images, one for dark mode and one for light mode, and then assign them a specific class (dark or light):

1
2

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

Shadow ：阴影

程序窗口的屏幕截图可以被认为显示了阴影效果：

The screenshots of the program window can be considered to show the shadow effect:

1

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

CDN URL ：CDN地址

如果您在CDN上托管图像，则可以通过分配_config.yml文件的变量img_cdn来节省重复写入CDN URL的时间：

If you host the images on the CDN, you can save the time of repeatedly writing the CDN URL by assigning the variable img_cdn of _config.yml file:

1

img_cdn: https://cdn.com

一旦分配了img_cdn，cdn URL将添加到以/开头的所有图像（网站头像和帖子的图像）的路径中。

Once img_cdn is assigned, the CDN URL will be added to the path of all images (images of site avatar and posts) starting with /.

例如，在使用图像时：

For instance, when using images:

1

![The flower](/path/to/flower.png)

解析结果会自动添加CDN前缀https://cdn.com在图像路径之前：

The parsing result will automatically add the CDN prefix https://cdn.com before the image path:

1

<img src="https://cdn.com/path/to/flower.png" alt="The flower">

Image Path ：图像路径

当一篇帖子包含许多图像时，重复定义图像的路径将是一项耗时的任务。为了解决这个问题，我们可以在帖子的YAML块中定义这个路径：

When a post contains many images, it will be a time-consuming task to repeatedly define the path of the images. To solve this, we can define this path in the YAML block of the post:

1
2
3

---
img_path: /img/path/
---

然后，Markdown的图像源可以直接写入文件名：

And then, the image source of Markdown can write the file name directly:

1

![The flower](flower.png)

输出将是：

The output will be:

1

<img src="/img/path/flower.png" alt="The flower">

Preview Image ：预览图像

如果你想在帖子顶部添加一张图片，请提供一张分辨率为1200 x 630的图片。请注意，如果图像纵横比不满足1.91:1，则图像将被缩放和裁剪。

If you want to add an image at the top of the post, please provide an image with a resolution of 1200 x 630. Please note that if the image aspect ratio does not meet 1.91 : 1, the image will be scaled and cropped.

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

Knowing these prerequisites, you can start setting the image’s attribute:

1
2
3
4
5

---
image:
  path: /path/to/image
  alt: image alternative text
---

comment: <> (Note that the [img_path](#image-path) can also be passed to the preview image, that is, when it has been set, the attribute path only needs the image file name. 路径指向文件不存在，报 internally linking to #image-path; the file exists, but the hash ‘image-path’ does not) Note that the img_path can also be passed to the preview image, that is, when it has been set, the attribute path only needs the image file name.

comment: <> (Note that the [img_path](#image-path) can also be passed to the preview image, that is, when it has been set, the attribute path only needs the image file name. 路径指向文件不存在，报 internally linking to #image-path; the file exists, but the hash ‘image-path’ does not) Note that the img_path can also be passed to the preview image, that is, when it has been set, the attribute path only needs the image file name.

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

For simple use, you can also just use image to define the path.

1
2
3

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

LQIP ：LQIP

对于预览图像：

For preview images:

1
2
3
4

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

您可以在post Text和Typography的预览图像中观察LQIP。

You can observe LQIP in the preview image of post Text and Typography.

对于正常图像：

For normal images:

1

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

Pinned Posts ：固定的帖子

你可以将一个或多个帖子固定在主页顶部，固定的帖子会根据发布日期按相反的顺序排列。启用方式：

You can pin one or more posts to the top of the home page, and the fixed posts are sorted in reverse order according to their release date. Enable by:

1
2
3

---
pin: true
---

Prompts ：鼓励

提示有几种类型：tip, info, warning, and danger。它们可以通过将类prompt-{type}添加到块引号中来生成。例如，定义类型为info的提示如下：

There are several types of prompts: tip, info, warning, and danger. They can be generated by adding the class prompt-{type} to the blockquote. For example, define a prompt of type info as follows:

1
2

> Example line for prompt.
{: .prompt-info }

Syntax ：语法

Inline Code ：内联代码

1

`inline code part`

Filepath Hightlight ：文件路径高亮

1

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

Code Block ：代码块

标记符号```可以很容易地创建如下代码块：

Markdown symbols ``` can easily create a code block as follows:

1
2
3

```
This is a plaintext code snippet.
```

Specifying Language ：指定语言

使用```{language}，您将获得一个带有语法突出显示的代码块：

Using ```{language} you will get a code block with syntax highlight:

1
2
3

```yaml
key: value
```

Jekyll标记{% highlight %}与此主题不兼容。

The Jekyll tag {% highlight %} is not compatible with this theme.

Line Number ：行编号

默认情况下，除plaintext明文、console控制台和terminal终端外的所有语言都将显示行号。如果要隐藏代码块的行号，请将类nolineno添加到其中：

By default, all languages except plaintext, console, and terminal will display line numbers. When you want to hide the line number of a code block, add the class nolineno to it:

1
2
3
4

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

Specifying the Filename ：指定文件名

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

You may have noticed that the code language will be displayed at the top of the code block. If you want to replace it with the file name, you can add the attribute file to achieve this:

1
2
3
4

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

Liquid Codes ：Liquid代码

如果您想显示Liquid代码段，请用{% raw %}和{% endraw %}包围Liquid代码：

If you want to display the Liquid snippet, surround the liquid code with {% raw %} and {% 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或更高版本）添加到帖子的YAML块中。

Or adding render_with_liquid: false (Requires Jekyll 4.0 or higher) to the post’s YAML block.

Videos ：视频

您可以使用以下语法嵌入视频：

You can embed a video with the following syntax:

1

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

其中Platform是平台名称的小写字母，ID是视频ID。

Where Platform is the lowercase of the platform name, and ID is the video ID.

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

The following table shows how to get the two parameters we need in a given video URL, and you can also know the currently supported video platforms.

Video URLPlatformID
https://www.youtube.com/watch?v=H-B46URT4mgyoutubeH-B46URT4mg
https://www.twitch.tv/videos/1634779211twitch1634779211

Learn More ：学习更多

有关Jekyll帖子的更多信息，请访问Jekyll Docs: Posts 文档：帖子。

For more knowledge about Jekyll posts, visit the Jekyll Docs: Posts.

官方文档, Chirpy
编写帖子
本文由作者按照 CC BY 4.0 进行授权