Markdown Formatter

Markdown Formatter Skill

Create beautifully formatted Markdown documents that are consistent, readable, and professionally presented. This skill helps you maintain high-quality documentation standards.

Purpose

This skill helps you:

• Format Markdown files for consistency
• Validate Markdown syntax
• Optimize for readability
• Generate table of contents
• Fix common formatting issues
• Enforce style guidelines
• Create reusable templates
• Convert between Markdown formats

When to Use

Use this skill when you need to:

• Standardize Markdown formatting across projects
• Clean up and improve documentation
• Validate Markdown syntax before publishing
• Generate automated table of contents
• Create professional README files
• Format code examples consistently
• Apply style guides to documentation
• Convert between Markdown dialects

Key Features

1. Formatting - Consistent styling for headers, lists, links 2. Validation - Check for syntax errors and issues 3. TOC Generation - Automatic table of contents 4. Linting - Enforce style rules and best practices 5. Conversion - Convert to/from HTML, PDF, and other formats 6. Templates - Ready-to-use document templates 7. Batch Processing - Format multiple files at once 8. Custom Rules - Define project-specific formatting rules

Instructions

When using this skill:

1. Provide Content - Share raw Markdown or file path 2. Specify Style - Choose formatting style or guidelines 3. Set Options - Configure TOC, links, code formatting 4. Format - Apply consistent formatting 5. Validate - Check for errors and issues 6. Review - Verify output meets requirements 7. Deploy - Use formatted Markdown in your project

Guidelines

• Consistency First - Use the same style throughout documents
• Readability Matters - Format for easy scanning and reading
• Semantic HTML - Use proper Markdown elements for meaning
• Accessible - Ensure documents work for all readers
• Version Control - Keep Markdown in Git for tracking changes
• Link Validation - Check that all links are valid
• Code Quality - Format code blocks properly

Examples

Example 1: Formatting a README

Input (Raw Markdown):

# My Project
this is a great project
## Installation
pip install myproject
## Usage
use it like this

import myproject

## Features
- fast
- reliable
- easy

Output (Formatted):

# My Project

This is a great project.

## Table of Contents

- [Installation](#installation)
- [Usage](#usage)
- [Features](#features)

## Installation

pip install myproject

## Usage

Use it like this:

import myproject

## Features

- Fast and performant
- Reliable and stable
- Easy to use and integrate

Example 2: Generate Table of Contents

Command:

Format this document and generate a table of contents

Generated TOC:

## Table of Contents

1. [Introduction](#introduction)
2. [Getting Started](#getting-started)
   - [Prerequisites](#prerequisites)
   - [Installation](#installation)
3. [Usage Examples](#usage-examples)
   - [Basic Usage](#basic-usage)
   - [Advanced Features](#advanced-features)
4. [Configuration](#configuration)
5. [Troubleshooting](#troubleshooting)
6. [Contributing](#contributing)
7. [License](#license)

Formatting Rules

Headers

# H1: Document Title
## H2: Main Sections
### H3: Subsections
#### H4: Sub-subsections

Lists

### Unordered Lists
- Item 1
- Item 2
  - Nested item
  - Another nested

### Ordered Lists
1. First step
2. Second step
3. Third step

Code Blocks

````markdown

code goes here

def hello():
    print("Hello, World!")

echo "This is a bash command"

````

Links and Images

[Link text](https://example.com)
[Reference link][1]

![Alt text](image.png)
![Reference image][logo]

[1]: https://example.com
[logo]: /path/to/logo.png

Tables

| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Data 1   | Data 2   | Data 3   |
| Data 4   | Data 5   | Data 6   |

Style Guidelines

Capitalization

• Capitalize headings consistently
• Use sentence case for body text
• ALL CAPS only for acronyms or emphasis

Spacing

• One blank line between sections
• Blank line before and after code blocks
• Consistent indentation (2 or 4 spaces)

Emphasis

*italic* or _italic_
**bold** or __bold__
***bold italic***
~~strikethrough~~
`inline code`

Common Issues Fixed

Validation Checks

The formatter validates:

• [ ] Proper heading hierarchy
• [ ] Valid link formatting
• [ ] Balanced bracket and parentheses
• [ ] Proper code block fencing
• [ ] Table structure and alignment
• [ ] Image path validity
• [ ] Duplicate heading IDs

Output Formats

This skill can export to:

• Markdown (.md) - Standard format
• HTML (.html) - Web-ready
• PDF (.pdf) - Printable documents
• HTML Slides - Presentation format
• EPUB (.epub) - E-book format

Markdown Flavors Supported

• CommonMark (standard)
• GitHub Flavored Markdown (GFM)
• MultiMarkdown
• Pandoc Markdown
• Custom dialects

Related Resources

• Markdown Syntax Guide
• Style Guidelines
• Formatting Templates
• Validation Scripts
• Example Documents

Best Practices

1. Use descriptive headers - Make document structure obvious 2. Link liberally - Connect related sections and external resources 3. Format code properly - Always use code blocks with language tags 4. Add images thoughtfully - Illustrate complex concepts 5. Create tables for data - Make comparisons clear 6. Write for scanners - Many users skim, not read 7. Keep it DRY - Avoid repeating information

Support

For Markdown formatting help: 1. Review the examples above 2. Check the syntax guide in references/ 3. Use validation scripts in scripts/ 4. Browse templates in assets/templates/