feat: add markdown lint configuration and enhance documentation checks in workflows (#24)

Author: tomchon

.github/workflows/.markdownlint-cli2.jsonc

@@ -0,0 +1,20 @@
+/*
+ * An example .markdownlint-cli2.jsonc file
+ */
+{
+  // Disable some built-in rules
+  "config": {
+	"MD013": false, // line-length 禁止行长度限制
+	"MD024": false, // no-duplicate-heading 禁止重复标题
+	"MD029": false, // ol-prefix 列表前缀可以任意设置
+	"MD025": false, // single-title 同一文档只能有一个一级标题
+	"MD033": false, // no-inline-html 禁止行内HTML
+	"MD041": false, // first-line-heading 禁止第一行必须是标题
+	"MD046": {"style": "fenced"}, // code-fence-style 代码块使用围栏样式
+	"MD048": {"style": "backtick"}, // Code fence style 只允许用反引号 ``` 作为围栏
+	"MD052": false  // reference-links-image: 禁止引用链接和图片
+  },
+  "ignores": ["node_modules/**", "dist/**"] // 忽略路径
+// Fix any fixable errors
+//   "fix": true
+}

.github/workflows/check_docs.yaml

@@ -32,13 +32,13 @@ jobs:
       - name: Check Typos
         uses: crate-ci/typos@v1.31.1
         with:
-          files: 'docs/**/*.md'
+          files: 'docs/'
           config: .github/workflows/typos.toml
 
       - name: Check with AutoCorrect
         uses: huacnlee/autocorrect-action@v2
         with:
-          args: --lint docs/**/*.md
+          args: --lint docs/**/*.md docs/**/*.mdx
 
       - name: Report ReviewDog
         if: always()
@@ -47,7 +47,14 @@ jobs:
           REVIEWDOG_GITHUB_API_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         with:
           reviewdog: true
-          args: ./docs/**/*.md
+          args: ./docs/**/*.md ./docs/**/*.mdx
+      
+      - name: Check Markdown Lint Cli2
+        uses: DavidAnson/markdownlint-cli2-action@v20
+        with:
+          config: '.github/workflows/.markdownlint-cli2.jsonc'
+          globs: 'docs/**/*.md,docs/**/*.mdx'
+      
 
   build:
     needs:

docs/01-intro.md

@@ -10,7 +10,8 @@ TDengine Asset Intelligence（TDengine AI）是一物联网、工业数据管理
 
 ## 基本功能
 
-### TDengine AI 具有如下功能：
+### TDengine AI 具有如下功能
+
 1. 提供物模型，以经典的树状结构来管理企业运营中物理的或逻辑的 Element(元素）。
 2. 对任何元素，可以配置各种静态的、动态的属性，任何一个属性可以映射到数据库的某张表的某一列，而且配置目标值、极限值、位置、预测算法、物理单位、显示的小数点位数等各种元数据，实现数据的语境化（Contextulization)。
 3. 对任何一个元素，可以创建实时分析，建立可视化看板，或生成周期性报表，设置事件通知模板等。分析可以针对元素自身，也可以针对元素下辖的子元素集合。
@@ -22,35 +23,48 @@ TDengine Asset Intelligence（TDengine AI）是一物联网、工业数据管理
 9. 提供系统配置的版本管理，容许多个用户同时修改系统，便于协同。
 10. 提供单点登录、基于角色的权限控制等企业运营必要的安全特性。
 
-### 特别提示：
+### 特别提示
+
 1. TDengine AI 内部不保留任何时序数据，全部依赖外部的 TDengine 或其他数据库。但 TDengine AI 为支持数据字典和一些元数据的查询，会提供自己保存的二维表，也可以从外部关系库动态获得二维表。
 2. TDengine AI 只是一数据管理平台，帮助用户洞察系统的运行，不是完整的物联网或工业互联网平台，因此它不提供控制命令下发、设备连接管理、固件更新等功能。但它能与工业互联网平台无缝集成。
 3. TDengine AI 不提供企业管理所需的人员、排班、维修工单管理等功能，但支持通过 SDK 与这些系统实现无缝集成，或直接对接相关系统的数据库获取元数据。
 
 ## 应用场景
 
 TDengine AI 能广泛应用于物联网、工业等各个领域，它包括：
+
 1. 工业过程监控与优化
-  - 制造业：实时监控生产线设备状态（如温度、压力、振动等），优化生产效率，减少停机时间。
-  - 化工/石油石化：跟踪反应釜、管道、储罐的实时数据，确保工艺安全与能效。
-  - 电力与能源：管理发电机组、电网负荷、可再生能源（风电、光伏）的实时性能。
+
+- 制造业：实时监控生产线设备状态（如温度、压力、振动等），优化生产效率，减少停机时间。
+- 化工/石油石化：跟踪反应釜、管道、储罐的实时数据，确保工艺安全与能效。
+- 电力与能源：管理发电机组、电网负荷、可再生能源（风电、光伏）的实时性能。
+
 2. 设备健康与预测性维护
-  - 通过分析设备传感器数据（如振动、电流、温度），预测故障风险，避免突发停机。
-  - 航空、发电、轨道交通等关键设备的寿命周期管理。
+
+- 通过分析设备传感器数据（如振动、电流、温度），预测故障风险，避免突发停机。
+- 航空、发电、轨道交通等关键设备的寿命周期管理。
+
 3. 能源管理与可持续发展
-  - 实时监测水、电、气等资源消耗，识别节能机会（如建筑能效、工厂碳足迹）。
-  - 支持碳排放数据追踪，助力企业实现 ESG 目标。
+
+- 实时监测水、电、气等资源消耗，识别节能机会（如建筑能效、工厂碳足迹）。
+- 支持碳排放数据追踪，助力企业实现 ESG 目标。
+
 4. 基础设施与智慧城市
-  - 公用事业：水、气、电的实时监测，管网泄漏检测。
-  - 智慧建筑：楼宇自动化系统（HVAC、照明等）的实时数据整合。
-  - 交通基础设施：隧道、桥梁、高铁、地铁、机场等设施的实时监测与维护
+
+- 公用事业：水、气、电的实时监测，管网泄漏检测。
+- 智慧建筑：楼宇自动化系统（HVAC、照明等）的实时数据整合。
+- 交通基础设施：隧道、桥梁、高铁、地铁、机场等设施的实时监测与维护
+
 5. 生命科学与制药
-  - 生物制药生产监控，比如发酵与细胞培养过程、纯化与下游工艺
-  - 严格合规环境下（如 GMP）的批次生产监控，确保药品生产参数符合标准。
+
+- 生物制药生产监控，比如发酵与细胞培养过程、纯化与下游工艺
+- 严格合规环境下（如 GMP）的批次生产监控，确保药品生产参数符合标准。
+
 6. 数据中心与 IT 运维
-  - 监控服务器、网络设备的实时性能（CPU、内存、流量），优化资源分配。
-  - 数据中心的环境与能源监控
-  - 监控各种互联网服务的实时性能
+
+- 监控服务器、网络设备的实时性能（CPU、内存、流量），优化资源分配。
+- 数据中心的环境与能源监控
+- 监控各种互联网服务的实时性能
 
 它涵盖了智能制造、发电、电网、石油、石化、汽车、矿山、新能源、制药、IT 设施等众多领域。
 
@@ -64,6 +78,7 @@ TDengine AI 计划支持其他时序数据库，但与 TDengine 的集成更加
 单纯从功能上看，TDengine AI 与 PI System 中的 PI Asset Framework + PI Vision 对应。如果把 TDengine 也考虑进来，那么 TDengine + TDengine AI 相当于 PI System (包含 PI Interface + PI Data Archive + PI Asset Framework + PI Vision)。市场上很多实时库也是对标 PI System。
 
 与 PI System 以及其他实时数据库相比，TDengine  + TDengine AI 的优势是：
+
 1. 借助 AI，TDengine AI 能自动生成实时分析、看板与报表
 2. 具有超强的水平扩展性，能够支持 10 亿个以上的测点
 3. 具有很好的开放性，支持 JDBC、ODBC、REST API 等接口，能与大量的第三方软件无缝集成
@@ -72,8 +87,9 @@ TDengine AI 计划支持其他时序数据库，但与 TDengine 的集成更加
 唯一的劣势是支持的数据源种类还不够，目前仅仅支持 OPC-UA/OPC-DA, MQTT 等。
 
 与通用的数据管理平台相比，TDengine AI 具有如下优势：
+
 1. 因为充分利用时序数据特点，具有超强的写入、查询性能，是通用的十倍以上
 2. 因为其独有的一个设备一张表的设计，数据压缩率是通用的十倍
 3. 从数据采集、清洗、存储到分析、治理、实时分析、可视化、事件管理等一站式解决
 4. 支持通过配置，无需编码从工业网关直接读取数据
-与通用的数据管理平台相比，TDengine AI 的唯一劣势是它仅能高效的处理时序数据。
+与通用的数据管理平台相比，TDengine AI 的唯一劣势是它仅能高效的处理时序数据。

docs/02-concept.md

@@ -34,4 +34,4 @@
 
 ## 元素模版 (Element Template)
 
-真实世界里，同一类型的设备或实体有多个，他们有同样的属性、需要做同样的分析、建同样的看板、面板，因此 TDasset 引入元素模版。对于同一类型的元素，先创建模版，然后基于模版再创建具体的元素，这样便于数据的标准化，并且能大幅提高配置的效率。元素模版里包含了属性模版、分析模版、面板模版、看板模版以及通知规则模版。
+真实世界里，同一类型的设备或实体有多个，他们有同样的属性、需要做同样的分析、建同样的看板、面板，因此 TDasset 引入元素模版。对于同一类型的元素，先创建模版，然后基于模版再创建具体的元素，这样便于数据的标准化，并且能大幅提高配置的效率。元素模版里包含了属性模版、分析模版、面板模版、看板模版以及通知规则模版。

docs/03-get-started/01-docker.md

@@ -17,12 +17,13 @@ TDengine AI 提供了 Docker 镜像，用户可以通过 Docker 快速启动 TDe
    ```bash
    docker pull tdengine/tdengine-ai
    ```
-   
+
 3. 使用以下命令启动 TDengine AI 的 Docker 容器：
 
    ```bash
     docker run -d --name tdengine-ai 
    ```
+
 4. 启动后，你可以通过浏览器访问 TDengine AI 的 Web 界面，默认地址为 `http://localhost:6042`。
 
-## 在 Docker 环境下体验 TDengine AI
+## 在 Docker 环境下体验 TDengine AI

docs/03-get-started/02-package.mdx

@@ -3,25 +3,29 @@ import TabItem from '@theme/TabItem';
 
 # 用安装包快速体验
 
-在 Linux 系统上,TDengine Asset Intelligence 提供 Deb 和 RPM 格式安装包,其中 Deb 支持 Debian/Ubuntu 及其衍生系统,RPM 支持 CentOS/RHEL/SUSE 及其衍生系统,用户可以根据自己的运行环境自行选择。同时我们也提供了 tar.gz 格式安装包。
+在 Linux 系统上，TDengine Asset Intelligence 提供 Deb 和 RPM 格式安装包，其中 Deb 支持 Debian/Ubuntu 及其衍生系统，RPM 支持 CentOS/RHEL/SUSE 及其衍生系统，用户可以根据自己的运行环境自行选择。同时我们也提供了 tar.gz 格式安装包。
 
-在 MacOS 系统上, TDengine Asset Intelligence 提供 pkg 格式安装包。
+在 MacOS 系统上，TDengine Asset Intelligence 提供 pkg 格式安装包。
 
-在 Windows 系统上, TDengine Asset Intelligence 提供 exe 格式安装包。
+在 Windows 系统上，TDengine Asset Intelligence 提供 exe 格式安装包。
 
 ## 运行环境要求
 
 在各系统上运行环境最低要求如下：
-1. 操作系统: 
-  - Linux: CentOS 8 及以上版本，Ubuntu 20 及以上版本
-  - macOS: 13.0 及以上版本
-  - Windows: Windows Server 2019/2022 和 Windows 11
+
+1. 操作系统：
+
+- Linux: CentOS 8 及以上版本，Ubuntu 20 及以上版本
+- macOS: 13.0 及以上版本
+- Windows: Windows Server 2019/2022 和 Windows 11
+
 2. Python: 3.10-3.12 版本
 3. Java: 21 及以上版本
 4. glibc: 2.25 及以上版本
 
 # 安装
-请根据您的操作系统类型,选择合适的安装方式,安装 TDengine AI。以下是不同安装方式的详细步骤:
+
+请根据您的操作系统类型，选择合适的安装方式，安装 TDengine AI。以下是不同安装方式的详细步骤：
 <Tabs>
 
   <TabItem label="tar.gz 安装" value="tar">
@@ -34,7 +38,8 @@ import TabItem from '@theme/TabItem';
    tar xf TDasset-<version>.tar.gz && cd TDasset-<version>
    ./install.sh -s
    ```
-3. 安装完成后, TDasset 的默认安装路径为 `/usr/local/tdasset`,
+
+3. 安装完成后，TDasset 的默认安装路径为 `/usr/local/tdasset`,
    你可以通过 `./install.sh -h` 查看更多安装选项。
 
    ```bash
@@ -51,7 +56,8 @@ import TabItem from '@theme/TabItem';
    ```bash
    dpkg -i TDasset-<version>.deb
    ```
-3. 安装完成后, TDasset 的默认安装路径为 `/usr/local/tdasset`
+
+3. 安装完成后，TDasset 的默认安装路径为 `/usr/local/tdasset`
   </TabItem>
 
   <TabItem label="RPM 安装" value="rpm">
@@ -63,7 +69,8 @@ import TabItem from '@theme/TabItem';
    ```bash
    rpm -i TDasset-<version>.rpm
    ```
-3. 安装完成后, TDasset 的默认安装路径为 `/usr/local/tdasset`
+
+3. 安装完成后，TDasset 的默认安装路径为 `/usr/local/tdasset`
 
   </TabItem>
 
@@ -72,30 +79,34 @@ import TabItem from '@theme/TabItem';
 
 2. 双击安装包，按照提示完成安装。
 
-3. 安装完成后, TDasset 的默认安装路径为 `/usr/local/tdasset`
+3. 安装完成后，TDasset 的默认安装路径为 `/usr/local/tdasset`
 
   </TabItem>
   <TabItem label="Windows 安装" value="windows">
 1. 从列表中下载获得 Windows 的安装包。
 
-2. 双击安装包，按照提示完成安装。 
+2. 双击安装包，按照提示完成安装。
 
-3. 安装完成后, TDasset 的默认安装路径为 `C:\TDasset`
+3. 安装完成后，TDasset 的默认安装路径为 `C:\TDasset`
 
   </TabItem>
 </Tabs>
 
 # 启动
+
 <Tabs>
 <TabItem label="Linux 系统" value="linux">
 
 ## 启动服务
+
 安装完成后，你可以使用 `svc-tdasset` 命令来启动 TDengine AI 的服务进程。
 
  ```bash
 ./svc-tdasset start 
 ```
+
 这将启动 TDengine AI 的所有相关服务，包括：
+
 - `tdasset-h2`：用于存储 TDengine AI 的元数据和配置。
 - `tdasset-ai`：用于处理 AI 相关的任务和分析。
 - `tdasset`：核心服务，负责管理和提供数据访问。
@@ -105,10 +116,12 @@ import TabItem from '@theme/TabItem';
 ```bash
 ./svc-tdasset status
 ./svc-tdasset stop
-``` 
+```
 
 ## 手动管理服务
+
 如果你想手动管理这些服务，可以使用以下命令，以下示例使用 `tdasset`:
+
 ```bash
 systemctl start tdasset
 systemctl stop tdasset
@@ -128,6 +141,7 @@ systemctl restart tdasset
 <TabItem label="Windows 系统" value="windows">
 
 安装后，可以在拥有管理员权限的 cmd 窗口执行以下命令来启动 TDengine 服务进程。。
+
 ```cmd
 sc start tdasset-h2
 sc start tdasset-ai
@@ -139,6 +153,7 @@ sc start tdasset
 <TabItem label="macOS 系统" value="macos">
 
 1. 安装后，可以运行 `sudo svc-tdasset start` 来启动 TDengine AI 服务进程。这将启动所有相关服务，包括：
+
 - `tdasset-h2`：用于存储 TDengine AI 的元数据和配置。
 - `tdasset-ai`：用于处理 AI 相关的任务和分析。
 - `tdasset`：核心服务，负责管理和提供数据访问。
@@ -148,7 +163,7 @@ sc start tdasset
 ```bash
 sudo svc-tdasset status
 sudo svc-tdasset stop
-``` 
+```
 
 3. 如果你想手动管理这些服务，可以使用以下命令，以下示例使用 `tdasset`:
 
@@ -172,18 +187,22 @@ sudo launchctl print system/com.taosdata.tdasset
 </Tabs>
 
 # 卸载
+
 1. 可通过如下命令卸载 TDasset 的服务
 
  ```bash
 rmtdasset -e yes
 ```
+
 2. 或者保留数据、日志和配置
+
  ```bash
 rmtdasset -e no
 ```
+
 3. 如果是通过 rpm或者 deb安装, 可以使用如下命令卸载：
 
 ```bash
 dpkg -r tdasset
 rpm -e tdasset
-```
+```

docs/03-get-started/03-cloud.md

@@ -2,4 +2,4 @@
 
 TDengine AI 提供了云服务版本，用户可以通过云服务快速体验 TDengine AI 的强大功能，而无需进行本地安装和配置。
 
-## 访问云服务
+## 访问云服务

docs/03-get-started/index.md

@@ -2,7 +2,6 @@
 
 TDengine AI 完整的软件包包括 TDengine AI 的数据库、前端 web 服务 以及后端 Java 服务。用户可以通过简单的安装步骤快速体验 TDengine AI 的强大功能。
 
-
 import DocCardList from '@theme/DocCardList';
 
 <DocCardList />

docs/04-feature/02-element.md

@@ -2,4 +2,4 @@
 
 TDengine AI 的用户界面（UI）由多个元素和属性组成，这些元素和属性共同构成了用户与系统交互的基础。以下是 TDengine AI 中常见的元素及其属性：
 
-## 元素
+## 元素

docs/04-feature/03-analysis.md

@@ -1,3 +1,3 @@
 # 分析
 
-TDengine AI 的分析模块是数据处理和分析的核心部分，提供了多种数据分析功能，帮助用户从数据中提取有价值的信息。以下是分析模块的主要功能和特点：
+TDengine AI 的分析模块是数据处理和分析的核心部分，提供了多种数据分析功能，帮助用户从数据中提取有价值的信息。以下是分析模块的主要功能和特点：