fix(markdown-validator): use global markdownlint config with MD013=160

.markdownlint.json

@@ -1,5 +1,9 @@
 {
   "MD013": {
-    "line_length": 160
-  }
+    "line_length": 160,
+    "heading_line_length": 120,
+    "code_block_line_length": 160,
+    "tables": false
+  },
+  "MD060": false
 }

markdown-validator/README.md

@@ -40,6 +40,44 @@ npm install -g cspell
 
 ## Configuration
 
+### Global Markdownlint Configuration
+
+This plugin uses a global markdownlint configuration file at `~/.markdownlint-cli2.yaml`. The configuration
+defines the validation rules used by this plugin. If this file is missing, the validation hook will fail with
+a clear error message prompting you to create it.
+
+**Recommended configuration** (`~/.markdownlint-cli2.yaml`):
+
+```yaml
+config:
+  default: true
+  MD013:
+    line_length: 160
+    heading_line_length: 120
+    code_block_line_length: 160
+    tables: false
+  MD060: false
+fix: true
+```
+
+> **Note:** The YAML format shown above uses markdownlint-cli2's structure with a `config:` wrapper for rules
+> and a top-level `fix:` option. If using JSON format (`.markdownlint.json`), use a flat structure without
+> the `config` wrapper and omit the `fix` property, as shown in this repository's `.markdownlint.json`.
+
+**Key settings:**
+
+- **MD013**: Line length limits configured for readability
+  - `line_length: 160`: Regular text lines (default 80 breaks sentences mid-sentence)
+  - `heading_line_length: 120`: Heading lines
+  - `code_block_line_length: 160`: Code block lines
+  - `tables: false`: Disable table line length checks
+- **MD060**: Disabled due to version mismatch between GitHub Actions and nixpkgs
+- **fix: true**: Auto-fix issues where possible during validation
+
+If you don't have this file, create it with the above configuration.
+
+### Hook Configuration
+
 The hook is configured in `hooks/hooks.json`:
 
 ```json
@@ -73,6 +111,7 @@ The hook is configured in `hooks/hooks.json`:
 ## Customization
 
 Edit `scripts/validate-markdown.sh` to:
+
 - Add more validation tools
 - Change validation rules
 - Skip certain file patterns

markdown-validator/scripts/validate-markdown.sh

@@ -33,7 +33,11 @@ errors=()
 
 # Run markdownlint-cli2
 if command -v markdownlint-cli2 &>/dev/null; then
-  if ! markdownlint_output=$(markdownlint-cli2 "$file_path" 2>&1); then
+  config_file="$HOME/.markdownlint-cli2.yaml"
+  if [[ ! -f "$config_file" ]]; then
+    errors+=("markdownlint-cli2 config not found: $config_file")
+    errors+=("Please create this file as documented in the plugin README.")
+  elif ! markdownlint_output=$(markdownlint-cli2 --config "$config_file" "$file_path" 2>&1); then
     errors+=("markdownlint-cli2 failed:")
     errors+=("$markdownlint_output")
   fi