markdown-linter

---
name: markdown-linter
description: Use when a user wants to check markdown files for issues (inconsistent heading levels, broken links, missing alt text, formatting inconsistencies) before publishing docs, or says "check my markdown" / "lint this doc" / "fix markdown issues".
version: 1.0.0
author: Hermes Agent
license: MIT
metadata:
  hermes:
    tags: [markdown, linting, documentation-quality]
    related_skills: [markdown-to-pdf, markdown-to-slides, hallmark-readme]
---

# markdown-linter

## Overview

Check markdown files for common issues: inconsistent heading levels, broken links, missing alt text, trailing whitespace, and formatting inconsistencies. The agent scans markdown files and reports a fixable punch list.

## When to Use

- The user wants to check their markdown for issues.
- The user is preparing documentation for publication.
- The user wants consistent markdown across a project.
- The user says "check my markdown", "lint this doc", or "fix markdown issues".

## Checks

```python
import re
from pathlib import Path

def lint_markdown(filepath: str) -> list:
    """Run all markdown linting checks and return issues."""
    with open(filepath, 'r') as f:
        lines = f.readlines()
        content = "".join(lines)

    issues = []

    # 1. Heading levels should not skip (h1 → h3 is bad)
    heading_levels = []
    for i, line in enumerate(lines, 1):
        match = re.match(r'^(#{1,6})\s', line)
        if match:
            level = len(match.group(1))
            heading_levels.append((i, level))

    for j, (line_num, level) in enumerate(heading_levels):
        if j > 0:
            prev_level = heading_levels[j-1][1]
            if level > prev_level + 1:
                issues.append({
                    "line": line_num,
                    "rule": "heading-skip",
                    "message": f"Heading level {level} skips from h{prev_level} — should be h{prev_level+1} max"
                })

    # 2. Multiple h1 headings
    h1_count = sum(1 for _, level in heading_levels if level == 1)
    if h1_count > 1:
        issues.append({
            "line": 0,
            "rule": "multiple-h1",
            "message": f"Found {h1_count} h1 headings — should have only one"
        })

    # 3. Trailing whitespace
    for i, line in enumerate(lines, 1):
        if line.rstrip() != line and line.strip():
            issues.append({
                "line": i,
                "rule": "trailing-whitespace",
                "message": "Trailing whitespace at end of line"
            })

    # 4. Images without alt text
    for i, line in enumerate(lines, 1):
        for match in re.finditer(r'!\[([^\]]*)\]\([^\)]+\)', line):
            alt = match.group(1)
            if not alt.strip():
                issues.append({
                    "line": i,
                    "rule": "missing-alt-text",
                    "message": "Image has no alt text"
                })

    # 5. Links without text
    for i, line in enumerate(lines, 1):
        for match in re.finditer(r'\[([^\]]*)\]\([^\)]+\)', line):
            text = match.group(1)
            if not text.strip() and not line.startswith('!'):
                issues.append({
                    "line": i,
                    "rule": "empty-link-text",
                    "message": "Link has no display text"
                })

    # 6. Inconsistent list markers (mixing - and *)
    dash_lists = sum(1 for line in lines if re.match(r'^\s*-\s', line))
    star_lists = sum(1 for line in lines if re.match(r'^\s*\*\s', line))
    if dash_lists > 0 and star_lists > 0:
        issues.append({
            "line": 0,
            "rule": "mixed-list-markers",
            "message": f"Mixed list markers: {dash_lists} dash, {star_lists} asterisk — pick one"
        })

    # 7. Code blocks without language
    in_code_block = False
    for i, line in enumerate(lines, 1):
        stripped = line.strip()
        if stripped.startswith("```"):
            if in_code_block:
                in_code_block = False
            else:
                lang = stripped[3:].strip()
                if not lang:
                    issues.append({
                        "line": i,
                        "rule": "missing-code-language",
                        "message": "Code block has no language specified"
                    })
                in_code_block = True

    # 8. Lines too long (over 120 chars, excluding URLs and tables)
    for i, line in enumerate(lines, 1):
        if len(line.rstrip()) > 120 and not line.strip().startswith("|") and "http" not in line:
            issues.append({
                "line": i,
                "rule": "line-too-long",
                "message": f"Line is {len(line.rstrip())} chars (max 120 recommended)"
            })

    return sorted(issues, key=lambda x: x["line"])
