帮助 · 安全工程计算

如果你要参与本书的写作贡献，请首先阅读本页的内容，以了解如何进行内容组织和排版。

网站生成方式#

本网站是一个预生成的静态网站，它是使用静态网站生成工具 Hugo 生成了所有网页内容。为了更好地组织和展示内容，我们专门为此网站开发了一个主题，本帮助文档有很大一部分是介绍关于此主题的相关功能。关于如何运行本网站，请自行阅读 Hugo 的帮助文档，其中最基本的操作包括以下三项：

安装 Hugo 程序#

如果你不是专业的程序设计人员，建议直接到 Github 上下载已经编译好了的 Hugo 可执行程序就好了（需要科学上网才能下载）。然后将其放置在你希望放置的目录（如 C:\bin），并设置你的 PATH 环境变量包含此目录。这样，你随时打开终端（在 Windows 上为命令提示符或 Powershell），键入 hugo 命令就能看到该程序的响应了。

在本地电脑上运行网站#

打开终端，进入到网站所在的目录，然后启动 Hugo 网站的后台服务。需要运行类似如下命令：

cd C:\path\to\website-dir
hugo server

保持该命令在后台运行，通过在浏览器地址栏输入 http://localhost:1313/、http://127.0.0.1:1313/ 或 http://mtkj.wang:1313/ 来访问此网站。

注意

根据你在 hugo.toml 文件中的 baseURL 项的设置，可能需要输入不同的网站 URL，如 http://localhost:1313/site_dir。最后的域名 mtkj.wang 是我们自己的域名，其被解析到本机 IP（127.0.0.1）。因为本主题使用的 KaTeX 显示公式的 JavaScript 库是引用网上自己托管的地址，为了防止该库被滥用而产生过高流量费，该库仅限制部分域名可以访问，其中包括 mtkj.wang，但无法包括 localhost 和 127.0.0.1。因此仅在使用 mtkj.wang 域名时，页面中的 LaTeX 公式才能正确显示。当然，你也可以将 KaTeX 库放置在本地硬盘，这需要在 hugo.toml 文件中设置 useLocalKatex = false，并把库下载到本地的 static 目录中。对于托管在互联网上的网页，只要域名在白名单中，则不存在此限制。

对于远端服务器，你也可以用类似的方法运行此网站。你也可以把生成的静态网站上传的远端服务器，使用 nginx、Apache或Caddy之类的网页服务器代理展示这些网页。不过在更多的时候，更建议你把网站部署到一些提供静态网页展示的服务平台，如阿里云、腾讯云的文件对象存储服务，这使你几乎可以零成本地运行一个网站，详情请参见 Hugo 的托管和部署。要部署网站，需要下一步操作。

生成网站的静态内容#

要生成静态的网站内容，需要运行如下命令：

cd C:\path\to\website-dir
hugo

默认生成的位置是网站的 public 目录，你也可以在 hugo.toml （或是 hugo.yaml、hugo.json）文件中通过 publishDir 特别指定此目录位置。之后，你只要把 publishDir 目录的内容上传到服务器上，就是一个网站了。建议通过 Rclone 上传。

熟悉 Markdown#

Hugo 主要使用 Markdown 撰写内容，准确来说，是使用 Github 风格的 Markdown。因此，你需要对 Markdown 这种格式非常熟悉。幸好，这学起来也很快。

为了编写 Markdown 文件，你需要一个编辑器。已经存在众多的这类软件，如 Visual Studio Code（万能的代码编辑器，建议你在电脑中始终安装这个软件，免费的，需要安装相关的 Markdown 扩展）、Typora（收费的，但不贵，所见即所得的编辑器）、Obsidian，还有很多，就不一一列举了。

提示

由于网站特意根据每个页面前导的 title 属性为页面添加标题，因此在编写 Markdown 文件内容时，不要再通过 # 给出一个一级标题，而总是从二级标题（对应行首为 ##）开始，并且应该有多个二级标题（否则它应该是本页面的标题）。

使用钩子、短代码和类#

Markdown 的表示能力毕竟有限，为了一些特别的表示需求，Hugo 分别额外添加了钩子（Hook，用来修改默认的 Markdown 渲染行为）和短代码（Shortcode，用来添加一些用 Markdown 没有定义的行为）功能，你可以使用各种 Hugo 预先定义的这些钩子和短代码。另外，我们在自己开发的主题中还额外添加了一些钩子和短代码。我们也定义量少量的类（class），通过添加到 Markdown 元素上可以改变其排版；更有甚者，你也可以直接输入 HTML 代码。

