markdown-formatter

Format and lint Markdown documents with consistent style, proper heading hierarchy, link validation, and code block formatting. Use when working with Markdown files, documentation, README files, or technical writing. Checks for common issues like broken links, inconsistent formatting, and missing alt text. Triggers on "format markdown", "lint markdown", "markdown style", ".md file", "documentation formatting".

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026⬇️1downloads

When & Why to Use This Skill

The Markdown Formatter skill is a specialized utility designed to automate the linting and styling of Markdown documents. It ensures professional-grade documentation by enforcing consistent heading hierarchies, validating internal links, and formatting code blocks with proper language tags. By identifying common errors such as broken links and missing image alt text, it helps maintain high-quality technical content, improves readability, and ensures compliance with documentation best practices.

Use Cases

  • Standardizing README files: Automatically apply consistent styling and structure to project READMEs to maintain a professional appearance across GitHub repositories.
  • Documentation Quality Assurance: Scan technical documentation folders to detect broken internal links and ensure all images include descriptive alt text for better accessibility and SEO.
  • Technical Blog Preparation: Format draft articles to adhere to specific style guides, ensuring proper list indentation, heading levels, and code block syntax highlighting.
  • Documentation Migration: Clean up and reformat legacy Markdown files when migrating content between platforms to ensure structural integrity and consistent formatting.
namemarkdown-formatter
descriptionFormat and lint Markdown documents with consistent style, proper heading hierarchy, link validation, and code block formatting. Use when working with Markdown files, documentation, README files, or technical writing. Checks for common issues like broken links, inconsistent formatting, and missing alt text. Triggers on "format markdown", "lint markdown", "markdown style", ".md file", "documentation formatting".

Markdown Formatter

Purpose

Format and lint Markdown documents to ensure consistent style, proper structure, and best practices.

When to Use

  • Formatting Markdown documentation
  • Linting README files
  • Checking markdown syntax
  • Validating links in documentation
  • Ensuring consistent style across docs

Core Instructions

  1. Read File: Load the Markdown file
  2. Check Syntax: Validate Markdown syntax
  3. Format: Apply consistent formatting
    • Heading hierarchy (h1 -> h2 -> h3, no skips)
    • List indentation (2 spaces)
    • Code block language tags
    • Link format consistency
  4. Validate: Check for common issues
    • Broken internal links
    • Missing alt text on images
    • Empty links
  5. Output: Write formatted file or report issues

Formatting Rules

  • Headings: ATX style (#, ##, ###)
  • Lists: 2-space indentation for nested items
  • Code blocks: Always specify language
  • Links: Use reference style for repeated links
  • Line length: 80-120 characters (guidance)

Example Pattern

# Main Title

## Section

### Subsection

Regular paragraph text.

- List item 1
  - Nested item
- List item 2

```python
def example():
    return "formatted"

Link text


## Dependencies

- Markdown parser (built-in)
- No external dependencies required

## Version

v1.0.0