如何更新文档

运维人员通过修改仓库中的 Markdown 文件更新网页内容，通常只需编辑 docs/ 目录。

1. 编辑哪些文件

路径	用途
`docs/*/.md`	产品资料正文（主要修改这里）
`docs/**/_category_.json`	侧边栏中文名称与排序
`src/data/products.js`	产品速查数据（型号、别名、关键规格、资料页清单）
`src/data/docsIndex.js`	站内搜索的文档索引（改完文档建议重新生成，见第 6 节）
`static/files/<产品>/`	Word / PDF 等附件原件，供客户下载（见第 7 节）
`static/img/`	图片等静态资源

不要随意修改 src/、docusaurus.config.js 等站点代码，除非有开发同事配合。

2. 产品资料的组织方式（重要）

一个产品 = docs/products/ 下的一个目录，页面按用户的任务拆分，不要写成一份超长文档：

docs/products/tp1110/
  _category_.json         # 侧边栏名称与排序
  index.md                # 产品概述：一眼看懂是什么 + 规格摘要 + 导航
  quickstart.md           # 5 分钟跑通：30 秒版命令 + 完整开局流程
  modes.md                # 三种通讯模式怎么选
  at-commands.md          # AT 指令总表（当索引用）
  rf-parameters.md        # 参数取值范围与对照表
  frequency-table.md      # 频点 0~499 完整对照表（纯查询页）
  troubleshooting.md      # 返回码与故障排查

每页开头用 front matter 写清 sidebar_label 与 description，客户更容易看懂、搜索也更容易命中：

---
sidebar_label: 射频与串口参数
sidebar_position: 5
description: TP1110 射频与串口参数对照表：频点、符号率、发射功率、地址、波特率。
keywords:
  - TP1110 频点
  - 符号率
---

左侧文档侧边栏按资源中心的三个板块拆分，各页只显示所属板块的目录： docs/products/（产品与资料）、docs/ops/ 与 docs/intro.md（文档指南）、 docs/upload-*.md（资料上传）。新文档放进对应目录即可出现在正确板块，结构调整请改 sidebars.js。

3. 本地预览（推荐）

在仓库根目录执行：

npm start

浏览器打开提示地址（默认 http://localhost:3000），修改 MD 后保存即可热更新查看效果。

4. 生产编译

确认内容无误后：

npm run build
npm run serve

npm run build：生成静态站点到 build/ 目录
npm run serve：在本地预览构建结果

将 build/ 目录交付给 Web 服务器托管即可（具体部署方式由环境决定）。

⚠️ 站点配置为 onBrokenLinks: 'throw'：任何一个内部链接写错都会让编译直接失败。拆页或改名后，务必检查所有 ./xxx.md 链接与实际文件名一致。

5. 新增产品文档

在 docs/products/ 下新建产品目录（建议用产品型号小写，如 tp1110/）；
添加 _category_.json（中文标签 + position）和上面那组 .md 文件；
在 src/data/products.js 的 products 数组里加一条记录（型号、别名、keySpecs、docs.links、keywords），/products 速查页与搜索的「产品优先」都读这份数据；
执行 node scripts/build-search-index.mjs 重新生成 src/data/docsIndex.js；
npm start 检查侧边栏与页面、试搜一下新型号，再 npm run build 确认无断链。

6. 站内搜索（产品优先 + 文档兜底）

产品资料页的搜索入口只在该场景出现（进入 /docs 后的任意页面），它查两份数据：

数据	文件	作用
产品层	`src/data/products.js`	型号、别名、分类、关键规格、应用场景、资料页标题 → 排在结果最前面
文档层	`src/data/docsIndex.js`	每页一个条目，含页面标题、各章节标题、正文摘录 → 兜底结果，可直达章节锚点

改了 docs/ 下的正文或新增页面后，重新生成文档索引：

node scripts/build-search-index.mjs

