格式约定

正文

中西文混排

为了阅读体验，在中西文混排时，单词与汉字之间添加间隔。若单词前后是标点符号，因标点符号已经起到间隔作用，故不需添加。

当单词或字母扮演着汉字字词的角色，例如「把这张图片P好了」，不添加间隔也可以接受，但整体上应保持风格一致。

我尚未学会如何通过 css 或其他代码方案，在中西文间添加间隔，故行文时手动添加空格作为折衷方案。

标点符号

参考 标点符号用法 ，但引号使用直角引号，如：「吸血鬼讨厌大蒜，因为他们喜欢『不辣的』」。转载引用时，若原文不太规范，但希望保留原文格式时，可能不进行修改。

标题以竖线分隔类别时左右添加间隔，如「东方 | 钱包空空的博丽灵梦」。

markdown

超链接单独占一行。一方面便于 markdown 中单独修改；另一方面，换行时会插入软换行符，在生成时会按西文板式自动添加空格，阅读体验较好。

点击
[此处](https://www.baidu.com/)
跳转百度

超链接也可以用 ref 和 relref ，如 [Post 1]({{% relref "/posts/post-1#foo" %}})。由于会在编译时检测，当站内跳转的 URL 不存在时会报错，起到检查的作用。虽然官网文档说它们只能用 {{% %}}，但实测 {{< >}} 也行，区别在于 {{% ref %}} 会新窗口打开超链接，而 relref 和 {{< ref >}} 在本窗口。

front matter

书写 toml 格式的 front matter 时，优先写单引号。如 title = '博客备忘'

基本顺序：

1. 标题：title
2. 描述：summary 和 description
3. 时间：date 和 lastmod
4. 分类：categories 和 tags
5. 其他：slug、externalUrl 之类的

分类、标签等关键词的顺序：

• 有层次关系的关键词，先写大类，如：植物、绿萝。
• 先写主干关键词，再写附加关键词，如记录熨衣服的文章：生活、笔记。

html

格式规范参考 前端 HTML-CSS 规范 、 HTML(5) 代码规范 。嵌入 html 时，自闭合元素的尾部不添加斜线。如空行，写作 <br> 而不是 <br />。

功能备忘

Markdown Alert

📝 备注

突出显示用户应考虑的信息，即便是粗略浏览时。

📝 自定义标题

您还可以为笔记警告提供自定义标题。

💡 提示

帮助用户更成功的可选信息。

📌 重要

用户成功所必需的关键信息。

⚠️ 警告

由于潜在风险而需要用户立即关注的关键内容。

🚨 注意

操作的潜在负面后果。

emoji

如 👋 写作：:wave:。参考 Emojis 。

附一个 emoji 代码查询网站 webfx ，一个直接复制 emoji 的网站 emoji 大全 。

脚注

芝士就是力量
— 法国就是培根¹

> 芝士就是力量<br>
> — <cite>法国就是培根[^quote]</cite>

[^quote]: 方括号里是脚注，不论写什么内容，渲染时都会依序显示为序号

Here’s a simple footnote,² and here’s a longer one.³

Here's a simple footnote,[^1] and here's a longer one.[^bignote]

[^1]: This is the first footnote.

[^bignote]: Here's one with multiple paragraphs and code.

    Indent paragraphs to include them in the footnote.

    `{ my code }`

    Add as many paragraphs as you like.

插入 gif

hugo 不支持以 markdown 插入图片的格式插入 gif，但 markdown 渲染基于 html，可利用 html 插入图片的方式：

<img src="路径">

图标 & 矢量图

一些资源网站： tabler 、 favicon 、 fontawesome

对于 SVG 矢量图，fill="currentColor" 能跟随深色主题反色。语法参考 SVG 基本语法

Stack front matter

description string 单页和列表页

页面的描述。

image string 单页和列表页

页面的特色图片。

comments bool 单页

显示或隐藏页面的评论部分。

license string|bool 单页

页面的许可证。如果设置为 false，许可证部分将被隐藏。 默认值：.Site.Params.article.license.default

math bool 单页

启用或禁用 KaTeX 渲染。

toc bool 单页

显示或隐藏页面的目录。仅在页面至少包含一个标题时才会显示。 默认值：.Site.Params.article.toc

截至 Stack 4.0.1 自测似乎默认值不起作用

style map[string]string 列表页

出现在文章页面中的分类术语徽章的附加 CSS 样式。

目前仅支持 background（徽章背景）和 color（文字颜色）。

keywords []string

页面的关键词。对 SEO 很有用。

readingTime bool

显示或隐藏页面的阅读时间。 默认值：.Site.Params.article.readingTime

从列表中隐藏页面

[build]
    list = "always"    # Change to "never" to hide the page from the list

配置文件

根目录的 /hugo.toml，hugo 先加载此文件，后加载 config 文件夹的配置，冲突项会被后者覆盖。

hasCJKLanguage = true # hugo 的功能，采用 CJK 方案估算阅读时长

#/config/_default/markup.toml

[goldmark]
[goldmark.extensions.cjk]
  enable = true   #1
  eastAsianLineBreaks = false   #2
  eastAsianLineBreaksStyle = 'css3draft'  #3
  escapedSpace = true   #4

1. 为 markdown 渲染引擎 goldmark 启用 cjk 板式。见 Configure markup#Goldmark 和 goldmark#cjk-extension
2. 亚洲书写习惯中，软换行不自动添加空格。我不启用该功能，因为我正文没有软换行的需求，无需避免该问题，且配合我自己的某些书写习惯，如插入超链接，便于渲染排版。
3. goldmark 针对 cjk 换行有两种风格，hugo 默认采用 simple，我采用更复杂的 css3draft。
4. 设置粗体时遇到标点符号会格式异常，可利用斜杠+空格分隔区域，如：所谓「实践出真知」就是如此，写为 所谓\ **「实践出真知」**\ 就是如此

Hugo

hugo new posts/test/index.md：根据 archetypes 文件夹中的模板创建文件

代码高亮 shortcode 文档

{{< details summary="点击查看，小心剧透" >}}
你知道的太多了
{{< /details >}}

使用 Stack 主题的 shortcode 嵌入 B 站视频：

{{< bilibili VIDEO_ID PART_NUMBER >}}