add docs templates for reference (#7569)

CONTRIBUTING.md

@@ -78,7 +78,7 @@ TiDB 中文文档的日常更新特别活跃，相应地，[TiDB 英文文档](h
     - [常用 bot 命令](#常用-bot-命令)
 - [PingCAP 中文文档风格指南](/resources/pingcap-style-guide-zh.pdf)
 - [PingCAP 中英术语表](https://shimo.im/sheets/tTRyydP8Xkdv8yxq/MODOC)
-- [TiDB 中文用户文档模板](/resources/tidb-docs-template-zh-v1.0.pdf)
+- [TiDB 中文用户文档模板](/resources/doc-templates)
 - [必须遵循的 Markdown 规范](#必须遵循的-markdown-规范)
 - [代码注释规范](https://github.com/pingcap/community/blob/master/contributors/code-comment-style.md)
 - 图片风格：[Figma 快速上手教程](/resources/figma-quick-start-guide.md)

explore-htap.md

@@ -100,5 +100,5 @@ TiFlash 部署完成后并不会自动同步数据，你需要指定需要同步
 
 ## 探索更多
 
-- 如果要查看 TiFlash 版本，以及 TiFlash 重要日志及系统表，请参阅 [TiFlash 集群运维](/tiflash/maintain-tiflash.md)。
+- 如果要查看 TiFlash 版本、TiFlash 重要日志及系统表，请参阅 [TiFlash 集群运维](/tiflash/maintain-tiflash.md)。
 - 如果需要移除某个 TiFlash 节点，请参阅[缩容 TiFlash 节点](/scale-tidb-using-tiup.md#缩容-tiflash-节点)。

quick-start-with-htap.md

@@ -201,4 +201,4 @@ limit 10;
 
 - [TiDB HTAP 形态架构](/tiflash/tiflash-overview.md#整体架构)
 - [深入探索 HTAP](/explore-htap.md)
-- [使用 TiFlash](/tiflash/use-tiflash.md)  
+- [使用 TiFlash](/tiflash/use-tiflash.md)

resources/doc-templates/template-concept.md

@@ -0,0 +1,65 @@
+---
+title: xxx（与文档一级标题保持一致）
+summary: xxx（一句话介绍该文档的主要内容，请尽可能多地包含本文的关键词，这有利于搜索引擎优化）
+---
+
+# 文档标题（与文首 metadata 中的 title 名称保持一致）
+
+模板说明：
+
+- 本文档为概念介绍类模板，主要包含概念和说明信息。你可直接复制使用，并删除模板中不需要的说明。该类文档示例：[TiDB Binlog](/tidb-binlog/tidb-binlog-overview.md)。
+- 对于新文档，请在 TOC.md 中合适的位置加目录（思考用户最有可能在目录哪里找文档）。
+- 文内标题级别不可跳级，尽量避免使用五级标题。
+
+[必须]第一段对该文档进行概括性介绍，几句话即可。
+
+对于某些概念和定义，你可在本段落用一到三句话介绍这些核心名词（类似定义）。
+
+## 二级标题 1
+
+以整体架构为例，你可以先一两句话介绍该架构包含哪些核心组件，再提供对应的架构图。
+
+<!--![架构图](图片相对链接)-->
+
+图片的大小请控制在 300 KB 以内，建议使用 .png 或.jpg 格式的图片，不支持使用 .gif 和 .svg 格式的图片。
+
+架构图下面可以提供通过无序列表的形式分别介绍各组件。
+
+这里可以简单介绍一下工作原理，或者融入到以上的组件介绍中。
+
+### 三级标题 1 （可选，如组件名称）
+
+如果文档内容较复杂，也可采用三级标题的形式。
+
+### 三级标题 2
+
+xxx
+
+## 二级标题 2（可选，如“主要特性/功能介绍/使用限制”）
+
+对于概念简介类文档，本标题下可介绍用户在使用前应了解的信息，如“主要特性/功能介绍/使用限制”等。如果不需要提供这类信息，可略去本标题。
+
+如果需要添加注意或警告事项，需严格遵循以下格式。
+
+> **警告：**
+>
+> 对于可能会给用户带来风险的信息，例如系统可用性、安全、数据丢失等，请使用警告。例如：当前该功能为实验特性，不建议在生产环境中使用。
+
+> **注意：**
+>
+> 对于一般性的提示内容，请使用注意。例如：读取历史数据时，即使当前数据的表结构相较于历史数据的表结构已经发生改变，历史数据也会以当时的历史表结构来返回。
+
+如果注意或警告事项嵌套在列表内，需要缩进四个空格（官网文档中的缩进建议统一采用四个空格，以避免 PingCAP 官网显示错乱）。
+
+## 探索更多
+
+本小节给出更多用户可能想看到的相关文档，如：
+
+- 如果需要查看 TiFlash 版本、TiFlash 重要日志及系统表，请参阅 [TiFlash 集群运维](/tiflash/maintain-tiflash.md)。
+- 如果需要移除某个 TiFlash 节点，请参阅[缩容 TiFlash 节点](/scale-tidb-using-tiup.md#缩容-tiflash-节点)。
+
+或直接给出用户接下来可能感兴趣的文档，如：
+
+- [TiDB HTAP 形态架构](/tiflash/tiflash-overview.md#整体架构)
+- [深入探索 HTAP](/explore-htap.md)
+- [使用 TiFlash](/tiflash/use-tiflash.md)

resources/doc-templates/template-new-feature.md

@@ -0,0 +1,108 @@
+---
+title: 特性名称（与文档一级标题保持一致）
+summary: xxx（一句话介绍该文档的主要内容，请尽可能多地包含本文的关键词，这有利于搜索引擎优化）
+---
+
+# 特性名称（与文首 metadata 中的 title 名称保持一致）
+
+模版说明：
+
+- 本文档为新增功能类模板，同时包含功能概念和使用信息。你可直接复制使用，并删除模板中不需要的说明。该类文档示例：[聚簇索引](/clustered-indexes.md)。
+- 功能一定要有对应的功能介绍文档。
+- 如果新增功能与其他厂商相同或相似，切忌完全照搬其他厂商文档中的示例。
+- 请在 TOC.md 中合适的位置加目录（思考用户最有可能在哪里找文档）。
+- 文内标题级别不可跳级，尽量避免使用五级标题。
+
+> **警告：**（可选）
+>
+> 当前该功能为实验特性，不建议在生产环境中使用。
+
+本文档介绍 XXX 的使用场景、使用方法、使用限制和使用该功能的常见问题。
+
+XXX 是什么。用于做什么，通过使用该特性，可以实现/优化什么（即下个小标题要叙述的使用场景的概括）。（实现细节或原理略写，或可考虑单独写成博客、参考指南）。
+
+如果需要添加注意或警告事项，需严格遵循以下格式。其中，“注意”为一般的提示，“警告”含义则为”不要这样做“。示例如下：
+
+> **注意：**
+>
+> 读取历史数据时，即使当前数据的表结构相较于历史数据的表结构已经发生改变，历史数据也会以当时的历史表结构来返回。
+
+> **警告：**
+>
+> 在集群中有多个 TiDB 实例时，如果表结构中有自增 ID，建议不要混用显式插入和隐式分配（即自增列的缺省值和自定义值），否则可能会破坏隐式分配值的唯一性。
+
+如果注意或警告事项嵌套在列表内，需要缩进四个空格（官网文档中的缩进建议统一采用四个空格，以避免 PingCAP 官网显示错乱）。
+
+## 使用场景
+
+使用场景非常重要。需要从用户的角度，介绍用户为什么要使用该特性、在什么场景下使用、能解决用户的什么问题。
+
+xxx 在以下场景中使用/有优势：
+
+- 无序列表
+- 无序列表
+
+### 具体场景一名称
+
+### 具体场景二名称
+
+## 前提条件（可选）
+
+如需使用表格，应注意表格必须有表头（即第一行），且表格后需空一行。
+
+| 条件 | 说明 |
+| :-- | :-- |
+| 条件 1 | 说明 1 |
+| 准备 xxx | 这里说明如何准备 xxx，可以给出参考文档的链接。 |
+| 确保 xxx | 这里说明如何能查看 xxx 是否符合条件。如果不符合条件，应该如何处理。 |
+
+## 使用方法/操作步骤
+
+TiDB 提供 x 种 xxx 的使用方法，分别是 xxx 方法 和 xxx 方法。
+
+在 xxx 情况下，为了 xxx, 推荐使用 xxx 方法。
+
+### 方法一名称 xxx
+
+1.方法一步骤 1
+1.方法一步骤 2
+1.方法一步骤 3
+
+### 方法二名称 xxx
+
+1.方法二步骤 1
+2.方法二步骤 2
+3.方法二步骤 3
+
+## 参数说明
+
+如果此特性主要一个新增的语法或命令，请使用表格呈现具体配置项或参数说明、默认值和示例等相关信息。使用表格时，应注意表格必须有表头（即第一行），且表格后需空一行。
+
+| 参数 | 说明 | 默认值 | 是否必填 | 示例 |
+| :-- | :-- | :-- | :-- | :-- |
+| xxx | xxx | xxx | xxx | xxx |
+
+## 使用限制
+
+这里列出使用限制。如果各个限制项之间没有顺序关系，推荐使用无序列表列出各项。
+
+## 兼容信息
+
+这里列出该特性的兼容性信息，通常包括与之前 TiDB 版本的兼容性信息，与 MySQL 的兼容性信息，或在不同架构或平台下的兼容性信息。
+
+## 常见问题（可选）
+
+如果内容较多，可以单独增加一篇常见问题文档。
+
+## 探索更多
+
+本小节给出更多用户可能想看到的相关文档，如：
+
+- 如果需要查看 TiFlash 版本、TiFlash 重要日志及系统表，请参阅 [TiFlash 集群运维](/tiflash/maintain-tiflash.md)。
+- 如果需要移除某个 TiFlash 节点，请参阅[缩容 TiFlash 节点](/scale-tidb-using-tiup.md#缩容-tiflash-节点)。
+
+或直接给出用户接下来可能感兴趣的文档，如：
+
+- [TiDB HTAP 形态架构](/tiflash/tiflash-overview.md#整体架构)
+- [深入探索 HTAP](/explore-htap.md)
+- [使用 TiFlash](/tiflash/use-tiflash.md)

resources/doc-templates/template-reference.md

@@ -0,0 +1,56 @@
+---
+title: xxx（与文档一级标题保持一致）
+summary: xxx（一句话介绍该文档的主要内容，请尽可能多地包含本文的关键词，这有利于搜索引擎优化）
+---
+
+# 文档标题（与文首 metadata 中的 title 名称保持一致）
+
+模板说明：
+
+- 本文档为参考手册类模板，主要包含命令、参数、选项等参考解释信息。你可直接复制使用，并删除模板中不需要的说明。该类文档示例：[TiDB 集群报警规则与处理方法](/alert-rules.md)。
+- 对于新文档，请在 TOC.md 中合适的位置加目录（思考用户最有可能在目录哪里找文档）。
+- 文内标题级别不可跳级，尽量避免使用五级标题。
+
+[必须]第一段对该文档进行概括性介绍，几句话即可。
+
+可采用类似“本文介绍……”的句型。
+
+## 二级标题 1（文内标题级别不可跳级，通常为大类的名称，或者直接是参数名）
+
+用一两句话简要介绍这一节的内容。
+
+### 三级标题 1（可选，如参数名）
+
+如需列举多个参数/配置项，可以使用无序列表（*/+/-）：
+
+- xxx：xxx
+- xxx：xxx
+- xxx：xxx
+
+### 三级标题 2
+
+xxx
+
+## 二级标题 2
+
+如果需要添加注意或警告事项，需严格遵循以下格式，其中，“注意”为一般的提示，“警告”含义则为”不要这样做“。示例如下：
+
+> **注意：**
+>
+> 读取历史数据时，即使当前数据的表结构相较于历史数据的表结构已经发生改变，历史数据也会以当时的历史表结构来返回。
+
+> **警告：**
+>
+> xxxxxxxxxxxxxx。
+
+如果注意或警告事项嵌套在列表内，需要缩进四个空格（官网文档中的缩进建议统一采用四个空格，以避免 PingCAP 官网显示错乱）。
+
+## 二级标题 3
+
+如需使用表格，应注意表格必须有表头（即第一行），且表格后需空一行。
+
+下表列出了具体配置项/参数的说明、默认值和示例等相关信息。
+
+| 参数 | 说明 | 默认值 | 是否必填 | 示例 |
+| :-- | :-- | :-- | :-- | :-- |
+| xxx | xxx | xxx | xxx | xxx |

resources/doc-templates/template-task.md

@@ -0,0 +1,126 @@
+---
+title: xxx（与文档一级标题保持一致）
+summary: xxx（一句话介绍该文档的主要内容，请尽可能多地包含本文的关键词，这有利于搜索引擎优化）
+category: xxx（如 how-to）
+---
+
+# 文档标题（与文首 metadata 中的 title 名称保持一致）
+
+模板说明：
+
+- 本文档为操作指南类模板，主要包含任务信息。你可直接复制使用，并删除模板中不需要的说明。该类文档示例：[TiDB 数据库快速上手指南](/quick-start-with-tidb.md)
+- 对于新文档，请在 TOC.md 中合适的位置加目录（思考用户最有可能在目录哪里找文档）。
+- 文内标题级别不可跳级，尽量避免使用五级标题。
+
+[必须]第一段对该文档进行概括性介绍，几句话即可。
+
+可采用类似“本文介绍如何（使用）……部署……”的句型。
+
+## 二级标题 1（文内标题级别不可跳级，通常为“准备环境”、“前置检查”等）
+
+介绍在开始操作前需准备的软硬件环境，如机器、网络、软件版本等。
+
+## 第 1 步：xxx
+
+每一步内可以分小步骤，通常使用有序列表（ 1, 2, 3, … ）来标示顺序。
+
+1. xxx
+
+    这里如果有进一步的解释内容，请在前面空一行，并在本行首缩进四个空格。
+
+    如果需要添加注意或警告事项，需严格遵循以下格式。
+
+    > **警告：**
+    >
+    > 对于可能会给用户带来风险的信息，例如系统可用性、安全、数据丢失等，请使用警告。例如：请勿在备份前删除此文件，否则可能导致系统不可用。
+
+    > **注意：**
+    >
+    > 对于一般性的提示内容，请使用注意。例如：读取历史数据时，即使当前数据的表结构相较于历史数据的表结构已经发生改变，历史数据也会以当时的历史表结构来返回。
+
+    如果注意或警告事项嵌套在列表内，需要缩进四个空格（官网文档中的缩进建议统一采用四个空格，以避免 PingCAP 官网显示错乱）。
+
+2. xxx
+
+    如果有代码块，也需在代码块前空一行，并且比上一级缩进四个空格。如果代码块里的内容是用户需要复制的（比如可执行的 shell/bash 命令、SQL 语句等），需要在代码块前加入 {{< copyable "" >}}，例如：
+
+    {{< copyable "shell-root" >}}
+
+    ```bash
+    xxx
+    xxx
+    ```
+
+    预期输出：
+
+    ```bash
+    xxx
+    xxx
+    ```
+
+    如果输出中有 xxx 报错，请进行 xxx 排除报错。
+
+3. xxx
+
+    如果还有子项，如果子项之间有先后顺序关系，请使用有序列表（1, 2, 3, …）来标示顺序，如果子项之间没有先后顺序关系，请使用无序列表（+/-/*），同样注意比上一级缩进四个空格。
+
+    1. 子步骤 1
+    2. 子步骤 2
+    3. 子步骤 3
+
+    或
+
+    + 并列项描述
+    + 并列项描述
+    + 并列项描述
+
+4. xxx 如果此步骤涉及到某配置文件的更新，请给出此配置文件的详细位置，比如是在哪个节点的哪个位置，配置文档的名称是什么，并在配置文件中关键字段进行解释，方便用户理解。
+
+    ```toml
+    ### tidb-lightning 全局配置
+
+    [lightning]
+    # 用于拉取 web 界面和 Prometheus 监控项的 HTTP 端口。设置为 0 时为禁用状态。
+    status-addr = ':8289'
+
+    # 切换为服务器模式并使用 web 界面
+    # 详情参见“TiDB Lightning web 界面”文档
+    server-mode = false
+
+    # 日志
+    level = "info"
+    file = "tidb-lightning.log"
+    max-size = 128 # MB
+    max-days = 28
+    max-backups = 14
+    ```
+
+5. xxx
+
+    每一步骤后，最好提供查看/验证操作是否成功的方法，以便用户参考。
+
+## 第 2 步：xxx
+
+1. xxx
+
+    1. xxx
+    2. xxx
+
+2. xxx
+
+3. xxx
+
+## 第 3 步：xxx
+
+## 探索更多
+
+本小节给出更多用户可能想看到的相关文档，如：
+
+- 如果需要查看 TiFlash 版本、TiFlash 重要日志及系统表，请参阅 [TiFlash 集群运维](/tiflash/maintain-tiflash.md)。
+- 如果需要移除某个 TiFlash 节点，请参阅[缩容 TiFlash 节点](/scale-tidb-using-tiup.md#缩容-tiflash-节点)。
+
+或直接给出用户接下来可能感兴趣的文档，如：
+
+- [TiDB HTAP 形态架构](/tiflash/tiflash-overview.md#整体架构)
+- [深入探索 HTAP](/explore-htap.md)
+- [使用 TiFlash](/tiflash/use-tiflash.md)