格式约定

正文

中西文混排

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

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

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

标点符号

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

markdown

格式规范参考 markdown 语法 。为了写作时方便审阅，如果下文在结构上是上文的子部分，当不空行不影响显示效果时，上文与下文之间不额外空行，如：

1
2
3
4
5

// 正确             // 错误
Tom likes these：   Tom like these：
1. apples           
2. banana           1. apples
                    1. banana

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

1
2
3

点击
[此处](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 />。

功能备忘

任务清单

• 鸡吃完了米
• 狗舔完了面
• 火烧断了锁

1
2
3

- [x] 鸡吃完了米
- [x] 狗舔完了面
- [ ] 火烧断了锁

emoji

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

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

脚注

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

1
2
3
4

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

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

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

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 插入图片的方式：

1

<img src="路径">

图标 & 矢量图

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

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

配置文件

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

1

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

/config/_default/markup.toml

1
2
3
4
5
6

[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. 设置粗体时遇到标点符号会格式异常，可利用斜杠+空格分隔区域，如：所谓「实践出真知」就是如此，写为

   1	所谓\ **「实践出真知」**\ 就是如此

Hugo

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

代码高亮

嵌入 B 站视频

见 在 hugo 博客中嵌入 B 站视频 。在 Hugo 博客中嵌入 B 站视频

1
2

{{< bili BV1Kj411g7Lu >}}
{{< bili id=BV1aM4y1R77W sec=61 auto=false danmaku=false >}}