id: documentation-style-guide title: 中文文档写作指南 keywords:
本文档是 Apache APISIX 中文文档的贡献指南,适用于为 APISIX 贡献中文文档的开发者,贡献者应遵循此文档以确保文档一致性。
要了解关于贡献的更多信息,请参考代码贡献流程。
:::note 注意
如果部分内容翻译后没有必要或者表达无意义,请根据上下文进行调整或删改。纯机翻没有意义,文档需要给予阅读者清晰明确的指引,而不是毫无意义的文字。
:::
2+3=5
。&
代替和
,/
代替或
。请参考一般注意事项了解更多信息。的
、地
、得
。在介绍中引用项目和引用项目社区时,使用 Apache APISIX 而不是 APISIX。
在文档中引用项目时,请使用 APISIX。
APISIX 特定的组件名称,如 Plugin、Route、Service 和 Consumer 等组件名称始终保持首字母大写。如果是表示概念则使用英文书写,如果表示一个实体(例如:创建一个路由),则使用中文名称。
必要时使用正确的首字母缩略词,例如:
✅ | ❌ |
---|---|
URL | url |
API | api |
APISIX Dashboard | Apisix dashboard |
gRPC | GRPC/grpc |
NGINX | Nginx |
如不清楚某些词汇到底应该以哪种形态出现,请及时使用搜索引擎进行查询。
关于 Markdown 使用指南,请参考 Markdown 基本要素
标题和副标题应当是有意义且简短概括的,不要出现「短句」来充当标题的现象。
必要时请使用 Docusaurus 提供的高级功能:
使用代码块显示代码。
./conf/config.yaml
)。在解释代码时使用行高亮提高使用者的注意力。$ cd Desktop
应修改为 cd Desktop
。使用 admonitions 突出显示重要信息。以下是每个 admonitions 的使用场景:
示例如下:
::note 注意 为用户提供基于其他内容的额外提示。 :::
请使用表格描述恰当的内容。
请正确使用标点符号。在中文文档中,请使用中文标点符号。
空格规范
jwt-auth
插件,你需要创建一个 Route。在 Markdown 文件中请使用相对路径而不是绝对路径。
如有多条类似内容进行描述时,请使用列表形式让描述更加清晰。
链接
对于需要在代码或者文本中表示一个变量的,请使用${变量名称}
。
如果一个值表示的是字符串,请使用"1"
。如果表示的是一个数值,请使用1
。
目前,Apache APISIX 官网的文档目录如下所示。如果要创建新文档,请选择文档写作时所用语言的 latest
文件夹中创建一个新文件。
/docs ├── assets │ ├── images │ │ ├── xxxxx.png │ └── other │ └── xxxxx.xxx ├── en │ └── zh | └── latest | ├── doc1.md │ └── folder │ └── doc2.md │ └── folder2 │ └── doc3.md │
配置文件位于 /docs/<locale>/latest/config.json
中,其中 locale 表示区域设置代码(语言)。有关详细信息,请参考本地语言。请注意,语言环境全部都是小写。
您可以从 Docusaurus 文档中了解有关侧边栏的更多信息。
{ "version": 2.3, "sidebar": [ // The left sidebar of the APISIX website { "type": "doc", "id": "doc2" // id is the filename of the md file }, { "type": "category", // category is a collapsed column, nestable "label": "folder", "items": [ { "type": "doc", "id": "folder/doc2" }, { "type": "category", "label": "folder2", "items": [ "folder2/doc3" ] } ] }, { "type": "link", "label": "CHANGELOG", "href": "https://github.com/apache/apisix/blob/master/CHANGELOG" } ] }
如需在本网站【文档-Apache APISIX】下添加技术文档(插件类文档),可参考以下内容架构:
jwt-auth
。