[Fix][Doc] fix doc tip style and add document format specification (#…

…8378)
apache · Dec 25, 2024 · 9f02943 · 9f02943
1 parent bd89d84
commit 9f02943
Show file tree

Hide file tree

Showing 9 changed files with 70 additions and 10 deletions.
diff --git a/docs/en/connector-v2/sink/Clickhouse.md b/docs/en/connector-v2/sink/Clickhouse.md
@@ -84,7 +84,7 @@ Option descriptions:
 
 ### save_mode_create_template
 
-Automatically create Doris tables using templates.  
+Automatically create Clickhouse tables using templates.  
 The table creation statements will be generated based on the upstream data types and schema. The default template can be modified as needed.
 
 Default template:
@@ -118,7 +118,7 @@ The following placeholders can be used:
 
 - `database`: Retrieves the database from the upstream schema.
 - `table_name`: Retrieves the table name from the upstream schema.
-- `rowtype_fields`: Retrieves all fields from the upstream schema and automatically maps them to Doris field descriptions.
+- `rowtype_fields`: Retrieves all fields from the upstream schema and automatically maps them to Clickhouse field descriptions.
 - `rowtype_primary_key`: Retrieves the primary key from the upstream schema (this may be a list).
 - `rowtype_unique_key`: Retrieves the unique key from the upstream schema (this may be a list).
 

diff --git a/docs/en/contribution/docs-format-specification.md b/docs/en/contribution/docs-format-specification.md
@@ -0,0 +1,28 @@
+# Docs Format Specification
+## Admonitions
+
+We have special admonitions syntax by wrapping text with a set of 3 colons, followed by a label denoting its type. When you want to emphasize the content, it is recommended to use admonitions.
+
+In use, the following specifications need to be followed:
+
+- Tip: mainly used for operational  tips and tricks.
+
+- Note: used for more details and explanations.
+
+- Caution: used for warnings and precautions.
+
+You may also specify an optional title. Here are the examples of admonitions syntax:
+
+```Markdown
+:::tip Tip
+Some content with tips
+:::
+
+:::info Note
+Some content with explanations
+:::
+
+:::caution Warning
+Some content with precuations and warnings
+:::
+```
diff --git a/docs/sidebars.js b/docs/sidebars.js
@@ -232,7 +232,8 @@ const sidebars = {
                 'contribution/new-license',
                 'contribution/coding-guide',
                 'contribution/contribute-transform-v2-guide',
-                'contribution/how-to-create-your-connector'
+                'contribution/how-to-create-your-connector',
+                'contribution/docs-format-specification'
             ],
         },
         "faq"

diff --git a/docs/zh/connector-v2/sink/Clickhouse.md b/docs/zh/connector-v2/sink/Clickhouse.md
@@ -67,7 +67,7 @@
 
 在开启同步任务之前，针对现有的表结构选择不同的处理方案。
 选项介绍：  
-`RECREATE_SCHEMA` ：表不存在时创建，表保存时删除并重建。
+`RECREATE_SCHEMA` ：表不存在时创建，表保存时删除并重建。  
 `CREATE_SCHEMA_WHEN_NOT_EXIST` ：表不存在时会创建，表存在时跳过。  
 `ERROR_WHEN_SCHEMA_NOT_EXIST` ：表不存在时会报错。  
 `IGNORE` ：忽略对表的处理。
@@ -83,7 +83,7 @@
 
 ### save_mode_create_template
 
-使用模板自动创建Doris表，
+使用模板自动创建 Clickhouse 表，
 会根据上游数据类型和schema类型创建相应的建表语句，
 默认模板可以根据情况进行修改。
 
@@ -119,7 +119,7 @@ CREATE TABLE IF NOT EXISTS  `${database}`.`${table}` (
 
 - database：用于获取上游schema中的数据库。
 - table_name：用于获取上游schema中的表名。
-- rowtype_fields：用于获取上游schema中的所有字段，自动映射到Doris的字段描述。
+- rowtype_fields：用于获取上游schema中的所有字段，自动映射到 Clickhouse 的字段描述。
 - rowtype_primary_key：用于获取上游模式中的主键（可能是列表）。
 - rowtype_unique_key：用于获取上游模式中的唯一键（可能是列表）。
 

diff --git a/docs/zh/connector-v2/sink/ClickhouseFile.md b/docs/zh/connector-v2/sink/ClickhouseFile.md
@@ -10,7 +10,7 @@
 
 - [ ] [精准一次](../../concept/connector-v2-features.md)
 
-:::小提示
+:::tip 提示
 
 你也可以采用JDBC的方式将数据写入Clickhouse。
 

diff --git a/docs/zh/connector-v2/sink/Hive.md b/docs/zh/connector-v2/sink/Hive.md
@@ -6,7 +6,7 @@
 
 将数据写入 Hive。
 
-:::提示
+:::tip 提示
 
 为了使用此连接器，您必须确保您的 Spark/Flink 集群已经集成了 Hive。测试过的 Hive 版本是 2.3.9 和 3.1.3。
 

diff --git a/docs/zh/connector-v2/sink/LocalFile.md b/docs/zh/connector-v2/sink/LocalFile.md
@@ -6,7 +6,7 @@
 
 将数据输出到本地文件。
 
-:::提示
+:::tip 提示
 
 如果你使用的是 spark/flink，为了使用此连接器，你必须确保你的 spark/flink 集群已集成 hadoop。已测试的 hadoop 版本是 2.x。
 

diff --git a/docs/zh/connector-v2/source/Hive.md b/docs/zh/connector-v2/source/Hive.md
@@ -6,7 +6,7 @@
 
 从 Hive 读取数据。
 
-:::提示
+:::tip 提示
 
 为了使用此连接器，您必须确保您的 Spark/Flink 集群已经集成了 Hive。测试过的 Hive 版本是 2.3.9 和 3.1.3。
 

diff --git a/docs/zh/contribution/docs-format-specification.md b/docs/zh/contribution/docs-format-specification.md
@@ -0,0 +1,31 @@
+# 文档格式规范
+## 注释说明
+
+注释说明在技术文档中起强调作用。在使用中，需遵循以下规范：
+
+- 根据提示内容，可以将注释分为“提示”、“备注”、“注意”三类。注释框标题与使用场景请遵循以下规范：
+
+  - 提示：主要用于操作技巧提示
+
+  - 备注：用于补充内容补充解释
+
+  - 注意：用于操作、注意事项警告
+
+- 提示框内容可以使用有序、无序、代码块
+
+
+下面是 Markdown 文档中注释说明示例：
+
+```Markdown
+:::tip 提示
+这是一条提示
+:::
+
+:::info 备注
+这是一条备注
+:::
+
+:::caution 注意
+这是一条注意事项
+:::
+```