193 lines
4.8 KiB
Markdown
193 lines
4.8 KiB
Markdown
# Troubleshooting Guide
|
|
|
|
Common issues and solutions for markdownlint-cli2 and the code-quality plugin.
|
|
|
|
## Hook Not Running
|
|
|
|
**Symptoms:** Markdown files created but not linted
|
|
|
|
**Causes:**
|
|
|
|
1. markdownlint-cli2 not installed → Install with npm
|
|
2. Hook disabled in settings → Check `.claude/settings.json` or `.claude/hooks.json`
|
|
3. File extension not .md or .markdown → Rename file or update hook configuration
|
|
4. Hook script not executable → Check file permissions
|
|
5. Wrong working directory → Hook runs from project root
|
|
|
|
**Solution:**
|
|
|
|
```bash
|
|
# Install markdownlint-cli2 (using local/project npm)
|
|
npm install --save-dev markdownlint-cli2
|
|
|
|
# Or install globally (alternative)
|
|
npm install -g markdownlint-cli2
|
|
|
|
# Test manually
|
|
markdownlint-cli2 --fix yourfile.md
|
|
|
|
# Check hook configuration
|
|
cat .claude/hooks.json
|
|
```
|
|
|
|
## Unfixable Issues
|
|
|
|
**Symptoms:** Hook reports issues that remain after fixing
|
|
|
|
**Causes:**
|
|
|
|
1. Rule requires manual judgment (e.g., heading hierarchy, heading content)
|
|
2. Content violates multiple conflicting rules
|
|
3. Structural issues (missing language, wrong heading level)
|
|
4. Semantic issues (duplicate headings, improper nesting)
|
|
|
|
**Solution:** Run `/mr-sparkle:lint-md` to see detailed error messages, then fix manually
|
|
|
|
**Common unfixable issues:**
|
|
|
|
- Heading hierarchy violations (must restructure manually)
|
|
- Multiple H1 headings (decide which to demote)
|
|
- Missing code block language (must choose appropriate language)
|
|
- Duplicate heading content (reword one of them)
|
|
|
|
## Configuration Not Applied
|
|
|
|
**Symptoms:** Custom rules not taking effect
|
|
|
|
**Causes:**
|
|
|
|
1. Configuration file in wrong location (see file precedence below)
|
|
2. Invalid JSON syntax (use a JSON validator)
|
|
3. Wrong filename or precedence issue
|
|
4. Parent directory config overriding your settings
|
|
5. Cached configuration (stale)
|
|
6. Using markdownlint file instead of markdownlint-cli2 file
|
|
|
|
**Solution:**
|
|
|
|
```bash
|
|
# Validate JSON syntax
|
|
npx jsonlint .markdownlint-cli2.jsonc
|
|
|
|
# Check which config file is being used
|
|
markdownlint-cli2 --help # Shows search order
|
|
|
|
# Test with explicit config
|
|
markdownlint-cli2 --config .markdownlint-cli2.jsonc "**/*.md"
|
|
|
|
# Debug config loading
|
|
markdownlint-cli2 yourfile.md 2>&1 | grep -i config
|
|
```
|
|
|
|
**File precedence reminder:**
|
|
|
|
1. `.markdownlint-cli2.jsonc` (highest priority, recommended)
|
|
2. `.markdownlint-cli2.yaml`
|
|
3. `.markdownlint.jsonc`
|
|
4. `.markdownlint.json`
|
|
|
|
For complete configuration details, fetch the official documentation: https://github.com/DavidAnson/markdownlint-cli2
|
|
|
|
## Linting Errors on Valid Markdown
|
|
|
|
**Symptoms:** Markdownlint reports errors on markdown that renders correctly
|
|
|
|
**Cause:** Markdown renderers are permissive; linters enforce stricter standards
|
|
|
|
**Solution:** This is expected behavior - linting enforces best practices even if renderers are forgiving
|
|
|
|
**Example:**
|
|
|
|
```markdown
|
|
#No space after hash - renders fine but fails MD018
|
|
```
|
|
|
|
Better to follow the standard for consistency.
|
|
|
|
## Performance Issues
|
|
|
|
**Symptoms:** Linting is slow on large repositories
|
|
|
|
**Solutions:**
|
|
|
|
1. Add appropriate ignore patterns to `.markdownlint-cli2.jsonc`
|
|
2. Use `.gitignore` integration (already enabled in our config)
|
|
3. Lint specific directories instead of entire tree
|
|
4. Exclude large generated files
|
|
|
|
```json
|
|
{
|
|
"ignores": [
|
|
"node_modules/**",
|
|
"dist/**",
|
|
"build/**",
|
|
"**/*.min.md",
|
|
"vendor/**"
|
|
]
|
|
}
|
|
```
|
|
|
|
## Command Not Found
|
|
|
|
**Symptoms:** `markdownlint-cli2: command not found`
|
|
|
|
**Causes:**
|
|
|
|
1. Not installed globally
|
|
2. npm global bin directory not in PATH
|
|
3. Installed locally instead of globally
|
|
|
|
**Solution:**
|
|
|
|
```bash
|
|
# Install globally
|
|
npm install -g markdownlint-cli2
|
|
|
|
# Or use npx (no installation needed)
|
|
npx markdownlint-cli2 "**/*.md"
|
|
|
|
# Or install locally and use npm scripts
|
|
npm install --save-dev markdownlint-cli2
|
|
# Then add to package.json scripts
|
|
```
|
|
|
|
## False Positives
|
|
|
|
**Symptoms:** Linter flags correct markdown as errors
|
|
|
|
**Solution:** If a rule doesn't fit your workflow, disable it in config:
|
|
|
|
```json
|
|
{
|
|
"config": {
|
|
"MD013": false // Disable specific rule
|
|
}
|
|
}
|
|
```
|
|
|
|
Or disable inline for specific cases:
|
|
|
|
```markdown
|
|
<!-- markdownlint-disable MD013 -->
|
|
This very long line won't be flagged
|
|
<!-- markdownlint-enable MD013 -->
|
|
```
|
|
|
|
## Hook Returns Non-Zero Exit
|
|
|
|
**Symptoms:** Hook fails and blocks Claude operations
|
|
|
|
**Cause:** Unfixable linting errors return exit code 1 (by design, non-blocking)
|
|
|
|
**Expected behavior:** The hook should report errors but NOT block the operation
|
|
|
|
**If blocking occurs:** Check hook configuration - should use `exit 1` (report) not `exit 2` (block)
|
|
|
|
## Getting Help
|
|
|
|
1. Check `pitfalls-reference.md` for common mistakes
|
|
2. Check `rules-reference.md` for rule details
|
|
3. Run `/mr-sparkle:lint-md` for detailed error messages
|
|
4. Visit <https://github.com/DavidAnson/markdownlint-cli2/issues>
|
|
5. Check markdownlint rules: <https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md>
|