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

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

Update markdown-validator plugin to use global markdownlint configuration
with 160-character line length instead of default 80-character limit.

Changes:
- Update validate-markdown.sh to use --config ~/.markdownlint-cli2.yaml
- Document global config requirement in README
- Update .markdownlint.json with MD013 settings and MD060 disabled

Configuration:
- line_length: 160 (regular text, prevents mid-sentence breaks)
- heading_line_length: 120 (headings)
- code_block_line_length: 160 (code blocks)
- tables: false (disable table length checks)
- MD060: false (version mismatch workaround)

Users must create ~/.markdownlint-cli2.yaml with these settings
(deployed automatically via nix-config for nix users).

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

* fix: address PR review feedback on config handling and docs

Changes made:
- Use $HOME instead of ~ for better portability
- Add config file existence check with user-friendly error message
- Update documentation to clarify config requirement and failure behavior
- Add note explaining YAML vs JSON config format differences

Addresses review threads on PR #11:
- Thread PRRT_kwDOQx7E5c5qZyRI: Config check and $HOME usage
- Thread PRRT_kwDOQx7E5c5qZzxw: Config file existence validation
- Thread PRRT_kwDOQx7E5c5qZzyF: YAML/JSON format clarification
- Thread PRRT_kwDOQx7E5c5qZzyW: Config requirement language

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: JacobPEvans-personal

.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