[{"content":" 目录 一、快速开始 二、Front Matter 完全指南 三、Markdown 基础语法 四、PaperMod 主题短代码 五、Hugo 内置短代码 六、本站增强语法 七、写作工具与工作流 八、实战：完整文章示例 九、常见坑与排查 十、速查表 一、快速开始 1.1 三个命令 hugo new content posts/我的新文章.md # 新建文章（自动套用 archetypes/default.md 模板） hugo server -D # 本地预览（-D 表示包含草稿），打开 http://localhost:1313 hugo --gc --minify # 构建发布（产物在 public/ 目录） 1.2 一篇文章的最小结构 --- title: \u0026#34;文章标题\u0026#34; date: 2026-10-07T10:00:00+08:00 draft: false tags: [\u0026#34;标签1\u0026#34;, \u0026#34;标签2\u0026#34;] categories: [\u0026#34;分类\u0026#34;] --- 正文从这里开始。 1.3 写作流程建议 hugo new content posts/xxx.md 新建（默认 draft: true） 写内容，浏览器开着 hugo server -D 实时预览 写完把 draft 改为 false hugo --gc --minify 构建，把 public/ 部署到托管平台 二、Front Matter 完全指南 Front matter 是文章头部的 YAML 配置块（--- 包裹）。所有字段都是可选的，不写的字段会使用 hugo.yaml 里的全局默认值。\n2.1 完整字段表 --- # ===== 基础信息 ===== title: \u0026#34;文章标题\u0026#34; # 必需。显示在页面顶部与列表页 date: 2026-10-07T10:00:00+08:00 # 必需。发布时间（推荐 ISO 8601 格式，带时区） lastmod: 2026-10-08T15:30:00+08:00 # 最后修改时间（会显示在页面上） draft: false # true = 草稿（构建时跳过，预览需加 -D） # ===== 描述与分类 ===== description: \u0026#34;文章摘要，显示在列表页、搜索结果与分享卡片\u0026#34; # 建议 50~150 字 summary: \u0026#34;列表页摘要（留空则自动截取正文开头）\u0026#34; # 可选 tags: [\u0026#34;哲学\u0026#34;, \u0026#34;读书\u0026#34;] # 标签（对应 /tags/ 页面） categories: [\u0026#34;随笔\u0026#34;] # 分类（对应 /categories/ 页面，Hugo 不支持多级） keywords: [\u0026#34;关键词1\u0026#34;, \u0026#34;关键词2\u0026#34;] # SEO 关键词 author: \u0026#34;Lumoes\u0026#34; # 作者（留空用全局配置） # ===== 封面图（对象结构，注意缩进）===== cover: image: \u0026#34;/images/cover/example.jpg\u0026#34; # 图片路径（相对 static/），如放 static/images/cover/ 就写 /images/cover/xxx.jpg alt: \u0026#34;封面描述\u0026#34; # 无障碍与 SEO caption: \u0026#34;封面说明文字\u0026#34; # 图片下方说明（可留空） relative: false # true = 路径相对于当前文章目录；false = 相对于 static/ # ===== 显示控制（不写则用全局默认）===== ShowToc: true # 显示目录 TocOpen: false # 目录默认展开 hidemeta: false # 隐藏日期/作者/阅读时间等元信息（适合「关于」页） hideSummary: false # 列表页不显示摘要 comments: true # 显示评论区（需先接入评论系统） ShowReadingTime: true # 显示阅读时间 ShowWordCount: true # 显示字数 ShowShareButtons: true # 显示分享按钮 ShowBreadCrumbs: true # 显示面包屑导航 ShowPostNavLinks: true # 显示上一篇/下一篇 ShowCodeCopyButtons: true # 代码块显示复制按钮 hideFooter: false # 隐藏页脚 # ===== 功能开关 ===== math: true # 开启数学公式（正文出现 $$ 也会自动开启，可省略） searchHidden: true # 从站内搜索中排除本文 robotsNoIndex: true # 让搜索引擎不收录本文 slug: \u0026#34;custom-url\u0026#34; # 自定义 URL（默认用文件名） # ===== 编辑链接（可选）===== editPost: URL: \u0026#34;https://github.com/你/仓库/content\u0026#34; Text: \u0026#34;编辑此页\u0026#34; appendFilePath: true --- 2.2 三种常用组合 普通文章（大多数情况）：\n--- title: \u0026#34;文章标题\u0026#34; date: 2026-10-07T10:00:00+08:00 draft: false tags: [\u0026#34;标签\u0026#34;] categories: [\u0026#34;随笔\u0026#34;] description: \u0026#34;一句话摘要\u0026#34; cover: image: \u0026#34;/images/cover/x.jpg\u0026#34; --- 静态页面（关于、友链等，无日期无目录）：\n--- title: \u0026#34;关于\u0026#34; url: \u0026#34;/about/\u0026#34; ShowToc: false hidemeta: true comments: false --- 技术长文（开目录、开公式）：\n--- title: \u0026#34;深入理解 XXX\u0026#34; date: 2026-10-07T10:00:00+08:00 tags: [\u0026#34;技术\u0026#34;] categories: [\u0026#34;技术\u0026#34;] ShowToc: true TocOpen: true math: true --- 2.3 字段优先级 同一个字段可以写在三处，优先级从高到低：\n文章 front matter（最高，覆盖下面两者） hugo.yaml 的 params（站点默认值） 主题内部默认值（最低） 例如：全局 ShowToc: true，某篇文章想关掉就写 ShowToc: false。\n三、Markdown 基础语法 3.1 标题 # 一级标题（一般不用，文章标题已是一级） ## 二级标题 ### 三级标题 #### 四级标题 ##### 五级标题 ###### 六级标题 目录（TOC）默认只收录 二级到四级 标题（可在 hugo.yaml 的 markup.tableOfContents 调整）。\n3.2 文本样式 **加粗** *斜体* ***粗斜体*** ~~删除线~~ `行内代码` 普通文字 效果：加粗、斜体、粗斜体、删除线、行内代码\n3.3 列表 - 无序项 - 无序项 - 嵌套项（缩进 2 空格） - 更深嵌套（缩进 4 空格） 1. 有序项 2. 有序项 1. 嵌套有序 - [x] 已完成的任务 - [ ] 未完成的任务 任务列表在 PaperMod 里会渲染成复选框样式，很适合写「清单」「进度」。\n3.4 引用 \u0026gt; 单行引用 \u0026gt; 多段引用第一段 \u0026gt; \u0026gt; 多段引用第二段 \u0026gt; 引用中嵌套引用 \u0026gt; \u0026gt; \u0026gt; 第二层引用 \u0026gt; **引用里也支持 Markdown**，比如**加粗**和[链接](https://example.com) 3.5 代码 行内代码：用反引号包裹，如 const a = 1\n代码块：三个反引号 + 语言名（会有语法高亮和复制按钮）\n```python def hello(name): return f\u0026#34;Hello, {name}\u0026#34; ``` ```javascript const greet = (name) =\u0026gt; `Hello, ${name}`; ``` ```bash hugo server -D ``` ```text 没有语法高亮的纯文本块（画 ASCII 图、贴日志时用） ``` 支持的语言名（部分）：python javascript typescript java go rust c cpp csharp php ruby sql bash shell powershell yaml json toml xml html css scss markdown text diff nginx dockerfile\n3.6 链接 [显示文字](https://example.com) [带标题的链接](https://example.com \u0026#34;鼠标悬停显示的文字\u0026#34;) \u0026lt;!-- 站内链接（推荐用 ref，路径改了也不会失效）--\u0026gt; [看这篇文章]({{\u0026lt; ref \u0026#34;posts/syntax-demo.md\u0026#34; \u0026gt;}}) \u0026lt;!-- 锚点跳转 --\u0026gt; [跳到本页某节](#三markdown-基础语法) 直接写裸链接也会自动变成可点击的链接：https://example.com\n3.7 图片 \u0026lt;!-- 基础写法（PaperMod 会自动把 alt 显示为图注）--\u0026gt; ![图片说明](/images/example.png) \u0026lt;!-- 带链接的图片 --\u0026gt; [![图片说明](/images/example.png)](https://example.com) 图片放在 static/images/ 目录下，引用路径写 /images/xxx.png 需要更精细控制（标题、图注、对齐）请用 figure 短代码（见 4.1）\n3.8 表格 | 左对齐 | 居中 | 右对齐 | |:---|:---:|---:| | 内容 | 内容 | 内容 | | 内容 | 内容 | 内容 | 效果：\n左对齐 居中 右对齐 内容 内容 内容 3.9 分割线 --- ⚠️ 注意：--- 前后要空一行，否则可能被误解析为标题下划线或 front matter。\n3.10 脚注 这句话有个脚注[^1]，还有另一个[^note]。 [^1]: 这是第一个脚注的内容。 [^note]: 脚注名可以是文字，会自动编号。 3.11 转义字符 需要显示 Markdown 符号本身时，在前面加反斜杠：\n\\* 这不是斜体 \\* \\# 这不是标题 \\[方括号\\] 不是链接 3.12 内联 HTML 本站在 hugo.yaml 里开启了 unsafe: true，所以可以直接在正文里写 HTML：\n\u0026lt;span style=\u0026#34;color: #ef4444;\u0026#34;\u0026gt;红色文字\u0026lt;/span\u0026gt; \u0026lt;u\u0026gt;下划线\u0026lt;/u\u0026gt; \u0026lt;kbd\u0026gt;Ctrl\u0026lt;/kbd\u0026gt; + \u0026lt;kbd\u0026gt;C\u0026lt;/kbd\u0026gt; \u0026lt;abbr title=\u0026#34;HyperText Markup Language\u0026#34;\u0026gt;HTML\u0026lt;/abbr\u0026gt; \u0026lt;br\u0026gt; \u0026lt;div style=\u0026#34;text-align: center;\u0026#34;\u0026gt;居中内容\u0026lt;/div\u0026gt; 这是本站「提示框」「高亮」「两栏」等增强语法的实现基础（见第六节）。\n3.13 原生折叠（HTML details） 不需要短代码的折叠写法：\n\u0026lt;details\u0026gt; \u0026lt;summary\u0026gt;点击展开\u0026lt;/summary\u0026gt; 这里是被折叠的内容，**支持 Markdown**。 \u0026lt;/details\u0026gt; 推荐用 collapse 短代码（见 4.3），样式更统一。\n四、PaperMod 主题短代码 短代码（shortcode）是 Hugo 的特殊语法，格式为 {{\u0026lt; 名称 参数 \u0026gt;}}，由主题/站点模板渲染成 HTML。\n4.1 figure 图片（最常用） \u0026lt;!-- 最简 --\u0026gt; {{\u0026lt; figure src=\u0026#34;/images/example.png\u0026#34; \u0026gt;}} \u0026lt;!-- 完整参数 --\u0026gt; {{\u0026lt; figure src=\u0026#34;/images/example.png\u0026#34; title=\u0026#34;图片标题\u0026#34; caption=\u0026#34;图片说明文字，支持 **Markdown**\u0026#34; alt=\u0026#34;无障碍描述\u0026#34; width=\u0026#34;600\u0026#34; height=\u0026#34;400\u0026#34; align=\u0026#34;center\u0026#34; class=\u0026#34;custom-class\u0026#34; link=\u0026#34;https://example.com\u0026#34; target=\u0026#34;_blank\u0026#34; rel=\u0026#34;noopener\u0026#34; \u0026gt;}} 参数 说明 src 图片路径（必需），如 /images/x.png title 图片上方的标题 caption 图片下方的说明（支持 Markdown） alt 无障碍描述（留空则用 caption） width / height 尺寸（像素） align 设为 center 可居中显示 link 点击图片跳转的链接 target / rel 链接的打开方式与安全属性 class 自定义 CSS 类 4.2 inTextImg 行内小图 适合在文字中插入小图标（如徽章、状态标识）：\n本站使用 {{\u0026lt; inTextImg url=\u0026#34;/images/logo.svg\u0026#34; alt=\u0026#34;logo\u0026#34; height=\u0026#34;20\u0026#34; \u0026gt;}} 作为站点图标。 参数 说明 url 图片路径（必需） alt 替代文字 height 高度（默认 15px） 4.3 collapse 折叠 {{\u0026lt; collapse summary=\u0026#34;点击展开 / 收起\u0026#34; \u0026gt;}} 这里是被折叠的内容，支持任意 Markdown。 - 列表 - **加粗** {{\u0026lt; /collapse \u0026gt;}} \u0026lt;!-- 默认展开 --\u0026gt; {{\u0026lt; collapse summary=\u0026#34;默认展开的面板\u0026#34; openByDefault=true \u0026gt;}} 内容… {{\u0026lt; /collapse \u0026gt;}} 参数 说明 summary 折叠标题（必须用命名参数写法 summary=\u0026quot;标题\u0026quot;） openByDefault true = 默认展开 ⚠️ 必须写 summary=\u0026quot;标题\u0026quot;，写成位置参数 {{\u0026lt; collapse \u0026quot;标题\u0026quot; \u0026gt;}} 会报警告且标题为空。\n4.4 rawhtml 原始 HTML 包裹需要原样输出的 HTML（避免被 Markdown 处理）：\n{{\u0026lt; rawhtml \u0026gt;}} \u0026lt;div class=\u0026#34;my-widget\u0026#34;\u0026gt; \u0026lt;iframe src=\u0026#34;https://example.com/embed\u0026#34; width=\u0026#34;100%\u0026#34; height=\u0026#34;400\u0026#34;\u0026gt;\u0026lt;/iframe\u0026gt; \u0026lt;/div\u0026gt; {{\u0026lt; /rawhtml \u0026gt;}} 本站已开启 unsafe: true，简单 HTML 可直接写；遇到被 Markdown 干扰的复杂结构时用这个包裹。\n4.5 audio / video 本地媒体 {{\u0026lt; audio src=\u0026#34;/media/demo.mp3\u0026#34; \u0026gt;}} {{\u0026lt; video src=\u0026#34;/media/demo.mp4\u0026#34; \u0026gt;}} 文件放在 static/media/ 下。音频/视频默认静音（muted），点击播放器可取消静音。\n4.6 ltr / rtl 文字方向 {{\u0026lt; ltr \u0026gt;}} 这段文字强制从左到右显示 {{\u0026lt; /ltr \u0026gt;}} {{\u0026lt; rtl \u0026gt;}} 这段文字强制从右到左显示（阿拉伯语等） {{\u0026lt; /rtl \u0026gt;}} \u0026lt;!-- 内容需要渲染 Markdown 时加 md=true --\u0026gt; {{\u0026lt; ltr md=true \u0026gt;}} **加粗**会被渲染 {{\u0026lt; /ltr \u0026gt;}} 五、Hugo 内置短代码 这些是 Hugo 自带的能力（无需主题支持）。\n5.1 youtube / vimeo 视频嵌入 {{\u0026lt; youtube i8Iiv9yFTdM \u0026gt;}} \u0026lt;!-- YouTube 视频 ID --\u0026gt; {{\u0026lt; youtube id=\u0026#34;i8Iiv9yFTdM\u0026#34; title=\u0026#34;视频标题\u0026#34; autoplay=\u0026#34;false\u0026#34; \u0026gt;}} {{\u0026lt; vimeo 123456789 \u0026gt;}} \u0026lt;!-- Vimeo 视频 ID --\u0026gt; 视频 ID 是 URL 里的那串字符：https://www.youtube.com/watch?v=i8Iiv9yFTdM → i8Iiv9yFTdM\n5.2 gist 代码片段 {{\u0026lt; gist 用户名 哈希值 \u0026gt;}} {{\u0026lt; gist 用户名 哈希值 文件名 \u0026gt;}} 5.3 details 折叠（Hugo 原生） {{\u0026lt; details \u0026#34;点击展开\u0026#34; \u0026gt;}} 内容，支持 Markdown。 {{\u0026lt; /details \u0026gt;}} {{\u0026lt; details summary=\u0026#34;也可以这样写\u0026#34; open=true \u0026gt;}} 内容… {{\u0026lt; /details \u0026gt;}} 与 PaperMod 的 collapse 功能相同，选一个用即可（collapse 样式与主题更统一）。\n5.4 highlight 代码高亮（精细控制） {{\u0026lt; highlight python \u0026#34;linenos=table,hl_lines=2-3,linenostart=1\u0026#34; \u0026gt;}} def hello(): print(\u0026#34;这行会高亮\u0026#34;) print(\u0026#34;这行也会高亮\u0026#34;) {{\u0026lt; /highlight \u0026gt;}} 参数 说明 linenos=table 显示行号 hl_lines=2-3 高亮第 2~3 行 linenostart=1 行号起始值 日常写作直接用普通代码块即可（自动高亮），需要高亮特定行时才用这个。\n5.5 ref / relref 站内链接 [看这篇文章]({{\u0026lt; ref \u0026#34;posts/syntax-demo.md\u0026#34; \u0026gt;}}) [同上，相对链接]({{\u0026lt; relref \u0026#34;posts/syntax-demo.md\u0026#34; \u0026gt;}}) 好处：文章改名/移动后链接自动更新，不会 404。强烈推荐站内跳转用这个。\n5.6 param 读取配置 本站作者是 {{\u0026lt; param author \u0026gt;}}，标题是 {{\u0026lt; param title \u0026gt;}}。 读取 hugo.yaml 里 params 下的字段值。\n5.7 qr 二维码 {{\u0026lt; qr text=\u0026#34;https://example.com\u0026#34; \u0026gt;}} {{\u0026lt; qr text=\u0026#34;https://example.com\u0026#34; level=\u0026#34;h\u0026#34; scale=\u0026#34;4\u0026#34; \u0026gt;}} 5.8 短代码转义（显示而非执行） 想在文章里展示短代码语法本身（而不是执行它），用 /* */ 包裹：\n{{\u0026lt; figure src=\u0026#34;/images/x.png\u0026#34; \u0026gt;}} → 页面显示 {{\u0026lt; figure src=\u0026#34;/images/x.png\u0026#34; \u0026gt;}} {{\u0026lt; youtube abc123 \u0026gt;}} → 页面显示 {{\u0026lt; youtube abc123 \u0026gt;}} 六、本站增强语法 以下语法由本站在 assets/css/extended/custom.css 与 layouts/ 中额外配置，AnZhiYu 的对应标签都可用它们替代。\n6.1 提示框（替代 {% note %}） 用 note 短代码（内容会经过 Markdown 渲染）：\n{{\u0026lt; note info \u0026gt;}}蓝色信息提示{{\u0026lt; /note \u0026gt;}} {{\u0026lt; note success \u0026gt;}}绿色成功提示{{\u0026lt; /note \u0026gt;}} {{\u0026lt; note warning \u0026gt;}}黄色警告提示{{\u0026lt; /note \u0026gt;}} {{\u0026lt; note danger \u0026gt;}}红色危险提示{{\u0026lt; /note \u0026gt;}} {{\u0026lt; note primary \u0026gt;}}紫色重点提示{{\u0026lt; /note \u0026gt;}} 带标题（第二个参数）： {{\u0026lt; note warning \u0026#34;注意\u0026#34; \u0026gt;}} 带自定义标题的提示框 {{\u0026lt; /note \u0026gt;}} 内容支持全部 Markdown： {{\u0026lt; note info \u0026gt;}} **加粗**、`行内代码`、[链接](https://example.com)、列表都可以。 {{\u0026lt; /note \u0026gt;}} ⚠️ 不要用 \u0026lt;div class=\u0026quot;note info\u0026quot;\u0026gt;…\u0026lt;/div\u0026gt; 的 HTML 写法：块级 HTML 内部的 Markdown 不会被解析（CommonMark 规范行为），**加粗** 会原样显示成星号。 如确要用 HTML 写法，标签与内容之间必须留空行。\n6.2 行内高亮（替代 {% label %}） \u0026lt;mark class=\u0026#34;hl red\u0026#34;\u0026gt;红色重点\u0026lt;/mark\u0026gt; \u0026lt;mark class=\u0026#34;hl green\u0026#34;\u0026gt;绿色\u0026lt;/mark\u0026gt; \u0026lt;mark class=\u0026#34;hl blue\u0026#34;\u0026gt;蓝色\u0026lt;/mark\u0026gt; \u0026lt;mark class=\u0026#34;hl yellow\u0026#34;\u0026gt;黄色\u0026lt;/mark\u0026gt; \u0026lt;mark class=\u0026#34;hl purple\u0026#34;\u0026gt;紫色\u0026lt;/mark\u0026gt; \u0026lt;mark class=\u0026#34;hl\u0026#34;\u0026gt;默认色\u0026lt;/mark\u0026gt; 实际效果：红色重点、绿色、蓝色、黄色、紫色\n6.3 两栏对比（替代 {% tabs %}） \u0026lt;div class=\u0026#34;columns\u0026#34;\u0026gt; \u0026lt;div\u0026gt; \u0026lt;h4\u0026gt;方案 A\u0026lt;/h4\u0026gt; \u0026lt;p\u0026gt;内容…\u0026lt;/p\u0026gt; \u0026lt;/div\u0026gt; \u0026lt;div\u0026gt; \u0026lt;h4\u0026gt;方案 B\u0026lt;/h4\u0026gt; \u0026lt;p\u0026gt;内容…\u0026lt;/p\u0026gt; \u0026lt;/div\u0026gt; \u0026lt;/div\u0026gt; 宽屏并排两栏，窄屏自动堆叠 三栏及以上也可以（自动换行） 这是静态对比（不像 tabs 可点击切换） 6.4 数学公式（KaTeX） \u0026lt;!-- 行内公式 --\u0026gt; 质能方程 $E = mc^2$ 是狭义相对论的核心。 \u0026lt;!-- 单行独立公式（推荐日常使用）--\u0026gt; $$\\int_{-\\infty}^{+\\infty} e^{-x^2} \\, dx = \\sqrt{\\pi}$$ \u0026lt;!-- 多行 / 复杂公式：必须用 math 短代码包裹 --\u0026gt; {{\u0026lt; math \u0026gt;}} \\begin{pmatrix} a \u0026amp; b \\\\ c \u0026amp; d \\end{pmatrix} \\begin{pmatrix} x \\\\ y \\end{pmatrix} = \\begin{pmatrix} ax + by \\\\ cx + dy \\end{pmatrix} {{\u0026lt; /math \u0026gt;}} \u0026lt;!-- 行内公式的短代码写法（需要显式指定 inline）--\u0026gt; {{\u0026lt; math inline \u0026gt;}}a^2 + b^2 = c^2{{\u0026lt; /math \u0026gt;}} 支持的语法：分数 \\frac{a}{b}、上下标 x^2 a_1、根号 \\sqrt{x}、求和 \\sum_{i=1}^{n}、积分 \\int_a^b、希腊字母 \\alpha \\beta \\pi、矩阵 \\begin{pmatrix}、多行对齐 \\begin{aligned}、分段函数 \\begin{cases} 等（完整语法见 KaTeX 支持列表）\n⚠️ 多行公式必须用 {{\u0026lt; math \u0026gt;}} 包裹，直接写多行 $$ 会被 Markdown 解析器破坏。\n6.5 Mermaid 图表 直接写代码块即可（不需要记短代码）：\n流程图：\n```mermaid flowchart TD A[开始] --\u0026gt; B{条件判断} B --\u0026gt;|满足| C[执行操作] B --\u0026gt;|不满足| D[结束] C --\u0026gt; D ``` 时序图：\n```mermaid sequenceDiagram participant 用户 participant 服务器 用户-\u0026gt;\u0026gt;服务器: 发起请求 服务器--\u0026gt;\u0026gt;用户: 返回数据 ``` 类图：\n```mermaid classDiagram class Animal { +String name +eat() } class Dog { +bark() } Animal \u0026lt;|-- Dog ``` 状态图：\n```mermaid stateDiagram-v2 [*] --\u0026gt; 待处理 待处理 --\u0026gt; 处理中 处理中 --\u0026gt; 已完成 已完成 --\u0026gt; [*] ``` 甘特图：\n```mermaid gantt title 项目排期 dateFormat YYYY-MM-DD section 阶段一 需求分析 :a1, 2026-10-01, 7d 设计 :a2, after a1, 5d ``` 饼图：\n```mermaid pie title 时间分配 \u0026#34;写作\u0026#34; : 45 \u0026#34;阅读\u0026#34; : 30 \u0026#34;其他\u0026#34; : 25 ``` 图表配色会自动跟随明暗主题切换。\n6.6 组合使用示例 一段技术说明可以这样组合：\n\u0026lt;div class=\u0026#34;note warning\u0026#34; data-title=\u0026#34;前置条件\u0026#34;\u0026gt; 使用前请先安装 **Hugo extended** 版本。 \u0026lt;/div\u0026gt; 处理流程如下： ```mermaid flowchart LR A[输入] --\u0026gt; B[处理] --\u0026gt; C[输出] 核心算法：\nT(n) = 2T(n/2) + O(n) 展开查看完整代码 def merge_sort(arr): if len(arr) \u0026lt;= 1: return arr mid = len(arr) // 2 return merge(merge_sort(arr[:mid]), merge_sort(arr[mid:])) ``` 七、写作工具与工作流 7.1 编辑器推荐 工具 适合场景 说明 VS Code 主力写作 装 Hugo / Markdown All in One / Markdown Preview Enhanced 插件；可开终端跑 hugo server Typora 沉浸写作 所见即所得，但需注意：它渲染的 HTML 与实际站点有差异（短代码不支持预览） Obsidian 知识管理 适合先在库里写，再导出到 content/posts/；双链语法需改成 Hugo 的 ref 任何文本编辑器 应急 因为全是纯文本 Markdown 推荐组合：VS Code 写 + 浏览器开 http://localhost:1313 实时看效果（hugo server 会热重载）。\n7.2 图片处理 存放位置：static/images/，引用路径 /images/xxx.png 格式建议：优先 WebP（体积小）或 PNG（需要透明时） 封面裁剪：首页/列表封面建议统一比例，可用裁剪工具处理后再放入 static/images/cover/ 图片优化：Hugo 支持图片处理（缩放/裁剪/格式转换），需要时可研究 resources 目录 7.3 命令速查 hugo new content posts/文章名.md # 新建文章 hugo new content about.md # 新建页面 hugo server -D # 预览（含草稿） hugo server -D --bind 0.0.0.0 # 允许局域网访问（手机上看效果） hugo server --navigateToChanged # 编辑后自动跳转到改动页面 hugo --gc --minify # 构建（清理 + 压缩） hugo --gc --minify --buildFuture # 构建含未来日期的文章 hugo list all # 列出所有文章及 URL hugo list drafts # 列出草稿 hugo config # 查看生效的完整配置 hugo new theme 主题名 # 创建新主题（一般用不到） 7.4 发布流程 hugo --gc --minify 构建 把 public/ 目录部署到托管平台（GitHub Pages / Cloudflare Pages / Vercel / Netlify） 推荐配置 CI：推送到 Git 后自动构建部署（Cloudflare Pages 可直接连仓库，构建命令 hugo --gc --minify，输出目录 public） 注意：themes/PaperMod 是用 git clone 装的，如果主仓库也要版本管理，建议把它作为 git submodule 或直接删除 .git 目录后纳入主仓库。\n八、实战：完整文章示例 以下是一篇完整文章的骨架，涵盖了常用语法：\n--- title: \u0026#34;深入理解 XXX\u0026#34; date: 2026-10-07T10:00:00+08:00 lastmod: 2026-10-07T10:00:00+08:00 draft: false description: \u0026#34;本文从 A 出发，推导出 B，并给出实践建议。\u0026#34; tags: [\u0026#34;技术\u0026#34;, \u0026#34;算法\u0026#34;] categories: [\u0026#34;技术\u0026#34;] keywords: [\u0026#34;XXX\u0026#34;, \u0026#34;算法\u0026#34;] math: true ShowToc: true TocOpen: false cover: image: \u0026#34;/images/cover/xxx.jpg\u0026#34; alt: \u0026#34;封面\u0026#34; caption: \u0026#34;图片来源：xxx\u0026#34; --- ## 背景 XXX 是一个常见问题。研究表明，**关键因素有三个**： 1. 因素一 2. 因素二 3. 因素三 \u0026lt;div class=\u0026#34;note info\u0026#34; data-title=\u0026#34;前置知识\u0026#34;\u0026gt; 阅读本文需要了解 \u0026lt;mark class=\u0026#34;hl blue\u0026#34;\u0026gt;线性代数\u0026lt;/mark\u0026gt; 基础。 \u0026lt;/div\u0026gt; ## 核心推导 设输入为 $x$，则输出为： $$y = \\sum_{i=1}^{n} w_i x_i + b$$ 多行推导： {{\u0026lt; math \u0026gt;}} \\begin{aligned} L \u0026amp;= \\frac{1}{2}(y - \\hat{y})^2 \\\\ \\frac{\\partial L}{\\partial w_i} \u0026amp;= (y - \\hat{y}) x_i \\end{aligned} {{\u0026lt; /math \u0026gt;}} ## 流程图 ```mermaid flowchart TD A[输入数据] --\u0026gt; B{数据是否完整?} B --\u0026gt;|是| C[特征提取] B --\u0026gt;|否| D[数据清洗] D --\u0026gt; C C --\u0026gt; E[模型训练] E --\u0026gt; F[输出结果] 两种方案对比 方案 A：简单直观 实现快，适合数据量小的场景。缺点是扩展性差。\n方案 B：复杂但可扩展 前期投入大，但数据量增长后优势明显。\n参考实现 def solve(x, w, b): return sum(wi * xi for wi, xi in zip(w, x)) + b 展开查看完整代码（含边界处理） def solve(x, w, b): if not x or len(x) != len(w): raise ValueError(\u0026#34;维度不匹配\u0026#34;) return sum(wi * xi for wi, xi in zip(w, x)) + b 小结 核心结论：**XXX 的关键在于 YYY**。 参考：官方文档\n--- ## 九、常见坑与排查 | 现象 | 原因 | 解决 | |---|---|---| | 文章写了但不显示 | `date` 是未来时间（`buildFuture: false`） | 改成过去时间，或构建加 `--buildFuture` | | 文章写了但不显示 | `draft: true` | 预览用 `hugo server -D`，发布前改成 `false` | | 多行公式显示成乱码/标题 | 直接写了多行 `$$…$$` | 用 `{{\u0026lt; math \u0026gt;}}…{{\u0026lt; /math \u0026gt;}}` 包裹 | | 公式显示为原始 LaTeX | KaTeX 加载失败或语法错误 | 检查 front matter 的 `math: true`；检查公式语法（`throwOnError: false` 会显示原文） | | Mermaid 显示为代码块 | 代码块语言名写错 | 必须是 `mermaid`（全小写） | | `collapse` 没有标题 | 用了位置参数 | 改成 `collapse summary=\u0026#34;标题\u0026#34;` 的命名参数写法 | | 短代码被当成文字显示 | 尖括号缺失或参数格式错误 | 检查写法；需要展示语法本身时用转义写法（见「短代码转义」一节） | | 图片不显示 | 路径错误 | 图片放 `static/images/`，引用写 `/images/xxx.png`（**不要**带 `static`） | | 图片不显示 | 文件名大小写不符 | 部署到 Linux 服务器时大小写敏感 | | 分类链接 404 | 分类名与已有分类不一致 | 统一分类命名 | | 表格没渲染 | 分隔行缺少或格式错误 | 表格第二行必须是 `|---|---|` | | HTML 被显示为文字 | `unsafe` 被关闭 | 确认 `hugo.yaml` 里 `markup.goldmark.renderer.unsafe: true` | | 中文标题 URL 很长 | 默认用标题生成 | 在 front matter 加 `slug: \u0026#34;english-name\u0026#34;` | --- ## 十、速查表 ### 10.1 语法一览 | 需求 | 语法 | |---|---| | 加粗 / 斜体 / 删除线 | `**粗**` / `*斜*` / `~~删~~` | | 行内代码 | `` `code` `` | | 代码块 | ` ```python ` … ` ``` ` | | 链接 | `[文字](url)` | | 站内链接 | `[文字]({{\u0026lt; ref \u0026#34;posts/x.md\u0026#34; \u0026gt;}})` | | 图片 | `![说明](/images/x.png)` | | 图片（带图注） | `{{\u0026lt; figure src=\u0026#34;/images/x.png\u0026#34; caption=\u0026#34;说明\u0026#34; \u0026gt;}}` | | 表格 | `\\| a \\| b \\|` + `\\|---\\|---\\|` | | 任务列表 | `- [x] 完成` | | 引用 | `\u0026gt; 文字` | | 脚注 | `文字[^1]` + `[^1]: 内容` | | 分割线 | `---`（前后空行） | | 提示框 | `\u0026lt;div class=\u0026#34;note info\u0026#34;\u0026gt;…\u0026lt;/div\u0026gt;` | | 高亮 | `\u0026lt;mark class=\u0026#34;hl red\u0026#34;\u0026gt;…\u0026lt;/mark\u0026gt;` | | 两栏 | `\u0026lt;div class=\u0026#34;columns\u0026#34;\u0026gt;\u0026lt;div\u0026gt;…\u0026lt;/div\u0026gt;\u0026lt;div\u0026gt;…\u0026lt;/div\u0026gt;\u0026lt;/div\u0026gt;` | | 折叠 | `{{\u0026lt; collapse summary=\u0026#34;标题\u0026#34; \u0026gt;}}…{{\u0026lt; /collapse \u0026gt;}}` | | 行内公式 | `$公式$` | | 单行公式 | `$$公式$$` | | 多行公式 | `{{\u0026lt; math \u0026gt;}}…{{\u0026lt; /math \u0026gt;}}` | | 流程图 | ` ```mermaid ` + `flowchart TD` | | YouTube | `{{\u0026lt; youtube 视频ID \u0026gt;}}` | | 本地视频 | `{{\u0026lt; video src=\u0026#34;/media/x.mp4\u0026#34; \u0026gt;}}` | | 本地音频 | `{{\u0026lt; audio src=\u0026#34;/media/x.mp3\u0026#34; \u0026gt;}}` | | 原始 HTML | `{{\u0026lt; rawhtml \u0026gt;}}…{{\u0026lt; /rawhtml \u0026gt;}}` | | 行内小图 | `{{\u0026lt; inTextImg url=\u0026#34;/images/x.svg\u0026#34; \u0026gt;}}` | | 显示短代码语法 | `{{\u0026lt; 短代码 \u0026gt;}}` | | 自定义 URL | front matter 里 `slug: \u0026#34;xxx\u0026#34;` | ### 10.2 常用组合模板 **技术文章**：front matter（`math: true`、`ShowToc: true`）+ 提示框（前置条件）+ Mermaid（流程）+ 代码块 + 折叠（完整代码） **思辨文章**：front matter（`categories: [\u0026#34;随笔\u0026#34;]`）+ 引用块（金句）+ 提示框（核心论点）+ 两栏（对比）+ 高亮（关键词） **教程文章**：front matter + 有序列表（步骤）+ 代码块 + 提示框（注意事项）+ 折叠（补充说明） --- \u0026gt; **文档维护**：新增语法或修改样式后，请同步更新本文档。 \u0026gt; **相关文件**：`hugo.yaml`（配置）、`assets/css/extended/custom.css`（样式）、`layouts/`（短代码与钩子） ","permalink":"https://blog.646474.xyz/posts/writing-guide/","summary":"\u003chr\u003e\n\u003ch2 id=\"目录\"\u003e目录\u003c/h2\u003e\n\u003cul\u003e\n\u003cli\u003e\u003ca href=\"/posts/writing-guide/#%e4%b8%80%e5%bf%ab%e9%80%9f%e5%bc%80%e5%a7%8b\"\u003e一、快速开始\u003c/a\u003e\u003c/li\u003e\n\u003cli\u003e\u003ca href=\"/posts/writing-guide/#%e4%ba%8cfront-matter-%e5%ae%8c%e5%85%a8%e6%8c%87%e5%8d%97\"\u003e二、Front Matter 完全指南\u003c/a\u003e\u003c/li\u003e\n\u003cli\u003e\u003ca href=\"/posts/writing-guide/#%e4%b8%89markdown-%e5%9f%ba%e7%a1%80%e8%af%ad%e6%b3%95\"\u003e三、Markdown 基础语法\u003c/a\u003e\u003c/li\u003e\n\u003cli\u003e\u003ca href=\"/posts/writing-guide/#%e5%9b%9bpapermod-%e4%b8%bb%e9%a2%98%e7%9f%ad%e4%bb%a3%e7%a0%81\"\u003e四、PaperMod 主题短代码\u003c/a\u003e\u003c/li\u003e\n\u003cli\u003e\u003ca href=\"/posts/writing-guide/#%e4%ba%94hugo-%e5%86%85%e7%bd%ae%e7%9f%ad%e4%bb%a3%e7%a0%81\"\u003e五、Hugo 内置短代码\u003c/a\u003e\u003c/li\u003e\n\u003cli\u003e\u003ca href=\"/posts/writing-guide/#%e5%85%ad%e6%9c%ac%e7%ab%99%e5%a2%9e%e5%bc%ba%e8%af%ad%e6%b3%95\"\u003e六、本站增强语法\u003c/a\u003e\u003c/li\u003e\n\u003cli\u003e\u003ca href=\"/posts/writing-guide/#%e4%b8%83%e5%86%99%e4%bd%9c%e5%b7%a5%e5%85%b7%e4%b8%8e%e5%b7%a5%e4%bd%9c%e6%b5%81\"\u003e七、写作工具与工作流\u003c/a\u003e\u003c/li\u003e\n\u003cli\u003e\u003ca href=\"/posts/writing-guide/#%e5%85%ab%e5%ae%9e%e6%88%98%e5%ae%8c%e6%95%b4%e6%96%87%e7%ab%a0%e7%a4%ba%e4%be%8b\"\u003e八、实战：完整文章示例\u003c/a\u003e\u003c/li\u003e\n\u003cli\u003e\u003ca href=\"/posts/writing-guide/#%e4%b9%9d%e5%b8%b8%e8%a7%81%e5%9d%91%e4%b8%8e%e6%8e%92%e6%9f%a5\"\u003e九、常见坑与排查\u003c/a\u003e\u003c/li\u003e\n\u003cli\u003e\u003ca href=\"/posts/writing-guide/#%e5%8d%81%e9%80%9f%e6%9f%a5%e8%a1%a8\"\u003e十、速查表\u003c/a\u003e\u003c/li\u003e\n\u003c/ul\u003e\n\u003chr\u003e\n\u003ch2 id=\"一快速开始\"\u003e一、快速开始\u003c/h2\u003e\n\u003ch3 id=\"11-三个命令\"\u003e1.1 三个命令\u003c/h3\u003e\n\u003cdiv class=\"highlight\"\u003e\u003cpre tabindex=\"0\" class=\"chroma\"\u003e\u003ccode class=\"language-bash\" data-lang=\"bash\"\u003e\u003cspan class=\"line\"\u003e\u003cspan class=\"cl\"\u003ehugo new content posts/我的新文章.md    \u003cspan class=\"c1\"\u003e# 新建文章（自动套用 archetypes/default.md 模板）\u003c/span\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan class=\"line\"\u003e\u003cspan class=\"cl\"\u003ehugo server -D                          \u003cspan class=\"c1\"\u003e# 本地预览（-D 表示包含草稿），打开 http://localhost:1313\u003c/span\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan class=\"line\"\u003e\u003cspan class=\"cl\"\u003ehugo --gc --minify                      \u003cspan class=\"c1\"\u003e# 构建发布（产物在 public/ 目录）\u003c/span\u003e\n\u003c/span\u003e\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\u003c/div\u003e\u003ch3 id=\"12-一篇文章的最小结构\"\u003e1.2 一篇文章的最小结构\u003c/h3\u003e\n\u003cdiv class=\"highlight\"\u003e\u003cpre tabindex=\"0\" class=\"chroma\"\u003e\u003ccode class=\"language-markdown\" data-lang=\"markdown\"\u003e\u003cspan class=\"line\"\u003e\u003cspan class=\"cl\"\u003e\u003cspan class=\"nn\"\u003e---\u003c/span\u003e\u003cspan class=\"w\"\u003e\n\u003c/span\u003e\u003c/span\u003e\u003c/span\u003e\u003cspan class=\"line\"\u003e\u003cspan class=\"cl\"\u003e\u003cspan class=\"nt\"\u003etitle\u003c/span\u003e\u003cspan class=\"p\"\u003e:\u003c/span\u003e\u003cspan class=\"w\"\u003e \u003c/span\u003e\u003cspan class=\"s2\"\u003e\u0026#34;文章标题\u0026#34;\u003c/span\u003e\u003cspan class=\"w\"\u003e\n\u003c/span\u003e\u003c/span\u003e\u003c/span\u003e\u003cspan class=\"line\"\u003e\u003cspan class=\"cl\"\u003e\u003cspan class=\"nt\"\u003edate\u003c/span\u003e\u003cspan class=\"p\"\u003e:\u003c/span\u003e\u003cspan class=\"w\"\u003e \u003c/span\u003e\u003cspan class=\"ld\"\u003e2026-10-07T10:00:00\u003c/span\u003e\u003cspan class=\"m\"\u003e+08\u003c/span\u003e\u003cspan class=\"p\"\u003e:\u003c/span\u003e\u003cspan class=\"m\"\u003e00\u003c/span\u003e\u003cspan class=\"w\"\u003e\n\u003c/span\u003e\u003c/span\u003e\u003c/span\u003e\u003cspan class=\"line\"\u003e\u003cspan class=\"cl\"\u003e\u003cspan class=\"nt\"\u003edraft\u003c/span\u003e\u003cspan class=\"p\"\u003e:\u003c/span\u003e\u003cspan class=\"w\"\u003e \u003c/span\u003e\u003cspan class=\"kc\"\u003efalse\u003c/span\u003e\u003cspan class=\"w\"\u003e\n\u003c/span\u003e\u003c/span\u003e\u003c/span\u003e\u003cspan class=\"line\"\u003e\u003cspan class=\"cl\"\u003e\u003cspan class=\"nt\"\u003etags\u003c/span\u003e\u003cspan class=\"p\"\u003e:\u003c/span\u003e\u003cspan class=\"w\"\u003e \u003c/span\u003e\u003cspan class=\"p\"\u003e[\u003c/span\u003e\u003cspan class=\"s2\"\u003e\u0026#34;标签1\u0026#34;\u003c/span\u003e\u003cspan class=\"p\"\u003e,\u003c/span\u003e\u003cspan class=\"w\"\u003e \u003c/span\u003e\u003cspan class=\"s2\"\u003e\u0026#34;标签2\u0026#34;\u003c/span\u003e\u003cspan class=\"p\"\u003e]\u003c/span\u003e\u003cspan class=\"w\"\u003e\n\u003c/span\u003e\u003c/span\u003e\u003c/span\u003e\u003cspan class=\"line\"\u003e\u003cspan class=\"cl\"\u003e\u003cspan class=\"nt\"\u003ecategories\u003c/span\u003e\u003cspan class=\"p\"\u003e:\u003c/span\u003e\u003cspan class=\"w\"\u003e \u003c/span\u003e\u003cspan class=\"p\"\u003e[\u003c/span\u003e\u003cspan class=\"s2\"\u003e\u0026#34;分类\u0026#34;\u003c/span\u003e\u003cspan class=\"p\"\u003e]\u003c/span\u003e\u003cspan class=\"w\"\u003e\n\u003c/span\u003e\u003c/span\u003e\u003c/span\u003e\u003cspan class=\"line\"\u003e\u003cspan class=\"cl\"\u003e\u003cspan class=\"nn\"\u003e---\u003c/span\u003e\u003cspan class=\"w\"\u003e\n\u003c/span\u003e\u003c/span\u003e\u003c/span\u003e\u003cspan class=\"line\"\u003e\u003cspan class=\"cl\"\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan class=\"line\"\u003e\u003cspan class=\"cl\"\u003e正文从这里开始。\n\u003c/span\u003e\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\u003c/div\u003e\u003ch3 id=\"13-写作流程建议\"\u003e1.3 写作流程建议\u003c/h3\u003e\n\u003col\u003e\n\u003cli\u003e\u003ccode\u003ehugo new content posts/xxx.md\u003c/code\u003e 新建（默认 \u003ccode\u003edraft: true\u003c/code\u003e）\u003c/li\u003e\n\u003cli\u003e写内容，浏览器开着 \u003ccode\u003ehugo server -D\u003c/code\u003e 实时预览\u003c/li\u003e\n\u003cli\u003e写完把 \u003ccode\u003edraft\u003c/code\u003e 改为 \u003ccode\u003efalse\u003c/code\u003e\u003c/li\u003e\n\u003cli\u003e\u003ccode\u003ehugo --gc --minify\u003c/code\u003e 构建，把 \u003ccode\u003epublic/\u003c/code\u003e 部署到托管平台\u003c/li\u003e\n\u003c/ol\u003e\n\u003chr\u003e\n\u003ch2 id=\"二front-matter-完全指南\"\u003e二、Front Matter 完全指南\u003c/h2\u003e\n\u003cp\u003eFront matter 是文章头部的 YAML 配置块（\u003ccode\u003e---\u003c/code\u003e 包裹）。\u003cstrong\u003e所有字段都是可选的\u003c/strong\u003e，不写的字段会使用 \u003ccode\u003ehugo.yaml\u003c/code\u003e 里的全局默认值。\u003c/p\u003e","title":"Hugo + PaperMod 写作语法大全"},{"content":"本站同一份源码部署在多个平台（GitHub Pages / Vercel / Netlify / Cloudflare Pages …）， 但主域名只有一个。本文档说明配置方式。\n一、本站采用的方案：主域名统一 hugo.yaml 里 baseURL 填的是主域名：\nbaseURL: \u0026#34;https://blog.646474.xyz/\u0026#34; 所有平台都用这一个值，构建命令不需要任何额外参数。这样做的效果：\n内容 实际行为 CSS / JS 资源 用相对路径（/assets/...）→ 每个平台都能正常加载 文章图片 根相对路径（/images/...）→ 同上 canonical 统一指向 https://blog.646474.xyz/... sitemap.xml / rss.xml 统一指向主域名 分享卡片（OG / Twitter） 统一指向主域名 SEO 效果 权重集中在主域名，不存在重复内容问题 其他平台的角色 镜像 / 备用入口（访问正常，但不与主站争夺收录） 这是最省心的多平台方案：配一次，处处可用。\n二、各平台配置表 平台 构建命令 输出目录 需要的环境变量 GitHub Pages hugo --gc --minify public 无（本仓库 Actions 已配好，只需 DEPLOY_TOKEN Secret） Vercel hugo --gc --minify public HUGO_VERSION = 0.167.0 Netlify hugo --gc --minify public HUGO_VERSION = 0.167.0 Cloudflare Pages hugo --gc --minify public HUGO_VERSION = 0.167.0 其他平台 hugo --gc --minify public 视平台而定 关键：HUGO_VERSION 必须填 0.167.0，且必须是 extended 版本（PaperMod 用 SCSS，标准版会构建失败）。Cloudflare Pages 默认装的即是 extended；Vercel / Netlify 需要确认。\n三、各平台详细步骤 3.1 GitHub Pages（本仓库已配置） .github/workflows/deploy.yml：推送 main → 构建 → 推送到 666mingqing6.github.io 仓库。\n只需配置一个 Secret：\n名称 值 DEPLOY_TOKEN 对 666mingqing6.github.io 有写权限的 GitHub Token（经典 Token 勾 repo） 3.2 Vercel 导入 blog-hugo 仓库 Framework Preset 选 Hugo Build Command：hugo --gc --minify Output Directory：public Environment Variables 加 HUGO_VERSION = 0.167.0 3.3 Netlify 导入仓库 Build command：hugo --gc --minify Publish directory：public Environment 加 HUGO_VERSION = 0.167.0 如构建报 SCSS 错误，在仓库根目录加 netlify.toml：\n[build] command = \u0026#34;hugo --gc --minify\u0026#34; publish = \u0026#34;public\u0026#34; [build.environment] HUGO_VERSION = \u0026#34;0.167.0\u0026#34; 3.4 Cloudflare Pages 连接 Git 仓库 Build command：hugo --gc --minify Build output directory：public Environment variables 加 HUGO_VERSION = 0.167.0 3.5 其他平台 / 自建服务器 hugo --gc --minify # 构建 # 把 public/ 作为静态站点根目录部署 四、备选方案：让各平台用自己的域名 如果你希望每个平台的域名都被独立收录（例如想分别推广），可以改为在构建时覆盖 baseURL：\n平台 构建命令 环境变量说明 Vercel hugo --gc --minify --baseURL \u0026quot;https://$VERCEL_URL/\u0026quot; VERCEL_URL 不含协议，需手动补 https:// Netlify hugo --gc --minify --baseURL \u0026quot;$URL/\u0026quot; URL 含协议 Cloudflare Pages hugo --gc --minify --baseURL \u0026quot;$CF_PAGES_URL/\u0026quot; CF_PAGES_URL 含协议 GitHub Pages hugo --gc --minify --baseURL \u0026quot;https://666mingqing6.github.io/\u0026quot; 无自动变量，写固定值 代价：同一内容出现在多个域名下，搜索引擎视为重复内容，权重会分散。\n若采用此方案又想避免重复内容，两种补救：\n只让主站被收录：其他平台的 static/robots.txt 写 User-agent: * Disallow: / canonical 统一指向主域名：需要自定义 layouts/_partials/post_canonical.html， 把 .Permalink 换成主域名拼路径。 五、常见问题 现象 原因 解决 页面能打开但样式全无 极少见（PaperMod 用相对路径，一般不会） 检查平台是否正确部署了 public/ 全部内容 分享卡片链接指向主域名 正常行为（主域名统一方案） 无需处理 搜索引擎只收录主域名 正常行为 无需处理；想改见第四节 某平台构建报 SCSS 错误 装的是标准版 Hugo 设 HUGO_VERSION=0.167.0 并确认平台提供 extended 构建成功但页面是旧的 平台 CDN 缓存 平台后台清缓存 想临时用其他域名本地预览 命令行覆盖即可 hugo server --baseURL http://localhost:1313/ 不确定产物里的地址对不对 构建后检查 grep -o '\u0026lt;link rel=canonical[^\u0026gt;]*\u0026gt;' public/posts/*/index.html | head 六、一句话总结 baseURL 固定填主域名 https://blog.646474.xyz/，所有平台共用； 资源走相对路径各平台都能显示，SEO 权重全部集中到主域名。 其他平台就是主站的镜像与备用入口。\n","permalink":"https://blog.646474.xyz/posts/multi-platform-deploy/","summary":"\u003cp\u003e本站同一份源码部署在多个平台（GitHub Pages / Vercel / Netlify / Cloudflare Pages …），\n但\u003cstrong\u003e主域名只有一个\u003c/strong\u003e。本文档说明配置方式。\u003c/p\u003e\n\u003chr\u003e\n\u003ch2 id=\"一本站采用的方案主域名统一\"\u003e一、本站采用的方案：主域名统一\u003c/h2\u003e\n\u003cp\u003e\u003ccode\u003ehugo.yaml\u003c/code\u003e 里 \u003ccode\u003ebaseURL\u003c/code\u003e 填的是主域名：\u003c/p\u003e\n\u003cdiv class=\"highlight\"\u003e\u003cpre tabindex=\"0\" class=\"chroma\"\u003e\u003ccode class=\"language-yaml\" data-lang=\"yaml\"\u003e\u003cspan class=\"line\"\u003e\u003cspan class=\"cl\"\u003e\u003cspan class=\"nt\"\u003ebaseURL\u003c/span\u003e\u003cspan class=\"p\"\u003e:\u003c/span\u003e\u003cspan class=\"w\"\u003e \u003c/span\u003e\u003cspan class=\"s2\"\u003e\u0026#34;https://blog.646474.xyz/\u0026#34;\u003c/span\u003e\u003cspan class=\"w\"\u003e\n\u003c/span\u003e\u003c/span\u003e\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\u003c/div\u003e\u003cp\u003e\u003cstrong\u003e所有平台都用这一个值\u003c/strong\u003e，构建命令不需要任何额外参数。这样做的效果：\u003c/p\u003e\n\u003ctable\u003e\n\t\u003cthead\u003e\n\t\t\t\u003ctr\u003e\n\t\t\t\t\t\u003cth\u003e内容\u003c/th\u003e\n\t\t\t\t\t\u003cth\u003e实际行为\u003c/th\u003e\n\t\t\t\u003c/tr\u003e\n\t\u003c/thead\u003e\n\t\u003ctbody\u003e\n\t\t\t\u003ctr\u003e\n\t\t\t\t\t\u003ctd\u003eCSS / JS 资源\u003c/td\u003e\n\t\t\t\t\t\u003ctd\u003e用相对路径（\u003ccode\u003e/assets/...\u003c/code\u003e）→ \u003cstrong\u003e每个平台都能正常加载\u003c/strong\u003e\u003c/td\u003e\n\t\t\t\u003c/tr\u003e\n\t\t\t\u003ctr\u003e\n\t\t\t\t\t\u003ctd\u003e文章图片\u003c/td\u003e\n\t\t\t\t\t\u003ctd\u003e根相对路径（\u003ccode\u003e/images/...\u003c/code\u003e）→ 同上\u003c/td\u003e\n\t\t\t\u003c/tr\u003e\n\t\t\t\u003ctr\u003e\n\t\t\t\t\t\u003ctd\u003e\u003ccode\u003ecanonical\u003c/code\u003e\u003c/td\u003e\n\t\t\t\t\t\u003ctd\u003e统一指向 \u003ccode\u003ehttps://blog.646474.xyz/...\u003c/code\u003e\u003c/td\u003e\n\t\t\t\u003c/tr\u003e\n\t\t\t\u003ctr\u003e\n\t\t\t\t\t\u003ctd\u003e\u003ccode\u003esitemap.xml\u003c/code\u003e / \u003ccode\u003erss.xml\u003c/code\u003e\u003c/td\u003e\n\t\t\t\t\t\u003ctd\u003e统一指向主域名\u003c/td\u003e\n\t\t\t\u003c/tr\u003e\n\t\t\t\u003ctr\u003e\n\t\t\t\t\t\u003ctd\u003e分享卡片（OG / Twitter）\u003c/td\u003e\n\t\t\t\t\t\u003ctd\u003e统一指向主域名\u003c/td\u003e\n\t\t\t\u003c/tr\u003e\n\t\t\t\u003ctr\u003e\n\t\t\t\t\t\u003ctd\u003e\u003cstrong\u003eSEO 效果\u003c/strong\u003e\u003c/td\u003e\n\t\t\t\t\t\u003ctd\u003e权重集中在主域名，\u003cstrong\u003e不存在重复内容问题\u003c/strong\u003e\u003c/td\u003e\n\t\t\t\u003c/tr\u003e\n\t\t\t\u003ctr\u003e\n\t\t\t\t\t\u003ctd\u003e\u003cstrong\u003e其他平台的角色\u003c/strong\u003e\u003c/td\u003e\n\t\t\t\t\t\u003ctd\u003e镜像 / 备用入口（访问正常，但不与主站争夺收录）\u003c/td\u003e\n\t\t\t\u003c/tr\u003e\n\t\u003c/tbody\u003e\n\u003c/table\u003e\n\u003cblockquote\u003e\n\u003cp\u003e这是最省心的多平台方案：\u003cstrong\u003e配一次，处处可用\u003c/strong\u003e。\u003c/p\u003e\n\u003c/blockquote\u003e\n\u003chr\u003e\n\u003ch2 id=\"二各平台配置表\"\u003e二、各平台配置表\u003c/h2\u003e\n\u003ctable\u003e\n\t\u003cthead\u003e\n\t\t\t\u003ctr\u003e\n\t\t\t\t\t\u003cth\u003e平台\u003c/th\u003e\n\t\t\t\t\t\u003cth\u003e构建命令\u003c/th\u003e\n\t\t\t\t\t\u003cth\u003e输出目录\u003c/th\u003e\n\t\t\t\t\t\u003cth\u003e需要的环境变量\u003c/th\u003e\n\t\t\t\u003c/tr\u003e\n\t\u003c/thead\u003e\n\t\u003ctbody\u003e\n\t\t\t\u003ctr\u003e\n\t\t\t\t\t\u003ctd\u003e\u003cstrong\u003eGitHub Pages\u003c/strong\u003e\u003c/td\u003e\n\t\t\t\t\t\u003ctd\u003e\u003ccode\u003ehugo --gc --minify\u003c/code\u003e\u003c/td\u003e\n\t\t\t\t\t\u003ctd\u003e\u003ccode\u003epublic\u003c/code\u003e\u003c/td\u003e\n\t\t\t\t\t\u003ctd\u003e无（本仓库 Actions 已配好，只需 \u003ccode\u003eDEPLOY_TOKEN\u003c/code\u003e Secret）\u003c/td\u003e\n\t\t\t\u003c/tr\u003e\n\t\t\t\u003ctr\u003e\n\t\t\t\t\t\u003ctd\u003e\u003cstrong\u003eVercel\u003c/strong\u003e\u003c/td\u003e\n\t\t\t\t\t\u003ctd\u003e\u003ccode\u003ehugo --gc --minify\u003c/code\u003e\u003c/td\u003e\n\t\t\t\t\t\u003ctd\u003e\u003ccode\u003epublic\u003c/code\u003e\u003c/td\u003e\n\t\t\t\t\t\u003ctd\u003e\u003ccode\u003eHUGO_VERSION = 0.167.0\u003c/code\u003e\u003c/td\u003e\n\t\t\t\u003c/tr\u003e\n\t\t\t\u003ctr\u003e\n\t\t\t\t\t\u003ctd\u003e\u003cstrong\u003eNetlify\u003c/strong\u003e\u003c/td\u003e\n\t\t\t\t\t\u003ctd\u003e\u003ccode\u003ehugo --gc --minify\u003c/code\u003e\u003c/td\u003e\n\t\t\t\t\t\u003ctd\u003e\u003ccode\u003epublic\u003c/code\u003e\u003c/td\u003e\n\t\t\t\t\t\u003ctd\u003e\u003ccode\u003eHUGO_VERSION = 0.167.0\u003c/code\u003e\u003c/td\u003e\n\t\t\t\u003c/tr\u003e\n\t\t\t\u003ctr\u003e\n\t\t\t\t\t\u003ctd\u003e\u003cstrong\u003eCloudflare Pages\u003c/strong\u003e\u003c/td\u003e\n\t\t\t\t\t\u003ctd\u003e\u003ccode\u003ehugo --gc --minify\u003c/code\u003e\u003c/td\u003e\n\t\t\t\t\t\u003ctd\u003e\u003ccode\u003epublic\u003c/code\u003e\u003c/td\u003e\n\t\t\t\t\t\u003ctd\u003e\u003ccode\u003eHUGO_VERSION = 0.167.0\u003c/code\u003e\u003c/td\u003e\n\t\t\t\u003c/tr\u003e\n\t\t\t\u003ctr\u003e\n\t\t\t\t\t\u003ctd\u003e其他平台\u003c/td\u003e\n\t\t\t\t\t\u003ctd\u003e\u003ccode\u003ehugo --gc --minify\u003c/code\u003e\u003c/td\u003e\n\t\t\t\t\t\u003ctd\u003e\u003ccode\u003epublic\u003c/code\u003e\u003c/td\u003e\n\t\t\t\t\t\u003ctd\u003e视平台而定\u003c/td\u003e\n\t\t\t\u003c/tr\u003e\n\t\u003c/tbody\u003e\n\u003c/table\u003e\n\u003cp\u003e\u003cstrong\u003e关键\u003c/strong\u003e：\u003ccode\u003eHUGO_VERSION\u003c/code\u003e 必须填 \u003ccode\u003e0.167.0\u003c/code\u003e，且必须是 \u003cstrong\u003eextended\u003c/strong\u003e 版本（PaperMod 用 SCSS，标准版会构建失败）。Cloudflare Pages 默认装的即是 extended；Vercel / Netlify 需要确认。\u003c/p\u003e","title":"Hugo 博客多平台部署与 baseURL 配置"},{"content":" 一、先说结论：工作量评估 项目 说明 文章正文 需要替换标签语法（见第二、三节），每篇约 5~15 分钟 front matter 需要调整字段（见第五节），可脚本批量处理 图片 从 source/img/ 移到 static/images/，路径前缀从 /img/ 改为 /images/ 特有功能 即刻短文、音乐播放器、首页轮播、AI 摘要、置顶卡片 PaperMod 都没有，需要自行实现或放弃 评论系统 需要重新接入（PaperMod 预留了 layouts/_partials/comments.html） 建议：先迁移 3~5 篇代表性文章，跑通流程后再批量处理。\n二、新博客不能用的语法（AnZhiYu / Hexo 专有） 以下标签在 Hugo + PaperMod 中不存在，写上去会原样显示成文本（或报错），必须替换：\n2.1 Hexo tag 插件（AnZhiYu 全部标签） AnZhiYu 标签 能否使用 替代方案 {% note info %} {% endnote %} ❌ {{\u0026lt; note info \u0026gt;}}…{{\u0026lt; /note \u0026gt;}}（短代码，内容支持 Markdown） {% label 文字 red %} ❌ \u0026lt;mark class=\u0026quot;hl red\u0026quot;\u0026gt;文字\u0026lt;/mark\u0026gt;（本项目已内置样式） {% mermaid %} {% endmermaid %} ❌ ```mermaid 代码块（本项目已配置好） {% katex %} / {% mathjax %} ❌ $$公式$$（单行）或 {{\u0026lt; math \u0026gt;}}…{{\u0026lt; /math \u0026gt;}}（多行） {% tabs %} / {% endtabs %} ❌ \u0026lt;div class=\u0026quot;columns\u0026quot;\u0026gt;…\u0026lt;/div\u0026gt;（静态两栏，本项目已内置）或删除 {% checkbox %} ❌ Markdown 任务列表 - [x] 已完成 {% timeline %} ❌ 有序列表，或自建样式 {% folding %} ❌ {{\u0026lt; collapse \u0026quot;标题\u0026quot; \u0026gt;}}内容{{\u0026lt; /collapse \u0026gt;}} {% links %} ❌ Markdown 列表 + 链接 {% btn %} / {% btns %} / {% cell %} ❌ Markdown 链接或 \u0026lt;a class=\u0026quot;...\u0026quot;\u0026gt; {% tip %} ❌ \u0026lt;div class=\u0026quot;note primary\u0026quot;\u0026gt;…\u0026lt;/div\u0026gt; {% span %} / {% u %} / {% emp %} / {% wavy %} / {% del %} / {% kbd %} / {% psw %} ❌ 原生 HTML：\u0026lt;u\u0026gt; \u0026lt;em\u0026gt; \u0026lt;del\u0026gt; \u0026lt;kbd\u0026gt; {% gallery %} ❌ 多张 {{\u0026lt; figure \u0026gt;}} 或用 Markdown 图片 {% hide %} ❌ {{\u0026lt; collapse \u0026gt;}} {% image %} / {% inlineImg %} ❌ {{\u0026lt; figure \u0026gt;}} / Markdown ![]() {% bilibili %} / {% media %} / {% dogeplayer %} ❌ {{\u0026lt; rawhtml \u0026gt;}}\u0026lt;iframe\u0026gt;…{{\u0026lt; /rawhtml \u0026gt;}} {% site %} / {% flink %} / {% iconfont %} / {% Introduction-card %} ❌ 手写 HTML 或用 rawhtml 2.2 其它 Hexo / AnZhiYu 专有写法 写法 说明 \u0026lt;div class=\u0026quot;video-container\u0026quot;\u0026gt;…\u0026lt;/div\u0026gt; + 配套 \u0026lt;style\u0026gt; AnZhiYu 的视频自适应写法 → 改用 {{\u0026lt; youtube ID \u0026gt;}} 或 {{\u0026lt; video src=\u0026quot;…\u0026quot; \u0026gt;}} \u0026lt;!-- more --\u0026gt; Hugo 用 ` （无空格），或在 front matter 写 summary:| |{% raw %}/{% endraw %}| Hugo 用{{\u0026lt; … \u0026gt;}}转义 shortcode | | Hexo 的_drafts/目录 | Hugo 用draft: true标记 | | 即刻短文（essay）系统 | ❌ 无对应，需自行实现（可考虑 Hugo 的独立 section） | | 音乐播放器 / APlayer | ❌ 需自行接入第三方 JS | | 首页轮播图 / 置顶卡片组 | ❌ 无对应，可用 PaperMod 的profileMode 或自建布局 | | AI 摘要（ai:字段） | ❌ 无对应，可改写到description` | | 站点统计（不蒜子等） | ❌ 需自行接入 |\n2.3 不能用的 front matter 字段 swiper_index、top_group_index、cover_fit、cover_day、cover_night、ai、abbrlink、background、aside、highlight_shrink、copyright / copyright_author / copyright_url / copyright_info、aplayer、mathjax、katex、toc_number、toc_style_simple、sticky、top_img\n这些字段写在 Hugo 里不会报错（被忽略），但也没有任何效果，建议清理。\n三、新博客支持的语法（怎么写） 3.1 基础 Markdown（完全通用） # 一级标题 ## 二级标题 **加粗**、*斜体*、~~删除线~~、`行内代码`、[链接](https://example.com) - 无序列表 - 第二项 - 嵌套 1. 有序列表 - [x] 已完成任务 - [ ] 未完成任务 | 表头 | 表头 | |---|---| | 单元格 | 单元格 | \u0026gt; 引用块 --- 3.2 PaperMod 自带 shortcode 语法 作用 {{\u0026lt; figure src=\u0026quot;/images/a.png\u0026quot; title=\u0026quot;标题\u0026quot; caption=\u0026quot;说明\u0026quot; align=\u0026quot;center\u0026quot; \u0026gt;}} 图片（带图注，比 Markdown 图片更精细） {{\u0026lt; inTextImg url=\u0026quot;/images/a.png\u0026quot; alt=\u0026quot;说明\u0026quot; \u0026gt;}} 行内小图标 {{\u0026lt; collapse \u0026quot;点击展开\u0026quot; \u0026gt;}}内容{{\u0026lt; /collapse \u0026gt;}} 折叠面板 {{\u0026lt; rawhtml \u0026gt;}}\u0026lt;div\u0026gt;任意 HTML\u0026lt;/div\u0026gt;{{\u0026lt; /rawhtml \u0026gt;}} 嵌入原始 HTML {{\u0026lt; video src=\u0026quot;/media/a.mp4\u0026quot; \u0026gt;}} 本地视频 {{\u0026lt; audio src=\u0026quot;/media/a.mp3\u0026quot; \u0026gt;}} 本地音频 {{\u0026lt; ltr \u0026gt;}} / {{\u0026lt; rtl \u0026gt;}} 强制文字方向 3.3 Hugo 内置 shortcode 语法 作用 {{\u0026lt; youtube VIDEO_ID \u0026gt;}} 嵌入 YouTube（替代 AnZhiYu 的 video-container） {{\u0026lt; vimeo VIDEO_ID \u0026gt;}} 嵌入 Vimeo {{\u0026lt; gist 用户名 哈希 \u0026gt;}} 嵌入 GitHub Gist {{\u0026lt; details \u0026quot;标题\u0026quot; \u0026gt;}}内容{{\u0026lt; /details \u0026gt;}} 折叠（Hugo 原生） {{\u0026lt; highlight python \u0026quot;linenos=table\u0026quot; \u0026gt;}}代码{{\u0026lt; /highlight \u0026gt;}} 带行号的代码块 {{\u0026lt; ref \u0026quot;posts/某篇文章.md\u0026quot; \u0026gt;}} 站内链接（自动处理路径） {{\u0026lt; param 参数名 \u0026gt;}} 读取配置参数 3.4 本项目已额外配置好的语法（实测可用） 提示框（对标 AnZhiYu 的 {% note %}，用短代码，内容支持 Markdown）：\n{{\u0026lt; note info \u0026gt;}} 信息提示，支持 **加粗**、`代码`、[链接](url) {{\u0026lt; /note \u0026gt;}} {{\u0026lt; note success \u0026gt;}}成功提示{{\u0026lt; /note \u0026gt;}} {{\u0026lt; note warning \u0026gt;}}警告提示{{\u0026lt; /note \u0026gt;}} {{\u0026lt; note danger \u0026gt;}}危险提示{{\u0026lt; /note \u0026gt;}} {{\u0026lt; note primary \u0026gt;}}重点提示{{\u0026lt; /note \u0026gt;}} {{\u0026lt; note info \u0026#34;自定义标题\u0026#34; \u0026gt;}} 带标题的提示框（第二个参数是标题） {{\u0026lt; /note \u0026gt;}} ⚠️ 不建议用 \u0026lt;div class=\u0026quot;note info\u0026quot;\u0026gt; 的 HTML 写法：块级 HTML 内部的 Markdown 不会被解析（CommonMark 规范行为），加粗会原样显示成星号。\n行内高亮（对标 {% label %}）：\n\u0026lt;mark class=\u0026#34;hl red\u0026#34;\u0026gt;红色重点\u0026lt;/mark\u0026gt; \u0026lt;mark class=\u0026#34;hl green\u0026#34;\u0026gt;绿色\u0026lt;/mark\u0026gt; \u0026lt;mark class=\u0026#34;hl blue\u0026#34;\u0026gt;蓝色\u0026lt;/mark\u0026gt; \u0026lt;mark class=\u0026#34;hl yellow\u0026#34;\u0026gt;黄色\u0026lt;/mark\u0026gt; \u0026lt;mark class=\u0026#34;hl purple\u0026#34;\u0026gt;紫色\u0026lt;/mark\u0026gt; 两栏对比（对标 {% tabs %} 的静态替代）：\n\u0026lt;div class=\u0026#34;columns\u0026#34;\u0026gt; \u0026lt;div\u0026gt; \u0026lt;h4\u0026gt;方案 A\u0026lt;/h4\u0026gt; \u0026lt;p\u0026gt;内容…\u0026lt;/p\u0026gt; \u0026lt;/div\u0026gt; \u0026lt;div\u0026gt; \u0026lt;h4\u0026gt;方案 B\u0026lt;/h4\u0026gt; \u0026lt;p\u0026gt;内容…\u0026lt;/p\u0026gt; \u0026lt;/div\u0026gt; \u0026lt;/div\u0026gt; 数学公式（KaTeX）：\n行内：$E = mc^2$ 单行独立公式（推荐日常使用）： $$E = mc^2$$ 多行 / 复杂公式（矩阵、多行推导必须用这个）： {{\u0026lt; math \u0026gt;}} \\begin{pmatrix} a \u0026amp; b \\\\ c \u0026amp; d \\end{pmatrix} {{\u0026lt; /math \u0026gt;}} ⚠️ 重要：多行公式不要直接写多行 $$——Markdown 解析器会把 \\end{pmatrix} 这类行误判成标题，导致公式破损。多行公式一律用 {{\u0026lt; math \u0026gt;}} 包裹。\nMermaid 流程图（直接用代码块，无需记短代码）：\n```mermaid flowchart TD A[开始] --\u0026gt; B{判断} B --\u0026gt;|是| C[结束] ``` 时序图、甘特图、类图等所有 Mermaid 图表类型都支持。\n3.5 开启数学公式的两种方式 文章 front matter 里任意一种写法都会自动加载 KaTeX：\nmath: true # 显式开启 或者正文里出现 $$ 也会自动检测开启。\n四、推荐的创作语法组合 日常写作最有价值的四件套：\n场景 推荐语法 强调重要结论 \u0026lt;div class=\u0026quot;note danger\u0026quot;\u0026gt;结论\u0026lt;/div\u0026gt; 补充说明、可选细节 {{\u0026lt; collapse \u0026quot;展开查看\u0026quot; \u0026gt;}}…{{\u0026lt; /collapse \u0026gt;}} 流程 / 结构 / 时序 ```mermaid 代码块 公式推导 $$单行$$ 或 {{\u0026lt; math \u0026gt;}}多行{{\u0026lt; /math \u0026gt;}} 图片带说明 {{\u0026lt; figure src=\u0026quot;…\u0026quot; caption=\u0026quot;…\u0026quot; \u0026gt;}} 代码 普通代码块（自带高亮 + 复制按钮） 对比两种方案 \u0026lt;div class=\u0026quot;columns\u0026quot;\u0026gt; 五、front matter 迁移对照表 Hexo (AnZhiYu) Hugo (PaperMod) 说明 title: \u0026quot;标题\u0026quot; title: \u0026quot;标题\u0026quot; 相同 date: 2026-04-24 19:40:46 date: 2026-04-24T19:40:46+08:00 Hugo 两种格式都能解析，但推荐 ISO 8601 updated: 2026-08-08 20:40:00 lastmod: 2026-08-08T20:40:00+08:00 字段名不同 tags: [a, b] tags: [\u0026quot;a\u0026quot;, \u0026quot;b\u0026quot;] 相同 categories: [[生活, 意识形态]] categories: [\u0026quot;生活\u0026quot;] Hugo 不支持多级分类，二级建议改成 tag cover: /img/webp/94.webp cover:\nimage: \u0026quot;/images/webp/94.webp\u0026quot; 结构不同（对象） description: \u0026quot;…\u0026quot; description: \u0026quot;…\u0026quot; 相同 keywords: [a, b] keywords: [\u0026quot;a\u0026quot;, \u0026quot;b\u0026quot;] 相同 abbrlink: xxx slug: xxx 自定义 URL top: true weight: 1（越小越前） 置顶需自行实现 toc: true ShowToc: true 字段名不同 toc_number: true UseHugoToc: true 近似 comments: false comments: false 相同 hide: true hideSummary: true 近似 mathjax: true / katex: true math: true 统一为 math swiper_index / top_group_index / ai / background / aside / cover_fit / cover_day / cover_night / copyright_* ❌ 无对应，删除即可 六、迁移操作步骤 1. 复制文章 # 在 Hexo 项目里（blog-demo/source/_posts/） cp 某篇文章.md Z:/ugoblog/content/posts/ 2. 调整 front matter updated → lastmod cover: /img/x.webp → cover.image: \u0026quot;/images/x.webp\u0026quot; 多级 categories 拆成一维 删除无对应字段 3. 替换正文标签 查找 替换为 {% note xxx %} … {% endnote %} {{\u0026lt; note xxx \u0026gt;}} … {{\u0026lt; /note \u0026gt;}} {% label 文字 颜色 %} \u0026lt;mark class=\u0026quot;hl 颜色\u0026quot;\u0026gt;文字\u0026lt;/mark\u0026gt; {% mermaid %} … {% endmermaid %} ```mermaid … ``` {% tabs %} … {% endtabs %} 删除或改 \u0026lt;div class=\u0026quot;columns\u0026quot;\u0026gt; {% folding 标题 %} … {% endfolding %} {{\u0026lt; collapse \u0026quot;标题\u0026quot; \u0026gt;}} … {{\u0026lt; /collapse \u0026gt;}} \u0026lt;div class=\u0026quot;video-container\u0026quot;\u0026gt; 整块 {{\u0026lt; youtube 视频ID \u0026gt;}} 4. 迁移图片 # Hexo: blog-demo/source/img/ → Hugo: Z:/ugoblog/static/images/ cp -r blog-demo/source/img/* Z:/ugoblog/static/images/ 正文里的 /img/xxx.webp 改成 /images/xxx.webp。\n5. 本地预览 cd Z:/ugoblog hugo server -D # 含草稿预览，浏览器打开 http://localhost:1313 6. 构建发布 hugo --gc --minify # 产物在 public/ 目录 七、常用命令速查 hugo new content posts/我的新文章.md # 新建文章（用 archetypes/default.md 模板） hugo server -D # 本地预览（含草稿） hugo server --bind 127.0.0.1 -p 1313 # 指定端口 hugo --gc --minify # 构建（清理缓存 + 压缩） hugo --gc --minify --buildFuture # 构建含未来日期的文章 hugo list all # 列出所有文章及 URL hugo config # 查看当前生效的完整配置 ⚠️ 注意：front matter 里 date 若是未来时间，默认不会构建（buildFuture: false）， 表现为「文章明明写了却不出现在页面上」。要么改成过去时间，要么加 --buildFuture。\n八、关键文件说明 文件 / 目录 作用 hugo.yaml 站点总配置（已汉化，所有配置项都有中文说明） archetypes/default.md 新建文章的模板（已汉化） content/posts/ 文章目录 content/search.md 搜索页（必须存在，否则搜索功能失效） content/archives.md 归档页 assets/css/extended/custom.css 自定义样式（提示框、高亮、两栏等） layouts/_partials/extend_head.html 注入 KaTeX / Mermaid（PaperMod 官方扩展点） layouts/_markup/render-codeblock-mermaid.html 让 ```mermaid 输出为图表容器 layouts/_markup/render-passthrough.html 数学公式原样输出（避免被转义） layouts/_shortcodes/math.html 多行公式 shortcode static/images/ 图片目录（引用路径为 /images/xxx） themes/PaperMod/ 主题本体（升级：cd themes/PaperMod \u0026amp;\u0026amp; git pull） 九、迁移后的功能对照 原 AnZhiYu 功能 PaperMod 状态 文章 + 标签 + 分类 ✅ 原生支持 归档页 ✅ 原生（content/archives.md） 站内搜索 ✅ 原生（Fuse.js，已配置） 暗色模式 ✅ 原生（跟随系统 + 手动切换） 目录 TOC ✅ 原生 代码高亮 + 复制 ✅ 原生 阅读时间 / 字数 ✅ 原生 分享按钮 ✅ 原生 数学公式 ✅ 已配置（KaTeX） Mermaid 流程图 ✅ 已配置 提示框 / 高亮 / 两栏 ✅ 已用自定义 CSS 补齐 评论 ⚠️ 需自行接入（Twikoo / Giscus / Waline） 即刻短文 ❌ 无对应 音乐播放器 ❌ 无对应 首页轮播 / 置顶卡片 ❌ 无对应 AI 摘要 ❌ 无对应 封面图 ✅ 支持（cover.image），但无「跟随主题色」等效果 ","permalink":"https://blog.646474.xyz/posts/hexo-to-hugo-migration/","summary":"\u003chr\u003e\n\u003ch2 id=\"一先说结论工作量评估\"\u003e一、先说结论：工作量评估\u003c/h2\u003e\n\u003ctable\u003e\n\t\u003cthead\u003e\n\t\t\t\u003ctr\u003e\n\t\t\t\t\t\u003cth\u003e项目\u003c/th\u003e\n\t\t\t\t\t\u003cth\u003e说明\u003c/th\u003e\n\t\t\t\u003c/tr\u003e\n\t\u003c/thead\u003e\n\t\u003ctbody\u003e\n\t\t\t\u003ctr\u003e\n\t\t\t\t\t\u003ctd\u003e\u003cstrong\u003e文章正文\u003c/strong\u003e\u003c/td\u003e\n\t\t\t\t\t\u003ctd\u003e需要替换标签语法（见第二、三节），每篇约 5~15 分钟\u003c/td\u003e\n\t\t\t\u003c/tr\u003e\n\t\t\t\u003ctr\u003e\n\t\t\t\t\t\u003ctd\u003e\u003cstrong\u003efront matter\u003c/strong\u003e\u003c/td\u003e\n\t\t\t\t\t\u003ctd\u003e需要调整字段（见第五节），可脚本批量处理\u003c/td\u003e\n\t\t\t\u003c/tr\u003e\n\t\t\t\u003ctr\u003e\n\t\t\t\t\t\u003ctd\u003e\u003cstrong\u003e图片\u003c/strong\u003e\u003c/td\u003e\n\t\t\t\t\t\u003ctd\u003e从 \u003ccode\u003esource/img/\u003c/code\u003e 移到 \u003ccode\u003estatic/images/\u003c/code\u003e，路径前缀从 \u003ccode\u003e/img/\u003c/code\u003e 改为 \u003ccode\u003e/images/\u003c/code\u003e\u003c/td\u003e\n\t\t\t\u003c/tr\u003e\n\t\t\t\u003ctr\u003e\n\t\t\t\t\t\u003ctd\u003e\u003cstrong\u003e特有功能\u003c/strong\u003e\u003c/td\u003e\n\t\t\t\t\t\u003ctd\u003e即刻短文、音乐播放器、首页轮播、AI 摘要、置顶卡片 \u003cstrong\u003ePaperMod 都没有\u003c/strong\u003e，需要自行实现或放弃\u003c/td\u003e\n\t\t\t\u003c/tr\u003e\n\t\t\t\u003ctr\u003e\n\t\t\t\t\t\u003ctd\u003e\u003cstrong\u003e评论系统\u003c/strong\u003e\u003c/td\u003e\n\t\t\t\t\t\u003ctd\u003e需要重新接入（PaperMod 预留了 \u003ccode\u003elayouts/_partials/comments.html\u003c/code\u003e）\u003c/td\u003e\n\t\t\t\u003c/tr\u003e\n\t\u003c/tbody\u003e\n\u003c/table\u003e\n\u003cp\u003e\u003cstrong\u003e建议\u003c/strong\u003e：先迁移 3~5 篇代表性文章，跑通流程后再批量处理。\u003c/p\u003e\n\u003chr\u003e\n\u003ch2 id=\"二新博客不能用的语法anzhiyu--hexo-专有\"\u003e二、新博客\u003cstrong\u003e不能用\u003c/strong\u003e的语法（AnZhiYu / Hexo 专有）\u003c/h2\u003e\n\u003cp\u003e以下标签在 Hugo + PaperMod 中\u003cstrong\u003e不存在\u003c/strong\u003e，写上去会原样显示成文本（或报错），必须替换：\u003c/p\u003e\n\u003ch3 id=\"21-hexo-tag-插件anzhiyu-全部标签\"\u003e2.1 Hexo tag 插件（AnZhiYu 全部标签）\u003c/h3\u003e\n\u003ctable\u003e\n\t\u003cthead\u003e\n\t\t\t\u003ctr\u003e\n\t\t\t\t\t\u003cth\u003eAnZhiYu 标签\u003c/th\u003e\n\t\t\t\t\t\u003cth\u003e能否使用\u003c/th\u003e\n\t\t\t\t\t\u003cth\u003e替代方案\u003c/th\u003e\n\t\t\t\u003c/tr\u003e\n\t\u003c/thead\u003e\n\t\u003ctbody\u003e\n\t\t\t\u003ctr\u003e\n\t\t\t\t\t\u003ctd\u003e\u003ccode\u003e{% note info %}\u003c/code\u003e \u003ccode\u003e{% endnote %}\u003c/code\u003e\u003c/td\u003e\n\t\t\t\t\t\u003ctd\u003e❌\u003c/td\u003e\n\t\t\t\t\t\u003ctd\u003e\u003ccode\u003e{{\u0026lt; note info \u0026gt;}}…{{\u0026lt; /note \u0026gt;}}\u003c/code\u003e（短代码，内容支持 Markdown）\u003c/td\u003e\n\t\t\t\u003c/tr\u003e\n\t\t\t\u003ctr\u003e\n\t\t\t\t\t\u003ctd\u003e\u003ccode\u003e{% label 文字 red %}\u003c/code\u003e\u003c/td\u003e\n\t\t\t\t\t\u003ctd\u003e❌\u003c/td\u003e\n\t\t\t\t\t\u003ctd\u003e\u003ccode\u003e\u0026lt;mark class=\u0026quot;hl red\u0026quot;\u0026gt;文字\u0026lt;/mark\u0026gt;\u003c/code\u003e（本项目已内置样式）\u003c/td\u003e\n\t\t\t\u003c/tr\u003e\n\t\t\t\u003ctr\u003e\n\t\t\t\t\t\u003ctd\u003e\u003ccode\u003e{% mermaid %}\u003c/code\u003e \u003ccode\u003e{% endmermaid %}\u003c/code\u003e\u003c/td\u003e\n\t\t\t\t\t\u003ctd\u003e❌\u003c/td\u003e\n\t\t\t\t\t\u003ctd\u003e\u003ccode\u003e```mermaid\u003c/code\u003e 代码块（本项目已配置好）\u003c/td\u003e\n\t\t\t\u003c/tr\u003e\n\t\t\t\u003ctr\u003e\n\t\t\t\t\t\u003ctd\u003e\u003ccode\u003e{% katex %}\u003c/code\u003e / \u003ccode\u003e{% mathjax %}\u003c/code\u003e\u003c/td\u003e\n\t\t\t\t\t\u003ctd\u003e❌\u003c/td\u003e\n\t\t\t\t\t\u003ctd\u003e\u003ccode\u003e$$公式$$\u003c/code\u003e（单行）或 \u003ccode\u003e{{\u0026lt; math \u0026gt;}}…{{\u0026lt; /math \u0026gt;}}\u003c/code\u003e（多行）\u003c/td\u003e\n\t\t\t\u003c/tr\u003e\n\t\t\t\u003ctr\u003e\n\t\t\t\t\t\u003ctd\u003e\u003ccode\u003e{% tabs %}\u003c/code\u003e / \u003ccode\u003e{% endtabs %}\u003c/code\u003e\u003c/td\u003e\n\t\t\t\t\t\u003ctd\u003e❌\u003c/td\u003e\n\t\t\t\t\t\u003ctd\u003e\u003ccode\u003e\u0026lt;div class=\u0026quot;columns\u0026quot;\u0026gt;…\u0026lt;/div\u0026gt;\u003c/code\u003e（静态两栏，本项目已内置）或删除\u003c/td\u003e\n\t\t\t\u003c/tr\u003e\n\t\t\t\u003ctr\u003e\n\t\t\t\t\t\u003ctd\u003e\u003ccode\u003e{% checkbox %}\u003c/code\u003e\u003c/td\u003e\n\t\t\t\t\t\u003ctd\u003e❌\u003c/td\u003e\n\t\t\t\t\t\u003ctd\u003eMarkdown 任务列表 \u003ccode\u003e- [x] 已完成\u003c/code\u003e\u003c/td\u003e\n\t\t\t\u003c/tr\u003e\n\t\t\t\u003ctr\u003e\n\t\t\t\t\t\u003ctd\u003e\u003ccode\u003e{% timeline %}\u003c/code\u003e\u003c/td\u003e\n\t\t\t\t\t\u003ctd\u003e❌\u003c/td\u003e\n\t\t\t\t\t\u003ctd\u003e有序列表，或自建样式\u003c/td\u003e\n\t\t\t\u003c/tr\u003e\n\t\t\t\u003ctr\u003e\n\t\t\t\t\t\u003ctd\u003e\u003ccode\u003e{% folding %}\u003c/code\u003e\u003c/td\u003e\n\t\t\t\t\t\u003ctd\u003e❌\u003c/td\u003e\n\t\t\t\t\t\u003ctd\u003e\u003ccode\u003e{{\u0026lt; collapse \u0026quot;标题\u0026quot; \u0026gt;}}内容{{\u0026lt; /collapse \u0026gt;}}\u003c/code\u003e\u003c/td\u003e\n\t\t\t\u003c/tr\u003e\n\t\t\t\u003ctr\u003e\n\t\t\t\t\t\u003ctd\u003e\u003ccode\u003e{% links %}\u003c/code\u003e\u003c/td\u003e\n\t\t\t\t\t\u003ctd\u003e❌\u003c/td\u003e\n\t\t\t\t\t\u003ctd\u003eMarkdown 列表 + 链接\u003c/td\u003e\n\t\t\t\u003c/tr\u003e\n\t\t\t\u003ctr\u003e\n\t\t\t\t\t\u003ctd\u003e\u003ccode\u003e{% btn %}\u003c/code\u003e / \u003ccode\u003e{% btns %}\u003c/code\u003e / \u003ccode\u003e{% cell %}\u003c/code\u003e\u003c/td\u003e\n\t\t\t\t\t\u003ctd\u003e❌\u003c/td\u003e\n\t\t\t\t\t\u003ctd\u003eMarkdown 链接或 \u003ccode\u003e\u0026lt;a class=\u0026quot;...\u0026quot;\u0026gt;\u003c/code\u003e\u003c/td\u003e\n\t\t\t\u003c/tr\u003e\n\t\t\t\u003ctr\u003e\n\t\t\t\t\t\u003ctd\u003e\u003ccode\u003e{% tip %}\u003c/code\u003e\u003c/td\u003e\n\t\t\t\t\t\u003ctd\u003e❌\u003c/td\u003e\n\t\t\t\t\t\u003ctd\u003e\u003ccode\u003e\u0026lt;div class=\u0026quot;note primary\u0026quot;\u0026gt;…\u0026lt;/div\u0026gt;\u003c/code\u003e\u003c/td\u003e\n\t\t\t\u003c/tr\u003e\n\t\t\t\u003ctr\u003e\n\t\t\t\t\t\u003ctd\u003e\u003ccode\u003e{% span %}\u003c/code\u003e / \u003ccode\u003e{% u %}\u003c/code\u003e / \u003ccode\u003e{% emp %}\u003c/code\u003e / \u003ccode\u003e{% wavy %}\u003c/code\u003e / \u003ccode\u003e{% del %}\u003c/code\u003e / \u003ccode\u003e{% kbd %}\u003c/code\u003e / \u003ccode\u003e{% psw %}\u003c/code\u003e\u003c/td\u003e\n\t\t\t\t\t\u003ctd\u003e❌\u003c/td\u003e\n\t\t\t\t\t\u003ctd\u003e原生 HTML：\u003ccode\u003e\u0026lt;u\u0026gt;\u003c/code\u003e \u003ccode\u003e\u0026lt;em\u0026gt;\u003c/code\u003e \u003ccode\u003e\u0026lt;del\u0026gt;\u003c/code\u003e \u003ccode\u003e\u0026lt;kbd\u0026gt;\u003c/code\u003e\u003c/td\u003e\n\t\t\t\u003c/tr\u003e\n\t\t\t\u003ctr\u003e\n\t\t\t\t\t\u003ctd\u003e\u003ccode\u003e{% gallery %}\u003c/code\u003e\u003c/td\u003e\n\t\t\t\t\t\u003ctd\u003e❌\u003c/td\u003e\n\t\t\t\t\t\u003ctd\u003e多张 \u003ccode\u003e{{\u0026lt; figure \u0026gt;}}\u003c/code\u003e 或用 Markdown 图片\u003c/td\u003e\n\t\t\t\u003c/tr\u003e\n\t\t\t\u003ctr\u003e\n\t\t\t\t\t\u003ctd\u003e\u003ccode\u003e{% hide %}\u003c/code\u003e\u003c/td\u003e\n\t\t\t\t\t\u003ctd\u003e❌\u003c/td\u003e\n\t\t\t\t\t\u003ctd\u003e\u003ccode\u003e{{\u0026lt; collapse \u0026gt;}}\u003c/code\u003e\u003c/td\u003e\n\t\t\t\u003c/tr\u003e\n\t\t\t\u003ctr\u003e\n\t\t\t\t\t\u003ctd\u003e\u003ccode\u003e{% image %}\u003c/code\u003e / \u003ccode\u003e{% inlineImg %}\u003c/code\u003e\u003c/td\u003e\n\t\t\t\t\t\u003ctd\u003e❌\u003c/td\u003e\n\t\t\t\t\t\u003ctd\u003e\u003ccode\u003e{{\u0026lt; figure \u0026gt;}}\u003c/code\u003e / Markdown \u003ccode\u003e![]()\u003c/code\u003e\u003c/td\u003e\n\t\t\t\u003c/tr\u003e\n\t\t\t\u003ctr\u003e\n\t\t\t\t\t\u003ctd\u003e\u003ccode\u003e{% bilibili %}\u003c/code\u003e / \u003ccode\u003e{% media %}\u003c/code\u003e / \u003ccode\u003e{% dogeplayer %}\u003c/code\u003e\u003c/td\u003e\n\t\t\t\t\t\u003ctd\u003e❌\u003c/td\u003e\n\t\t\t\t\t\u003ctd\u003e\u003ccode\u003e{{\u0026lt; rawhtml \u0026gt;}}\u0026lt;iframe\u0026gt;…{{\u0026lt; /rawhtml \u0026gt;}}\u003c/code\u003e\u003c/td\u003e\n\t\t\t\u003c/tr\u003e\n\t\t\t\u003ctr\u003e\n\t\t\t\t\t\u003ctd\u003e\u003ccode\u003e{% site %}\u003c/code\u003e / \u003ccode\u003e{% flink %}\u003c/code\u003e / \u003ccode\u003e{% iconfont %}\u003c/code\u003e / \u003ccode\u003e{% Introduction-card %}\u003c/code\u003e\u003c/td\u003e\n\t\t\t\t\t\u003ctd\u003e❌\u003c/td\u003e\n\t\t\t\t\t\u003ctd\u003e手写 HTML 或用 \u003ccode\u003erawhtml\u003c/code\u003e\u003c/td\u003e\n\t\t\t\u003c/tr\u003e\n\t\u003c/tbody\u003e\n\u003c/table\u003e\n\u003ch3 id=\"22-其它-hexo--anzhiyu-专有写法\"\u003e2.2 其它 Hexo / AnZhiYu 专有写法\u003c/h3\u003e\n\u003ctable\u003e\n\t\u003cthead\u003e\n\t\t\t\u003ctr\u003e\n\t\t\t\t\t\u003cth\u003e写法\u003c/th\u003e\n\t\t\t\t\t\u003cth\u003e说明\u003c/th\u003e\n\t\t\t\u003c/tr\u003e\n\t\u003c/thead\u003e\n\t\u003ctbody\u003e\n\t\t\t\u003ctr\u003e\n\t\t\t\t\t\u003ctd\u003e\u003ccode\u003e\u0026lt;div class=\u0026quot;video-container\u0026quot;\u0026gt;…\u0026lt;/div\u0026gt;\u003c/code\u003e + 配套 \u003ccode\u003e\u0026lt;style\u0026gt;\u003c/code\u003e\u003c/td\u003e\n\t\t\t\t\t\u003ctd\u003eAnZhiYu 的视频自适应写法 → 改用 \u003ccode\u003e{{\u0026lt; youtube ID \u0026gt;}}\u003c/code\u003e 或 \u003ccode\u003e{{\u0026lt; video src=\u0026quot;…\u0026quot; \u0026gt;}}\u003c/code\u003e\u003c/td\u003e\n\t\t\t\u003c/tr\u003e\n\t\t\t\u003ctr\u003e\n\t\t\t\t\t\u003ctd\u003e\u003ccode\u003e\u0026lt;!-- more --\u0026gt;\u003c/code\u003e\u003c/td\u003e\n\t\t\t\t\t\u003ctd\u003eHugo 用 `\u003c/td\u003e\n\t\t\t\u003c/tr\u003e\n\t\u003c/tbody\u003e\n\u003c/table\u003e","title":"从 Hexo(AnZhiYu) 迁移到 Hugo(PaperMod) 完整记录"},{"content":"本文档列出本站支持的全部写作语法，每条都给出「写法」与「实际效果」对照，方便直接照着抄。\n提示：右侧目录可快速跳转。\n一、快速开始 新建文章（自动套用模板）：\nhugo new content posts/我的新文章.md 本地预览（写完保存自动刷新）：\nhugo server -D 推送发布（等价于原来 Hexo 的 hexo push）：\n./push.sh # Git Bash push.bat # 或直接双击这个文件 二、Front Matter（文章头部配置） 写法：\n--- title: \u0026#34;文章标题\u0026#34; date: 2026-10-07T10:00:00+08:00 lastmod: 2026-10-07T10:00:00+08:00 draft: false description: \u0026#34;文章摘要，显示在列表页与搜索结果里\u0026#34; tags: [\u0026#34;标签一\u0026#34;, \u0026#34;标签二\u0026#34;] categories: [\u0026#34;随笔\u0026#34;] keywords: [\u0026#34;关键词\u0026#34;] math: true # 开启数学公式 ShowToc: true # 显示目录 cover: image: \u0026#34;/images/cover/x.jpg\u0026#34; alt: \u0026#34;封面描述\u0026#34; caption: \u0026#34;封面说明\u0026#34; --- 说明：所有字段都可选，不写就用 hugo.yaml 里的全局默认值。draft: true 的文章不会发布。\n三、文本与结构 3.1 标题 写法：\n## 二级标题 ### 三级标题 #### 四级标题 效果：见本页各级标题（目录只收录二至四级）。\n3.2 文本样式 写法：\n**加粗**、*斜体*、***粗斜体***、~~删除线~~、`行内代码` 效果：\n加粗、斜体、粗斜体、删除线、行内代码\n3.3 列表 写法：\n- 无序项 - 无序项 - 嵌套项（缩进 2 空格） 1. 有序项 2. 有序项 效果：\n无序项 无序项 嵌套项 有序项 有序项 3.4 任务列表 写法：\n- [x] 已完成的任务 - [ ] 未完成的任务 效果：\n已完成的任务 未完成的任务 3.5 引用 写法：\n\u0026gt; 引用文字，支持 **Markdown**。 \u0026gt; \u0026gt; 第二段。 效果：\n引用文字，支持 Markdown。\n第二段。\n3.6 表格 写法：\n| 左对齐 | 居中 | 右对齐 | |:---|:---:|---:| | 内容 | 内容 | 内容 | 效果：\n左对齐 居中 右对齐 内容 内容 内容 3.7 分割线 写法（前后各留一个空行）：\n--- 效果：\n3.8 脚注 写法：\n这句话有脚注[^1]。 [^1]: 脚注内容写在这里。 效果：\n这句话有脚注1。\n3.9 链接 写法：\n[外部链接](https://gohugo.io) [站内链接]({{\u0026lt; ref \u0026#34;posts/syntax-demo.md\u0026#34; \u0026gt;}}) 效果：外部链接 ｜ 站内链接\n站内跳转推荐用 ref，文章改名后链接自动更新。\n3.10 图片 写法：\n![图片说明](/images/example.png) 效果：PaperMod 会自动把 alt 显示为图片下方的图注。更精细的控制用 figure 短代码（见 5.1）。\n四、代码 4.1 行内代码 写法：`const a = 1` → 效果：const a = 1\n4.2 代码块 写法：\n```python def hello(name): return f\u0026#34;Hello, {name}\u0026#34; ``` 效果：\ndef hello(name): return f\u0026#34;Hello, {name}\u0026#34; 代码块自动语法高亮，右上角带复制按钮。\n4.3 高亮指定行 写法：\n{{\u0026lt; highlight python \u0026#34;linenos=table,hl_lines=2\u0026#34; \u0026gt;}} def hello(): print(\u0026#34;这行会高亮\u0026#34;) {{\u0026lt; /highlight \u0026gt;}} 效果：\n1 2 def hello(): print(\u0026#34;这行会高亮\u0026#34;) 五、短代码（Shortcodes） 5.1 figure 图片（带标题与图注） 写法：\n{{\u0026lt; figure src=\u0026#34;/images/example.png\u0026#34; title=\u0026#34;图片标题\u0026#34; caption=\u0026#34;图片说明，支持 **Markdown**\u0026#34; align=\u0026#34;center\u0026#34; \u0026gt;}} 参数：src（必需）、title、caption、alt、width、height、align=\u0026quot;center\u0026quot;、link、target、rel、class\n5.2 collapse 折叠 写法：\n{{\u0026lt; collapse summary=\u0026#34;点击展开\u0026#34; \u0026gt;}} 折叠里的内容，支持 **Markdown**。 {{\u0026lt; /collapse \u0026gt;}} 效果：\n点击展开 折叠里的内容，支持 Markdown。\n列表也行 代码块也行 ⚠️ 必须写 summary=\u0026quot;标题\u0026quot;，写成位置参数 {{\u0026lt; collapse \u0026quot;标题\u0026quot; \u0026gt;}} 会没有标题。\n5.3 note 提示框（本站增强） 写法：\n{{\u0026lt; note info \u0026gt;}} 这是**信息**提示框，内部支持 Markdown。 {{\u0026lt; /note \u0026gt;}} 五种类型：\ninfo —— 一般信息提示 success —— 成功 / 推荐做法 warning —— 注意事项 danger —— 危险 / 强烈警告 primary —— 重点强调 带标题（第二个参数）：\n{{\u0026lt; note warning \u0026#34;前置条件\u0026#34; \u0026gt;}} 内容… {{\u0026lt; /note \u0026gt;}} 效果：\n需要先安装 Hugo extended 版本。 为什么用短代码而不是 HTML？ 直接写 \u0026lt;div class=\u0026quot;note info\u0026quot;\u0026gt;…\u0026lt;/div\u0026gt; 时， 块级 HTML 内部的 Markdown 不会被解析（CommonMark 规范行为）， **加粗** 会原样显示成星号。短代码会先把内容渲染成 Markdown 再填入。\n5.4 rawhtml 原始 HTML 写法：\n{{\u0026lt; rawhtml \u0026gt;}} \u0026lt;div class=\u0026#34;my-widget\u0026#34;\u0026gt;任意 HTML\u0026lt;/div\u0026gt; {{\u0026lt; /rawhtml \u0026gt;}} 5.5 音频与视频 写法：\n{{\u0026lt; audio src=\u0026#34;/media/demo.mp3\u0026#34; \u0026gt;}} {{\u0026lt; video src=\u0026#34;/media/demo.mp4\u0026#34; \u0026gt;}} {{\u0026lt; youtube i8Iiv9yFTdM \u0026gt;}} 5.6 行内小图标 写法：\n{{\u0026lt; inTextImg url=\u0026#34;/images/logo.svg\u0026#34; alt=\u0026#34;logo\u0026#34; height=\u0026#34;20\u0026#34; \u0026gt;}} 5.7 details 折叠（Hugo 原生） 写法：\n{{\u0026lt; details \u0026#34;点击展开\u0026#34; \u0026gt;}} 内容，支持 **Markdown**。 {{\u0026lt; /details \u0026gt;}} 效果：\nDetails 内容，支持 Markdown。\n5.8 显示短代码语法本身 想在文章里展示短代码而不让它执行，用 /* */ 包裹：\n写法：\n{{\u0026lt; note info \u0026gt;}}内容{{\u0026lt; /note \u0026gt;}} 页面效果：会原样显示成 内容 （纯文本），而不是渲染成提示框。\n若只写单边（如 {{\u0026lt; note info \u0026gt;}} 而没有对应的闭合标记），Hugo 会报 shortcode \u0026quot;note\u0026quot; must be closed or self-closed 构建失败 —— 成对书写即可。\n六、增强语法 6.1 行内高亮 写法：\n\u0026lt;mark class=\u0026#34;hl red\u0026#34;\u0026gt;红色重点\u0026lt;/mark\u0026gt; \u0026lt;mark class=\u0026#34;hl green\u0026#34;\u0026gt;绿色\u0026lt;/mark\u0026gt; \u0026lt;mark class=\u0026#34;hl blue\u0026#34;\u0026gt;蓝色\u0026lt;/mark\u0026gt; \u0026lt;mark class=\u0026#34;hl yellow\u0026#34;\u0026gt;黄色\u0026lt;/mark\u0026gt; \u0026lt;mark class=\u0026#34;hl purple\u0026#34;\u0026gt;紫色\u0026lt;/mark\u0026gt; 效果：\n红色重点、绿色、蓝色、黄色、紫色\n6.2 两栏对比 写法：\n\u0026lt;div class=\u0026#34;columns\u0026#34;\u0026gt; \u0026lt;div\u0026gt; \u0026lt;h4\u0026gt;方案 A\u0026lt;/h4\u0026gt; \u0026lt;p\u0026gt;内容（这里用 HTML 标签，不用 Markdown）\u0026lt;/p\u0026gt; \u0026lt;/div\u0026gt; \u0026lt;div\u0026gt; \u0026lt;h4\u0026gt;方案 B\u0026lt;/h4\u0026gt; \u0026lt;p\u0026gt;内容\u0026lt;/p\u0026gt; \u0026lt;/div\u0026gt; \u0026lt;/div\u0026gt; 效果：\n方案 A 简单直观，实现快，适合小数据量场景。\n方案 B 前期投入大，但数据量增长后优势明显。\n注意：columns 内部用 HTML 标签（\u0026lt;p\u0026gt; \u0026lt;h4\u0026gt;），不要写 Markdown —— 原因同上（块级 HTML 内不解析 Markdown）。\n6.3 数学公式 行内公式 —— 写法：$E = mc^2$ → 效果：E = mc^2\n单行独立公式 —— 写法：\n$$\\int_{-\\infty}^{+\\infty} e^{-x^2} \\, dx = \\sqrt{\\pi}$$ 效果：\n\\int_{-\\infty}^{+\\infty} e^{-x^2} \\, dx = \\sqrt{\\pi}多行 / 复杂公式 —— 必须用 math 短代码包裹：\n{{\u0026lt; math \u0026gt;}} \\begin{pmatrix} a \u0026amp; b \\\\ c \u0026amp; d \\end{pmatrix} {{\u0026lt; /math \u0026gt;}} 效果：\n\\begin{pmatrix} a \u0026 b \\\\ c \u0026 d \\end{pmatrix} \\begin{pmatrix} x \\\\ y \\end{pmatrix} = \\begin{pmatrix} ax + by \\\\ cx + dy \\end{pmatrix} ⚠️ 多行公式直接写多行 $$ 会被 Markdown 解析器破坏（\\end{pmatrix} 会被当成标题），必须用 math 短代码。\n6.4 Mermaid 图表 直接写代码块即可（不需要记短代码）。\n流程图 —— 写法：\n```mermaid flowchart TD A[开始] --\u0026gt; B{判断} B --\u0026gt;|是| C[结束] ``` 效果：\nflowchart TD A[开始] --\u0026gt; B{判断} B --\u0026gt;|是| C[结束] 时序图 —— 写法：\n```mermaid sequenceDiagram 用户-\u0026gt;\u0026gt;服务器: 发起请求 服务器--\u0026gt;\u0026gt;用户: 返回数据 ``` 效果：\nsequenceDiagram 用户-\u0026gt;\u0026gt;服务器: 发起请求 服务器--\u0026gt;\u0026gt;用户: 返回数据 饼图 —— 写法：\n```mermaid pie title 时间分配 \u0026#34;写作\u0026#34; : 45 \u0026#34;阅读\u0026#34; : 30 \u0026#34;其他\u0026#34; : 25 ``` 效果：\npie title 时间分配 \u0026#34;写作\u0026#34; : 45 \u0026#34;阅读\u0026#34; : 30 \u0026#34;其他\u0026#34; : 25 图表配色会自动跟随明暗主题切换。\n七、常用组合 一段技术说明可以这样写：\n写法：\n{{\u0026lt; note warning \u0026#34;前置条件\u0026#34; \u0026gt;}} 需要 **Hugo extended** 版本。 {{\u0026lt; /note \u0026gt;}} ```mermaid flowchart LR A[输入] --\u0026gt; B[处理] --\u0026gt; C[输出] 核心公式：\nT(n) = 2T(n/2) + O(n) **效果**： 需要 Hugo extended 版本。 ```mermaid flowchart LR A[输入] --\u0026gt; B[处理] --\u0026gt; C[输出] 核心公式：\nT(n) = 2T(n/2) + O(n) 八、常见坑 现象 原因 解决 提示框里 **加粗** 没生效 用了 HTML 写法，块级 HTML 内不解析 Markdown 改用 note 短代码 多行公式显示成标题 直接写了多行 $$…$$ 用 math 短代码包裹 Mermaid 显示为代码块 语言名写错 必须是 ```mermaid（全小写） collapse 没有标题 用了位置参数 改成 summary=\u0026quot;标题\u0026quot; 文章写了但不显示 date 是未来时间 改成过去时间或加 --buildFuture 文章写了但不显示 draft: true 改成 false，或预览加 -D 短代码被当成文字显示 参数格式错误 检查尖括号与引号 九、更多 Hugo + PaperMod 写作语法大全 —— 含 Front Matter 全字段、各短代码参数细节 从 Hexo(AnZhiYu) 迁移到 Hugo(PaperMod) 完整记录 Hugo 博客多平台部署与 baseURL 配置 脚注内容写在这里。\u0026#160;\u0026#x21a9;\u0026#xfe0e;\n","permalink":"https://blog.646474.xyz/posts/writing-guide-demo/","summary":"\u003cp\u003e本文档列出本站支持的\u003cstrong\u003e全部写作语法\u003c/strong\u003e，每条都给出「\u003cstrong\u003e写法\u003c/strong\u003e」与「\u003cstrong\u003e实际效果\u003c/strong\u003e」对照，方便直接照着抄。\u003c/p\u003e\n\u003cblockquote\u003e\n\u003cp\u003e提示：右侧目录可快速跳转。\u003c/p\u003e\n\u003c/blockquote\u003e\n\u003chr\u003e\n\u003ch2 id=\"一快速开始\"\u003e一、快速开始\u003c/h2\u003e\n\u003cp\u003e新建文章（自动套用模板）：\u003c/p\u003e\n\u003cdiv class=\"highlight\"\u003e\u003cpre tabindex=\"0\" class=\"chroma\"\u003e\u003ccode class=\"language-bash\" data-lang=\"bash\"\u003e\u003cspan class=\"line\"\u003e\u003cspan class=\"cl\"\u003ehugo new content posts/我的新文章.md\n\u003c/span\u003e\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\u003c/div\u003e\u003cp\u003e本地预览（写完保存自动刷新）：\u003c/p\u003e\n\u003cdiv class=\"highlight\"\u003e\u003cpre tabindex=\"0\" class=\"chroma\"\u003e\u003ccode class=\"language-bash\" data-lang=\"bash\"\u003e\u003cspan class=\"line\"\u003e\u003cspan class=\"cl\"\u003ehugo server -D\n\u003c/span\u003e\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\u003c/div\u003e\u003cp\u003e推送发布（等价于原来 Hexo 的 \u003ccode\u003ehexo push\u003c/code\u003e）：\u003c/p\u003e\n\u003cdiv class=\"highlight\"\u003e\u003cpre tabindex=\"0\" class=\"chroma\"\u003e\u003ccode class=\"language-bash\" data-lang=\"bash\"\u003e\u003cspan class=\"line\"\u003e\u003cspan class=\"cl\"\u003e./push.sh        \u003cspan class=\"c1\"\u003e# Git Bash\u003c/span\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan class=\"line\"\u003e\u003cspan class=\"cl\"\u003epush.bat         \u003cspan class=\"c1\"\u003e# 或直接双击这个文件\u003c/span\u003e\n\u003c/span\u003e\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\u003c/div\u003e\u003chr\u003e\n\u003ch2 id=\"二front-matter文章头部配置\"\u003e二、Front Matter（文章头部配置）\u003c/h2\u003e\n\u003cp\u003e\u003cstrong\u003e写法\u003c/strong\u003e：\u003c/p\u003e\n\u003cdiv class=\"highlight\"\u003e\u003cpre tabindex=\"0\" class=\"chroma\"\u003e\u003ccode class=\"language-yaml\" data-lang=\"yaml\"\u003e\u003cspan class=\"line\"\u003e\u003cspan class=\"cl\"\u003e\u003cspan class=\"nn\"\u003e---\u003c/span\u003e\u003cspan class=\"w\"\u003e\n\u003c/span\u003e\u003c/span\u003e\u003c/span\u003e\u003cspan class=\"line\"\u003e\u003cspan class=\"cl\"\u003e\u003cspan class=\"nt\"\u003etitle\u003c/span\u003e\u003cspan class=\"p\"\u003e:\u003c/span\u003e\u003cspan class=\"w\"\u003e \u003c/span\u003e\u003cspan class=\"s2\"\u003e\u0026#34;文章标题\u0026#34;\u003c/span\u003e\u003cspan class=\"w\"\u003e\n\u003c/span\u003e\u003c/span\u003e\u003c/span\u003e\u003cspan class=\"line\"\u003e\u003cspan class=\"cl\"\u003e\u003cspan class=\"nt\"\u003edate\u003c/span\u003e\u003cspan class=\"p\"\u003e:\u003c/span\u003e\u003cspan class=\"w\"\u003e \u003c/span\u003e\u003cspan class=\"ld\"\u003e2026-10-07T10:00:00\u003c/span\u003e\u003cspan class=\"m\"\u003e+08\u003c/span\u003e\u003cspan class=\"p\"\u003e:\u003c/span\u003e\u003cspan class=\"m\"\u003e00\u003c/span\u003e\u003cspan class=\"w\"\u003e\n\u003c/span\u003e\u003c/span\u003e\u003c/span\u003e\u003cspan class=\"line\"\u003e\u003cspan class=\"cl\"\u003e\u003cspan class=\"nt\"\u003elastmod\u003c/span\u003e\u003cspan class=\"p\"\u003e:\u003c/span\u003e\u003cspan class=\"w\"\u003e \u003c/span\u003e\u003cspan class=\"ld\"\u003e2026-10-07T10:00:00\u003c/span\u003e\u003cspan class=\"m\"\u003e+08\u003c/span\u003e\u003cspan class=\"p\"\u003e:\u003c/span\u003e\u003cspan class=\"m\"\u003e00\u003c/span\u003e\u003cspan class=\"w\"\u003e\n\u003c/span\u003e\u003c/span\u003e\u003c/span\u003e\u003cspan class=\"line\"\u003e\u003cspan class=\"cl\"\u003e\u003cspan class=\"nt\"\u003edraft\u003c/span\u003e\u003cspan class=\"p\"\u003e:\u003c/span\u003e\u003cspan class=\"w\"\u003e \u003c/span\u003e\u003cspan class=\"kc\"\u003efalse\u003c/span\u003e\u003cspan class=\"w\"\u003e\n\u003c/span\u003e\u003c/span\u003e\u003c/span\u003e\u003cspan class=\"line\"\u003e\u003cspan class=\"cl\"\u003e\u003cspan class=\"nt\"\u003edescription\u003c/span\u003e\u003cspan class=\"p\"\u003e:\u003c/span\u003e\u003cspan class=\"w\"\u003e \u003c/span\u003e\u003cspan class=\"s2\"\u003e\u0026#34;文章摘要，显示在列表页与搜索结果里\u0026#34;\u003c/span\u003e\u003cspan class=\"w\"\u003e\n\u003c/span\u003e\u003c/span\u003e\u003c/span\u003e\u003cspan class=\"line\"\u003e\u003cspan class=\"cl\"\u003e\u003cspan class=\"nt\"\u003etags\u003c/span\u003e\u003cspan class=\"p\"\u003e:\u003c/span\u003e\u003cspan class=\"w\"\u003e \u003c/span\u003e\u003cspan class=\"p\"\u003e[\u003c/span\u003e\u003cspan class=\"s2\"\u003e\u0026#34;标签一\u0026#34;\u003c/span\u003e\u003cspan class=\"p\"\u003e,\u003c/span\u003e\u003cspan class=\"w\"\u003e \u003c/span\u003e\u003cspan class=\"s2\"\u003e\u0026#34;标签二\u0026#34;\u003c/span\u003e\u003cspan class=\"p\"\u003e]\u003c/span\u003e\u003cspan class=\"w\"\u003e\n\u003c/span\u003e\u003c/span\u003e\u003c/span\u003e\u003cspan class=\"line\"\u003e\u003cspan class=\"cl\"\u003e\u003cspan class=\"nt\"\u003ecategories\u003c/span\u003e\u003cspan class=\"p\"\u003e:\u003c/span\u003e\u003cspan class=\"w\"\u003e \u003c/span\u003e\u003cspan class=\"p\"\u003e[\u003c/span\u003e\u003cspan class=\"s2\"\u003e\u0026#34;随笔\u0026#34;\u003c/span\u003e\u003cspan class=\"p\"\u003e]\u003c/span\u003e\u003cspan class=\"w\"\u003e\n\u003c/span\u003e\u003c/span\u003e\u003c/span\u003e\u003cspan class=\"line\"\u003e\u003cspan class=\"cl\"\u003e\u003cspan class=\"nt\"\u003ekeywords\u003c/span\u003e\u003cspan class=\"p\"\u003e:\u003c/span\u003e\u003cspan class=\"w\"\u003e \u003c/span\u003e\u003cspan class=\"p\"\u003e[\u003c/span\u003e\u003cspan class=\"s2\"\u003e\u0026#34;关键词\u0026#34;\u003c/span\u003e\u003cspan class=\"p\"\u003e]\u003c/span\u003e\u003cspan class=\"w\"\u003e\n\u003c/span\u003e\u003c/span\u003e\u003c/span\u003e\u003cspan class=\"line\"\u003e\u003cspan class=\"cl\"\u003e\u003cspan class=\"nt\"\u003emath\u003c/span\u003e\u003cspan class=\"p\"\u003e:\u003c/span\u003e\u003cspan class=\"w\"\u003e \u003c/span\u003e\u003cspan class=\"kc\"\u003etrue\u003c/span\u003e\u003cspan class=\"w\"\u003e                 \u003c/span\u003e\u003cspan class=\"c\"\u003e# 开启数学公式\u003c/span\u003e\u003cspan class=\"w\"\u003e\n\u003c/span\u003e\u003c/span\u003e\u003c/span\u003e\u003cspan class=\"line\"\u003e\u003cspan class=\"cl\"\u003e\u003cspan class=\"nt\"\u003eShowToc\u003c/span\u003e\u003cspan class=\"p\"\u003e:\u003c/span\u003e\u003cspan class=\"w\"\u003e \u003c/span\u003e\u003cspan class=\"kc\"\u003etrue\u003c/span\u003e\u003cspan class=\"w\"\u003e              \u003c/span\u003e\u003cspan class=\"c\"\u003e# 显示目录\u003c/span\u003e\u003cspan class=\"w\"\u003e\n\u003c/span\u003e\u003c/span\u003e\u003c/span\u003e\u003cspan class=\"line\"\u003e\u003cspan class=\"cl\"\u003e\u003cspan class=\"nt\"\u003ecover\u003c/span\u003e\u003cspan class=\"p\"\u003e:\u003c/span\u003e\u003cspan class=\"w\"\u003e\n\u003c/span\u003e\u003c/span\u003e\u003c/span\u003e\u003cspan class=\"line\"\u003e\u003cspan class=\"cl\"\u003e\u003cspan class=\"w\"\u003e  \u003c/span\u003e\u003cspan class=\"nt\"\u003eimage\u003c/span\u003e\u003cspan class=\"p\"\u003e:\u003c/span\u003e\u003cspan class=\"w\"\u003e \u003c/span\u003e\u003cspan class=\"s2\"\u003e\u0026#34;/images/cover/x.jpg\u0026#34;\u003c/span\u003e\u003cspan class=\"w\"\u003e\n\u003c/span\u003e\u003c/span\u003e\u003c/span\u003e\u003cspan class=\"line\"\u003e\u003cspan class=\"cl\"\u003e\u003cspan class=\"w\"\u003e  \u003c/span\u003e\u003cspan class=\"nt\"\u003ealt\u003c/span\u003e\u003cspan class=\"p\"\u003e:\u003c/span\u003e\u003cspan class=\"w\"\u003e \u003c/span\u003e\u003cspan class=\"s2\"\u003e\u0026#34;封面描述\u0026#34;\u003c/span\u003e\u003cspan class=\"w\"\u003e\n\u003c/span\u003e\u003c/span\u003e\u003c/span\u003e\u003cspan class=\"line\"\u003e\u003cspan class=\"cl\"\u003e\u003cspan class=\"w\"\u003e  \u003c/span\u003e\u003cspan class=\"nt\"\u003ecaption\u003c/span\u003e\u003cspan class=\"p\"\u003e:\u003c/span\u003e\u003cspan class=\"w\"\u003e \u003c/span\u003e\u003cspan class=\"s2\"\u003e\u0026#34;封面说明\u0026#34;\u003c/span\u003e\u003cspan class=\"w\"\u003e\n\u003c/span\u003e\u003c/span\u003e\u003c/span\u003e\u003cspan class=\"line\"\u003e\u003cspan class=\"cl\"\u003e\u003cspan class=\"nn\"\u003e---\u003c/span\u003e\u003cspan class=\"w\"\u003e\n\u003c/span\u003e\u003c/span\u003e\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\u003c/div\u003e\u003cp\u003e\u003cstrong\u003e说明\u003c/strong\u003e：所有字段都可选，不写就用 \u003ccode\u003ehugo.yaml\u003c/code\u003e 里的全局默认值。\u003ccode\u003edraft: true\u003c/code\u003e 的文章不会发布。\u003c/p\u003e\n\u003chr\u003e\n\u003ch2 id=\"三文本与结构\"\u003e三、文本与结构\u003c/h2\u003e\n\u003ch3 id=\"31-标题\"\u003e3.1 标题\u003c/h3\u003e\n\u003cp\u003e\u003cstrong\u003e写法\u003c/strong\u003e：\u003c/p\u003e","title":"写作语法速查（写法 + 效果对照）"},{"content":"这是一篇语法速查示例，演示 Hugo + PaperMod 支持的全部写作语法。 迁移旧文章时，可以对照本文把 AnZhiYu 的标签替换成这里的写法。\n一、基础 Markdown 普通段落、加粗、斜体、删除线、行内代码、链接。\n无序列表 第二项 嵌套项 有序列表 第二项 已完成的任务 未完成的任务 这是引用块，适合放金句或重要观点。\n支持多段引用。\n二、表格 功能 AnZhiYu 写法 PaperMod 写法 提示框 {% note info %} \u0026lt;div class=\u0026quot;note info\u0026quot;\u0026gt; 折叠 {% folding %} {{\u0026lt; collapse \u0026gt;}} 流程图 {% mermaid %} ```mermaid 代码块 数学公式 {% katex %} $公式$ 或 $$公式$$ 三、代码块 def greet(name: str) -\u0026gt; str: \u0026#34;\u0026#34;\u0026#34;代码块会自动高亮，并带复制按钮\u0026#34;\u0026#34;\u0026#34; return f\u0026#34;Hello, {name}!\u0026#34; hugo new content posts/我的新文章.md # 新建文章 hugo server -D # 本地预览（含草稿） hugo # 构建静态文件到 public/ 四、提示框（用 note 短代码，内容支持 Markdown） 这是信息提示框（info）。内部支持 加粗、行内代码、链接、列表等全部 Markdown 语法。 这是成功提示框（success） 这是警告提示框（warning） 这是危险提示框（danger） 带标题的提示框：第二个参数就是标题。Markdown 依然生效。 为什么不用 HTML 写法？（点击了解） 直接写 \u0026lt;div class=\u0026quot;note info\u0026quot;\u0026gt;…\u0026lt;/div\u0026gt; 时，块级 HTML 内部的 Markdown 不会被解析 （这是 CommonMark 规范的行为），**加粗** 会原样显示成星号。\n所以本站提供 note 短代码：内容会先经过 Markdown 渲染再填入提示框。 如需用 HTML 写法，标签与内容之间必须留空行：\n\u0026lt;div class=\u0026#34;note info\u0026#34;\u0026gt; **加粗**会被解析 \u0026lt;/div\u0026gt; 五、高亮与两栏对比 行内高亮：重点内容、正确做法、补充信息\n两栏对比（并排显示，适合替代 AnZhiYu 的 tabs）：\n方案 A：Hexo + AnZhiYu 标签丰富、生态成熟、上手快。适合喜欢现成组件、愿意维护插件依赖的场景。\n方案 B：Hugo + PaperMod 构建极快（毫秒级）、零依赖、配置简单。适合专注内容创作、追求长期可维护性。\n六、折叠内容 点击展开 / 收起 这里是被折叠的内容，适合放补充说明、长代码、参考资料。\n列表也可以 支持任意 Markdown 七、数学公式（KaTeX） 行内公式：质能方程 E = mc^2，欧拉恒等式 e^{i\\pi} + 1 = 0。\n独立公式：\n\\int_{-\\infty}^{+\\infty} e^{-x^2} \\, dx = \\sqrt{\\pi} 矩阵（多行公式 —— 用 math 短代码包裹，避免 Markdown 误判）：\n\\begin{pmatrix} a \u0026 b \\\\ c \u0026 d \\end{pmatrix} \\begin{pmatrix} x \\\\ y \\end{pmatrix} = \\begin{pmatrix} ax + by \\\\ cx + dy \\end{pmatrix} 矩阵（单行公式 —— 直接写 $$...$$ 即可，内容写在同一行）：\n\\begin{pmatrix} a \u0026 b \\\\ c \u0026 d \\end{pmatrix} \\begin{pmatrix} x \\\\ y \\end{pmatrix} = \\begin{pmatrix} ax + by \\\\ cx + dy \\end{pmatrix}八、Mermaid 流程图 直接写 ```mermaid 代码块即可（本模板已自动转换，不需要记短代码）：\nflowchart TD A[Hexo + AnZhiYu] --\u0026gt; B{是否长期创作?} B --\u0026gt;|是| C[迁移到 Hugo + PaperMod] B --\u0026gt;|否| D[保持现状] C --\u0026gt; E[转换 front matter] E --\u0026gt; F[替换标签语法] F --\u0026gt; G[完成迁移] 时序图也支持：\nsequenceDiagram participant 作者 participant Hugo participant 浏览器 作者-\u0026gt;\u0026gt;Hugo: 写 Markdown Hugo-\u0026gt;\u0026gt;Hugo: 构建（毫秒级） Hugo-\u0026gt;\u0026gt;浏览器: 输出静态 HTML 浏览器--\u0026gt;\u0026gt;作者: 极快的访问体验 九、图片 普通 Markdown 写法（PaperMod 会自动生成图注）：\n更精细的控制用 figure 短代码：\n图片标题图片说明文字，会显示在图下方\n十、视频与音频 {{\u0026lt; youtube VIDEO_ID \u0026gt;}} YouTube 视频 {{\u0026lt; vimeo VIDEO_ID \u0026gt;}} Vimeo 视频 {{\u0026lt; video src=\u0026#34;/media/demo.mp4\u0026#34; \u0026gt;}} 本地视频 {{\u0026lt; audio src=\u0026#34;/media/demo.mp3\u0026#34; \u0026gt;}} 本地音频 十一、原始 HTML 需要写复杂 HTML（如 iframe 嵌入）时用 rawhtml 短代码：\n{{\u0026lt; rawhtml \u0026gt;}} \u0026lt;div class=\u0026#34;my-widget\u0026#34;\u0026gt;任意 HTML\u0026lt;/div\u0026gt; {{\u0026lt; /rawhtml \u0026gt;}} 以上就是全部可用语法。日常写作里最常用的组合是：提示框 + 代码块 + 数学公式 + Mermaid。\n","permalink":"https://blog.646474.xyz/posts/syntax-demo/","summary":"演示 PaperMod 支持的写作语法：提示框、折叠、数学公式、Mermaid 流程图、图片、表格等。","title":"PaperMod 语法速查（示例文章）"},{"content":"这里写你的自我介绍。\n提示：hidemeta: true 会隐藏页面顶部的日期/作者等信息，适合「关于」「友链」这类静态页面。\n","permalink":"https://blog.646474.xyz/about/","summary":"关于我","title":"关于"}]