博客备忘

格式约定

正文

由于 Markdown 中单独一个换行符不会作为段落分隔的标志，每句话单独一行我觉得不错，所以我会尽量这样组织 .md 文件。（只要没忘了

中西文混排

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

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

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

标点符号

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

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

Markdown

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

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

站内的超链接也可以用 永久链接 [Link A]({{% ref "/books/book-1" %}})。和 相对永久链接 [Link A]({{% relref "/books/book-1" %}}) 。由于会在编译时检测，当站内跳转的 URL 不存在时会报错，起到检查的作用。官网文档说它们需要用 {{% %}} 格式。

当引用块和列表嵌套时，列表行之间空不空行是不同的。

不加空行：列表项紧凑，行间距小，像条目清单

1
2
> * 第一行
> * 第二行

会生成一个 <ul> 列表，每个 <li> 之间没有额外的间距。这是最常见的写法，适合普通引用列表。

加空行：列表项松散，条目之间有明显空隙，更像几个要点的分段描述

1
2
3
> * 第一行
>
> * 第二行

CommonMark 规定，列表中如果有一个列表项之间有空行隔开，这个列表就变成「松散列表」（loose list）。每个 <li> 的内容会被包裹在 <p> 标签里，从而产生额外的段落间距。

front matter

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

各 front matter 没有什么书写的先后顺序，但为了格式统一，我在自己的博客这么约定：

标题：title
描述：summary 和 description
时间：date 和 lastmod
分类：categories 和 tags
URL 一类的：slug、externalUrl 之类的
其他，自行安排

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

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

html

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

功能备忘

Markdown Alert

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

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

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

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

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

🚨 注意
操作的潜在负面后果。

emoji

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

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

脚注

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

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

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

1
2
3
4
5
6
7
Here's a simple footnote,[^1] and here's a longer one.[^bignote]

    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 基本语法

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

style map[string]string 列表页

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

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

keywords []string

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

readingTime bool

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

从列表中隐藏页面

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

配置文件

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

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

1
2
3
4
5
6
7
# config/_default/markup.toml
[goldmark]
[goldmark.extensions.cjk]
  enable = true   #1
  eastAsianLineBreaks = false   #2
  eastAsianLineBreaksStyle = 'css3draft'  #3
  escapedSpace = true   #4

为 Markdown 渲染引擎 Goldmark 启用 CJK 板式。见 Hugo 官网配置文档和 goldmark 仓库关于 CJK extension 的文档
亚洲书写习惯中，软换行不自动添加空格。我不启用该功能，因为我正文没有软换行的需求，无需避免该问题，且配合我自己的某些书写习惯，如插入超链接，便于渲染排版。
Goldmark 针对 CJK 换行有两种风格，Hugo 默认采用 simple，我采用更复杂的 css3draft。
设置粗体时遇到标点符号会格式异常，可利用斜杠+空格分隔区域：所谓「实践出真知」就是如此，写为 所谓\ **「实践出真知」**\ 就是如此。不过如果只是为了强调引号内的文字，不需要加粗引号本身。

Hugo

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

Hugo 代码高亮 shortcode 官网文档

点击查看，小心剧透

你知道的太多了

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

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

1
{{< bilibili VIDEO_ID PART_NUMBER >}}

方括号里是脚注，不论写什么内容，渲染时都会依序显示为序号 ↩︎
This is the first footnote. ↩︎
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. ↩︎