连接点303

hugo-cmpt-tmdb：给 Hugo 文章加一张影视卡片

2026-10-17T23:55:00+08:00

hugo-cmpt-tmdb 是一个 Hugo 影视卡片组件，用一行短代码即可展示电影、电视剧资料和个人评分。

因为直接爬取豆瓣会被限流，又没有可用的 API，只能用 TMDB 了 🥲

能做什么

按 TMDB ID 获取海报、片名、年份、类型、简介、演职员和 TMDB 评分。

资料和海报在构建时获取并缓存，浏览时只加载本站图片和 CSS，无需额外的 JavaScript。支持 FixIt v1 的深浅色和手机布局。

封面是本站《沙尘暴》：王良对家的执念，刘盈盈的困局与反抗中的卡片截图。

如何接入

组件需要 Hugo 0.166.0 或更新版本。在站点根目录添加子模块：

git submodule add https://github.com/yuehei/hugo-cmpt-tmdb.git themes/hugo-cmpt-tmdb

以 FixIt 为例，在 Hugo 配置中追加组件和样式入口，保留列表中的已有项：

theme = ["FixIt", "hugo-cmpt-tmdb"]

[params.custom_partials]
head = ["inject/tmdb.html"]

使用 API 需配置自己的 TMDB 凭据；仅使用本地资料时无需凭据。

在文章中使用

插入《沙尘暴》，个人评分为 9.1：

{{< tmdb type="tv" id="272100" personal_rating=9.1 >}}

type 填 tv（电视剧）或 movie（电影），id 填 TMDB 条目 ID。personal_rating 为可选的个人评分，范围是 0～10。

默认优先读取本地资料，缺少可用条目时再调用 API；本地字段可覆盖远程资料。完整配置见项目 README。

《沙尘暴》：王良对家的执念，刘盈盈的困局与反抗

2026-10-17T12:00:00+08:00

《沙尘暴》中，王良希望刘盈盈留下，让自己拥有一个完整的家。刘盈盈的前途与婚姻，却被父亲和弟弟当成可以牺牲的东西。王良想留住的，恰好是她想要摆脱的生活。

简介

一桩焚尸旧案被重查，基层民警陈江河也被紧急调回。当他再次进入小城，搅局的骗子、撒谎的真凶、复仇的牺牲者，犹如一场沙尘暴将他笼罩其中。但他坚信罪恶皆有源，再大的风暴也终会平息，天地总会恢复澄澈。

导演：谭嘉言

编剧：赵冬苓

主演：段奕宏 / 王锵 / 张佳宁 / 张瑶 / 杨新鸣 / 黄小蕾 / 郑好 / 郑楚一

我的评分 9.1 / 10

注意

以下涉及人物关系和剧情，重点讨论王良与刘盈盈的行为及其关系。

两个人物所处的位置

观察角度	王良	刘盈盈
关系中的位置	希望得到刘盈盈、留住一个家	被父亲与弟弟要求牺牲自己
行为与处境	将自身期待放在她的意愿之前	被迫为刘家父子的利益承担后果
核心问题	以自己的理由越过他人的意愿	婚姻与人生选择被他人支配

王良：恶而不自知才让人不寒而栗

整部剧里，让人恨的角色有很多，但最让人害怕的角色，我认为只有王良。

王良似乎觉得，自己对刘盈盈有感情，也为她付出了，便有理由要求她接受。他以自己的用心判断对错，却不以她受到的伤害反省自己，因此即使让她痛苦，也仍觉得自己的要求理所当然。

王良：想要一个永远在泺车的家

王良想留住一个不会离散的家：家人在身边，自己不再是被留下的那个人。对他来说，只要人还在，这个家就是完整的。

从留住母亲，到留住刘盈盈

母亲想摆脱的生活，对王良而言却是他不愿失去的家。他想让母亲留下，让自己熟悉的生活继续下去。

他对刘盈盈的执念，也可以这样理解：她离开，意味着他再次失去一个家。从母亲到刘盈盈，他想留住的人变了，不愿再次被留下的恐惧却延续了下来。

刘盈盈成为家庭想象的载体

他需要刘盈盈成为妻子，让这个家成立。在他想象的那个“永远在泺车的家”里，每个人都应该留在他认定的位置上，刘盈盈也因此被当成了实现家庭想象的载体。

他执意保住家的完整，却没有给家人选择另一种生活的自由。

刘盈盈：被父亲与弟弟牺牲的人生

刘盈盈的处境，从上大学时的选择就有迹可循。家里优先供弟弟读本科，她则选择了大专。她的前途更早就被放在了弟弟之后。

后来，为掩盖刘大志杀人的真相，刘三成又逼她嫁给知情的王良。最初让步的是求学机会，随后被牺牲的则是婚姻和往后的人生。

这些付出并未换来相应的支持。多多患白血病后，她向刘大志求助，弟弟却不愿配合骨髓配型。

父子对她的要求还在继续：为消除隐患，两人又先后要求她除掉王良。从让出机会到被迫嫁人，再到被要求杀人，需要保全的始终是他们，承担代价的始终是她。

这样的家庭，为什么王良却觉得温馨？他只看到他想看到的一面。

刘盈盈的反抗

多多曾让刘盈盈与王良有了共同的牵挂，救治女儿也让他们有了共同的目标。

多多的死亡，是刘盈盈开始反抗的主要原因。

失去多多后，她觉得自己已经一无所有，原本支撑她忍耐的理由也随之消失，只剩下仇恨。

与王良联手，是因为两人的目标一致了。她并没有因此原谅王良，只是因为彼此相似。

沙漠中的曼陀罗

第12集：沙暴中的曼陀罗

刘盈盈与王良的母亲，就像沙暴中以血浇灌的曼陀罗，美丽而悲凉。

走出困局的方向

你想离开这儿，你想去哪儿，你随时都能走，你不用非得通过我呀。

这句话是“吸血鬼”刘大志对程春说的，却也点出了剧中所有人走出困局的方向：别把希望，寄托在别人身上。

Markdown 基础与扩展语法

2025-01-01T09:00:00+08:00

标题、段落、列表、表格、引用与脚注，集中查阅常用排版语法。

本篇属于 Markdown 语法手册。按章内目录跳转，代码块提供可复制源码，其后的正文和组件展示实际效果。

基础排版：标题、段落与文字

标题与段落

文章标题由 front matter 的 title 提供，正文通常从二级标题开始，避免重复一级标题。

## 一次出发
### 路上的风景

这是第一段。连续的普通换行通常仍属于同一段。

空一行，开始第二段。

一次出发

这是第一段。连续的普通换行通常仍属于同一段。

空一行，开始第二段。

上方为了保持本页目录层级，将实际演示标题降为四级。标题符号后必须留一个空格；段落之间留一个空行。

换行：另起一行，还是另起一段

普通换行主要用于整理源码。想在同一段内明确换行，可以在行尾写反斜杠；想另起一段，就空一行。

第一行，先记下天气。\
第二行，再写下此刻的心情。

这一段换了一个话题。

第一行，先记下天气。
第二行，再写下此刻的心情。

这一段换了一个话题。

行尾两个空格也能产生硬换行，但编辑器可能自动清理它们。对于需要稳定保持行数的短诗，反斜杠更容易在源码里识别。不要用连续空格做段落缩进，网页通常会折叠这些空格。

强调与行内代码

**值得记住**，*轻声提醒*，以及 `hugo server`。

值得记住，轻声提醒，以及 hugo server。

中文字体的斜体显示由设备字体决定。文件名、命令与配置键适合行内代码，避免整段加粗。

分隔线与转义

上半部分。

---

下半部分。\*这是星号，不是强调\*。

上半部分。

下半部分。*这是星号，不是强调*。

分隔线前后留空行，避免与标题下划线语法混淆。反斜杠可以转义 Markdown 标点；但 Hugo 短代码需要专用注释转义，见短代码入门与提示框。

列表与引用

有序与无序列表

- 收集想法
- 整理材料
 - 记录来源
 - 保存图片

1. 写下初稿
2. 本地预览
3. 检查链接

