commit 74b07819928a6feae9ad94cee9d77f49b10c80b5 Author: Zhongwei Li Date: Sun Nov 30 08:53:32 2025 +0800 Initial commit diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..c1f827b --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,16 @@ +{ + "name": "markdown-linter-fixer", + "description": "Systematically fix linting issues in markdown files using markdownlint-cli2. This skill provides structured workflows to diagnose, fix, and verify markdown formatting issues with special focus on MD029 errors.", + "version": "1.5.4", + "author": { + "name": "s2005", + "email": "s2005@users.noreply.github.com", + "url": "https://github.com/s2005" + }, + "skills": [ + "./skills/markdown-linter-fixer" + ], + "commands": [ + "./commands/mdlinter.md" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..1f53dda --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# markdown-linter-fixer + +Systematically fix linting issues in markdown files using markdownlint-cli2. This skill provides structured workflows to diagnose, fix, and verify markdown formatting issues with special focus on MD029 errors. diff --git a/commands/mdlinter.md b/commands/mdlinter.md new file mode 100644 index 0000000..246880c --- /dev/null +++ b/commands/mdlinter.md @@ -0,0 +1,65 @@ +--- +description: Check or fix markdown linting issues with optional scope +--- + +# Markdown Linter - {{ARGUMENTS}} + +Use the `markdown-linter-fixer` skill to check or fix markdown linting issues. + +**Command format:** `/markdown-linter-fixer:mdlinter [mode] [scope]` + +**Arguments:** + +- Mode (optional): `{{ARGUMENTS}}` + - First argument can be either `check` or `fix` + - `check` - scan and report issues WITHOUT making changes (DEFAULT if not specified or invalid) + - `fix` - scan and automatically fix all issues + - **Safety default**: If no mode is provided or an invalid mode is given, defaults to `check` mode + +- Scope (optional): + - Can be specified as second argument (or first if mode is omitted) + - Can be: a specific file, multiple files (space-separated), a folder, or a glob pattern + - If not provided, operates on ALL markdown files in the project + +**Examples:** + +- `/markdown-linter-fixer:mdlinter` - check all files (default mode) +- `/markdown-linter-fixer:mdlinter check` - explicitly check all files +- `/markdown-linter-fixer:mdlinter fix` - fix all files +- `/markdown-linter-fixer:mdlinter README.md` - check only README.md (default mode) +- `/markdown-linter-fixer:mdlinter check README.md` - explicitly check only README.md +- `/markdown-linter-fixer:mdlinter fix docs/` - fix all files in docs folder +- `/markdown-linter-fixer:mdlinter check README.md CONTRIBUTING.md` - check specific files + +**Workflow based on mode:** + +**IMPORTANT**: If mode is not specified or is invalid, always use CHECK mode as the safe default. + +**For CHECK mode:** + +1. Verify markdownlint-cli2 installation +2. Check for existing configuration files +3. Run diagnostic scans on the specified scope +4. Categorize and analyze all errors by type +5. Generate comprehensive report +6. IMPORTANT: Do NOT execute auto-fix (--fix flag) +7. Do NOT make any manual fixes to files +8. ONLY scan and report the issues found + +**For FIX mode:** + +1. Verify markdownlint-cli2 installation +2. Check/create configuration files +3. Run diagnostic scans on the specified scope +4. Apply automatic fixes using --fix flag +5. Handle any remaining manual fixes (especially MD029 issues) +6. Verify all issues are resolved +7. Provide comprehensive summary report + +**Report should include:** + +- Total files scanned +- All errors found by type (MD001, MD029, MD032, etc.) +- File names and line numbers for each error +- Count of each error type +- Which errors are auto-fixable vs require manual intervention diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..5f7fea4 --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,57 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:s2005/markdown-linter-fixer-skill:", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "a6bbdb7c77bdbb7fc1aebd6a0ca4c37aea7953a4", + "treeHash": "3ecafc2bb620d65f65b0c52705fb55eb8559bb615e02259ee56c76dd0f0500e2", + "generatedAt": "2025-11-28T10:28:06.667036Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "markdown-linter-fixer", + "description": "Systematically fix linting issues in markdown files using markdownlint-cli2. This skill provides structured workflows to diagnose, fix, and verify markdown formatting issues with special focus on MD029 errors.", + "version": "1.5.4" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "1fd98197f89f914cf66aeaa99ba5856ad745003795605357bad6b31a5da400ac" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "48162d2d9e5e2bd71c95db57c74aa261117c18d24b1b50df4fb1c813e0f8e580" + }, + { + "path": "commands/mdlinter.md", + "sha256": "450896a8ffd24e98363000dd73b2cd20a1a46e224b932ddfaa8c7bd4ab57399e" + }, + { + "path": "skills/markdown-linter-fixer/SKILL.md", + "sha256": "c89a29fa38a3d7bdd16227a6acba29e7490529445664a8b2d633553762652124" + }, + { + "path": "skills/markdown-linter-fixer/references/MD029-Fix-Guide.md", + "sha256": "c2dbb11bd3f09168f51cf7ee80dd574d9c961d873b4b95b4743d0821c7057db1" + }, + { + "path": "skills/markdown-linter-fixer/references/MD036-Guide.md", + "sha256": "d55a0dd607282766568e80679649ed932528c9f150365e2091992d660b5951f9" + } + ], + "dirSha256": "3ecafc2bb620d65f65b0c52705fb55eb8559bb615e02259ee56c76dd0f0500e2" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file diff --git a/skills/markdown-linter-fixer/SKILL.md b/skills/markdown-linter-fixer/SKILL.md new file mode 100644 index 0000000..a5dcfea --- /dev/null +++ b/skills/markdown-linter-fixer/SKILL.md @@ -0,0 +1,327 @@ +--- +name: markdown-linter-fixer +description: Systematically fix linting issues in markdown files using markdownlint-cli2. This skill should be used when needing to scan, diagnose, and fix markdown formatting issues in projects with one or more .md files, with special attention to ordered list numbering (MD029) errors. +allowed-tools: Bash, Read, Write, Edit, Glob, Grep +--- + +# Markdown Linter Fixer + +## Overview + +Systematically fix linting issues in `*.md` files using markdownlint-cli2 through a structured workflow that diagnoses, fixes automatically where possible, and guides manual fixes when needed. + +## When to Use This Skill + +Use this skill when: + +- Fixing markdown linting errors in projects +- Standardizing markdown formatting across multiple files +- Addressing ordered list numbering issues (MD029) +- Preparing markdown documentation for quality standards +- Setting up markdown linting for the first time in a project + +## Workflow Process + +### Phase 1: Environment Setup & Prerequisites + +#### Verify markdownlint-cli2 Installation + +Check if markdownlint-cli2 is installed: + +```bash +markdownlint-cli2 --version +``` + +If missing, install it globally via npm: + +```bash +npm install -g markdownlint-cli2 +``` + +Handle any permission or installation errors by suggesting: + +- Local installation: `npm install --save-dev markdownlint-cli2` +- Using npx: `npx markdownlint-cli2` +- User-specific npm directory configuration + +#### Configuration File Check + +Look for existing markdown configuration files in the project root: + +- `.markdownlint-cli2.jsonc` +- `.markdownlint.json` +- `.markdownlint.yaml` +- `.markdownlint.yml` +- `.markdownlintrc` + +If none exist, create `.markdownlint-cli2.jsonc` with: + +```json +{ + "config": { + "MD013": false + }, + "ignores": [] +} +``` + +This disables max line length warnings while keeping other rules active. The `ignores` array can be used to exclude specific files from linting (e.g., example files with intentional errors). + +**IMPORTANT - Configuration Policy**: + +- **Do not ignore/hide linting errors** by modifying `.markdownlint-cli2.jsonc` +- **Only modify the `ignores` array** based on: + - Explicit user input or approval + - Content from `.gitignore` file (files already ignored by git) +- **Always ask the user** before adding files to the ignore list +- **Never suppress errors** without user consent - fix them instead + +### Phase 2: Diagnostic Assessment + +#### Initial Root-Level Scan + +Run linter on root-level markdown files: + +```bash +markdownlint-cli2 "*.md" +``` + +Document all issues found, including: + +- Error codes (e.g., MD029, MD001, MD032) +- File names and line numbers +- Brief description of each issue + +#### Comprehensive Recursive Scan + +Scan all markdown files including subdirectories: + +```bash +markdownlint-cli2 "**/*.md" +``` + +This includes files in directories like: + +- `docs/` +- `guides/` +- Any other subdirectories containing markdown + +Create a complete inventory of all issues across the project. + +### Phase 3: Issue Analysis + +#### Categorize Errors by Type + +Group all identified linting errors by error code: + +- Track frequency of each error type +- Identify which errors are auto-fixable +- Flag special attention areas (especially MD029, which often requires understanding indentation issues) + +Common error types: + +- **MD001**: Heading levels should increment by one level at a time +- **MD009**: Trailing spaces +- **MD010**: Hard tabs +- **MD012**: Multiple consecutive blank lines +- **MD029**: Ordered list item prefix (requires special attention - often caused by improper indentation) +- **MD032**: Lists should be surrounded by blank lines +- **MD047**: Files should end with a single newline character + +Document patterns such as: + +- "Found 15 MD029 errors across 5 files" +- "MD032 appears in all documentation files" +- "MD029 errors primarily in files with code blocks within lists" + +### Phase 4: Automatic Fixes + +#### Execute Auto-Fix + +Run the auto-fix command to correct all auto-fixable issues: + +```bash +markdownlint-cli2 "**/*.md" --fix +``` + +This command will: + +- Automatically fix formatting issues where possible +- Preserve original content intent +- Modify files in place + +#### Monitor for Issues + +Watch for: + +- Errors during the fix process +- Files that couldn't be modified (permissions) +- Any unexpected side effects + +Document what was fixed automatically versus what remains. + +### Phase 5: Manual Fixes + +#### Handle MD029 Issues + +For remaining MD029 (ordered list item prefix) issues: + +Load and consult `references/MD029-Fix-Guide.md` for detailed guidance on: + +- Understanding the root cause: **improper indentation of content between list items** +- Proper 4-space indentation for code blocks within lists +- Indentation requirements for paragraphs, blockquotes, and nested content +- Common mistakes and how to avoid them +- Real-world examples showing before/after fixes +- Alternative solutions and when to use them + +**Key insight**: MD029 errors often occur when code blocks, paragraphs, or other content between list items lack proper indentation (typically 4 spaces), causing markdown parsers to break list continuity. + +#### Apply Manual Corrections + +For issues not auto-fixed: + +- Open affected files +- Apply fixes according to error type +- Maintain consistency with existing markdown style +- Verify fixes don't break content + +### Phase 6: Verification & Reporting + +#### Re-run Linter + +Confirm all issues are resolved: + +```bash +markdownlint-cli2 "**/*.md" +``` + +If no errors appear, linting is complete. If errors remain, document them for additional manual fixes. + +#### Generate Summary Report + +Provide a comprehensive summary including: + +1. **Files Processed** + - Total count + - List of files modified + - Any files skipped or with errors + +2. **Issues Fixed by Type** + - Count of each error type fixed + - Auto-fixed vs. manually fixed + - Special notes on MD029 fixes + +3. **Remaining Issues** (if any) + - Error codes still present + - Files requiring manual attention + - Recommended next steps + +4. **Completion Status** + - Confirmation of successful completion, or + - Clear explanation of remaining work needed + - Any error details with suggested solutions + +## Key Principles + +### Preserve Content Intent + +Always maintain the original meaning and structure of markdown content. Fix formatting without altering the author's intended message. + +### Configuration Awareness + +Respect existing markdown configuration files. Don't override project-specific linting rules unless explicitly requested. + +### Progressive Fixing + +Work from automatic fixes first, then manual fixes. This maximizes efficiency and reduces the risk of introducing errors. + +### Comprehensive Reporting + +Provide clear, detailed reports at each phase so users understand: + +- What was found +- What was fixed +- What remains (if anything) +- How to proceed + +### Error Handling + +When encountering errors: + +- Provide clear error messages +- Suggest alternative approaches +- Offer workarounds if primary methods fail +- Never proceed without user confirmation on alternative paths + +## Common Scenarios + +### Scenario 1: Clean Project Setup + +User request: "Set up markdown linting for my documentation" + +Process: + +1. Install markdownlint-cli2 +2. Create `.markdownlint-cli2.jsonc` with MD013 disabled +3. Run diagnostic scan +4. Execute auto-fix +5. Report results + +### Scenario 2: Fix Existing Issues + +User request: "Fix all markdown linting errors in my project" + +Process: + +1. Verify markdownlint-cli2 available +2. Run comprehensive diagnostic +3. Categorize and report issues +4. Execute auto-fix +5. Guide through remaining manual fixes +6. Verify and report completion + +### Scenario 3: MD029-Focused Fixing + +User request: "I have ordered list numbering issues in my markdown files" or "My lists with code blocks are showing MD029 errors" + +Process: + +1. Scan for MD029 errors specifically +2. Attempt auto-fix +3. For remaining issues, load MD029-Fix-Guide.md +4. Guide through proper 4-space indentation for code blocks and content within lists +5. Verify list continuity is maintained +6. Report completion + +## Resources + +### references/ + +#### MD029-Fix-Guide.md + +Comprehensive guide for handling MD029 (ordered list item prefix) errors, focusing on the root cause: improper indentation. This reference provides: + +- Explanation of why MD029 errors occur (content breaking list continuity) +- Proper indentation rules: 4 spaces for code blocks, paragraphs, and other content +- Indentation table showing requirements for different content types +- Common mistakes with clear ❌ wrong vs ✅ correct examples +- Real-world before/after examples +- Alternative solutions and when to use markdownlint-disable comments +- Best practices for maintaining list continuity +- Verification steps + +Load this file when MD029 errors persist after auto-fix, or when user needs guidance on fixing ordered list issues. The guide is particularly valuable when lists contain code blocks or mixed content. + +#### MD036-Guide.md + +Comprehensive style guide for avoiding MD036 (no emphasis as heading) errors. This reference provides: + +- Clear explanation of the MD036 rule and why it matters +- Wrong vs. correct examples showing bold text vs. proper heading syntax +- Heading level hierarchy guidelines (h1 through h6) +- Common violations to avoid when creating markdown files +- Best practices for using headings vs. bold text +- Quick checklist for markdown file creation and modification + +Load this file when creating new markdown documentation or when encountering MD036 errors. Use as a reference to maintain consistent heading structure and avoid using bold text as heading substitutes. diff --git a/skills/markdown-linter-fixer/references/MD029-Fix-Guide.md b/skills/markdown-linter-fixer/references/MD029-Fix-Guide.md new file mode 100644 index 0000000..8153ee0 --- /dev/null +++ b/skills/markdown-linter-fixer/references/MD029-Fix-Guide.md @@ -0,0 +1,263 @@ + +# Fixing MD029 Markdownlint Errors: Ordered List Item Prefix + +> **Note:** This documentation file has markdownlint rules disabled at the top because it intentionally contains examples of problematic markdown code that would otherwise trigger linting errors. This is a common practice in documentation that demonstrates what NOT to do. + +## Problem Description + +The MD029 markdownlint rule triggers the following error: + +```text +MD029/ol-prefix: Ordered list item prefix [Expected: 1; Actual: 2; Style: 1/1/1] +``` + +This error occurs when markdownlint detects what it perceives as separate ordered lists instead of a continuous numbered list. + +## Root Cause + +The primary cause of MD029 errors is **improper indentation of content between ordered list items**. When code blocks, paragraphs, or other content appear between list items without proper indentation, Markdown parsers interpret this as breaking the list continuity. + +### Example of Problematic Code + + + +```markdown +1. First item + +```bash +some code here +``` + +2. Second item + +```text + + + +In the above example, the code block breaks the list, causing item 2 to be seen as starting a new list. + +## Solution: Proper Indentation + +### For Code Blocks + +Indent code blocks with **4 spaces** (or more, depending on nesting level) to maintain list continuity: + +```markdown +1. First item + + ```bash + some code here + ``` + +2. Second item + +3. Third item + + ```bash + another code block + ``` + +4. Fourth item +``` + +### For Paragraphs + +Indent continuation paragraphs with **at least 1 space** (typically 4 spaces for consistency): + +```markdown +1. First item + + This is a continuation paragraph that belongs to item 1. + It should be indented to maintain list continuity. + +2. Second item + + Another continuation paragraph. + +3. Third item +``` + +### For Mixed Content + +You can mix different types of content by maintaining proper indentation: + +```markdown +1. First step + + ```bash + command --option value + ``` + + This command does something important. + +2. Second step + + ```bash + another-command --flag + ``` + + Additional explanation here. + +3. Final step +``` + +## Indentation Rules + +| Content Type | Indentation Required | +|--------------|---------------------| +| Code blocks (fenced) | 4 spaces minimum | +| Code blocks (indented) | 8 spaces minimum | +| Paragraphs | 4 spaces (recommended) | +| Blockquotes | 4 spaces + `>` | +| Nested lists | 4 spaces per level | + +## Common Mistakes to Avoid + + + +### ❌ Wrong: No indentation + +```markdown +1. Item one + +```bash +code here +``` + +2. Item two +```text + +### ❌ Wrong: Insufficient indentation + +```markdown +1. Item one + + ```bash + code here + ``` + +2. Item two +```text + + + +### ✅ Correct: Proper indentation +```markdown +1. Item one + + ```bash + code here + ``` + +2. Item two +``` + +## Alternative Solutions (Not Recommended) + +While the following approaches can technically resolve MD029 errors, they are not recommended as they affect readability and functionality: + +### Using Only "1." for All Items + +```markdown +1. First item +1. Second item +1. Third item +``` + +### Disabling the Rule + +```markdown + +1. First item +2. Second item +3. Third item +``` + +### Ignoring MD029 Errors in Specific Sections + +Sometimes you need to intentionally include examples of problematic markdown (like in this documentation file). In such cases, you can disable the MD029 rule for specific sections: + +```markdown + + +1. Item one + +```bash +code here +``` + +2. Item two + + +```text + +**When to use this approach:** +- In documentation files showing examples of problematic code +- When demonstrating what NOT to do +- In code examples that are meant to illustrate errors + +**Note:** This documentation file itself uses `` at the top to prevent errors from the intentional "bad examples" shown throughout the document. + +## Best Practices + +1. **Always use 4-space indentation** for content within list items +2. **Maintain consistent indentation** throughout the document +3. **Test your markdown** with a preview to ensure proper rendering +4. **Use fenced code blocks** (```) rather than indented code blocks when possible +5. **Keep list items logically grouped** - if content doesn't belong to a list item, consider restructuring + +## Real-World Example + +Here's a common scenario showing how proper indentation fixes MD029 errors: + +### Before (with MD029 errors): + +```markdown +1. Clone the repository + +```bash +git clone https://github.com/example/project.git +``` + +2. Install dependencies + +```bash +npm install +``` + +3. Run the application + +### After (MD029 errors fixed) + +```markdown +1. Clone the repository + + ```bash + git clone https://github.com/example/project.git + ``` + +2. Install dependencies + + ```bash + npm install + ``` + +3. Run the application + + ```bash + npm start + ``` + +## Verification + +After applying the fixes, run markdownlint to verify: + +```bash +markdownlint your-file.md +``` + +You should see no MD029 errors in the output. + +## Conclusion + +The key to fixing MD029 errors is understanding that Markdown requires proper indentation to maintain list continuity. By indenting code blocks and other content with 4 spaces, you ensure that the markdown parser recognizes them as part of the list items rather than separate elements that break the list. diff --git a/skills/markdown-linter-fixer/references/MD036-Guide.md b/skills/markdown-linter-fixer/references/MD036-Guide.md new file mode 100644 index 0000000..c6aa644 --- /dev/null +++ b/skills/markdown-linter-fixer/references/MD036-Guide.md @@ -0,0 +1,43 @@ +# Markdown Style Guide + +## MD036 Rule - No Emphasis as Heading + +**Rule**: Never use bold text (`**text**`) as a heading substitute. Always use proper markdown heading syntax. + +### ❌ Wrong + +```markdown +**Configuration File Check** + +Some content here... +``` + +### ✅ Correct + +```markdown +#### Configuration File Check + +Some content here... +``` + +### Heading Level Guidelines + +- Use `#` through `######` for headings (h1-h6) +- Maintain proper heading hierarchy: + - `#` Main title (h1) + - `##` Major sections (h2) + - `###` Subsections under h2 (h3) + - `####` Subsections under h3 (h4) +- Never skip heading levels (e.g., don't jump from h2 to h4) + +### Common Violations to Avoid + +1. **Bold text on standalone lines** - These should be headings +2. **Section dividers using bold** - Use proper heading levels instead +3. **Emphasis for structure** - Use headings for document structure, bold only for emphasis within content + +### When Creating/Modifying Markdown Files + +- Always use heading syntax (`####`) for section titles +- Reserve bold text (`**text**`) for emphasis within paragraphs only +- Run `markdownlint-cli2` to verify before committing