脚本会扫描 docs/（自动跳过 sample-device-* 与 _category_.json），覆盖写入 src/data/docsIndex.js。如果环境里没有 Node，也可以直接手工编辑该文件：每个页面一个对象，slug 用页面真实路径（含 /docs 前缀），sections 里每个 ##/### 标题一条，body 写 60~140 字的纯文本摘录（别写 Markdown 符号）。

搜索匹配规则（src/utils/search.js）：

归一化：小写、去掉空格与 - _ /，所以 tp 1110、TP-1110、470-110 都能命中；
每个关键词单独计分，命中字段权重：型号 > 别名/分类 > 关键规格 > 关键词 > 摘要 > 页面标题；
查询词按空格/顿号切分，多个词时全部命中会额外加分（470 无线 这种组合也能查）。

7. 附件：把编辑好的 Word / PDF 放进产品资料

原则：网页正文用 Markdown，Word / PDF 只作为「固定版本的导出稿」提供下载。 Word 是二进制文件，Docusaurus 只会把它当附件发布：站内搜索搜不到里面任何内容，手机/平板上必须先下载再看，也没法做章节锚点和链接引用。所以不要让它成为唯一的内容载体。

7.1 文件放哪里

static/files/<产品 id>/
  TP1110-UserManual-v1.2-20260214.docx
  TP1110-UserManual-v1.2-20260214.pdf

路径即 URL：static/files/tp1110/xxx.docx → 站点根路径 /files/tp1110/xxx.docx，构建时自动拷进 build/；
文件名用 ASCII 字母数字与 -，带上版本号和日期，别用空格与中文（中文也能用，但 URL 编码后很难看、转发容易断）；
更新时新增版本、不要覆盖旧版本（客户可能已经引用过旧链接）。

7.2 登记到产品数据（页面自动出现下载入口）

编辑 src/data/products.js，在对应产品的 downloads 数组里加一条：

downloads: [
  {
    label: 'TP1110 用户手册（Word 版）',
    href: '/files/tp1110/TP1110-UserManual-v1.2-20260214.docx',
    format: 'word', // word | pdf | excel | zip
    size: '2.4 MB',
    version: 'v1.2',
    date: '2026-02-14',
    note: '可打印 / 离线查阅',
  },
],

登记后，产品资料页（docs/products/<id>/index.md 结尾的 <Downloads productId="…" />）与「产品速查」页会同时出现下载入口，附件名称也会进入搜索关键词（客户搜「手册」也能命中该产品）。 downloads 为空数组时下载区完全不渲染，不会留下空标题。

附件用的是普通 <a href> 链接，不参与 onBrokenLinks 校验：文件名写错不会让构建失败，而是变成 404。登记后请点一下确认能下载。

7.3 需要正文上网时：Word 转 Markdown

不要直接粘贴 Word 的富文本，先转成 Markdown 再清洗：

# 方案一：pandoc（推荐，需自行安装）
pandoc -f docx -t gfm --wrap=none -o docs/products/tp1110/_draft.md "手册.docx"

# 方案二：仓库自带脚本（只用 Python 标准库，无需安装任何依赖）
python scripts/docx-to-md.py "手册.docx" -o docs/products/tp1110/_draft.md

转换后必须人工过一遍：

标题层级改成 ## / ###（页面大标题只留一个 #）；
表格收窄到能看（超宽表格拆开或改成列表）；
图片存到 static/img/ 再引用，不要留 Word 里的内嵌图；
AT 指令与参数一律用反引号包起来，例如 AT+SEND=<addr>,<len>,<data>；
收敛完成后并入正式页面，并删掉 _draft.md——_ 开头的文件不会进侧边栏，也不会进搜索索引。

7.4 网页导入台：拖入 .docx，按大章节自动分层

如果手册本身就是结构规范的 Word / WPS 文档（用「标题 1」当章），可以直接用导入台一键分层，不用手工复制粘贴。

npm run import:ui        # 启动本地导入台，浏览器打开 http://127.0.0.1:3100

流程：拖入 .docx → 选「大章节级别」→ 逐页预览生成的 Markdown → 点「确认写入 docs/」。

命令行等价用法（默认只预览，不加 --commit 不动 docs/）：