收集想法
整理材料
- 记录来源
- 保存图片

写下初稿
本地预览
检查链接

子列表需要缩进。复杂列表内放代码块时，缩进应与该列表项正文对齐。

列表项里放说明和代码

一项操作可能不止一句话。把后续段落和代码块缩进到该项正文的位置，就能保留步骤的归属关系。

1. 新建文章。

 文件名采用简短英文，中文标题写在文章头部。

 ```sh
 ./scripts/hugo.sh new content posts/weekend-notes.md
 ```

2. 写一个能概括内容的开头。

 - 说明遇到了什么问题。
 - 说明读者能从本文得到什么。

新建文章。

文件名采用简短英文，中文标题写在文章头部。
```
./scripts/hugo.sh new content posts/weekend-notes.md
```
写一个能概括内容的开头。
- 说明遇到了什么问题。
- 说明读者能从本文得到什么。

这里列表项从 1. 后的第四列开始，因此后续内容缩进三个空格。不同标记宽度可能需要不同缩进，不要机械地给所有嵌套内容加相同空格。

引用

> 沧浪之水清兮，可以濯吾缨
>
> 沧浪之水浊兮，可以濯吾足。

沧浪之水清兮，可以濯吾缨

沧浪之水浊兮，可以濯吾足。

每段引用以 > 开始。空引用行可以把引用拆成两个段落。

引用中也能包含结构

> **本周记录**
>
> - 完成一篇技术笔记。
> - 修正一处模糊的解释。
>
> 写作不是一次完成，而是在回看时不断变清楚。

本周记录

完成一篇技术笔记。

修正一处模糊的解释。

写作不是一次完成，而是在回看时不断变清楚。

引用里的空行也写一个 >，这样段落和列表都明确属于引用。只有需要表达“引用中的引用”时，再使用 >>。

表格与任务清单

表格与对齐

| 内容 | 用途 | 数量 |
| :--- | :---: | ---: |
| 文章 | 记录 | 5 |
| 合集 | 归档 | 1 |

内容	用途	数量
文章	记录	5
合集	归档	1

分隔行中的冒号决定左、中、右对齐。单元格中需要竖线时写 \|。表格适合短内容，长段落更适合列表。

表格中的链接、强调与竖线

| 写法 | 用途 | 示例 |
| :--- | :--- | :--- |
| **加粗** | 提醒读者关注 | **先检查草稿状态** |
| 链接 | 指向解释页面 | [合集](/collections/markdown/) |
| 竖线 | 表示“或”等关系 | A \| B |
| 行内代码 | 配置项或文件名 | `hugo.toml` |

写法	用途	示例
加粗	提醒读者关注	先检查草稿状态
链接	指向解释页面	合集
竖线	表示“或”等关系	A \| B
行内代码	配置项或文件名	`hugo.toml`

表格中的竖线需要转义，否则会被当作新列。复杂代码、多段说明或大幅图片不适合挤在单元格里；可以在表格中概括，再在表格外解释。

任务清单

- [x] 整理目录
- [x] 完成初稿
- [ ] 校对后发布

整理目录
完成初稿
校对后发布

[ ] 内是一个半角空格。这里的复选框是文章内容展示，不会将点击状态保存到 Markdown。

有层次的发布清单

- [x] 完成正文
 - [x] 补齐来源
 - [x] 给示例添加说明
- [ ] 完成验收
 - [x] 桌面预览
 - [ ] 手机预览
 - [ ] 检查深色模式

完成正文
- 补齐来源
- 给示例添加说明
完成验收
- 桌面预览
- 手机预览
- 检查深色模式

父项不会自动根据子项完成情况更新，需要在 Markdown 源文件中手动维护。清单写成可以验证的动作，比“继续优化”“做好检查”更容易执行。

链接、脚注与术语

把链接定义放到段落后面

同一个目标在一篇文章中出现多次时，引用式链接能让正文更清楚。

基础语法见[第一篇][basics]，所有文章收录在[写作合集][collection]。
读完后，也可以回到[第一篇][basics]做一次练习。

[basics]: /wiki/markdown-basics/ "Markdown 基础语法"
[collection]: /collections/markdown/ "完整合集"

基础语法见第一篇，所有文章收录在写作合集。读完后，也可以回到第一篇做一次练习。

定义可以放在文末，不会单独显示。标识建议用简短英文，避免修改可见标题时还要同时修改所有引用。

脚注

先写正文，再补充背景。[^note]

[^note]: 脚注可用于来源、术语或不影响主线的解释。

先写正文，再补充背景。¹

引用和定义使用相同标识，渲染器会生成编号、文末脚注与返回链接。

脚注里的第二段

本次只记录已经验证的行为。[^scope]

[^scope]: 验证范围是当前固定版本。

 不同版本或不同配置可能产生不同结果，升级后需要重新检查。

本次只记录已经验证的行为。²

脚注后续段落缩进四个空格。不要把重要步骤藏在脚注中；脚注更适合补充范围、来源或背景。

定义列表

Front matter
: 位于文件开头的元数据。

Page bundle
: 将文章正文和图片放在同一目录的内容组织方式。

Front matter: 位于文件开头的元数据。
Page bundle: 将文章正文和图片放在同一目录的内容组织方式。

文字扩展

删除、高亮与上下标

~~旧方案~~，==重点==，H~2~O，x^2^。

~~旧方案~~，重点，H₂O，x²。

这些扩展由固定版本的 markup.goldmark.extensions.extras 开启。上下标内容不要包含未转义空格；复杂表达式使用数学公式章节。

下划线与组合强调

++新增内容++，**加粗文字**，*斜体文字*，***加粗且斜体***。

新增内容，加粗文字，斜体文字，加粗且斜体。

++...++ 是本站启用的插入文本扩展，通常显示为下划线，不是所有 Markdown 编辑器都支持。下划线容易让人误认为链接，因此正文强调优先使用加粗。

Emoji

:books: 整理知识，:wrench: 记录折腾，:pencil: 随手写下想法。

📚 整理知识，🔧 记录折腾，📝 随手写下想法。

本站开启了 enableEmoji，支持 Emoji 简码；也可以直接输入 📚、🔧、✏️。字符 Emoji 的外观由系统决定，不能保证所有设备完全相同。

链接、图片与代码入门

普通链接与定位标记

[阅读写作流程](/wiki/writing-workflow/ "文章模板与写作发布流程")