自定义短代码#

除了 Hugo 自带的一些短代码之外，本主题也自定义了一些短代码：

mathblock：插入块级公式；
gallery：插入画廊；
alert：插入警告信息；
icon：插入图标，其形式为 {{< icon icon-name >}}，其中 icon-name 可以在这里找到，如 {{< icon bell >}} 将显示为；
kbd：插入快捷键，如 {{< kbd Ctrl Shift P >}} 将显示为 Ctrl+Shift+P；
div 和 span：插入无明确语义的 HTML 标记，其中 div 为块级标记，span 为行内标记，通过这两个标记可以为内容添加额外的类或其他属性。这两种短代码几乎是全能的，但使用比较复杂，且要配合特定的 CSS 类，一般可以不用理会。例如，如下所示为使用 div 进行分栏显示：
```
{{< div class="row" >}}
    {{< div class="col-4" >}}
    左侧
    {{< /div >}}
    {{< div class="col-4" >}}
    中间
    {{< /div >}}
    {{<div class="col-4" >}}
    右侧
    {{< /div >}}
{{< /div >}}
```
其显示效果为：

左侧

中间

右侧

当然，这些类依靠额外的 CSS 样式，这里就不一一介绍了。

自定义属性#

使用自定义的类之前，需要在网站的配置文件（一般是 hugo.toml 一类的文件）设置如下属性：

[goldmark.parser.attribute]
    block = true

然后，可以通过如下方式为块级元素添加属性：

这是一个段落。
{class="foo bar" id="baz"}

或

