写作规范

目录结构

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] 网页）
    • 格式要点见 引用与参考文献

所有笔记完成后运行 npm run build。修改渲染插件时还需检查生成 HTML，并在可用浏览器中确认显示。

命名约定

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

图题与表题

图题放在图片或 Mermaid 图之后，表题放在表格之前。图、表分别在单篇文档内按首次出现顺序连续编号，标题使用中文分隔符 ｜：

![regcmd 的字段布局](assets/regcmd-format.svg){width=100% height=auto}

> **图 1｜regcmd 的字段布局**。三个字段分别占 16/32/16 bit。

> **表 1｜任务描述符的字段**

| 字段 | 含义 |
|---|---|
| 地址 | 命令缓冲区的设备地址 |
| 长度 | 命令字数量 |

Markdown 中保留 > 写法，网页的 fig-refs 插件会将以“图 N｜”或“表 N｜”开头的引用块转换成独立题注：英文与数字用 Times New Roman，中文用楷体，字号比正文小 1 px，水平居中，不显示引用框的竖线或缩进。题注靠近图表一侧的间距为 0.35em，与正文一侧的间距为 1.35em；图题紧接图片，表题紧接表格。编号与标题保留加粗，说明文字正常排版；链接、引用上标与公式仍可使用。一般引用和 emoji 提示块保留各自样式。

论文截图的图题说明来源与引用编号，例如 > **图 2｜模型架构**（取自论文 Figure 1[1]）。……。图题说明图中内容与阅读要点，具体论证放入正文。

紧凑表格与列宽

列数较多时，可在 Markdown 表格前使用共享布局注释；不用为单页手写 HTML 或 CSS：

<!-- kb-table: compact widths=20,30,50 -->

| 型号 | 资源 | 说明 |
|---|---|---|
| A | 8 MiB | 配置查询结果 |

compact 缩小字号；widths 按列指定百分比，数量须与列数一致，每项大于 0、合计 100，最多 20 列。指定列宽时，网页使用固定布局、较窄内边距，窄屏可横向滚动。可加 nowrap=3 让第 3 列保持不换行；不指定 widths 时沿用自动列宽。注释不显示在正文中；PDF 命令行导出仍使用共享的自动列宽规则。

在 Markdown 中指定图片尺寸

在 Markdown 图片后紧接尺寸属性，使用 Pandoc 风格的 {width=… height=…}；普通行内代码和代码块里的示例不会执行：

![架构图](assets/architecture.svg){width=80%}
![字段图](assets/fields.svg){width=640 height=auto}
![局部细节](assets/detail.png){width="480px" height="240px"}
  • width 和 height 可分别省略；裸数字按 px 解释，也支持 %、px、em、rem、vw、vh、pt、cm、mm、in 和 auto。
  • 百分比宽度以正文容器为基准。常用 width=100% height=auto，按正文宽度等比显示。
  • 同时指定宽高时，图片按等比方式放入指定尺寸框；网页宽度最多为正文容器宽度。
  • 未指定尺寸的图片沿用站点默认样式。尺寸配置控制网页显示，PDF 仍按共享导出规则限制最大尺寸。
  • 网页所有图默认水平居中（与 PDF 导出"独立图片水平居中"口径一致）：mermaid 图（.mermaid flex 居中）与独占一个段落的图片（p:has(> img:only-child)）由 plugins/fig-refs/assets/figs.css 的共享规则居中；与文字混排的行内小图不居中。
  • 不用改 SVG 的文字或比例来弥补网页尺寸；位字段、结构示意等适合保留为可编辑 SVG。Mermaid 用于计算流程、数据流与时序，模型架构优先用论文截图或 SVG。

修改与 TODO 备注

用短的内联备注标出需要修改或待补充的位置。xxedit 插件使用浅灰底色：修改说明为蓝色文字，TODO 为橙色文字。

