From 134c03a903ca3520d8a7988afce66f9085859e5d Mon Sep 17 00:00:00 2001
From: Sebastian <19554889+sebslight@users.noreply.github.com>
Date: Fri, 6 Feb 2026 09:14:36 -0500
Subject: [PATCH] feat: add markdownlint configuration for documentation
 formatting and linting

---
 .markdownlint-cli2.jsonc | 58 ++++++++++++++++++++++++++++++++++++++++
 package.json             |  5 ++++
 2 files changed, 63 insertions(+)
 create mode 100644 .markdownlint-cli2.jsonc

diff --git a/.markdownlint-cli2.jsonc b/.markdownlint-cli2.jsonc
new file mode 100644
index 000000000..3f321b5af
--- /dev/null
+++ b/.markdownlint-cli2.jsonc
@@ -0,0 +1,58 @@
+{
+  "globs": ["docs/**/*.md", "docs/**/*.mdx", "README.md"],
+  "ignores": ["docs/zh-CN/**", "docs/.i18n/**"],
+  "config": {
+    "default": true,
+
+    "MD013": false,
+    "MD025": false,
+    "MD026": false,
+    "MD029": false,
+    "MD030": false,
+    "MD031": false,
+    "MD032": false,
+
+    "MD033": {
+      "allowed_elements": [
+        "Note",
+        "Info",
+        "Tip",
+        "Warning",
+        "Card",
+        "CardGroup",
+        "Columns",
+        "Steps",
+        "Step",
+        "Tabs",
+        "Tab",
+        "Accordion",
+        "AccordionGroup",
+        "CodeGroup",
+        "Frame",
+        "Callout",
+        "ParamField",
+        "ResponseField",
+        "RequestExample",
+        "ResponseExample",
+        "img",
+        "a",
+        "br",
+        "details",
+        "summary",
+        "p",
+        "strong",
+        "picture",
+        "source",
+        "Tooltip",
+        "Check",
+      ],
+    },
+
+    "MD034": false,
+    "MD036": false,
+    "MD037": false,
+    "MD040": false,
+    "MD041": false,
+    "MD046": false,
+  },
+}
diff --git a/package.json b/package.json
index 50c97adfe..8bf938356 100644
--- a/package.json
+++ b/package.json
@@ -35,6 +35,7 @@
     "build": "pnpm canvas:a2ui:bundle && tsdown && node --import tsx scripts/canvas-a2ui-copy.ts && node --import tsx scripts/copy-hook-metadata.ts && node --import tsx scripts/write-build-info.ts && node --import tsx scripts/write-cli-compat.ts",
     "canvas:a2ui:bundle": "bash scripts/bundle-a2ui.sh",
     "check": "pnpm tsgo && pnpm lint && pnpm format",
+    "check:docs": "pnpm format:docs && pnpm lint:docs && pnpm docs:build",
     "check:loc": "node --import tsx scripts/check-ts-max-loc.ts --max 500",
     "dev": "node scripts/run-node.mjs",
     "docs:bin": "node scripts/build-docs-list.mjs",
@@ -43,6 +44,8 @@
     "docs:list": "node scripts/docs-list.js",
     "format": "oxfmt --check",
     "format:all": "pnpm format && pnpm format:swift",
+    "format:docs": "git ls-files 'docs/**/*.md' 'docs/**/*.mdx' 'README.md' | xargs oxfmt --check",
+    "format:docs:fix": "git ls-files 'docs/**/*.md' 'docs/**/*.mdx' 'README.md' | xargs oxfmt --write",
     "format:fix": "oxfmt --write",
     "format:swift": "swiftformat --lint --config .swiftformat apps/macos/Sources apps/ios/Sources apps/shared/OpenClawKit/Sources",
     "gateway:dev": "OPENCLAW_SKIP_CHANNELS=1 CLAWDBOT_SKIP_CHANNELS=1 node scripts/run-node.mjs --dev gateway",
@@ -54,6 +57,8 @@
     "ios:run": "bash -lc 'cd apps/ios && xcodegen generate && xcodebuild -project OpenClaw.xcodeproj -scheme OpenClaw -destination \"${IOS_DEST:-platform=iOS Simulator,name=iPhone 17}\" -configuration Debug build && xcrun simctl boot \"${IOS_SIM:-iPhone 17}\" || true && xcrun simctl launch booted ai.openclaw.ios'",
     "lint": "oxlint --type-aware",
     "lint:all": "pnpm lint && pnpm lint:swift",
+    "lint:docs": "pnpm dlx markdownlint-cli2",
+    "lint:docs:fix": "pnpm dlx markdownlint-cli2 --fix",
     "lint:fix": "oxlint --type-aware --fix && pnpm format:fix",
     "lint:swift": "swiftlint lint --config .swiftlint.yml && (cd apps/ios && swiftlint lint --config .swiftlint.yml)",
     "mac:open": "open dist/OpenClaw.app",