```

## Auto-fix

```python
def fix_markdown(filepath: str) -> dict:
    """Auto-fix simple markdown issues."""
    with open(filepath, 'r') as f:
        content = f.read()

    fixes = 0

    # Fix trailing whitespace
    lines = content.split("\n")
    fixed_lines = []
    for line in lines:
        fixed = line.rstrip()
        if fixed != line:
            fixes += 1
        fixed_lines.append(fixed)

    # Normalize list markers (use - consistently)
    for i, line in enumerate(fixed_lines):
        if re.match(r'^(\s*)\*\s', line):
            fixed_lines[i] = re.sub(r'^(\s*)\*\s', r'\1- ', line)
            fixes += 1

    with open(filepath, 'w') as f:
        f.write("\n".join(fixed_lines))

    return {"fixes": fixes, "file": filepath}
```

## Workflow

1. Run `lint_markdown` to get all issues
2. Present issues sorted by line number
3. Offer to auto-fix trailing whitespace and list markers
4. For other issues, show the line and suggested fix
5. Let the user decide which to fix

## Common Pitfalls

1. **Frontmatter.** YAML frontmatter (between `---` lines) is not markdown. Skip it during linting.
2. **Tables.** Table rows can be long. The line-length check skips lines starting with `|`.
3. **URLs.** Long URLs make lines long. The check skips lines containing `http`.
4. **Nested code blocks.** Code blocks inside code blocks (quarto, mdx) can confuse the parser. The `in_code_block` toggle handles simple cases.
5. **Auto-fix is conservative.** Only fixes whitespace and list markers. Heading levels, alt text, and link text require manual judgment.

## Verification Checklist

- [ ] `lint_markdown` was run and its full issue list — not just a sample — was reported, sorted by line number
- [ ] YAML frontmatter block was excluded from line-length and heading checks
- [ ] `fix_markdown` was only applied to whitespace/list-marker issues; heading levels, alt text, and link text were left for manual review
- [ ] Re-running `lint_markdown` after fixes shows the fixed issue count reduced accordingly

# markdown-linter



Check markdown files for consistency, broken links, missing alt text, and common formatting issues.



## What it does



The agent scans a markdown file and checks for 8 common issues: heading level skips, multiple h1s, trailing whitespace, missing image alt text, empty link text, mixed list markers, code blocks without language, and lines over 120 chars. Reports a sorted punch list with line numbers. Can auto-fix trailing whitespace and normalize list markers.



## Install



```bash

hermes skills install https://raw.githubusercontent.com/THEROCKSSS/hermes-skills-portfolio/main/skills/markdown-linter/SKILL.md

```



## How to use



```

"Lint my README.md"

```



The agent:

1. Runs all 8 checks

2. Reports issues sorted by line number

3. Offers to auto-fix trailing whitespace and list markers



## Checks



| Rule | What it catches |

|---|---|

| heading-skip | h1 → h3 (skipping h2) |

| multiple-h1 | More than one # heading |

| trailing-whitespace | Spaces at end of lines |

| missing-alt-text | Images without alt text |

| empty-link-text | Links with no display text |

| mixed-list-markers | Mixing - and * for lists |

| missing-code-language | Code blocks without a language |

| line-too-long | Lines over 120 characters |



## Example



```

User: "Check my docs for markdown issues"



Agent:

  1. Lints docs.md

  2. Finds:

     Line 12: trailing-whitespace

     Line 34: missing-alt-text (image)

     Line 45: mixed-list-markers (mixing - and *)

     Line 67: missing-code-language

  3. Offers: "Auto-fix 2 issues (whitespace, list markers)?"

  4. User approves → fixes applied

```