核心概念

目录约定

docs/
├── index.md              # 中文首页
├── guide/                # 指南（概念、上手）
├── products/             # 产品文档
├── changelog.md          # 更新日志
├── en/                   # 英文版，结构与上面完全一致
├── th/                   # 泰文版，结构与上面完全一致
└── public/               # 图片等静态资源

核心约定：三个语言目录的文件路径一一对应。 这不仅是整洁问题——自动化翻译脚本靠路径配对来判断哪些文档缺译、哪些已过期。

内容分层

层级	回答的问题	写法
指南	这是什么？为什么用它？	叙述式，可以有观点
产品文档	具体怎么配？参数是什么？	表格 + 代码块，精确无歧义
更新日志	变了什么？影响谁？	按版本倒序，标注破坏性变更

写作规范

front-matter 必填

---
title: 页面标题          # 用于浏览器标签和搜索结果
description: 一句话摘要  # 用于 SEO 和搜索预览
---

术语统一

同一概念在全站必须用同一个词，中英泰三语各自固定译法。术语表维护在 scripts/glossary.json，自动翻译时会强制套用。

可用的提示框

提示

补充信息、技巧。

注意

容易踩的坑。

危险

会造成数据丢失或不可逆后果的操作。

图片

放在 docs/public/ 下，引用时用绝对路径：

![架构图](/images/architecture.png)

文件命名

图片文件名用纯 ASCII（如 arch-overview-v2.png），不要用中文——部分 CDN 和浏览器对中文路径处理不一致。

版本与变更

任何对外有影响的改动都要在更新日志留痕。改了中文版而英文版未同步时，自动化巡检会标记该页「翻译过期」。