Initial commit

skills/markdown-linter-fixer/references/MD029-Fix-Guide.md

@@ -0,0 +1,263 @@
+<!-- markdownlint-disable MD029 -->
+# 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
+
+<!-- markdownlint-disable MD029 MD032 -->
+
+```markdown
+1. First item
+
+```bash
+some code here
+```
+
+2. Second item  <!-- This triggers MD029 error -->
+
+```text
+
+<!-- markdownlint-enable MD029 MD032 -->
+
+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  <!-- No MD029 error -->
+
+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
+
+<!-- markdownlint-disable MD029 MD032 MD031 -->
+
+### ❌ Wrong: No indentation
+
+```markdown
+1. Item one
+
+```bash
+code here
+```
+
+2. Item two  <!-- MD029 error -->
+```text
+
+### ❌ Wrong: Insufficient indentation
+
+```markdown
+1. Item one
+
+  ```bash
+  code here  <!-- Only 2 spaces, not enough -->
+  ```
+
+2. Item two  <!-- MD029 error -->
+```text
+
+<!-- markdownlint-enable MD029 MD032 MD031 -->
+
+### ✅ Correct: Proper indentation
+```markdown
+1. Item one
+
+    ```bash
+    code here  <!-- 4 spaces indentation -->
+    ```
+
+2. Item two  <!-- No error -->
+```
+
+## 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  <!-- Auto-numbered by renderer -->
+1. Third item
+```
+
+### Disabling the Rule
+
+```markdown
+<!-- markdownlint-disable MD029 -->
+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
+<!-- markdownlint-disable MD029 MD032 -->
+
+1. Item one
+
+```bash
+code here
+```
+
+2. Item two  <!-- This would normally trigger MD029 error -->
+
+<!-- markdownlint-enable MD029 MD032 -->
+```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 `<!-- markdownlint-disable MD029 -->` 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  <!-- MD029 error here -->
+
+```bash
+npm install
+```
+
+3. Run the application  <!-- MD029 error here -->
+
+### After (MD029 errors fixed)
+
+```markdown
+1. Clone the repository
+
+    ```bash
+    git clone https://github.com/example/project.git
+    ```
+
+2. Install dependencies  <!-- No error -->
+
+    ```bash
+    npm install
+    ```
+
+3. Run the application  <!-- No error -->
+
+    ```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.

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