NOTE: 该教程还没有完成从 Jekyll 版本的迁移，请谨慎参考。 { .prompt-warning }

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

命名和路径

创建一个名为 YYYY-MM-DD-TITLE.EXTENSION{: .filepath} 的新文件，并将其放在根目录的 _posts{: .filepath} 中。请注意，EXTENSION{: .filepath} 必须是 md{: .filepath} 和 markdown{: .filepath} 之一。如果您想节省创建文件的时间，请考虑使用插件 Jekyll-Compose 来完成此操作。

前言

基本上，您需要在文章顶部填写前言，如下所示：

---
title: 标题
date: YYYY-MM-DD HH:MM:SS +/-TTTT
categories: [主分类, 子分类]
tags: [标签]     # 标签名称应始终为小写
---

文章的_布局_默认已设置为post，因此无需在前言块中添加变量_layout_。 {: .prompt-tip }

日期的时区

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

分类和标签

每篇文章的 categories 设计为最多包含两个元素，而 tags 中的元素数量可以从零到无穷大。例如：

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

作者信息

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

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

<作者ID>:
  name: <全名>
  twitter: <作者的推特>
  url: <作者的主页>

{: file="_data/authors.yml" }

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

---
author: <作者ID>                     # 单个条目
# 或
authors: [<作者1ID>, <作者2ID>]   # 多个条目
---

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

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

文章描述

默认情况下，文章的第一句话用于在首页的文章列表、进一步阅读 部分以及RSS源的XML中显示。如果您不想为文章显示自动生成的描述，可以使用 前言 中的 description 字段自定义它，如下所示：

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

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

目录

默认情况下，目录（TOC）显示在文章的右侧面板上。如果您想全局关闭它，请转到 _config.yml{: .filepath} 并将变量 toc 的值设置为 false。如果您想为特定文章关闭TOC，请将以下内容添加到文章的前言中：

---
toc: false
---

评论

评论的全局设置由 _config.yml{: .filepath} 文件中的 comments.provider 选项定义。一旦为此变量选择了评论系统，所有文章将启用评论。

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

---
comments: false
---

媒体

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

URL前缀

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

• 如果您使用CDN托管媒体文件，可以在 _config.yml{: .filepath } 中指定 cdn。然后，站点头像和文章的媒体资源的URL将以CDN域名为前缀。

  cdn: https://cdn.com
  

  {: file='_config.yml' .nolineno }

• 要为当前文章/页面范围指定资源路径前缀，请在文章的 前言 中设置 media_subpath：

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

  {: .nolineno }

选项 site.cdn 和 page.media_subpath 可以单独使用或组合使用，以灵活组合最终的资源URL：[site.cdn/][page.media_subpath/]file.ext

图片

标题

在图片的下一行添加斜体，然后它将成为标题并显示在图片底部：

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

{: .nolineno}

尺寸

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

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

{: .nolineno}

对于SVG，您至少必须指定其 宽度，否则它不会被渲染。 {: .prompt-info }

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

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

{: .nolineno}

位置

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

一旦指定了位置，就不应添加图片标题。 {: .prompt-warning }

• 普通位置

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

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

  {: .nolineno}

• 向左浮动

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

  {: .nolineno}

• 向右浮动

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

  {: .nolineno}

暗/亮模式

您可以使图片跟随暗/亮模式的主题偏好。这需要您准备两张图片，一张用于暗模式，一张用于亮模式，然后为它们分配特定的类（dark 或 light）：

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

阴影

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

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

{: .nolineno}

预览图片

如果您想在文章顶部添加图片，请提供分辨率为 1200 x 630 的图片。请注意，如果图片的宽高比不符合 1.91 : 1，图片将被缩放和裁剪。

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

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

请注意，media_subpath 也可以传递给预览图片，也就是说，当它已经设置好时，属性 path 只需要图片文件名。

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

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

LQIP

对于预览图片：

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