\xxedit{这里改为先介绍概念，再解释结构。}
\xxtodo{补充 rknpu 0.9.8 的实机结果。}
\xxedit{TODO: 核对寄存器字段。}

示例：修改 调整 定义 与行内公式 xix_{i}。 TODO 补充 来源链接。

  • 备注正文支持同一行内的加粗、链接、行内公式和引用编号。
  • 用成对花括号包住内容；公式和代码中的嵌套花括号会保留。备注写在同一行，不使用多段落内容。
  • xxedit 内容以 TODO: 开头时也采用 TODO 样式；xxtodo 是专用的待办写法。
  • 代码块、行内代码与转义的命令保持字面形式。长的多段提示使用既有 Hints，而不是拆开备注的花括号。

论文原文悬停框（quote-pop）

正文里需要“凝练中文介绍 + 原文收进悬停框”时（论文笔记常见），用 🗨（U+1F5E8）开头的引用块标记原文：首行是可见标签，空一行后写原文（每段一段，悬停时按引用块排版）：

1. **3.1 Little Builtin [Parsimony]**:凝练介绍……
   > 🗨 论文原文(§II)
   >
   > The system is based on a minimal number of fundamental concepts…
   >
   > A success criterion for customization is…
  • 由本地插件 plugins/quote-pop/ 在 page 钩子转成悬停触发器：触发器自动迁移到前一段落的文字末尾，像超链接一样行内显示（虚线下划线、与正文同字号），不单独占一行；正文悬停 / 键盘聚焦时以浮动卡片展开。原文里的引用上标、行内代码不受影响；弹出的段落转成 <span class="quote-pop-para"> 块显示，嵌套合法。
  • 🗨 不是 Hints 的 emoji，两种块互不干扰；Github / VSCode 预览与 PDF 导出会降级为普通引用块，全文可见。
  • ⚠️ HonKit 会把只隔一个空行的两个引用块合并成一个，因此 🗨 引用块（含 Hints）上下相邻兄弟不能是引用块，中间要有普通段落、标题、图片或列表项隔开；放进列表项时缩进 3 空格对齐 1. 之后。
  • 样式变量（--qpp-*）集中在 plugins/quote-pop/assets/quote-pop.css，不为一页手写局部 CSS。

公式（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

PDF 导出统一使用 Pandoc + XeLaTeX。单篇笔记通过固定脚本导出，默认生成到 outputs/；分类入口 README.md 采用分类名作为 PDF 文件名：

npm run pdf:page -- content/hardware/on-device-npu/kernel-fusion/README.md --toc

# 指定输出位置；--toc 可省略
npm run pdf:page -- content/writing-guide.md outputs/writing-guide.pdf

# 按 SUMMARY.md 顺序导出整本知识库，包含 Mermaid 图
npm run pdf

版式由 scripts/pdf/ 集中维护，无需修改笔记或每次重写导出参数：

  • 页面：A4，四边页边距 20 mm，正文使用 11 pt 中文字体。
  • 表格：每个表格必须在上方提供 > **表 N｜标题**，按文内首次出现顺序连续编号；表题与表格开头一起分页。按各列内容长度自动分配正文宽度，单元格自动换行；跨页重复表头。表格内的小图标默认与文字同高。
  • 独立图片：默认水平居中，宽度不超过正文宽度（170 mm），高度不超过正文区高度的 65%（约 167 mm），保持原始宽高比；紧随图片的中文图注与图片一起分页。
  • 图注与表注：使用 9.5 pt 深灰文字，编号与标题保留加粗，与正文留出间距。可沿用 > **图 1｜标题**……，表注同样写作 > **表 1｜标题**……；也支持不带引用块的 **表 1｜标题**……。
  • 链接与代码：长 URL 和代码块允许换行。

本机需安装 Pandoc、TeX Live/MacTeX；导出含 SVG 的笔记还需要 rsvg-convert（brew install librsvg）。

© 2026 Yang Huan · yanghuan9812@qq.com

results matching ""

    No results matching ""