Docs: lint and check broken link (#3139)

* Docs: lint and check broken link * Disable autocorrect for some docs * Update * Fix trailing slash in links * Fix lint * Update check-doc.yaml
juicedata · Dec 30, 2022 · 5f329b1 · 5f329b1
1 parent fe20ebc
commit 5f329b1
Show file tree

Hide file tree

Showing 105 changed files with 10,658 additions and 1,279 deletions.
diff --git a/.autocorrectrc b/.autocorrectrc
@@ -0,0 +1,24 @@
+rules:
+  # Default rules: https://github.com/huacnlee/autocorrect/raw/main/autocorrect/.autocorrectrc.default
+  spellcheck: 1
+textRules:
+  # Config some special rule for some texts
+  # For example, if we wants to let "Hello你好" just warning, and "Hi你好" to ignore
+  # "Hello你好": 2
+  # "Hi你好": 0
+fileTypes:
+  # Config the files associations, you config is higher priority than default.
+  # "rb": ruby
+  # "Rakefile": ruby
+  # "*.js": javascript
+  # ".mdx": markdown
+spellcheck:
+  words:
+    # Please do not add a general English word (eg. apple, python) here.
+    # Users can add their special words to their .autocorrectrc file by their need.
+    - Digital Ocean = DigitalOcean
+    - JucieFS = JuiceFS
+    - JueicFS = JuiceFS
+    - JuiecFS = JuiceFS
+    - filesystem = file system
+    - mountpoint = mount point
diff --git a/.github/workflows/check-doc.yaml b/.github/workflows/check-doc.yaml
@@ -0,0 +1,45 @@
+name: Check document
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - 'package.json'
+      - '.autocorrectrc'
+      - '.markdownlint-cli2.jsonc'
+      - '.github/workflows/check-doc.yaml'
+  pull_request:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - 'package.json'
+      - '.autocorrectrc'
+      - '.markdownlint-cli2.jsonc'
+      - '.github/workflows/check-doc.yaml'
+
+jobs:
+  check-doc:
+    name: Check document
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+      - name: Use Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '16.x'
+          cache: 'npm'
+      - name: Install dependencies
+        run: |
+          npm ci
+      - name: Lint Markdown files (markdownlint)
+        run: |
+          npm run markdown-lint
+      - name: Lint Markdown files (autocorrect)
+        uses: huacnlee/autocorrect-action@main
+        with:
+          args: --lint ./docs/
+      - name: Check broken link (including broken anchor)
+        run: |
+          npm run check-broken-link
diff --git a/.gitignore b/.gitignore
@@ -27,3 +27,4 @@ cmd/cmd
 *.out
 .hypothesis
 __pycache__
+/node_modules
diff --git a/.markdownlint-cli2.jsonc b/.markdownlint-cli2.jsonc
@@ -0,0 +1,177 @@
+{
+  "customRules": [
+    "markdownlint-rule-enhanced-proper-names/src/enhanced-proper-names.js",
+    "markdownlint-rule-no-trailing-slash-in-links/src/no-trailing-slash-in-links.js"
+  ],
+  "config": {
+    "default": true,
+    "first-heading-h1": false,
+    "heading-style": {
+      "style": "atx"
+    },
+    "ul-style": false,
+    "no-hard-tabs": {
+      "spaces_per_tab": 4
+    },
+    "line-length": false,
+    "no-duplicate-heading": {
+      "allow_different_nesting": true
+    },
+    "no-inline-html": {
+      "allowed_elements": [
+        "Badge",
+        "TabItem",
+        "Tabs",
+        "a",
+        "br",
+        "div",
+        "img",
+        "kbd",
+        "p",
+        "span",
+        "sup"
+      ]
+    },
+    "fenced-code-language": false,
+    "first-line-heading": false,
+    "no-alt-text": false,
+    "code-block-style": {
+      "style": "fenced"
+    },
+    "code-fence-style": {
+      "style": "backtick"
+    },
+    "link-fragments": false,
+    "no-trailing-slash-in-links": true,
+    "enhanced-proper-names": {
+      "code_blocks": false,
+      "html_elements": false,
+      "heading_id": false,
+      "names": [
+        "ACL",
+        "AI",
+        "API",
+        "ARM",
+        "ARM64",
+        "AWS",
+        "Amazon",
+        "Ansible",
+        "Apache",
+        "Azure",
+        "BSD",
+        "BadgerDB",
+        "CDH",
+        "CPU",
+        "CSI Driver",
+        "CSI",
+        "CentOS",
+        "Ceph",
+        "CephFS",
+        "ClickHouse",
+        "Cloud SQL",
+        "Colab",
+        "Consul",
+        "Debian",
+        "DevOps",
+        "DistCp",
+        "Docker Compose",
+        "Docker",
+        "Dockerfile",
+        "Doris",
+        "ECI",
+        "Elasticsearch",
+        "FTP",
+        "FUSE",
+        "Flink",
+        "Fluid",
+        "FoundationDB",
+        "GCC",
+        "GID",
+        "Git",
+        "GitHub",
+        "Google",
+        "Grafana",
+        "Graphite",
+        "HBase",
+        "HDFS",
+        "HDP",
+        "HTTP",
+        "HTTPS",
+        "Hadoop",
+        "Hive Metastore",
+        "Hive",
+        "Hudi",
+        "IAM",
+        "ID",
+        "IOPS",
+        "IP",
+        "Iceberg",
+        "JAR",
+        "JDK",
+        "JSON",
+        "Java",
+        "JuiceFS",
+        "JuiceFSRuntime",
+        "Juicedata",
+        "K8s",
+        "Kerberos",
+        "KeyDB",
+        "Kubernetes",
+        "LDAP",
+        "LZ4",
+        "Linux",
+        "M1",
+        "MariaDB",
+        "Maven",
+        "MinIO",
+        "MySQL",
+        "NFS",
+        "POSIX",
+        "PV",
+        "PVC",
+        "PostgreSQL",
+        "PowerShell",
+        "Prometheus",
+        "Pushgateway",
+        "Python",
+        "QPS",
+        "QoS",
+        "RADOS",
+        "RESTful",
+        "RGW",
+        "RPC",
+        "Raft",
+        "Ranger",
+        "Redis",
+        "S3",
+        "SDK",
+        "SFTP",
+        "SID",
+        "SMB",
+        "SQL",
+        "SQLite",
+        "SSH",
+        "Samba",
+        "Scala",
+        "Spark",
+        "StarRocks",
+        "ThriftServer",
+        "TiKV",
+        "UID",
+        "UUID",
+        "Ubuntu",
+        "Unix",
+        "VFS",
+        "WebDAV",
+        "WinFsp",
+        "Windows",
+        "YAML",
+        "YARN",
+        "Zstandard",
+        "etcd",
+        "macFUSE",
+        "macOS"
+      ]
+    }
+  }
+}
diff --git a/README_CN.md b/README_CN.md
@@ -11,7 +11,7 @@ JuiceFS 是一款高性能 [POSIX](https://en.wikipedia.org/wiki/POSIX) 文件
 
 JuiceFS 可以简单便捷的将海量云存储直接接入已投入生产环境的大数据、机器学习、人工智能以及各种应用平台，无需修改代码即可像使用本地存储一样高效使用海量云端存储。
 
-📺 **视频**：[什么是 JuiceFS?](https://www.bilibili.com/video/BV1HK4y197va/)
+📺 **视频**：[什么是 JuiceFS?](https://www.bilibili.com/video/BV1HK4y197va)
 
 📖 **文档**：[快速上手指南](https://juicefs.com/docs/zh/community/quick_start_guide)
 

diff --git a/docs/en/administration/fault_diagnosis_and_analysis.md b/docs/en/administration/fault_diagnosis_and_analysis.md
@@ -4,7 +4,6 @@ sidebar_position: 5
 slug: /fault_diagnosis_and_analysis
 description: This article describes how to view and interpret logs in various operating systems for JuiceFS FUSE, CSI Driver, Hadoop Java SDK S3 gateway, S3 gateway clients.
 ---
-# Fault Diagnosis and Analysis
 
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
@@ -100,7 +99,7 @@ Different JuiceFS clients obtain access log in different ways, which are describ
 There is a virtual file named `.accesslog` in the root directory of the JuiceFS file system mount point, the contents of which can be viewed by the `cat` command (the command will not exit), for example (assuming the root directory of the mount point is `/jfs`):
 
 ```bash
-$ cat /jfs/.accesslog
+cat /jfs/.accesslog
 ```
 
 ```output
@@ -111,7 +110,7 @@ $ cat /jfs/.accesslog
 
 ### Kubernetes CSI Driver
 
-Please refer to [CSI Driver documentation](https://juicefs.com/docs/csi/troubleshooting) to find the mount pod or CSI driver pod depending on the version of JuiceFS CSI Driver you are using, and the `.accesslog` file can be viewed in the root directory of the JuiceFS file system mount point in the pod. The mount point path in the pod is `/jfs/<pv_volumeHandle>`. Assuming there is a mount pod named as `juicefs-1.2.3.4-pvc-d4b8fb4f-2c0b-48e8-a2dc-530799435373`, in which `pvc-d4b8fb4f-2c0b-48e8-a2dc-530799435373` is  `<pv_volumeHandle>`, you can then use the following command to view the `.accesslog` file:
+Please refer to [CSI Driver documentation](https://juicefs.com/docs/csi/troubleshooting) to find the mount pod or CSI Driver pod depending on the version of JuiceFS CSI Driver you are using, and the `.accesslog` file can be viewed in the root directory of the JuiceFS file system mount point in the pod. The mount point path in the pod is `/jfs/<pv_volumeHandle>`. Assuming there is a mount pod named as `juicefs-1.2.3.4-pvc-d4b8fb4f-2c0b-48e8-a2dc-530799435373`, in which `pvc-d4b8fb4f-2c0b-48e8-a2dc-530799435373` is  `<pv_volumeHandle>`, you can then use the following command to view the `.accesslog` file:
 
 ```bash
 kubectl -n kube-system exec juicefs-chaos-k8s-002-pvc-d4b8fb4f-2c0b-48e8-a2dc-530799435373 -- cat /jfs/pvc-d4b8fb4f-2c0b-48e8-a2dc-530799435373/.accesslog
@@ -125,7 +124,6 @@ You need to add the [`--access-log` option](../reference/command_reference.md#ju
 
 You need to add the `juicefs.access-log` configuration item in the [client configurations](../deployment/hadoop_java_sdk.md#other-configurations) of the JuiceFS Hadoop Java SDK to specify the path of the access log output, and the access log is not output by default.
 
-
 ## Runtime information
 
 By default, JuiceFS clients will listen to a TCP port locally via [pprof](https://pkg.go.dev/net/http/pprof) to get runtime information such as Goroutine stack information, CPU performance statistics, memory allocation statistics. You can see the specific port number that the current JuiceFS client is listening on by using the system command (e.g. `lsof`):
@@ -135,7 +133,7 @@ If you mount JuiceFS as the root user, you need to add `sudo` before the `lsof`
 :::
 
 ```bash
-$ lsof -i -nP | grep LISTEN | grep juicefs
+lsof -i -nP | grep LISTEN | grep juicefs
 ```
 
 ```output
@@ -150,18 +148,21 @@ By default, pprof listens on port numbers ranging from 6060 to 6099. That's why
 - CPU performance statistics: `http://localhost:<port>/debug/pprof/profile?seconds=30`
 - Memory allocation statistics: `http://localhost:<port>/debug/pprof/heap`
 -
+
 :::tip
 You can also use the debug command to automatically collect these runtime information and save it locally. By default, it is saved to the debug directory under the current directory, for example:
+
 ```bash
 juicefs debug /mnt/jfs
 ```
+
 For more information about the debug command, see [command reference](https://juicefs.com/docs/community/command_reference#juicefs-debug)
 :::
 
 To make it easier to analyze this runtime information, you can save it locally, e.g.:
 
 ```bash
-$ curl 'http://localhost:<port>/debug/pprof/goroutine?debug=1' > juicefs.goroutine.txt
+curl 'http://localhost:<port>/debug/pprof/goroutine?debug=1' > juicefs.goroutine.txt
 ```
 
 ```bash

diff --git a/docs/en/administration/metadata/_mysql_best_practices.md b/docs/en/administration/metadata/_mysql_best_practices.md
@@ -4,4 +4,4 @@ sidebar_position: 2
 ---
 # MySQL Best Practices
 
-Working in progress.
+Working in progress.
diff --git a/docs/en/administration/metadata/_tikv_best_practices.md b/docs/en/administration/metadata/_tikv_best_practices.md
@@ -2,4 +2,4 @@
 sidebar_label: TiKV
 sidebar_position: 3
 ---
-# TiKV Best Practices
+# TiKV Best Practices
diff --git a/docs/en/administration/metadata/postgresql_best_practices.md b/docs/en/administration/metadata/postgresql_best_practices.md
@@ -45,7 +45,7 @@ It is recommended to make a plan for regularly backing up your database, and at
 
 ## Using connection pooler
 
-Connection pooler is a middleware that works between client and database and reuses the earlier connection from the pool, which improve connection efficiency and reduce the loss of short connections. Commonly used connection poolers are [PgBouncer](https://www.pgbouncer.org/) and [Pgpool-II](https://www.pgpool.net/).
+Connection pooler is a middleware that works between client and database and reuses the earlier connection from the pool, which improve connection efficiency and reduce the loss of short connections. Commonly used connection poolers are [PgBouncer](https://www.pgbouncer.org) and [Pgpool-II](https://www.pgpool.net).
 
 ## High Availability