npm run import:docx -- "手册.docx" --product tp1110 --chapter-level 1
npm run import:docx -- "手册.docx" --product tp1110 --chapter-level 1 --commit

规则与行为：

大章节级别 N（默认自动猜、可手工指定）决定怎么切页：每个 N 级标题 → 一个页面文件；页面内 N+1 级标题渲染为 ##，再下一级为 ###；
章节标题之前的开头文字超过 40 字时，单独生成 00-文档说明.md；文档大标题（Title 样式）不单独成页；
自动补齐 front matter（sidebar_label / sidebar_position / description）；
自动做 MDX 安全化：< > { } 要么包成行内代码，要么实体化，避免 npm run build 因 MDX 语法报错；
表格转 Markdown，图片从 word/media 抽出写到 static/img/<产品 id>/ 并改好引用；
写入前把同名旧文件备份到 docs/products/<产品 id>/_backup-<时间戳>/，预览产物在 .import-preview/<产品 id>/（两者都已加进 .gitignore）；
导入台只监听 127.0.0.1，用完 Ctrl+C 关闭。

导入后仍需人工：超宽表格收窄、合并单元格还原、给「产品概述」页（index.md）补一句话与规格摘要、核对 AT 指令是否需要加反引号。

收尾两件事：

npm run search:index     # 重建站内搜索索引（新页面才搜得到）
npm start                # 本地预览；发布用 npm run build

只吃 .docx。旧版 .doc 与 WPS 私有 .wps 是二进制私有格式，读不了——请在 Word / WPS 里「另存为 .docx」后再上传。

8. Markdown 小提示

文件头部可写 front matter，例如：

---
sidebar_label: 快速上手
sidebar_position: 2
---

sidebar_position 控制同一目录内的排序；
文档内的章节标题从 ## 开始写（页面大标题由 # 标题 提供一次即可）；
指令、参数一律用反引号包起来，例如 AT+FREQ=400，避免渲染异常。

9. 下载中心：给访客提供文件下载

「下载中心」页面（/downloads）集中展示可下载的资料文件，访客点击「立即下载」即可保存到本地。

上传方式（二选一，效果相同）：

网页面板（推荐）：打开「资源中心 → 上传下载文件」，填分类、选文件、授权仓库根目录后上传，清单自动重建，刷新 /downloads 即可见；
手动放文件：按下面的目录结构把文件放进仓库，再重新构建。

static/files/downloads/
├── 产品手册/          ← 一级子文件夹名 = 页面上的分类名
│   └── TP1110产品手册.pdf
└── 配置工具/
    └── 配置上位机.zip

把 PDF、Word、压缩包等文件放进 static/files/downloads/<分类>/（分类文件夹不存在就新建一个，文件名即页面上展示的标题）；
重新 npm run build（本地预览则重启 npm start）——文件名、分类、大小、更新时间都会自动登记进 src/data/downloadsIndex.js，不需要改任何代码；
直接放在 downloads/ 根目录（不建子文件夹）的文件会归入「其他」分类。

删除文件可在「上传下载文件」面板的文件列表里点「删除」，或直接从文件夹里删掉再重新构建；页面列表按更新时间倒序排列。

特殊分类「使用工具」：上传到该分类的文件（如桌面版工具 exe）除了出现在下载中心，还会自动展示在「使用工具」页面的「桌面版工具下载」区块，供访客直接下载。

如何更新文档

1. 编辑哪些文件​

2. 产品资料的组织方式（重要）​

3. 本地预览（推荐）​

4. 生产编译​

5. 新增产品文档​

6. 站内搜索（产品优先 + 文档兜底）​

7. 附件：把编辑好的 Word / PDF 放进产品资料​

7.1 文件放哪里​

7.2 登记到产品数据（页面自动出现下载入口）​

7.3 需要正文上网时：Word 转 Markdown​

7.4 网页导入台：拖入 .docx，按大章节自动分层​

8. Markdown 小提示​

9. 下载中心：给访客提供文件下载​