这是一个段落。
{.foo .bar #baz}

一般主要为文本添加类或 ID，当然，也可以添加其他属性。

可以通过颜色类为文本设置颜色（这些颜色必须是色彩及其可用的类表格中定义的。例如：

这个段落的文字将显示为红色，并具有浅蓝色背景。
{ .fg-red .bg-blue-de }

其显示效果为：

这个段落的文字将显示为红色，并具有浅蓝色背景。

使用自定义类是一个高级话题，有很多自定义类可用，需要自行查看主题的源代码，这里无法一一列举。

内容的组织#

网站所有的内容都处在 content 目录中。其内容主要有两种类型：

页面（Page）：内容组织的单元，页面有可能对应一个 .md 文件，也有可能对应一个目录；
栏目（Section）：页面的集合，它定义了页面的组织结构，栏目是树形的，相当于目录结构，栏目总是对应一个目录；

有两种方式存放页面（Page）：

用一个 .md 存放页面。当页面内容不需要和其他资源（如图片）关联时，这种方式不失是一种最简单的方式；
用一个目录存放页面。当页面包含许多其他资源，这些资源和其他页面的资源混在一起会非常难以管理，这时可用这种方式。这种情况下目录内必须有一个 index.md 文件，需要在该页面放置 Markdown 格式的文字内容。

对于栏目（Section），其必然对应一个目录，与页面对应的目录不同的是，栏目目录内必须有一个 _index.md 文件（注意文件名前面必须有一个下划线），然后该目录内可以进一步放置页面或栏目。_index.md 文件中也是可以有文字内容的，这些内容相当于对其中各个页面的介绍（或称概述、引言）。

我们正在创作的是一个书籍，其主要是对章和节的组织，统一要求如下：

章要么对应一个栏目，要么对应一个页面，但都必须直接位于 content 目录下；
当章较大时，尽量要分成多个节，这时章应该为一个栏目，该栏目目录下又包含多个节的页面；
节下面不能再有小节这样的页面，这意味着，当章为栏目时，节是栏目目录下的一个页面；当章是页面时，节是该页面内的一个二级标题（用 ## 标示）；
小节只处在页面内，用二级或三级标题标示，没有单独的小节页面。

为了便于排序，建议可在章节的文件或目录名称前面加上 01、02 这样的前缀，不过这些前缀和实际显示的章节组织并没有关系。

实际显示的章节组织主要由前导信息（Front Matter）中的 weight 参数值决定，该权重是升序排列的，权重越小，其在章节中的位置越靠前。当页面不属于章节时（如本帮助页面，或关于页面），则不给出加任何权重。

前导信息#

前导信息（Front Matter）是放在栏目或页面前面的元数据。形式如下（TOML 格式，也可以为 YAML 或 JSON 格式）：

+++
title = "前言"
author = ["匿名"]
tags = ["前言", "介绍", "原则", "创新"]
description = "对本页面内容的简要介绍。"
date = 2025-01-01
lastmod = 2025-01-01
draft = false
toc = true
enableKatex = false
weight = 1
[menus.main]
    identifier = "preface"
    name = "前言"
    weight = 10
+++

其中许多项目的含义是一目了然的。需要说明的有：

draft：当该项为 true 时（默认为 true），使用 Hugo 时将不包含本页（栏目）内容；
enableKatex：仅当该项为 true 时（默认为 false），才可以在页面中插入 LaTeX 数学公式，这样做是为了防止页面中不必要地加载一些资源；
toc：仅当该项不为 false （默认为 true），且二级标题的个数大于等于 2 时，才会在页面右侧（在大屏幕上）或右下方（在小屏幕上）显示本页目录（或目录按钮），如非为了禁止显示目录，可以省略该项；
weight：仅当出现该项时，该页面或栏目才被看作是章节内容，并在首页和左侧目录列出，该项参数的值越小，其排名越靠前；
[menus.main]部分：这些是控制一个页面是否在顶部菜单栏中展示。

插入图片#

插入单个图片#

当页面包含图片时，建议用一个目录组织此页面内容，并且将图片放置在页面目录中的 images 子目录中。这样，就可以使用如下 Markdown 语法插入图片：

![雏菊](images/雏菊.jpg "漂亮的花朵")

其中 雏菊 是图片的替换文字，漂亮的花朵 是图片的标题。其显示结果如下：

注意，这和默认的 Markdown 显示效果不一样，我们使用图片框（figure 元素）来显示图片，并为图片添加了带编号的标题，这得益于我们针对 Markdown 图像语法构建了自己的渲染钩子（Hook）。

上面插入图片的语法中，"漂亮的花朵" 这个标题也可以省略，这时前面的 雏菊 就是标题。

如果你觉得该图像尺寸过大，也可以通过为图像添加类来控制其尺寸。其方法如下：

![雏菊](images/雏菊.jpg "漂亮的花朵")
{ .w-6f }

这将显示：

这里 .w-6f 中前导的点 . 表示要添加的属性是一个类（class，如果前导的是 #，则表示要添加的属性是一个 id），其中的 6p 表示占页面宽度的 6//12，也可以把 6 替换为其他 1～12 的数字。在设置宽度后，高度也会等比例缩放，只能设置宽度，不能设置高度。另外，即便已设置了宽度，在小屏幕（宽度小于 800px，如手机）上，该图像仍可能占满屏幕。

有时，需要让图片浮动到右侧，左侧被文字包围，这可以通过添加 .float-right 类属性来实现。其他还有 .float-left（浮动到左侧）、.center（居中对齐）；这些属性值对大屏幕（宽度大于 800px）有效。如下所示：

![雏菊](images/雏菊.jpg)
{ .w-4f .float-right }

其显示效果见右图。

请尽量不要使用 .float-left 和 .center 这两个属性，因为我们想使页面的显示效果看起来更加统一。

如果想让多个图片显示在一行上，则可以直接采用如下方式：

![雏菊](images/雏菊.jpg "第 1 个")
{ .w-4f }

![雏菊](images/雏菊.jpg "第 2 个")
{ .w-4f }

![雏菊](images/雏菊.jpg "第 3 个")
{ .w-4f }

这将显示：

当几个图片的宽度之和不超过 12 时，他们将自动显示在一行。

画廊#

进一步地，如果想让多个图片作为子图显示在一起，但只有一个带编号的标题，则需要使用我们额外开发的画廊 gallery 短代码功能，其用法如下：

{{< gallery class="cols-3" caption="漂亮的花朵" >}}
    {{< figure src="images/雏菊.jpg" title="（a）第 1 个" >}}
    {{< figure src="images/雏菊.jpg" title="（b）第 2 个" >}}
    {{< figure src="images/雏菊.jpg" title="（c）第 3 个" >}}
    {{< figure src="images/雏菊.jpg" title="（d）第 4 个" >}}
    {{< figure src="images/雏菊.jpg" title="（e）第 5 个" >}}
    {{< figure src="images/雏菊.jpg" title="（f）第 6 个" >}}
{{< /gallery >}}

下面是得到的结果：

注意上述代码中的 cols-3 表示每行具有 3 个图像，也可以指定其他数值，但不能超过 6。

插入公式#

可以在网页中插入 LaTeX 格式的公式。要在页面中插入公式，需要首先在前导信息中使 enableKatex = true。按照所处的位置，公式分为两种：

行内公式：嵌入在文字流中的公式，使用 $ $ 或  这样的符号对包括公式的 LaTeX 代码，如 $x_1=\frac{-b\pm \sqrt{b^2-4ac}}{2a}$ 或 $x_1=\frac{-b\pm \sqrt{b^2-4ac}}{2a}$，这两个公式都将显示为：$ x_1=\frac{-b\pm \sqrt{b^2-4ac}}{2a} $。
行级公式：许多公式编辑软件又称其为显示公式，是单独占一行、居中显示的公式，需要用使用 $$ $$ 或 \[ \] 包括公式，并单独放在一行上，上下是空行。如
```
$$ x_1=\frac{-b\pm \sqrt{b^2-4ac}}{2a} $$

或

\[ x_1=\frac{-b\pm \sqrt{b^2-4ac}}{2a} \]
```
这两行公式都将显示为：
\[ x_1=\frac{-b\pm \sqrt{b^2-4ac}}{2a} \]

为了能显示公式编号，我们在主题中专门开发了 mathblock 短代码。其使用方式如下：

{{< mathblock >}}
$$x_1=\frac{-b\pm \sqrt{b^2-4ac}}{2a}$$
{{< /mathblock >}}

这会则右侧自动插入一个公式编号，如下所示：

x_1=\frac{-b\pm \sqrt{b^2-4ac}}{2a}

当插入块级公式时，建议一直使用此段代码。如果不想要公式编号，则可以为其添加一个 nocount=true 参数键值对。如下所示：

{{< mathblock nocount=true >}}
$$x_1=\frac{-b\pm \sqrt{b^2-4ac}}{2a}$$
{{< /mathblock >}}

其显示结果为：

x_1=\frac{-b\pm \sqrt{b^2-4ac}}{2a}

有多种方式可以生成 LaTeX 公式文本：

当使用桌面版公式编辑器编辑公式时，可通过设置将公式拷贝为 LaTeX 文本，常用的公式编辑器包括：
- MathType：老牌的公式编辑器；
- AxMath：一个国产的公式编辑器，功能强大、显示优美、价格便宜，强烈推荐！
在线的 LaTeX 公式编辑器：基本上也能用；
手写 LaTeX 公式：维基百科的帮助页面列出了一些常用的 LaTeX 公式功能，可甩出作为快速参考。

插入表格#

尽管可以使用 Markdown 编辑表格，很难细致地控制其表格结构和显示效果，且无法为表格添加标题。为此，我们干脆就放弃了使用 Markdown 形式的表格，而直接使用 HTML 格式的表格。常见的表格 HTML 代码如下：

<div class="table-wrapper"><table>
 <caption class="table-counter">算术运算符</caption>
 <colgroup>
  <col style="width: 80px">
  <col style="width: 200px">
  <col style="width: 150px">
  <col style="width: 100px">
 </colgroup>
 <thead>
  <tr>
   <th>运算符</th>
   <th>说明</th>
   <th>示例表达式</th>
   <th>结果</th>
  </tr>
 </thead>
 <tbody>
  <tr>
   <td><code>+</code></td>
   <td>加</td>
   <td><code>43.3 + 10</code></td>
   <td><code>53.3</code></td>
  </tr>
  <tr>
   <td><code>-</code></td>
   <td>减</td>
   <td><code>43.3 - 10</code></td>
   <td><code>33.3</code></td>
  </tr>
  <tr>
   <td><code>*</code></td>
   <td>乘</td>
   <td>
    <code>43.3 * 10</code>
   </td>
   <td>
    <code>433.0</code>
   </td>
  </tr>
  <tr>
   <td><code>/</code></td>
   <td>除，其结果总是为浮点数<br>（注意除数不能为零）</td>
   <td>
    <code>43 / 10</code><br>
    <code>43.3 / 10</code>
   </td>
   <td>
    <code>4.3</code><br>
    <code>4.33</code>
   </td>
  </tr>
 </tbody>
</table></div>

其中的 <div class="table-wrapper"></div> 封装使很宽的表格能够超过页面的宽度而不至于所有的列挤在一起，<caption class="table-counter">算术运算符</caption> 表示一个带编号的表格标题。<colgroup> </colgroup> 中的各项可以分别指定各列的宽度，注意页面内容的最大宽度是 780px，如果不是实在放不下，尽量不要超过这个宽度。以上表格的显示效果为：

算术运算符
运算符	说明	示例表达式	结果
`+`	加	`43.3 + 10`	`53.3`
`-`	减	`43.3 - 10`	`33.3`
`*`	乘	`43.3 * 10`	`433.0`
`/`	除，其结果总是为浮点数（注意除数不能为零）	`43 / 10` `43.3 / 10`	`4.3` `4.33`

我们还未表格额外定义了一些类，其中可能有用的包括 auto-layout 和 nowrap。前者是浏览器自动对表格调整布局（对于大型复杂表格经常不太理想），后者则禁止表格中的文字自动换行（若有大段文字，将会使表格变得很宽）。可以通过 <table class="auto-layout"> 或 <table class="nowrap"> 的形式使用这些功能。

总的来说，复杂表格的编辑是一项非常困难的工作，你不会很正常，这时可交给其他人来干。

插入代码#

本站支持代码语法高亮，但没有使用 Hugo 自带的代码高亮功能，而是使用 Prism.js 这个语法高亮引擎。插入代码的方式就是传统的 Markdown 插入代码的方式，如下所示：


```python
fib0 = 0
fib1 = 1
n = int(input('你想要生成多少个菲波拿契数？ '))
if n >= 1:
    print(fib1)
    for i in range(n-1):
        temp = fib0 + fib1
        fib0 = fib1
        fib1 = temp
        print(fib1)
```

其渲染效果如下：

fib0 = 0
fib1 = 1
n = int(input('你想要生成多少个菲波拿契数？ '))
if n >= 1:
    print(fib1)
    for i in range(n-1):
        temp = fib0 + fib1
        fib0 = fib1
        fib1 = temp
        print(fib1)

对于 Bash（或 Shell）代码，包括直接在终端中输入的命令，一般会在输入的命令前面显示一个符号（Linux 不需要管理员权限一般显示 $，需要管理员权限一般显示 #，Windows 终端命令一般显示 %），这些可以通过类似如下方式定义：


```bash { data-prompt="$" data-output="2-4,6" }
cat 夜莺颂.txt
我的心在痛，困顿和麻木
刺进了感官，有如饮过毒鸠，
又象是刚刚把鸦片吞服，
cat 纪念白求恩.txt
一个人能力有大小，但只要有这点精神...
exit
```

上面 data-prompt="$" 指定了命令前面显示 $ 提示符，data-output 表示第 2～4 行和第 6 行非命令，而是命令输出。上面代码的显示效果如下：

cat 夜莺颂.txt
我的心在痛，困顿和麻木
刺进了感官，有如饮过毒鸠，
又象是刚刚把鸦片吞服，
cat 纪念白求恩.txt
一个人能力有大小，但只要有这点精神...
exit

关于 Bash 代码的显示，还有更多的功能可定义，请自行参见这个文档。

为了减少加载量，本站只加载了少量语言的语法高亮功能，你可以根据需要到 Prism.js 的官方网站自定义下载相关功能，将得到的 prism.js 文件放置到 static/js 目录（替换已有文件）即可。至于 CSS 样式文件，已经制作成黑白主题内嵌到本网站的 CSS 文件中了，你不需要下载。

展现详细信息#

Hugo 自带 details 短代码支持 HTML 最新的 details 元素，即详细信息展现元素。利用此功能相当于获得了一个不用额外用 JavaScript 定义的交互操作功能。比如，如果给出了一个示例，又不想让读者立刻看到答案，那么可以这样写答案：

{{< details summary="答案" >}}
这里是答案。

先暂时封闭。

需要点击才能显示。
{{< /details >}}

效果如下：

答案

这里是答案。

先暂时封闭。

需要点击才能显示。

details 短代码有更多的使用方法，请自行对照文档查看。

色彩及其使用#

本网站预设了一套配色方案，主要可使用的色系包括：

major：主体使用的白底黑字的配色
gray：低调的灰色
green：清新的绿色系
cyan：清冷的青色系
blue：悦目的蓝色系
red：张扬的红色系
purple：神秘的紫色系
yellow：明亮的黄色系
navy：沉稳冷静的蓝灰色系
inky：与 major 相反的黑底白字的配色

这些色系所使用的颜色是不确定的。如 yellow 所使用的颜色，实际可能是橙色，因为黄色实在太不显眼了；red 所显示的颜色，可能是粉红，只是觉得粉红比正红更鲜艳且好看。

可以使用一些类为文字、边框、背景指定颜色，见下表：

色彩及其可用的类
颜色名称	强调色	减淡色	边框色	背景色	浅淡背景
fg-major	fg-major-em	fg-major-de	bd-major	bg-major	bg-major-de
fg-gray	fg-gray-em	fg-gray-de	bd-gray	bg-gray	bg-gray-de
fg-green	fg-green-em	fg-green-de	bd-green	bg-green	bg-green-de
fg-cyan	fg-cyan-em	fg-cyan-de	bd-cyan	bg-cyan	bg-cyan-de
fg-blue	fg-blue-em	fg-blue-de	bd-blue	bg-blue	bg-blue-de
fg-red	fg-red-em	fg-red-de	bd-red	bg-red	bg-red-de
fg-purple	fg-purple-em	fg-purple-de	bd-purple	bg-purple	bg-purple-de
fg-yellow	fg-yellow-em	fg-yellow-de	bd-yellow	bg-yellow	bg-yellow-de
fg-navy	fg-navy-em	fg-navy-de	bd-navy	bg-navy	bg-navy-de
fg-inky	fg-inky-em	fg-inky-de	bd-inky	bg-inky	bg-inky-de

警告信息#

警告信息是需要突出显示的信息。目前定义了两种可以显示警告信息的方式，分别是通过块引用和通过短代码。前者属于扩展的 Markdown 格式，后者具有较强的自定义性。但块引用形式的警告能满足需求时，应尽量使用这种形式，因为这时可以在 Markdown 编辑器中直接看到结果。

通过块引用#

Hugo 本身具有对块引用的渲染钩子，使得块引用除了能渲染为块引用之外，也能渲染为各种类型的警告信息。也就是所谓 Github 风格的警告信息。另外，其他编辑器，如 Obsidian 和 Typora，也支持这种警告信息。示例如下：

> [!CAUTION]
> 提醒某种行为可能引起风险或负面效果，也可给出建议。

> [!WARNING]
> 表示非常紧急，为了避免出现问题，需要用户立刻采取行动。

> [!IMPORTANT]
> 为了达成某种目标，用户需要知道的某些关键信息。

> [!NOTE]
> 用户需要知道的某些有用信息，在略读内容时更需要知道。

> [!TIP]
> 为了更好地、更轻松地完成某些事情的帮助信息。

其显示效果如下：

危险

提醒某种行为可能引起风险或负面效果，也可给出建议。

警告

表示非常紧急，为了避免出现问题，需要用户立刻采取行动。

重要

为了达成某种目标，用户需要知道的某些关键信息。

注意

用户需要知道的某些有用信息，在略读内容时更需要知道。

提示

为了更好地、更轻松地完成某些事情的帮助信息。

虽然能额外指定警告信息的标题，但却不能识别中文标题。因此，相当于就这几种警告信息，你也不能把方括号中的英文改变为中文。

通过短代码#

为了能显示更多的警告信息，并稍微改变警告信息的显示方式，这里还定义了显示警告信息的短代码，其功能和上述通过块引用基本相同，但能更多地进行自定义。

{{< alert title="禁止" color="red" icon="forbid" >}}
这项操作可能引起严重的后果，你不能继续！
{{< /alert >}}

渲染结果为：

这项操作可能引起严重的后果，你不能继续！

该短代码可自定义三项属性，分别是：

title：要显示的标题。当不指定 title 时，图标和正文将显示在一行。。
color：文本配色，其可使用的颜色与色彩及其使用一节所介绍相同。当不指定 color，默认将显示灰色 gray。

icon ：要展示的图标。当不指定 icon 时，默认将显示为 bell。目前可选的图标名称有：

ID	显示效果	ID	显示效果
`alert`		`bell`
`bulb`		`check`
`comment`		`error`
`flag`		`forbid`
`helmet`		`important`
`info`		`key`
`question`		`shield`

如下一些示例：

{{< alert color="green" >}}
恭喜，操作成功！
{{< /alert >}}

{{< alert >}}
**提示**：你不可以进行这项操作！
{{< /alert >}}

显示效果：

恭喜，操作成功！

提示：你不可以进行这项操作！

通过添加类#

如果连图标也不想添加，可以直接为段落添加 .alert .alert-color-name 类来实现，如下所示：

这里是需要突出显示的文字信息。
{ .alert .alert-cyan }

默认显示为灰色。
{ .alert }

其显示效果如下：

这里是需要突出显示的文字信息。

默认显示为灰色。

黯淡的文字#

当一些信息不十分重要时，可以显示为黯淡的、较小号的文字，这时可以使用 muted 短代码。其示例如下：

{{< muted color="navy" >}}
Beautiful is better than ugly. \
Explicit is better than implicit. \
Simple is better than complex. \
Complex is better than complicated. \
Flat is better than nested. \
Sparse is better than dense. \alert
Readability counts. \
Special cases aren't special enough to break the rules.
{{< /muted >}}

渲染结果为：

Beautiful is better than ugly.
Explicit is better than implicit.
Simple is better than complex.
Complex is better than complicated.
Flat is better than nested.
Sparse is better than dense.
Readability counts.
Special cases aren’t special enough to break the rules.

其中 color 的可选值与以上 note、alert、alert 相同。当不指定 color 时，其显示效果如下：

自动编号#

通过类自动编号#

Markdown 本身支持多级列表，同时也支持在一个列表项中包含多个段落（需要在后续段落中用空格或制表符缩进段落）。但在学术写作中，有时候不习惯使用这种带缩进的文本，而只是简单的使用 (1)、(2)、(3) 等进行编号。可以手动进行编号，也可以自动编号。我们额外定义了两个类，可以为段落添加自动编号功能。如下示例

开始一个新的编号，需要同时为段落添加 `new-counter` 和 `counter` 类
{ .new-counter .counter }

接续上一次编号，需要为段落添加 `counter` 类
{ .counter }

继续编号，继续为段落添加 `counter` 类
{ .counter }

显示结果如下：

开始一个新的编号，需要同时为段落添加 new-counter 和 counter 类

接续上一次编号，需要为段落添加 counter 类

继续编号，继续为段落添加 counter 类

由于手动编号也不是太难，因此并不特别推荐使用自动编号。但有的时候编号项实在太多，且经常调整次序，则可以使用这种自动编号。

通过标题自动编号#

除了通过类为标题添加编号外，也可以直接通过五、六级标题添加编号。如下代码：

##### 这个 5 级标题会自动添加带圆括号的数字编号

这是这个编号下面的内容。

##### 这个 5 级标题会继续上次的编号

若遇到 1、2、3、4 级标题，或为 5 级标题添加 `.new-counter` 类，则此编号将被重置。

###### 这个 6 级标题将显示为字母编号

###### 这个 6 级标题将继续上次字母编号

##### 这个 5 级标题将继续上次数字编号

以下需要开始一个新的编号序列：

##### 这个 5 级标题将重置编号 { .new-counter }

这将显示：

这个 5 级标题会自动添加带圆括号的数字编号#

这是这个编号下面的内容。

这个 5 级标题会继续上次的编号#

若遇到 1、2、3、4 级标题，或为 5 级标题添加 .new-counter 类，则此编号将被重置。

这个 6 级标题将显示为带圈数字编号#

这个 6 级标题将继续上次带圈数字编号#

这个 5 级标题将继续上次数字编号#

以下需要开始一个新的编号序列：

这个 5 级标题将重置编号#

通过五、六级标题添加的编号实际上是标题而非段落。当一个页面没有 2～4 级标题时，推荐采用这种形式。比如，如果你在构建一个常见问题解答（FAQ）页面，每个问题对应一个小标题，页面内没有其他的 2～4 级标题，这时用这种标题就很好。