[回到本节](#链接图片与代码入门)

阅读写作流程 · 回到本节

链接文字说明目的，括号里填写地址，可选的引号内容是悬停说明。页内链接使用标题生成的锚点；标题修改后应重新检查对应锚点。不要把本机磁盘路径当成站内地址。

图片与替代文本

![本站图标](/favicon.svg "本站图标")

本站图标

方括号中是替代文本，用来描述图片；引号中的 title 是附加说明。本站开启的图片灯箱对带 title 的图片生效。较复杂的图文排版与资源路径见富文本写作。

围栏代码块

```sh
hugo version
```

hugo version

三个反引号开始和结束代码块，语言名控制高亮。要演示包含三个反引号的源码，外层使用四个反引号。代码高亮、行号、标题与复制按钮的详细写法统一放在富文本写作。

注释与少量 HTML

可见的文字。
<!-- 编辑备注：这段说明不显示在正文中。 -->
按 <kbd>Esc</kbd> 退出。

可见的文字。

按 Esc 退出。

HTML 注释不显示为正文，但不要用它保存密码或其他秘密。少量 HTML 可补充 Markdown 无法表达的内容；是否允许渲染取决于站点配置，不同平台可能过滤这些标签。

扩展能力与专题入口

警示块

> [!NOTE]
> 保存后先本地预览，再检查图片和链接。

注意

保存后先本地预览，再检查图片和链接。

警示块适合短提示。复杂提示框、折叠、标签页与文件树见Shortcodes 与组件，避免把所有组件说明都挤进基础语法文章。

Markdown 属性

本站支持给部分 Markdown 块附加属性。写法是在元素后面紧接一行花括号；属性支持范围由渲染器与主题共同决定。

> 一段居中展示的短句。
{.blockquote-center}

一段居中展示的短句。

这里的 .blockquote-center 是主题提供的样式类，不是通用 Markdown 语法。不要任意添加未知类名并期待它自动生效。

公式与图表

简单行内公式可以写作 $a^2+b^2=c^2$ ，效果为 $a^2+b^2=c^2$ 。公式需要本站的数学渲染配置支持；其他编辑器可能直接显示源码。

多行公式、Mermaid、ECharts 和 Markmap 的可复制示例统一见数学公式与可视化图表。

标题层级与写作检查

如何组织长文

层级	写法	本文用途
一级 H1	`# 标题`	由文章 front matter 的 `title` 生成，正文无需重复
二级 H2	`## 标题`	基础排版、列表与引用等大类
三级 H3	`### 标题`	一项具体语法及其源码、效果、说明
四级 H4	`#### 标题`	必要时继续拆分，不用于单纯缩小字号

当前目录默认收录 H2–H3，四级及更深标题仍在正文中正常显示。尽量按 H2 → H3 → H4 逐层展开，不要为了视觉大小跳级。多数写作手册使用 H2、H3 就足够；短小内容直接写段落，不必每一句都加标题。

发布前检查

源码与实际效果是否一致，示例能否直接复制。
标题是否形成清晰的大类与小节，而不是全部平铺。
列表、代码围栏、引用与表格前后是否有必要的空行。
内部链接和标题锚点是否仍然有效。
扩展语法是否说明本站依赖，避免误认为所有 Markdown 平台都支持。

参考：官方基础语法与官方扩展语法。本文按本站实际配置整理常用内容；图片、短代码和图表的进阶用法继续维护在合集对应专题中。

脚注可用于来源、术语或不影响主线的解释。 ↩︎
验证范围是当前固定版本。

不同版本或不同配置可能产生不同结果，升级后需要重新检查。 ↩︎

Shortcodes 与组件

2025-01-01T09:00:00+08:00

提示框、折叠、标签页、文件树、链接卡片、原始 HTML、版本标记和时间线。

本篇属于 Markdown 语法手册。按章内目录跳转，代码块提供可复制源码，其后的正文和组件展示实际效果。

先学会安全展示源码

在 Markdown 文件的代码围栏内，把短代码起止符写成 {{</* 与 */>}}；百分号形式对应 {{%/* 与 */%}}。Hugo 输出时会去掉这对注释标记，让读者复制到可执行的语法。

下面的示例在本页源文件中已经转义，页面上的复制按钮复制到的是正常短代码。不要只用反斜杠转义花括号。

提示框 admonition

{{< admonition type="tip" title="写作提示" open=true >}}
先完成 **内容**，再微调样式。
{{< /admonition >}}

写作提示

先完成内容，再微调样式。

参数	作用
`type`	提示类型，例如 `note`、`tip`、`warning`、`danger`
`title`	自定义标题，支持 Markdown
`open`	布尔值，`false` 时默认折叠

{{< admonition type="warning" title="发布前检查" open=false >}}
确认草稿状态、图片路径和合集链接。
{{< /admonition >}}

发布前检查

确认草稿状态、图片路径和合集链接。

短代码与 Markdown 怎么配合

短代码解决 Markdown 本身不擅长的布局问题，但不应代替普通段落。一个提示只有一句话时，先考虑强调或引用；需要明确的“提醒”“警告”语义时，再使用提示框。

写法	适用范围	本手册中的例子
普通 Markdown	标题、段落、列表、代码	大多数正文
尖括号短代码	由短代码模板组织输出	`admonition`、`details`、`image`
百分号短代码	需要 Markdown 继续处理输出的场景	`tabs` 中的 `tab`

不能仅凭外观决定是否使用百分号：不同短代码内部实现不同。比如 admonition 和 details 已经主动调用页面 Markdown 渲染，而 tab 需要按本手册的嵌套写法处理正文。

一组不同语义的提示

{{< admonition type="note" title="适用范围" >}}
本文只讨论当前固定版本的写法。
{{< /admonition >}}

{{< admonition type="success" title="检查完成" >}}
文章、图片和合集链接都已检查。
{{< /admonition >}}

{{< admonition type="danger" title="注意覆盖范围" >}}
不要将生成的 `public/` 目录当作内容源文件编辑。
{{< /admonition >}}

适用范围

本文只讨论当前固定版本的写法。

检查完成

文章、图片和合集链接都已检查。

注意覆盖范围

不要将生成的 public/ 目录当作内容源文件编辑。

颜色服务于语义，不必为了配合站点主色把所有提示框改成同一种颜色。长文章里也不宜连续堆叠提示框，这里集中排列是为了方便对比。

提示框内放代码与步骤

{{< admonition type="example" title="新建草稿" >}}
1. 在项目根目录执行：

 ```sh
 ./scripts/hugo.sh new content posts/my-note.md
 ```

2. 填写标题，保持 `draft: true`，先完成正文。
{{< /admonition >}}

新建草稿

在项目根目录执行：

./scripts/hugo.sh new content posts/my-note.md

填写标题，保持 draft: true，先完成正文。

这里代码属于列表第一步，因此需要缩进。短代码开始、结束行独占一行，正文中的代码围栏前后留空行，可以减少嵌套时的排版问题。

类型选择速查

类型	适合表达	示例标题
`note` / `info`	中性补充信息	适用范围、背景说明
`tip`	可选的改进建议	写作提示
`warning`	容易遗漏的前提	发布前检查
`danger`	需要明确注意的行为	覆盖范围
`success`	已完成的结果	检查完成
`question`	需要思考的问题	为什么使用合集
`example`	示范或练习	新建草稿

这些类型直接来自固定版本的 layouts/_partials/plugin/admonition.html。升级时若出现变化，应以新版本源码为准。

原生折叠 details

{{< details summary="展开查看检查清单" open=false >}}
- 检查错别字
- 检查代码复制结果
- 检查手机阅读效果
{{< /details >}}

展开查看检查清单

检查错别字
检查代码复制结果
检查手机阅读效果

summary 是折叠标题，open 控制初始状态。给多个 details 相同的 name，可在支持的浏览器中组成互斥展开的组。title 是元素提示文字，不替代 summary。

标签页 tabs / tab

{{< tabs defaultTab=0 type="underline" placement="top" >}}
{{% tab title="写作" %}}
先用 **Markdown** 写正文，再加入短代码。
{{% /tab %}}
{{% tab title="预览" %}}
运行 `hugo server --bind 127.0.0.1 --disableFastRender`。
{{% /tab %}}
{{< /tabs >}}

先用 Markdown 写正文，再加入短代码。

运行 hugo server --bind 127.0.0.1 --disableFastRender。

defaultTab 从 0 开始；placement 可为 top、bottom、start、end；type="underline" 使用下划线样式。每个 tab 必须直接放在 tabs 内。

这里外层使用尖括号形式，内层 tab 使用百分号形式，使面板中的 Markdown 经 Hugo 渲染。该版本 tab.html 直接输出内部 HTML，不能假设尖括号形式会自动解析面板中的 Markdown。

用同一组折叠做问答

{{< details summary="为什么预览能看到，构建后看不到？" name="writing-faq" >}}
先检查文章是否为草稿，以及日期是否晚于构建时间。
{{< /details >}}

{{< details summary="图片为什么显示不出来？" name="writing-faq" >}}
检查路径大小写，以及 URL 是否误写了 `static/` 前缀。
{{< /details >}}

为什么预览能看到，构建后看不到？

先检查文章是否为草稿，以及日期是否晚于构建时间。

图片为什么显示不出来？

检查路径大小写，以及 URL 是否误写了 static/ 前缀。

支持原生 details 分组的浏览器，会在打开一个项目时关闭同名组里的另一个。旧浏览器可能允许同时展开，但问答内容仍可阅读。不要给不同章节的独立问答误用相同 name。

在标签页里比较配置格式

{{< tabs defaultTab=1 type="underline" placement="top" >}}
{{% tab title="TOML" %}}
```toml
[params]
collection_list = true
collection_navigation = true
```
{{% /tab %}}
{{% tab title="YAML" %}}
```yaml
params:
 collection_list: true
 collection_navigation: true
```
{{% /tab %}}
{{< /tabs >}}

[params]
collection_list = true
collection_navigation = true

params:
 collection_list: true
 collection_navigation: true

defaultTab=1 默认选中第二个面板。本项目实际使用 TOML；YAML 面板仅展示对应写法，不需要把两份配置同时放进项目。

什么时候不该折叠

关键前提、必须执行的步骤和最终结论，最好直接放在正文中。折叠适合故障细节、长日志和补充推导；标签页适合几个互相替代的方案，不适合依次执行的步骤。

内容	更合适的组织方式
所有人都要执行的三步操作	有序列表
只在失败时需要的排查信息	折叠
同一配置的两种格式	标签页
决定能否继续的重要前提	正文或展开的提示框

发布前应实际点击每个标签和折叠项，并确认面板里的代码可以复制。还要用键盘 Tab 键检查控件是否可聚焦，避免只在鼠标操作下看起来正常。

居中引用 center-quote

{{< center-quote >}}
把经历写下来，让想法有迹可循。
{{< /center-quote >}}

把经历写下来，让想法有迹可循。

该短代码不需要额外参数，适合短引文，不宜包裹长篇段落。

version：标注版本信息

{{< version "1.0.0-beta.3" "new" >}}

第一个位置参数是版本号，第二个参数是状态，可用 new、changed、deleted、deprecated。默认链接由主题的 repo_version.url 与版本号拼接而成；此处链接到主题对应发布版本。

版本标记表达的是文章中的版本说明，不会自动安装或更新主题。当前站点真正的主题锁定来自 Git submodule 的提交记录。

timeline：按时间组织记录

{{< timeline reverse=false placement="bottom" >}}
events:
 - timestamp: "2026-10-01"
 content: "整理写作主题，列出最常查询的语法。"
 - timestamp: "2026-10-08"
 content: "补充源码和渲染效果，检查手机布局。"
 - timestamp: "2026-10-13"
 content: "将文章整理为五篇专题，形成可持续维护的手册。"
{{< /timeline >}}

整理写作主题，列出最常查询的语法。

2026-10-01

补充源码和渲染效果，检查手机布局。

2026-10-08

将文章整理为五篇专题，形成可持续维护的手册。

2026-10-13

内容是 YAML 数据：顶层为 events，每个事件有 timestamp 和 content。日期使用带引号的 ISO 格式，便于排序。reverse=true 可把较新的记录排在前面；placement 控制时间戳的位置。

时间线适合回顾阶段性变化，不适合代替任务清单。如果每一项都是“接下来要做什么”，请使用任务清单。

给短代码准备稳定的数据

复杂短代码通常由“容器参数”和“内部内容”两部分组成。先让一个最小例子正常渲染，再增加事件、图注或其他参数，排查问题会更直接。

检查点	例子
参数是否属于当前版本	对照 `layouts/_shortcodes/`
成对标签是否闭合	`timeline` 和 `/timeline`
内部数据格式是否正确	YAML 缩进、JSON 引号
演示源码是否转义	代码围栏里的短代码也要转义
是否依赖外部内容	外部视频、地图和远程图片可能需要网络

本手册优先演示不需要第三方账号、令牌或个人数据的短代码。音视频、地图等组件可以按文章需要再引入，避免每篇笔记都承担额外资源加载。

文件树 file-tree：说明目录结构

文件树适合展示文章包、配置目录和项目结构。相比截图，读者可以复制名称，还能展开或折叠目录。手册演示使用内联数据，不扫描实际项目目录。

可复制源码：

{{< file-tree level=2 folder_slash=true >}}
- name: my-note
 type: dir
 children:
 - name: index.md
 type: file
 - name: cover.webp
 type: file
 - name: images
 type: dir
 children:
 - name: diagram.png
 type: file
{{< /file-tree >}}

实际效果：

my-note/
- images/
  - diagram.png
- index.md
- cover.webp

参数或字段	说明
`level`	初始展开层级；`0` 全部折叠，`-1` 全部展开
`folder_slash`	为目录名显示末尾斜杠，使用当前版本的下划线写法
`name` / `type`	节点名称及类型，类型为 `dir` 或 `file`
`children`	目录下的子节点列表，注意 YAML 缩进
`file`	从页面资源或 assets 中读取 JSON、YAML、TOML 数据
`data`	从 `data/filetree/` 中读取指定数据
`path`	扫描文件系统目录；静态示例通常不需要

内容来源的优先级是内联内容、资源文件、数据文件、文件系统。建议文档优先使用内联数据，确保示例不会随着工作目录内容变化。单纯想展示可复制的目录文本，也可以直接使用普通代码块。

链接卡片 link：突出一个参考入口

段落中的普通引用优先使用 Markdown 链接；需要强调文档、工具或站点入口时，再使用卡片。下面显式指定图标，避免为了展示图标而在构建时请求远程 favicon。

{{< link
 href="https://gohugo.io/"
 content="Hugo 官方文档"
 title="查看内容组织、模板和构建说明"
 card=true
 card-icon="fa-solid fa-book"
>}}

Hugo 官方文档 gohugo.io/

参数	说明
`href`	链接目的地址，站内页面可以使用 `/posts/.../`
`content`	展示的链接文字
`title`	鼠标悬停时的补充说明
`card`	是否使用卡片样式
`card-icon`	卡片图标，可使用主题支持的 Font Awesome 类名

card-icon 是这个短代码的参数名，不应机械改成 card_icon。同一段不要堆叠过多卡片；一组长期维护的网站入口更适合放入本站的链接页数据。

原始 HTML raw：保留少量自定义标记

只有 Markdown 或现有短代码无法表达时，再使用 raw。例如，希望在一句话里保留 HTML 的键盘按键标记：

保存文件：{{< raw "span" >}}<kbd>⌘</kbd> + <kbd>S</kbd>{{< /raw >}}

保存文件：⌘ + S

第一个位置参数指定外层 HTML 标签，默认是 div。放在段落中时选 span，避免把块级元素塞进一行文字。raw 中的 Markdown 标记不会自动变成加粗或列表；需要自行写 HTML。

不要将不可信的脚本或整页 HTML 粘贴进文章。可以用标准 Markdown 表达的内容，继续使用标准语法，后续迁移和维护更轻松。

常用 Shortcodes 选择表

写作需求	推荐写法	注意事项
提示、警告、补充说明	`admonition`	根据内容选择语义，不只按颜色选择
收起较长的补充内容	`details`	关键结论留在外面
比较多种语言或配置	`tabs` / `tab`	标签名称明确，同组内容结构一致
展示目录结构	`file-tree`	优先用稳定的内联示例数据
强调参考入口	`link`	普通段落引用仍用 Markdown 链接
居中引用	`center-quote`	适合短句，不适合大段正文
标注版本变化	`version`	确认版本链接指向正确项目
按时间记录事件	`timeline`	保持时间格式一致
少量原始 HTML	`raw`	避免替代整篇文章的 Markdown 排版

图片与代码见富文本写作，公式与图表见数学公式与可视化图表。这些内容各自维护在对应专题，避免同一份示例出现多个不一致版本。

以上参数以本站固定版本的短代码源码为准。官方参考：扩展短代码、文件树。

富文本写作：图片、链接与代码

2025-01-01T09:00:00+08:00

图片与图注、链接与锚点、代码高亮与复制，以及文章资源管理。

本篇属于 Markdown 语法手册。按章内目录跳转，代码块提供可复制源码，其后的正文和组件展示实际效果。

图文排版示例：星空下的一页笔记

写完一段文字，有时可以留一张图，让读者稍作停顿。下面使用本站星空头像的 WebP 展示版，展示正文、较大图片和图注组合后的实际效果。

连接点303 · 把想法写进星空里

星点散落在深蓝色的背景上，中央的提示符像是一段尚未写完的命令。写作也可以从这里开始：先留下一个问题，再慢慢补上观察、尝试与答案。

图片负责呈现氛围，正文负责补充信息。 图注可以交代图片内容或来源；替代文本则应描述画面，方便图片加载失败或使用读屏时理解。

复制这段图文源码

写完一段文字，有时可以留一张图，让读者稍作停顿。

{{< image src="/images/avatars/avatar-starfield-dark.webp" alt="深蓝星空中，白色终端提示符与绿色光标居于中央" caption="连接点303 · 把想法写进星空里" width="640" linked=true >}}

星点散落在深蓝色的背景上，中央的提示符像是一段尚未写完的命令。

这里的 width="640" 控制桌面展示宽度，手机上由主题响应式样式缩小；不指定高度，以保留原图比例。点击图片可放大查看，图注会沿用本站的深浅色次要文字色。WebP 展示版位于 static/images/avatars/，PNG 原图保留在其 originals/ 子目录，无需修改或复制到 public/。

Markdown 图片

![连接点303终端图标](/favicon.svg "连接点303的标记")

连接点303的标记

方括号中是替代文本，便于读屏和加载失败时理解内容；引号中是标题。static/favicon.svg 在生成站点中对应 /favicon.svg，URL 不应包含 static/。

带图注的 image 短代码

{{< image src="/images/avatars/avatar-starfield-dark.webp" alt="深色星空中的头像" caption="连接点303 · 星空头像" width="320" linked=true >}}

连接点303 · 星空头像

参数	说明
`src`	图片路径；支持页面资源、assets 资源和静态资源
`alt`	描述图片内容，避免只写“图片”
`caption`	图注，支持 Markdown
`width` / `height`	显示尺寸，可仅指定宽度保留比例
`linked`	是否包裹原图链接
`loading`	默认 `lazy`；首屏必要图片可用 `eager`
`optimise`	是否启用主题图片优化

本页 front matter 使用 lightgallery: true。带标题或图注的图片可在画廊中查看；小屏幕宽度由主题响应式样式约束。

普通链接与页内锚点

[回到合集](/collections/markdown/)
[查看本页资源建议](#资源放在哪里)

回到合集 · 查看本页资源建议

内部链接优先使用稳定路径；文件改名后需要同步检查链接。

link 短代码与卡片

{{< link href="https://fixit.lruihao.cn/" content="主题官方文档" title="前往官方文档" card=true card-icon="fa-solid fa-book" >}}

主题官方文档 fixit.lruihao.cn/

href 指定目标，content 指定链接文字，title 提供悬浮提示，card=true 使用卡片布局。card-icon 指定 Font Awesome 图标，避免自动请求外部 favicon。省略 card 则显示行内链接。外部站点需要网络访问。

资源放在哪里

content/posts/a-trip/
├── index.md
└── coast.jpg

static/images/avatars/avatar-starfield-dark.webp
static/brand-wordmark.png
static/favicon.svg

文章专属图片推荐与 index.md 组成 leaf bundle，正文写 ![海岸](coast.jpg)。需要 Hugo 图片处理的公共资源放 assets/；需要原样发布的文件放 static/。public/ 是生成结果，不应直接编辑。

图片只展示，不打开原图

{{< image src="/favicon.svg" alt="连接点303终端标记" width="64" height="64" linked=false optimise=false >}}

linked=false 适合小图标，避免为装饰性图片提供没有必要的放大操作。optimise=false 明确关闭图片优化；SVG 本身是矢量图，不需要栅格化缩放。

使用明确的锚点

自动生成的中文标题锚点方便阅读，但标题改名后地址也可能改变。需要长期引用的章节可以指定英文 ID。

### 图片验收清单 {#image-review}

- 图片有明确的替代文本。
- 手机屏幕上没有横向溢出。

[跳到图片验收清单](#image-review)

图片验收清单

图片有明确的替代文本。
手机屏幕上没有横向溢出。

跳到图片验收清单

同一页面内 ID 必须唯一。标题属性由本站继承的 Goldmark 配置支持，不应把这类扩展写法视作所有 Markdown 编辑器都支持的语法。

用内部链接串起学习路径

{{< link href="/wiki/markdown-basics/" content="从基础排版开始" title="回到基础章节" >}}

从基础排版开始

对不需要特殊样式的链接，普通 Markdown 往往更简洁。短代码适合需要卡片、下载属性或图标等额外参数的场景；不要为了使用短代码而重写所有普通链接。

图片与链接的检查顺序

先确认原始文件存在，且文件名大小写一致。
看浏览器最终请求的路径，不要只看编辑器里的预览。
区分页面相对路径和站点根路径；page bundle 图片通常使用相对路径。
检查有无过大的图片，优先缩小源图或使用主题图片优化。
在深色背景下检查透明图片、黑色文字图片是否仍然清晰。
点击内部链接和锚点，确认跳到的是预期位置。

本站字标使用原始 PNG，图标使用 SVG；这两类文件可以共存。SVG 更适合线条图形，照片和复杂纹理更适合 WebP、JPEG 或 PNG，不必为了统一格式而强行转换。

代码块与复制

下面是 Markdown 源码，外层使用四个反引号，从而容纳里面的三个反引号。

```go {title="hello.go" hl_lines=[3]}
package main

func main() {
 println("你好，连接点303")
}
```

实际效果：

package main

func main() {
 println("你好，连接点303")
}

go 选择语法高亮语言，title 设置标题，hl_lines 指定高亮行（从 1 开始）。主题默认提供复制按钮。这里使用 v1 的块属性，旧版 data-* 属性不再作为写法示范。

代码高亮行与起始行号

```toml {title="hugo.toml 摘录" linenostart=20 hl_lines=[2,3]}
[params]
collection_list = true
collection_navigation = true
```

[params]
collection_list = true
collection_navigation = true

linenostart=20 改变显示的起始行号；hl_lines 仍按此代码片段从 1 开始计数，所以高亮的是显示编号 21、22 的两行。代码标题应说明片段来自哪里，不要让读者误以为这是完整配置。

用 diff 展示前后改动

```diff {title="草稿状态调整"}
-draft: true
+draft: false
 title: 我的第一篇笔记
```

-draft: true
+draft: false
 title: 我的第一篇笔记

行首 - 表示删除，+ 表示新增，空格表示上下文。这种代码块适合解释修改，不适合直接复制为配置文件；读者需要去掉 diff 标记后再使用。

多语言代码片段

同一个概念可用不同语法表达。语言名控制高亮，不会执行代码。

```json {title="article.json"}
{
 "title": "连接点303笔记",
 "draft": false,
 "tags": ["Markdown", "写作"]
}
```

{
 "title": "连接点303笔记",
 "draft": false,
 "tags": ["Markdown", "写作"]
}

```yaml {title="同一份数据的 YAML 表达"}
title: 连接点303笔记
draft: false
tags:
 - Markdown
 - 写作
```

title: 连接点303笔记
draft: false
tags:
 - Markdown
 - 写作

JSON 要求双引号和严格的逗号分隔；YAML 用缩进表达结构。文章里可以并列展示它们，方便比较，但不能把两种语法混写到同一个配置文件。

不需要高亮的输出

日志、目录树和终端输出可标记为 text，避免被误判成程序语言。

```text {title="示例构建摘要"}
Pages: 47
Warnings: 0
Errors: 0
```

Pages: 47
Warnings: 0
Errors: 0

这里是为了展示排版而写的示例摘要，不是实时构建结果。教程应清楚区分“输入命令”和“输出结果”，以免读者把日志也复制到终端执行。

行内反引号与代码围栏

用 `` `name` `` 展示包含反引号的行内代码。

用 `name` 展示包含反引号的行内代码。

如果正文需要展示三个反引号组成的代码围栏，外层就用四个反引号；需要展示四个时，外层再多一个。源码与渲染效果分开写，比在代码块里叠加复杂转义更容易维护。

数学公式与可视化图表

2025-01-01T09:00:00+08:00

KaTeX 公式、Mermaid 流程与时序图、ECharts 柱状图与折线图及环形图。

本篇属于 Markdown 语法手册。按章内目录跳转，代码块提供可复制源码，其后的正文和组件展示实际效果。

行内与块级公式

圆的面积为 $A = \pi r^2$。

$$
\sum_{k=1}^{n} k = \frac{n(n+1)}{2}
$$

圆的面积为 $A = \pi r^2$ 。

\sum_{k=1}^{n} k = \frac{n(n+1)}{2}

单个美元符号包裹行内公式，双美元符号包裹独立公式。本站继承主题的 Goldmark passthrough，并使用 v1 的 math.enable 和 math.type: katex，公式在构建时渲染。不要使用旧版 params.page.math。

math:
 enable: true
 type: katex

上面是页面 front matter 的覆盖写法。本站还启用了 params.math.katex.throw_on_error，公式语法错误会使构建失败，方便发布前发现问题。

分式、根号与下标

$$
f(x) = \frac{x^2 + 1}{\sqrt{x + 2}}, \qquad x > -2
$$

平均值为 $\bar{x} = \frac{1}{n}\sum_{i=1}^{n}x_i$。

f(x) = \frac{x^2 + 1}{\sqrt{x + 2}}, \qquad x > -2

平均值为 $\bar{x} = \frac{1}{n}\sum_{i=1}^{n}x_i$ 。

\frac 接收分子和分母，\sqrt 表示平方根，_ 和 ^ 分别表示下标和上标。超过一个字符的内容要用花括号分组，例如 x_{i+1}，否则通常只有紧接着的一个字符属于下标。

多行推导与对齐

$$
\begin{aligned}
(a+b)^2 &= (a+b)(a+b) \\
 &= a^2 + 2ab + b^2
\end{aligned}
$$

\begin{aligned} (a+b)^2 &= (a+b)(a+b) \\ &= a^2 + 2ab + b^2 \end{aligned}

aligned 环境用于对齐推导，& 指定对齐位置，两个反斜杠表示换行。正文直接写 LaTeX 时不需要像 JSON 字符串一样把所有反斜杠再次转义。

分段函数与矩阵

$$
|x| = \begin{cases}
x, & x \ge 0 \\
-x, & x < 0
\end{cases}
\qquad
A = \begin{bmatrix}1 & 2 \\ 3 & 4\end{bmatrix}
$$

|x| = \begin{cases} x, & x \ge 0 \\ -x, & x < 0 \end{cases} \qquad A = \begin{bmatrix}1 & 2 \\ 3 & 4\end{bmatrix}

cases 提供左大括号，bmatrix 提供方括号。矩阵中的 & 分隔列，两个反斜杠分隔行。手机上特别长的公式应拆分，避免为了保持一行而把文字缩到难以阅读。

公式排查清单

现象	优先检查
公式原样显示	`math.enable` 和 passthrough 配置
下标只包含一个字符	是否使用花括号分组
构建报告 KaTeX 错误	命令拼写、括号闭合、环境名称
公式太宽	改用多行推导或拆成多个块
普通金额被识别为数学内容	对字面美元符号使用反斜杠转义

不要把完整 LaTeX 文档的 documentclass 等命令复制到公式块。网页公式渲染支持的是数学表达式，不能把它当成完整的 TeX 排版系统。

Mermaid 流程图

{{< mermaid >}}
flowchart LR
 A[写 Markdown] --> B[本地预览]
 B --> C{检查通过?}
 C -->|是| D[生产构建]
 C -->|否| A
{{< /mermaid >}}

flowchart LR
 A[写 Markdown] --> B[本地预览]
 B --> C{检查通过?}
 C -->|是| D[生产构建]
 C -->|否| A

flowchart LR 表示从左到右，改为 TD 则从上到下。节点 ID 用简短英文，方括号内显示中文。短代码可设置 wrapper=false 关闭图表工具栏；默认继承站点配置。

也可使用 Mermaid 代码块：

```mermaid
sequenceDiagram
 participant A as 作者
 participant H as Hugo
 A->>H: 保存文章
 H-->>A: 更新预览
```

sequenceDiagram
 participant A as 作者
 participant H as Hugo
 A->>H: 保存文章
 H-->>A: 更新预览

Mermaid 在浏览器中运行，首次打开需要访问配置中的 jsDelivr 模块。没有网络时，仍可阅读相邻的图表源码和文字说明。

时序图中的成功与失败分支

```mermaid
sequenceDiagram
 participant W as 作者
 participant H as Hugo
 W->>H: 提交待构建的 Markdown
 alt 语法检查通过
 H-->>W: 生成静态页面
 else 存在错误
 H-->>W: 返回文件位置和错误说明
 end
```

sequenceDiagram
 participant W as 作者
 participant H as Hugo
 W->>H: 提交待构建的 Markdown
 alt 语法检查通过
 H-->>W: 生成静态页面
 else 存在错误
 H-->>W: 返回文件位置和错误说明
 end

participant 定义参与者，英文 ID 用来连接，as 后显示中文名称。alt、else、end 描述互斥分支。实线和虚线箭头可以区分请求与响应，但这种约定应在图附近说明。

流程图分组

```mermaid
flowchart TD
 subgraph Draft[写作阶段]
 A[记录想法] --> B[整理结构]
 B --> C[补齐示例]
 end
 subgraph Review[检查阶段]
 D[本地预览] --> E[检查链接]
 E --> F[生产构建]
 end
 C --> D
```

flowchart TD
 subgraph Draft[写作阶段]
 A[记录想法] --> B[整理结构]
 B --> C[补齐示例]
 end
 subgraph Review[检查阶段]
 D[本地预览] --> E[检查链接]
 E --> F[生产构建]
 end
 C --> D

subgraph 把相关步骤归成一组。纵向 TD 通常更适合手机，横向 LR 适合节点较少的流程。长说明放在正文，节点里只保留简短动作。

图表写作建议

一张图回答一个问题，避免把所有细节塞进同一张图。
节点 ID 使用稳定英文，显示文字可以改为中文。
图后补一两句话解释结论，便于读屏和无网络时阅读。
不依赖颜色作为唯一标识，同时写出节点名称和分支文字。
本主题会在图进入视口后延迟绘制，刚打开页面时未绘制的图不一定代表错误。

ECharts 柱状图

{{< echarts width="100%" height="360px" >}}
{
 "tooltip": {"trigger": "axis"},
 "legend": {"data": ["示例数"], "top": 12},
 "grid": {"left": 45, "right": 20, "bottom": 45},
 "xAxis": {"type": "category", "data": ["基础", "扩展", "短代码", "图片", "图表"]},
 "yAxis": {"type": "value", "minInterval": 1},
 "series": [{"name": "示例数", "type": "bar", "data": [6, 6, 4, 5, 4]}]
}
{{< /echarts >}}

{
 "tooltip": {"trigger": "axis"},
 "legend": {"data": ["示例数"], "top": 12},
 "grid": {"left": 45, "right": 20, "bottom": 45},
 "xAxis": {"type": "category", "data": ["基础", "扩展", "短代码", "图片", "图表"]},
 "yAxis": {"type": "value", "minInterval": 1},
 "series": [{"name": "示例数", "type": "bar", "data": [6, 6, 4, 5, 4]}]
}

数据仅用于演示。width="100%" 适配容器，height 必须提供适合阅读的高度。默认内容为严格 JSON：键名和字符串使用双引号，不能加注释和尾随逗号。

xAxis 定义横轴，yAxis 定义纵轴，series 定义数据系列。将 type 从 bar 改成 line 可得到折线图。主题会根据深浅色模式初始化配色，并在尺寸变化时调整图表。

折线图：观察变化

{{< echarts width="100%" height="340px" >}}
{
 "tooltip": {"trigger": "axis"},
 "grid": {"left": 45, "right": 20, "top": 30, "bottom": 45},
 "xAxis": {"type": "category", "boundaryGap": false, "data": ["周一", "周二", "周三", "周四", "周五"]},
 "yAxis": {"type": "value", "name": "字数"},
 "series": [{"name": "写作字数", "type": "line", "data": [300, 600, 450, 900, 750], "smooth": false}]
}
{{< /echarts >}}

{
 "tooltip": {"trigger": "axis"},
 "grid": {"left": 45, "right": 20, "top": 30, "bottom": 45},
 "xAxis": {"type": "category", "boundaryGap": false, "data": ["周一", "周二", "周三", "周四", "周五"]},
 "yAxis": {"type": "value", "name": "字数"},
 "series": [{"name": "写作字数", "type": "line", "data": [300, 600, 450, 900, 750], "smooth": false}]
}

这组数据只是示例。boundaryGap=false 让折线两端贴近坐标区边界，smooth=false 用直线连接观测点，避免平滑曲线让读者误以为中间过程也经过测量。为纵轴标明单位，比只显示一列数字更清楚。

环形图：展示组成

{{< echarts width="100%" height="360px" >}}
{
 "tooltip": {"trigger": "item"},
 "legend": {"bottom": 8},
 "series": [{
 "name": "时间分配",
 "type": "pie",
 "radius": ["38%", "64%"],
 "center": ["50%", "43%"],
 "label": {"show": false},
 "data": [
 {"name": "写作", "value": 50},
 {"name": "校对", "value": 30},
 {"name": "整理", "value": 20}
 ]
 }]
}
{{< /echarts >}}

{
 "tooltip": {"trigger": "item"},
 "legend": {"bottom": 8},
 "series": [{
 "name": "时间分配",
 "type": "pie",
 "radius": ["38%", "64%"],
 "center": ["50%", "43%"],
 "label": {"show": false},
 "data": [
 {"name": "写作", "value": 50},
 {"name": "校对", "value": 30},
 {"name": "整理", "value": 20}
 ]
 }]
}

radius 的两个值分别是内、外半径；内半径大于零时形成环形图。示例隐藏外侧标签以适配小屏，通过图例和提示框读取类别。为了让不操作图表的读者也能获得数据，正文再给出一份表格：

活动	示例占比
写作	50%
校对	30%
整理	20%

参数与排查

参数或现象	说明
`tooltip.trigger`	`axis` 适合坐标轴图；`item` 适合扇区等独立图形
`grid`	控制坐标区域的留白，避免刻度被裁剪
`legend`	展示系列或类别名称，可用于切换显示
图表空白	检查浏览器脚本是否加载，以及 JSON 是否有效
图表高度为零	给短代码设置明确的 `height`
标签挤在一起	缩短标签、减少刻度或调整布局

这三个示例都使用主题本地 ECharts 资源，不需要额外启用旧版 params.page 配置。图表内部颜色承担数据区分作用，与站点正文颜色不必完全相同；仍应检查深浅模式下的对比度。

Markmap：用 Markdown 写思维导图

Markmap 适合把标题和列表转换成可展开的知识结构。本站已安装官方 cmpt-markmap 组件，普通文章使用 markmap 代码围栏即可，不需要更改文章布局。

可复制源码：

```markmap {height="360px"}
# Markdown 写作
## 组织内容
- 标题与段落
- 列表与引用
## 丰富表达
- 图片与链接
- 代码与公式
## 发布检查
- 本地预览
- 链接与移动端
```

实际效果：

# Markdown 写作
## 组织内容
- 标题与段落
- 列表与引用
## 丰富表达
- 图片与链接
- 代码与公式
## 发布检查
- 本地预览
- 链接与移动端

标题构成主分支，列表构成子节点；点击节点圆点可以折叠或展开，工具栏支持缩放、适配视口与全屏。上图把写作分成组织内容、丰富表达、发布检查三部分。

配置	说明
围栏语言 `markmap`	将代码块渲染成思维导图
`height="360px"`	图表区域高度，省略时为 `24rem`
页面 `layout: markmap`	可选的全文分栏导图布局；普通文章无需设置
`params.markmap` 或页面 `markmap`	配置键使用 `snake_case`，如 `color_freeze_level`
围栏内 YAML 的 `markmap`	使用 Markmap 原生 `camelCase`，如 `colorFreezeLevel`

组件根据内容渲染标记加载资源；首页处理含导图文章的摘要时也可能加载 Markmap 资源。导图运行时会从 CDN 获取依赖，需要网络；因此保留上方源码和文字说明，便于复制与阅读。

文章模板与写作发布流程

2025-01-01T09:00:00+08:00

元数据、草稿、摘要、文章模板、本地预览与发布检查。

本篇属于 Markdown 语法手册。按章内目录跳转，代码块提供可复制源码，其后的正文和组件展示实际效果。

内容文件放在哪里

本站按官方内容组织说明整理目录。日常文章放在 content/posts/，Wiki 知识文档放在 content/wiki/，关于和链接等独立页面放在 content/；不要编辑构建生成的 public/。

content/
├── about.md # 关于页
├── links.md # 链接页，layout: friends
├── posts/
│ ├── _index.md # 文章列表的标题和说明
│ └── my-note/ # 带资源的文章包（新文章示例）
│ ├── index.md # 文章正文
│ ├── cover.webp # 本文封面
│ └── diagram.png # 本文插图
├── wiki/
│ ├── _index.md # 普通页面使用独立 wiki 类型
│ └── markdown/
│ └── Markdown 基础与扩展语法.md # slug: markdown-basics；URL 不变
└── collections/
 └── markdown-语法/_index.md # 合集介绍与固定地址
assets/images/ # 多篇文章共用、可处理的图片
static/badge/ # 原样发布的徽章
data/friends.yml # 链接页面的数据

my-note/ 是目录示例，不是已发布的文章。本站 Markdown 手册使用文章标题作为文件名，并在 Front Matter 中设置固定英文 slug，例如 Markdown 基础与扩展语法.md 设置 slug: markdown-basics，访问地址仍为 /wiki/markdown-basics/。以后修改文件名或标题时保留 slug，地址就不会随之变化。其他内容仍可使用简短英文和连字符命名。

单文件文章与文章包

写法	适用情况	默认访问地址
`content/posts/my-note.md`	主要是文字，图片不多	`/posts/my-note/`
`content/posts/my-note/index.md`	图片、附件与文章一起维护	`/posts/my-note/`
`content/posts/_index.md`	描述文章列表，不是独立文章	`/posts/`
`content/wiki/markdown/my-note.md`	Wiki 知识文档	`/wiki/my-note/`
`content/about.md`	独立页面	`/about/`

index.md 表示叶子页面包，适合一篇文章和它的资源；_index.md 表示分支或列表页，适合栏目与合集。不要为了给文章加图片，把 index.md 写成 _index.md，也不要同时创建同名的单文件文章和文章包。

新建纯文字文章：

./scripts/hugo.sh new content posts/my-note.md

新建带图文章：

./scripts/hugo.sh new content posts/my-note/index.md

把图片复制到 content/posts/my-note/ 后，用相对文件名引用：

---
title: 我的图文笔记
date: 2026-10-14T09:00:00+08:00
draft: true
authors: [yuehei]
description: 记录一次图文写作的过程。
featured_image: cover.webp
tags: [笔记]
---

这里写一段可独立阅读的首页摘要。

<!--more-->

## 正文

![流程示意图](diagram.png)

先放好示例中引用的两张图片，再预览。本站首页将封面显示为标题上方的宽幅图片；无封面的文章不必设置 featured_image。

本地资源路径怎么写

实际位置	引用示例	用途
`content/posts/my-note/diagram.png`	`diagram.png`	本文独有的图片，随文章包管理
`assets/images/shared.png`	`/images/shared.png`	多篇文章共享、可交给 Hugo 处理的资源
`static/badge/fixit-logo.svg`	`/badge/fixit-logo.svg`	原样输出的文件

主题资源解析会先找页面资源，再找 assets，最后使用静态路径。引用时不要写成 /static/badge/... 或 /assets/images/...；这两个目录名不是发布后的 URL 前缀。尽量避免在多个位置存放同名资源，以免命中意外的文件。

图片语法、图注和代码高亮详见富文本写作。

目录、栏目与合集的区别

文件目录决定内容组织和默认 URL；本站 mainSections = ['posts', 'wiki'] 控制首页主要文章来源。
categories 和 tags 在文章、Wiki 及后续其他栏目之间共享；分类表示较宽泛的主题，标签表示具体工具、对象或问题，不要求移动文件。
collections 用来组织连续阅读的内容；本站手册名称为 Markdown 语法。
manual_part 是本站手册目录使用的自定义分组字段，不是所有文章都需要填写。

分类按需填写，不要求每篇都有；标签使用少量稳定关键词。同一主题跨栏目使用相同名称，例如 Hugo 文章和 Hugo 部署 Wiki 都可使用 categories: ['技术']、tags: [Hugo]，不另建“Wiki 技术”或“文章技术”。分类和标签页会聚合来自不同栏目的关联内容。

Wiki 不再作为分类名称。“收录于 Wiki”始终指向 Wiki 栏目并保留彩色图标，有合集时继续显示合集；即使 Wiki 文档填写了主题分类，也不在这一行追加分类。普通文章仍显示分类。新增栏目是否进入首页、全站归档及订阅，需另行配置，不由分类或标签决定。

新增手册文章时，可填写：

collections: ['Markdown 语法']
manual_part: '富文本写作'

当前分组为“基础排版、富文本写作、组件、数学与图表、写作流程”。如果创建新的分组名称，还要同步更新 layouts/manual.html，否则它不会出现在本站自定义的合集目录里。文章顺序由日期升序决定，不需要给标题加数字编号。

本站 content/wiki/_index.md 通过 cascade 为普通页面统一设置 type: wiki 和 url: /wiki/:slugorcontentbasename/，阅读模板通过挂载复用 FixIt 的原生实现，新增 Wiki 文档无需重复填写，也不再自动赋予 Wiki 分类。target.kind: page 避免把栏目列表页当成文章。知识文档使用 /wiki/.../ 地址；日常写作继续使用 content/posts/。合集仍由 collections 字段关联，不由文件目录自动决定。 markdown/ 仅用于文件整理，不设置 _index.md，因此面包屑直接显示“Wiki → 文章标题”，Wiki 下所有普通文章 URL 使用 /wiki/文章名/，省略中间目录，不添加 aliases。

迁移文章时，在 Front Matter 的 aliases 中保留旧 URL，并更新正文内链。Twikoo 默认按 URL 路径关联评论，旧地址跳转不会自动迁移评论；若原文章已有评论，应同时处理评论数据或单独保留其评论路径。

独立页面与链接列表

普通独立页面可使用 layout: page；本站关于页已经采用这种方式。链接页使用内置的 layout: friends 和 friend_scheme: domino，实际链接维护在 data/friends.yml：

- nickname: 网站名称
 url: https://example.com/
 avatar: /images/site-avatar.png
 description: 一句话说明这个网站。
 weight: 10

头像需要先保存到对应位置；也可省略 avatar 使用默认图标。权重越大越靠前。添加链接不需要安装项目组件，也不需要 GitHub 仓库或访问令牌。

最小文章头部

---
title: 我的第一篇笔记
date: 2026-10-01T09:00:00+08:00
draft: false
authors: [yuehei]
tags: [笔记]
collections: ['Markdown 语法']
---

draft: true 只在带 -D 的预览中出现；description 可提供文章摘要。合集文章依日期升序排列，请给每篇安排明确的日期。

给长文章写一个有用的开头

技术文章的开头可以回答三个问题：读者遇到了什么、这篇文章解决到什么程度、需要什么前置条件。下面是一段可改写的示范：

我想把零散的笔记整理成一个可以持续更新的博客。
这篇文章记录从新建 Markdown 文件到本地预览的最短流程。

开始前需要准备：

- 一个已能运行的 Hugo 项目。
- 支持 UTF-8 的文本编辑器。
- 十分钟可以专心写作的时间。

我想把零散的笔记整理成一个可以持续更新的博客。这篇文章记录从新建 Markdown 文件到本地预览的最短流程。

开始前需要准备：

一个已能运行的 Hugo 项目。
支持 UTF-8 的文本编辑器。
十分钟可以专心写作的时间。

本站使用显式摘要分隔标记控制首页摘录，见本页源文件中的 。它是写在正文中的 Hugo 摘要标记，不应放入文章头部。首页摘要应能独立说明文章主题，而不是只剩下“前言”两个字。

一份可复制的短文骨架

---
title: 一次小改动的记录
date: 2026-10-13T09:00:00+08:00
draft: true
authors: [yuehei]
description: 记录问题、尝试与结论。
tags: [笔记]
---

用两三句话交代这次遇到的问题。

## 当时的情况

写下触发条件、期望结果和实际结果。

## 我做了什么

1. 先确认最容易验证的事实。
2. 每次只改变一个条件。
3. 保存有价值的观察结果。

## 得到的结论

区分已经验证的结论与仍然需要观察的部分。

## 后续可以尝试

- [ ] 补充另一个使用场景。
- [ ] 一周后回看这次判断。

这是完整文件模板，不应直接追加到已有正文里。创建新文件后，先检查标题和日期，发布前再设置 draft: false。日期晚于构建时间的文章也可能不出现在普通构建中。

常见问题速查

现象	常见原因	调整方式
标题显示成普通文字	`#` 后没有空格	写成 `## 标题`
两段连成一段	段落之间没有空行	空一行再写下一段
子列表跑出父列表	缩进不足或混用制表符	使用空格，对齐正文列
星号没有按预期显示	被识别成强调语法	写成 `\*`
文章没有出现在首页	草稿状态或未来日期	检查 `draft`、`date` 和预览参数

练习：用这一篇介绍的语法写一则周记，包含两个二级标题、一个列表、一处引用和一个内部链接。参照基础与扩展语法，再为它增加任务清单和脚注。

选择哪种结构

要表达的内容	推荐结构	原因
两个版本的差别	diff 代码块	改动位置一眼可见
多个参数的含义	简短表格	便于按列比较
有顺序的操作	有序列表	明确先后依赖
发布前的检查	任务清单	完成标准清楚
次要背景和来源	脚注	保持主线连贯
多套可选方案	标签页	避免连续堆叠大段内容

可以用折叠与标签页组织这些内容，让长文章既能连续阅读，也能快速查找。

常用文章元数据

字段	用途	建议
`title`	页面标题	明确说明文章要解决的问题
`description`	页面描述	用一句完整的话概括价值
`date`	发布日期与排序依据	带时区，避免时间含糊
`lastmod`	最近更新时间	有实质更新时维护
`draft`	是否草稿	发布前检查是否为 `false`
`tags`	交叉检索	少量稳定关键词
`categories`	内容归类	使用清晰的分类名
`collections`	连续阅读的合集	本手册使用 `Markdown 语法`
`aliases`	旧地址跳转	改 URL 时保留必要旧路径

文章拆分或合并时，最容易遗漏的是旧链接和合集归属。标题可自由调整，已经分享过的 URL 应尽量稳定；需要改路径时，为旧地址添加别名。

本地预览与生产构建

./scripts/hugo.sh server --bind 127.0.0.1 --port 1313 --disableFastRender -D

预览服务启动后，在另一终端确认实际监听地址：

lsof -nP -iTCP:1313 -sTCP:LISTEN

应看到 127.0.0.1:1313。这表示服务只对本机开放。浏览器访问本地地址检查文章，完成后使用 Ctrl+C 停止服务。

./scripts/hugo.sh --environment production --gc --minify --cleanDestinationDir

生产构建生成 public/，不等于上传或部署。本站的 Hugo 包装脚本只负责找到本地 Dart Sass 并设置缓存目录，底层仍直接调用 Hugo。

可以复用的发布检查清单

- [ ] 标题、摘要和发布日期正确
- [ ] draft 已改为 false
- [ ] 合集名称与已有文章一致
- [ ] 每个代码片段都说明了输入和结果
- [ ] 演示短代码没有在源码区意外执行
- [ ] 图片、内部链接和锚点可访问
- [ ] 桌面、手机和深色模式正常
- [ ] 生产构建通过

标题、摘要和发布日期正确
draft 已改为 false
合集名称与已有文章一致
每个代码片段都说明了输入和结果
演示短代码没有在源码区意外执行
图片、内部链接和锚点可访问
桌面、手机和深色模式正常
生产构建通过

这里的清单是供每篇新文章复用的模板，不表示本手册的实时验收状态。