加载中...

写作与 Wiki 指南

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

1. 撰写文章

1.1 创建文章

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

文件位于 source/_posts/，不需要子目录。

1.2 最小 front-matter

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

其他常用字段：

字段用途说明
keywordsSEO 关键词如 '关键词1, 关键词2'
excerpt文章摘要显示在列表页
coverImg封面图路径如 /medias_webp/cover/xxx.webp
top置顶true 置顶
toc目录false 关闭

1.3 abbrlink（永久链接）

永久链接格式为 posts/:abbrlink/（如 /posts/13894dce/）。abbrlink 由 hexo-abbrlink 插件在首次构建时自动生成并写回 front-matter，永远不要手改已有文章的 abbrlink，否则永久断链。

1.4 内容语法

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

2. Wiki Frontmatter

Wiki 页面 frontmatter 必须包含：

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

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

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

其他可选字段与博客文章一致（toc / mathjax / mermaid / closeAutoTocNum 等）。

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 目录结构

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

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

3.2 URL 规则

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

3.3 回落机制

  • 有英文版（source/en/ 有对应文件）→ 访问 /en/... 显示英文
  • 无英文版 → 访问 /en/... 回落显示中文内容 + 顶部提示条（“该页暂无 en 版本，当前显示默认语言内容”），并 noindex 防 SEO 重复
  • 翻译源约定：source/en/{wiki}/{页面}.md——新增翻译直接放源文件即可，无需改配置

3.4 编写建议

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

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

3.5 文章翻译版

博客文章也可以创建多语言版本。翻译文件放在 source/{lang}/_posts/ 下，与中文原版同名：

---
layout: post
title: 文章标题（英文）
abbrlink: 13894dce      # 必须与中文原版一致
lang: en
categories:
  - Category Name
tags:
  - tag1
  - tag2
---
要点说明
文件位置source/en/_posts/{与中文同名}.md
abbrlink必须与中文原版一致，否则中英链接无法关联
lang 字段必须添加 lang: en
构建产物自动生成 /en/posts/{abbrlink}/ 路径

abbrlink 由 hexo-abbrlink 插件在首次构建时自动生成并写回 front-matter，永远不要手改已有文章的 abbrlink。

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

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

5. 验证

  • 本地构建：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
评论
数据加载中 ...