# 撰写新文章

发表于 %Y/%m/%d
作者 一凡
16 分钟 阅读
撰写新文章

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

## 命名和路径

创建一个新文件，使用 `hugo new content/post/YYYY-MM-DD-TITLE.md`。您可以根据自己的喜好更改路径，但请注意，所有文章都应该放在根目录的 `content/post` 中。

## 前言

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

    1
    2
    3
    4
    5

    ---
    title: 标题
    date: YYYY-MM-DD HH:MM:SS +/-TTTT
    draft: true
    ---

您可以根据需要添加以下字段：

    1
    2
    3
    4

    categories: [主分类, 子分类] # 只支持两个分类
    tags: [标签]     # 标签名称应始终为小写
    pin: true      # 表示这篇文章将显示在首页顶部
    description: 文章描述 # 该文章的描述

> 文章的_布局_默认已设置为`post`，因此无需在前言块中添加变量_layout_。

### 分类和标签

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

    1
    2
    3
    4

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

### 作者信息

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

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

    1
    2
    3

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

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

    1
    2
    3
    4
    5

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

如果您不想在每篇文章的前言中指定作者，可以在 `config/_default/params.toml` 中设置全局作者。

    1

    author: <作者ID>

> 在每篇文章前言中指定的作者将覆盖全局作者设置。因此，如果任何文章的作者与全局作者不同，可以直接在其前言中添加作者。

要在启用 i18n 的站点上支持多语言作者信息，您可以在 `data/authors/` 下组织特定语言的 YAML 文件中的作者数据。例如：

- 英语：`data/authors/en.yaml`
- 简体中文：`data/authors/zh-CN.yaml`

只需用相应的作者详细信息填充每个文件：

    1
    2
    3

    <作者ID>:
      name: <作者英文名>
      url: <作者的主页>

    1
    2
    3

    <作者ID>:
      name: <作者中文名>
      url: <作者的主页>

### 文章描述

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

    1
    2
    3

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

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

## 目录

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

    1
    2
    3

    ---
    toc: false
    ---

## 评论

评论的全局设置由 `config/_default/params.toml` 文件中的 `comments.provider` 选项定义。一旦为此变量选择了评论系统，所有文章将启用评论。

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

    1
    2
    3

    ---
    comments: false
    ---

## 媒体

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

### URL前缀

> URL 前缀功能正在开发中。

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

- 如果您使用CDN托管媒体文件，可以在 `config/_default/params.toml` 中指定 `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`

### 图片

#### 标题

在图片的下一行添加 HTML 属性 `caption`，然后它将作为标题显示在图片底部：

    1
    2

    ![图片描述](/path/to/image)
    { caption="图片的标题" }

#### 尺寸

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

    1
    2

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

> 对于SVG，您至少必须指定其 宽度，否则它不会被渲染。

#### 位置

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

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

- 普通位置

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

      1
      2

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

- 向左浮动

      1
      2

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

- 向右浮动

      1
      2

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

#### 暗/亮模式

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

    1
    2
    3
    4

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

#### 阴影

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

    1
    2

    ![桌面视图](/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` 也可以传递给预览图片，也就是说，当它已经设置好时，属性 `path` 只需要图片文件名。

### 视频

#### 社交媒体平台

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

    1

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

    {{< embed/video.html src="{URL}" >}}

其中 `URL` 是指向视频文件的 URL，例如 `/path/to/sample/video.mp4`。

您还可以为嵌入的视频文件指定其他属性。以下是允许的属性的完整列表。

- `poster='/path/to/poster.png'` — 视频的海报图片，在视频下载时显示
- `title='文本'` — 显示在视频下方的标题，外观与图片标题相同
- `autoplay=true` — 视频在准备好后自动开始播放
- `loop=true` — 在视频播放结束时自动回到起点
- `muted=true` — 音频最初将被静音
- `types` — 指定其他视频格式的扩展名，用 `|` 分隔。确保这些文件与您的主视频文件存在于同一目录中。

考虑使用上述所有内容的示例：

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10

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

### 音频

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

    1

    {{<  embed/audio.html src="{URL}" >}}

其中 `URL` 是指向音频文件的 URL，例如 `/path/to/audio.mp3`。

您还可以为嵌入的音频文件指定其他属性。以下是允许的属性的完整列表。

- `title='文本'` — 显示在音频下方的标题，外观与图片标题相同
- `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`。它们可以通过向引用块添加类 `prompt-{type}` 来生成。例如，按如下方式定义 `info` 类型的提示框：

    1
    2

    > 提示框示例文本。
    { .prompt-info }

## 语法

### 内联代码

    1

    `内联代码部分`

### 文件路径高亮

    1

    {{< filepath src="/path/to/a/file.extend" >}}

### 代码块

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

    1
    2
    3

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

#### 指定语言

使用 ````{language}` 您将获得带有语法高亮的代码块：

    1
    2
    3

    ```yaml
    key: value
    ```

#### 指定文件名

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

    1
    2
    3

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

## 数学公式

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

    1
    2
    3

    ---
    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
    22
    23
    24
    25
    26

    <!-- 块级数学公式，保留所有空行 -->

    $$
    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_数学表达式 $$

## Mermaid

> Mermaid 支持正在开发中

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

    1
    2
    3

    ---
    mermaid: true
    ---

然后您可以像其他 markdown 语言一样使用它：将图表代码用 ````mermaid` 和 ````` 包围起来。

## 了解更多

要了解更多关于撰写 Hugo 文章的知识，请访问 Hugo 文档。

博客 , 教程
写作
本文由作者按照 CC BY 4.0 进行授权

## 最近更新

- 自定义网站图标
- 开始使用
- 撰写新文章
- 文本和排版

## 热门标签

排版 入门指南 网站图标 写作

## 文章内容

### 相关文章

## 热门标签

排版 入门指南 网站图标 写作