写作规范

目录结构

knowledge-base/
├── book.json              # HonKit 配置（插件、语言、根目录）
├── package.json           # 依赖与脚本
├── content/
│   ├── SUMMARY.md         # 侧边栏目录（必须维护）
│   ├── README.md          # 首页
│   ├── references.bib     # 所有引用来源的统一数据库
│   └── *.md               # 各知识条目
├── assets/                # 图片、附件
├── csl/                   # 引用样式文件（自动下载）
└── scripts/
    └── pandoc-render.sh   # 学术引用样式渲染

新增一篇笔记

  1. 在 content/ 新建 xxx.md
  2. 在 content/SUMMARY.md 添加 * [标题](xxx.md) —— 不加就不会显示
  3. 引用来源元数据写入 content/references.bib
  4. 正文引用（全库统一：数字编号 + GB/T 7714）：
    • 正文用编号 [n]（按首次出现顺序，重复引用沿用同一编号）
    • 文末 ## 参考文献，按 GB/T 7714—2015 列出： 作者. 题名[类型]//出处. 年份. 链接. （作者 YANG S 姓全大写 + 名缩写；>3 人 et al.，中文用「等」； 类型：[J] 期刊、[C] 会议、[J/OL] 预印本、[EB/OL] 网页）
    • 格式要点见 引用与参考文献

命名约定

  • 文件名用小写英文 + 连字符：attention-mechanism.md
  • BibTeX key：作者年份关键词，如 vaswani2017attention
  • 引用网页务必记录访问日期 urldate

公式（KaTeX）

支持两种写法：

  • 行内：一个美元符号包裹，如 $O(N^2)$

  • 块级：独占一行，首尾各用一个双美元符号（写成两个连续的 $）：

    E=mc2
  E = mc^2
  E=mc​2​​

底层由 gitbook-plugin-katex 提供：它的块语法只识别双美元符号， 所以仓库自建的 plugins/katex-inline 在 page:before 钩子里把行内单美元 公式改写成双美元（改写后不含换行，插件会按行内模式渲染）。

转换会跳过围栏代码块、行内代码反引号与已有的双美元块，因此：

  • 代码块 / 行内代码里的美元符号原样保留，不会误渲染；
  • 想写字面美元符号用反斜杠转义；
  • Mermaid 节点内用双美元书写的数学语法不受影响。

注意：列表项 / 表格单元格中的行内代码反引号不会被 HonKit 的 preparePage 保护，因此不要在这两类位置把两个双美元符号写在同一行—— 它们会被当成块级公式的开闭符，把中间的文字送进 KaTeX 而报错。

导出 PDF 中文字体

honkit pdf 依赖 Calibre。中文 PDF 建议用 Pandoc + XeLaTeX：

pandoc content/*.md -o out.pdf --pdf-engine=xelatex -V CJKmainfont="PingFang SC"

© 2026 Yang Huan · yanghuan9812@qq.com

results matching ""

    No results matching ""