写作与 Wiki 指南

本页汇总博客写作（文章 post）与 Wiki 系统的编写方法、多语言约定与注意事项。适合新增/维护内容时参考。

阅读方式：每个可复制的示例都按「效果（页面上/产物里变成什么样）→ 对应源码/命令 → 输出」成对给出，先看结果再抄写法。

1. 撰写文章

1.1 创建文章

效果：source/_posts/ 下多一个 Markdown 文件，已带好 scaffold 的 front-matter 骨架，直接写正文即可。

对应命令：

hexo new post "文章标题"
# 生成 source/_posts/文章标题.md（构建时自动转小写）

输出：终端打印 INFO Created: ~/.../source/_posts/文章标题.md；文件位于 source/_posts/，不需要子目录。

1.2 最小 front-matter

效果：文章被识别为博客文章（layout: post），首页/归档出现卡片，分类页与标签页能索引到它。

对应源码：

---
layout: post
title: 文章标题
categories:
  - 分类名
tags:
  - 标签名
---

输出：构建后生成 /posts/<abbrlink>/ 页面，public/categories/、public/tags/ 下出现对应条目。

其他常用字段：

字段	用途	说明
`keywords`	SEO 关键词	如 `'关键词1, 关键词2'`
`excerpt`	文章摘要	显示在列表页
`img`	文章封面图（首页卡片展示）	如 `/medias_webp/cover/xxx.webp`
`top`	置顶	`true` 置顶
`hide`	完全隐藏	不进首页列表、不进轮播
`cover`	进入首页轮播	`hide: true` 时无效
`coverImg`	轮播自定义图	优先于默认图
`toc`	是否显示目录	`false` 关闭
`tochide`	默认隐藏目录栏	`true` 隐藏但可展开
`mathjax`	加载 MathJax 数学公式	`true` 启用
`mermaid`	加载 Mermaid 图表	`true` 启用
`echarts`	加载 ECharts 图表	`true` 启用
`comments`	是否开启评论	`false` 关闭
`comment`	指定评论引擎	如 `waline`；`false` 关闭
`password`	文章加密密码	单独加密时使用
`reprintPolicy`	版权声明策略	如 `cc_by_nc_sa`

完整字段表（23 个）见目录结构与内容管理 §4。

1.3 abbrlink（永久链接）

效果：文章 URL 固定为 /posts/<abbrlink>/（如 /posts/13894dce/），改标题也不变；一旦手改 abbrlink，旧链接立即 404。

对应命令（查看现有值）：

grep -m1 '^abbrlink' source/_posts/<文件名>.md

输出：

abbrlink: 13894dce

永久链接格式为 posts/:abbrlink/（如 /posts/13894dce/）。abbrlink 由 hexo-abbrlink 插件生成并写入 front-matter（writeback: false 后不再回写，字段固定），永远不要手改已有文章的 abbrlink，否则永久断链。

1.4 内容语法

效果：容器语法 ::: tip 渲染成带色条的提示块（不是纯文本）；同样的内容用 Markdown/tag 写法都能得到对应组件。

对应源码：

::: tip
这是一条 tip 提示块。
:::

输出：HTML 里变成 <div class="tip">…</div> 一类容器块，页面显示为彩色提示框。

文章与 Wiki 使用相同的 Markdown 渲染引擎（hexo-renderer-markdown-it），支持全部 markdown-it 插件和 matery 14 个自定义 tag 插件。语法细节见「Markdown 语法扩展」与「内容 Tag 插件」。

2. Wiki Frontmatter

目录约定：每个 wiki 子站在 source/{wiki}/ 下（如 source/tutorial/），英文版在 source/en/{wiki}/（如 source/en/tutorial/）。

效果：页面套用 wiki 布局（三栏 + 侧栏目录），并归入指定 wiki 子站的侧栏树。

对应源码：

---
title: 页面标题
layout: wiki        # 必须：wiki 布局（三栏 + 侧栏）
wiki: tutorial      # 必须：所属 wiki 子站（docs / api / tutorial）
---

输出：访问 /tutorial/<路径> 得到带侧栏的页面；wiki 值不匹配时侧栏找不到当前页。

英文版须加 lang: en（否则侧栏链接回落到中文路径）：

效果：英文页的侧栏链接带 /en/ 前缀，指向英文版；不加则侧栏仍指向中文路径。

对应源码：

---
title: Page Title
layout: wiki
wiki: tutorial
lang: en            # 英文版必须
---

输出：构建后生成 /en/tutorial/...，侧栏链接前缀为 /en/。

其他可选字段与博客文章一致（toc / mathjax / mermaid / echarts / closeAutoTocNum / comment 等）。Wiki 页面也支持通过 front-matter 的 comment: false 关闭评论（由 post-filter.js 统一处理）。

Wiki 页面支持的 Markdown 语法与博客文章一致：

全部 markdown-it 插件：emoji / abbr / 脚注 / 任务列表 / 表格 / 容器 / 数学公式（ $...$ ）等
matery 14 个自定义 tag 插件：`{% note %}`、`{% tabs %}`、`{% timeline %}`、`{% mermaid %}`、`{% button %}`、`{% label %}`、`{% groupimage %}`、`{% wechat_dialog %}`、`{% cardurl %}` 等
容器语法（:::）：::: tip / ::: warning / ::: note / ::: info / ::: attention / ::: error / ::: hint（渲染为色条提示块）

