markdown-formatter

Markdown Formatter

This skill helps format, validate, and improve markdown documents.

Quick Start

Basic Formatting Rules

1. Headers: Use ATX-style headers (#, ##, etc.)
2. Lists: Consistent indentation (2 or 4 spaces)
3. Code blocks: Always specify language for syntax highlighting
4. Links: Use descriptive text, not "click here"

Generate Table of Contents

def generate_toc(markdown_content):
    """Generate TOC from markdown headers"""
    lines = markdown_content.split('\n')
    toc = []

    for line in lines:
        if line.startswith('#'):
            level = len(line.split()[0])
            title = line.lstrip('#').strip()
            anchor = title.lower().replace(' ', '-')
            indent = '  ' * (level - 1)
            toc.append(f"{indent}- [{title}](#{anchor})")

    return '\n'.join(toc)

Fix Common Issues

Fix List Indentation

def fix_list_indentation(content):
    """Ensure consistent 2-space indentation"""
    lines = content.split('\n')
    fixed = []

    for line in lines:
        if line.strip().startswith('-') or line.strip().startswith('*'):
            # Count leading spaces
            spaces = len(line) - len(line.lstrip())
            # Normalize to multiple of 2
            normalized = (spaces // 2) * 2
            fixed.append(' ' * normalized + line.lstrip())
        else:
            fixed.append(line)

    return '\n'.join(fixed)

Add Language to Code Blocks

def add_code_language(content, default_lang='bash'):
    """Add language specifier to code blocks"""
    return content.replace('```\n', f'```{default_lang}\n')

Best Practices

1. One sentence per line: Makes diffs cleaner
2. Empty line before/after headers: Improves readability
3. Consistent list markers: Pick - or *, stick with it
4. Code block languages: Always specify for syntax highlighting
5. Link references: Use reference-style for repeated URLs

Tools