chore: fix markdown lint coverage, write-translations command, and a deprecation

.github/workflows/gh-page.yml

@@ -18,9 +18,9 @@ jobs:
       uses: DavidAnson/markdownlint-cli2-action@v18.0.0
       with:
         globs: |
-          README.md
-          CHANGELOG.md
-          docs/*.md
+          *.md
+          docs/**/*.md
+          i18n/**/*.md
 
   typescript-lint:
     name: TypeScript Lint

AGENTS.md

@@ -4,7 +4,7 @@ Instructions for AI coding agents working with this repository.
 
 ## Project Overview
 
-This is the documentation site for **Kubedoop Data Platform** (https://kubedoop.dev),
+This is the documentation site for **Kubedoop Data Platform** (<https://kubedoop.dev>),
 built with [Docusaurus 3](https://docusaurus.io/). The site is deployed to GitHub
 Pages and supports both English and Chinese (zh-Hans).
 
@@ -16,7 +16,7 @@ Pages and supports both English and Chinese (zh-Hans).
 
 ## Repository Structure
 
-```
+```text
 docs/                  # English documentation source
 i18n/zh/docusaurus-plugin-content-docs/current/  # Chinese documentation source
 src/                   # React components and custom CSS
@@ -48,7 +48,9 @@ npm run typecheck      # TypeScript type checking (npx tsc --noEmit)
 - **English docs**: place in `docs/` directory
 - **Chinese docs**: place in `i18n/zh/docusaurus-plugin-content-docs/current/`
 - Filenames use kebab-case (e.g., `service-discovery.md`)
-- After adding Chinese docs, run `npm run write-translations --locale zh`
+- After adding Chinese docs, run `npm run write-translations -- --locale zh-Hans`
+  (the `--` separator is required, otherwise npm swallows `--locale` and the
+  bare `zh` is read as a site directory)
 
 ### Sidebar Updates
 
@@ -80,7 +82,7 @@ Advanced, Troubleshooting, Clean Up, Related Links.
 
 Follow [Conventional Commits](https://www.conventionalcommits.org/):
 
-```
+```text
 <type>(<scope>): <subject>
 ```
 

docs/developer-manual/document-guideline.md

@@ -4,9 +4,9 @@ If you want to participate in document writing, please read this document to und
 
 The project documentation is built based on [docusaurus](https://docusaurus.io/), and the documentation source code is located in the `docs` directory.
 
-The default language of the current document is English, and it now supports both Chinese and English. If you need to contribute English documents, 
+The default language of the current document is English, and it now supports both Chinese and English. If you need to contribute English documents,
 you can write directly in the `docs` directory. If you contribute Chinese documents, you need to write in the `i18n/zh/docusaurus-plugin-content-docs` directory.
-After writing, please run `yarn write-translations --locale zh` to generate the Chinese internationalization configuration, 
+After writing, please run `npm run write-translations -- --locale zh-Hans` to generate the Chinese internationalization configuration,
 and then adjust the Chinese internationalization configuration in `i18n/zh`.
 
 ## Writing Norms

docs/operators/_template.md

@@ -99,7 +99,7 @@ kubectl get pods -n {operator-name}
 
 Expected output:
 
-```
+```text
 NAME                                   READY   STATUS    RESTARTS   AGE
 {pod-name}-0                           1/1     Running   0          2m
 ```

docusaurus.config.ts

@@ -20,7 +20,15 @@ const config: Config = {
   projectName: 'docs', // Usually your repo name.
 
   onBrokenLinks: 'throw',
-  onBrokenMarkdownLinks: 'warn',
+
+  markdown: {
+    // Render ```mermaid fenced blocks as diagrams instead of plain code blocks.
+    mermaid: true,
+    hooks: {
+      onBrokenMarkdownLinks: 'warn',
+    },
+  },
+  themes: ['@docusaurus/theme-mermaid'],
 
   // Even if you don't use internationalization, you can use this field to set
   // useful metadata like html lang. For example, if your site is Chinese, you
@@ -66,6 +74,10 @@ const config: Config = {
   themeConfig: {
     // Replace with your project's social card
     image: 'img/docusaurus-social-card.jpg',
+    // Follow the site colour mode, otherwise diagrams stay light on a dark page.
+    mermaid: {
+      theme: {light: 'neutral', dark: 'dark'},
+    },
     navbar: {
       title: 'Kubedoop Data Platform',
       logo: {

i18n/zh/docusaurus-plugin-content-docs/current/operators/_template.md

@@ -99,7 +99,7 @@ kubectl get pods -n {operator-name}
 
 预期输出：
 
-```
+```text
 NAME                                   READY   STATUS    RESTARTS   AGE
 {pod-name}-0                           1/1     Running   0          2m
 ```