3. 多语言支持

3.1 Wiki 目录结构

效果：同一页面中英两份文件并存，构建后各生成一条 URL；中文无前缀，英文在 /en/ 下。

对应源码（目录布局）：

source/tutorial/guide/writing.md     # 中文版（默认语言，无前缀）
source/en/tutorial/guide/writing.md  # 英文版（/en/ 前缀，必须写 lang: en）

输出：public/tutorial/guide/writing.html 与 public/en/tutorial/guide/writing.html 两个文件（实测产物为 .html，不是目录）。

3.2 URL 规则

效果：两种语言各自有稳定路径，切换语言时只换前缀。

对应输出：

语言	URL
中文（默认）	`/tutorial/guide/writing`（无前缀）
英文	`/en/tutorial/guide/writing`（/en/ 前缀）

3.3 回落机制

效果：访问 /en/... 时——有英文版就显示英文；没有则显示中文内容，并在顶部加提示条（“该页暂无 en 版本，当前显示默认语言内容”），同时 noindex 防 SEO 重复收录。

对应源码：source/en/{wiki}/{页面}.md——新增翻译直接放源文件即可，无需改配置。

有英文版（source/en/ 有对应文件）→ 访问 /en/... 显示英文
无英文版 → 访问 /en/... 回落显示中文内容 + 顶部提示条，并 noindex
翻译源约定：source/en/{wiki}/{页面}.md

3.4 编写建议

效果：按下面四条写，新增页面后侧栏有条目、语言切换不断链、翻译 key 不裸露。

对应做法：

默认语言（中文）优先：先写中文，再补英文
侧栏 key 英文化：source/_data/{wiki}-sidebar.yml 的 key 用英文 snake_case（如 getting_started），显示文本走 languages/*.yml 翻译
内部链接：正文链接用绝对路径 + .html（如 /tutorial/guide/writing.html）——多语言下自动加语言前缀，避免相对路径错位
新增 wiki 页面后：更新 source/_data/{wiki}-sidebar.yml 加侧栏条目

输出：侧栏出现新条目；/en/tutorial/... 下的正文链接自动变成 /en/tutorial/...。

说明：source/_data/{wiki}-sidebar.yml 是本主题的侧栏约定——多数 Hexo 博客在主题配置或模板里维护侧栏，本主题改为在 _data/ 下按 wiki 放一个数据文件，便于分开管理。

3.5 文章翻译版

效果：同一篇文章生成中英两条 URL（/posts/<abbrlink>/ 与 /en/posts/<abbrlink>/），语言切换按钮能在两版之间跳转。

目录约定：翻译文件放在 source/{lang}/_posts/ 下（如 source/en/_posts/），与中文原版同名。

对应源码（翻译文件 front-matter）：

---
layout: post
title: 文章标题（英文）
abbrlink: 13894dce      # 必须与中文原版一致
lang: en
categories:
  - Category Name
tags:
  - tag1
  - tag2
---

输出：public/en/posts/13894dce/index.html。

要点	说明
文件位置	`source/en/_posts/{与中文同名}.md`
abbrlink	必须与中文原版一致，否则中英链接无法关联
lang 字段	必须添加 `lang: en`
构建产物	自动生成 `/en/posts/{abbrlink}/` 路径

abbrlink 由 hexo-abbrlink 插件在首次构建时生成并写入 front-matter（writeback: false 后不再回写，字段固定），永远不要手改已有文章的 abbrlink。

4. 段落编号注意事项（重要）

效果：默认 CSS 会给 h2–h6 自动加编号（1.、1.1、1.1.1…）；若标题里已手写编号，页面上会变成双重编号（1. 1. 概述）。加 closeAutoTocNum: true 后只保留手写编号。

对应源码（手写编号的页面 front-matter）：

---
title: 页面标题
layout: wiki
wiki: tutorial
closeAutoTocNum: true    # 关闭 CSS 自动编号，避免双重编号
---

输出：1. 概述 只显示一层编号；不加该字段则显示 1. 1. 概述。

主题 CSS 自动编号（默认开启）：自动给 h2-h6 加编号
手写编号（如 ## 1. 概述、### 1.1 背景）会与 CSS 自动编号双重编号
手写编号的页面必须设 closeAutoTocNum: true（frontmatter）关闭 CSS 自动编号
不手写编号的页面不要设该字段（让 CSS 自动编号）

5. 验证

效果：逐项确认构建产物与预期一致——中英两版都在、未翻译页有回落提示、英文页链接不回落。

对应命令：

# 本地构建后检查产物
ls public/tutorial/guide/writing.html
ls public/en/tutorial/guide/writing.html

输出：两条路径都存在（ls 无报错），即中英两版都已生成。

本地构建：npm run build 后访问 /tutorial/xxx 与 /en/tutorial/xxx，确认两版内容正确渲染
多语言：在 source/en/tutorial/ 下新增一个测试页并配好 front-matter，确认 /en/tutorial/<name> 显示英文；再访问一个未翻译的页面，确认显示默认语言内容 + 顶部回落提示条
英文页 lang: en：确认所有 source/en/tutorial/**/*.md 都包含 lang: en，否则侧栏链接会回落到中文路径（/docs/ 而非 /en/docs/）
侧栏翻译：启用了几种语言，就检查对应 languages/*.yml 中是否有 sidebar.tutorial.* 条目，避免侧栏显示原始 key