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
```python
import myproject

Features

• fast
• reliable
• easy

**Output (Formatted):**
```markdown
# My Project

This is a great project.

## Table of Contents

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

## Installation

```bash
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:**
```markdown
## 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

```language
code goes here
```

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

```bash
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/