From b2958a55ecebea680711c7953240a0d3e9e47508 Mon Sep 17 00:00:00 2001
From: xzl <xiangzelong@radxa.com>
Date: Tue, 13 Jan 2026 17:02:03 +0800
Subject: [PATCH 1/2] docs: add pre-commit hook to enforce hyphen-based
 markdown filenames

- Add check-markdown-filename hook to validate markdown file naming
  - Reject files containing underscores (except those starting with _)
  - Provide helpful error messages with renaming examples
- Update standardize-doc.md workflow documentation
  - Add requirement for download.md placement in top-level directory
  - Specify download.md should have sidebar_position: 99
---
 .pre-commit-config.yaml                | 21 +++++++++++++++++++++
 .windsurf/workflows/standardize-doc.md |  1 +
 2 files changed, 22 insertions(+)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 284473215..120d5ebe6 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -110,3 +110,24 @@ repos:
         language: system
         entry: bash
         pass_filenames: false
+      - id: check-markdown-filename
+        name: Check Markdown filenames for underscores
+        language: system
+        entry: bash
+        files: '\.md$'
+        args:
+          - -c
+          - |
+            for file in "$@"; do
+              filename=$(basename "$file")
+              if [[ "$filename" =~ ^_ ]]; then
+                continue
+              fi
+              if [[ "$filename" =~ _ ]]; then
+                echo "Error: Markdown file contains underscore: $file"
+                echo "Please rename to use hyphens (-) instead of underscores (_)"
+                echo "Example: file_name.md -> file-name.md"
+                exit 1
+              fi
+            done
+          - --
diff --git a/.windsurf/workflows/standardize-doc.md b/.windsurf/workflows/standardize-doc.md
index 2e52728dd..964da830e 100644
--- a/.windsurf/workflows/standardize-doc.md
+++ b/.windsurf/workflows/standardize-doc.md
@@ -24,6 +24,7 @@ description: 标准化和验证中文文档路径、文件名及链接
 - **入口文件**：每个目录应使用 `README.md`（不是 `index.md`）
 - **安装目录**：统一使用 `install-system`（不是 `install-os`）
 - **嵌套深度**：避免超过 2-3 层目录
+- **结构规范**：`download.md` 应该位于一级目录（即和产品的 README 同级）且权重应该为 99（最后一项）
 
 **检查项**：
 

From 5c709786782b6e4b76ffbced12569181cdb555de Mon Sep 17 00:00:00 2001
From: xzl <xiangzelong@radxa.com>
Date: Tue, 13 Jan 2026 17:04:51 +0800
Subject: [PATCH 2/2] fix: limit markdown filename check to pre-commit stage
 only

---
 .pre-commit-config.yaml | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 120d5ebe6..ba881f0fc 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -115,6 +115,8 @@ repos:
         language: system
         entry: bash
         files: '\.md$'
+        stages:
+          - pre-commit
         args:
           - -c
           - |