name	markdown-content-formatter
description	Format and validate markdown documents with auto-generated TOC, frontmatter, structure validation, and cross-reference linking. Export to GitHub/CommonMark/Jekyll/Hugo.

Markdown Content Formatter

Structure, validate, and format long-form markdown content for documentation, blogs, and static site generators. Auto-generate tables of contents, add frontmatter, validate structure, and convert between markdown flavors.

Workflow

The markdown formatting process follows these steps:

Load - Read markdown file or content
Validate - Check heading hierarchy, broken links, structure issues
Format - Apply formatting rules (spacing, code blocks, etc.)
Generate - Add TOC, frontmatter, cross-references
Export - Save in target markdown flavor

Quick Start

from scripts.markdown_formatter import MarkdownFormatter

# Load and format markdown
formatter = MarkdownFormatter(file_path='document.md')

# Generate table of contents
toc = formatter.generate_toc(max_depth=3)

# Validate structure
validation = formatter.validate_structure()
if not validation['valid']:
    print("Issues found:")
    for error in validation['errors']:
        print(f"  - {error['message']}")

# Add frontmatter
formatter.add_frontmatter({
    'title': 'My Document',
    'author': 'John Doe',
    'date': '2024-01-15'
})

# Export formatted version
formatter.export(
    output_path='formatted.md',
    include_toc=True,
    target_flavor='github'
)

Formatting Operations

1. Table of Contents Generation

Auto-generate TOC from document heading structure:

Customizable depth (H2, H3, etc.)
GitHub-style anchor links
Numbered or bulleted format
Smart indentation based on heading levels

2. Frontmatter Management

Add YAML/TOML/JSON frontmatter for static site generators:

YAML (---) for Jekyll/Hugo
TOML (+++) for Hugo
JSON for custom parsers
Structured metadata (title, author, date, tags, etc.)

3. Structure Validation

Check document structure for common issues:

Heading hierarchy - Detect skipped levels (H2 → H4)
Broken links - Find invalid internal (#anchors) and external links
Duplicate headings - Identify heading ID conflicts
Missing elements - Check for required sections

4. Code Block Formatting

Enhance code blocks with syntax highlighting markers:

Add language tags to fenced code blocks
Convert indented code to fenced blocks
Default language specification
Consistent formatting

5. Cross-Reference Linking

Auto-link headings and create cross-references:

Generate unique heading IDs
Link section mentions (e.g., "see Introduction")
Create anchor links for internal navigation
Handle duplicate heading names

6. Spacing and Consistency

Apply consistent formatting rules:

Line breaks around headings
List formatting (bullets, numbers)
Code block spacing
Paragraph breaks
Horizontal rules

7. Flavor Conversion

Convert between markdown flavors:

GitHub Flavored Markdown - Task lists, tables, syntax highlighting
CommonMark - Standard specification
Jekyll - Liquid templates, includes
Hugo - Shortcodes, taxonomies

Validation Checks

The validator identifies these common issues:

Issue Type	Description	Example
Heading Skip	Level jumps (H2 → H4)	Missing H3 between H2 and H4
Broken Link	Invalid internal/external link	`[link](#missing-section)`
Duplicate Heading	Same heading appears multiple times	Two "Introduction" headings
Missing ID	Heading lacks unique identifier	Anchor link fails
Invalid Structure	Incorrect nesting or formatting	List inside heading

API Reference

MarkdownFormatter

Initialization:

formatter = MarkdownFormatter(
    file_path='document.md',  # OR
    content='# Markdown text...'
)

Parameters:

file_path (str): Path to markdown file (optional)
content (str): Direct markdown content (optional)

One of file_path or content must be provided.

generate_toc()

toc = formatter.generate_toc(
    max_depth=3,        # Max heading level (1-6)
    start_level=2,      # Start from H2 (skip H1)
    style='github'      # 'github', 'numbered', 'bullets'
)

Returns: TOC markdown string

Styles:

github - Bulleted list with anchor links
numbered - Numbered outline
bullets - Simple bullet list

Example Output (github style):

## Table of Contents

- [Introduction](#introduction)
- [Getting Started](#getting-started)
  - [Installation](#installation)
  - [Configuration](#configuration)
- [Advanced Topics](#advanced-topics)

Frontmatter

add_frontmatter()

content = formatter.add_frontmatter(
    metadata={
        'title': 'Document Title',
        'author': 'John Doe',
        'date': '2024-01-15',
        'tags': ['markdown', 'documentation']
    },
    format='yaml'  # 'yaml', 'toml', or 'json'
)

Returns: Markdown content with frontmatter prepended

Example Output (YAML):

---
title: Document Title
author: John Doe
date: 2024-01-15
tags:
  - markdown
  - documentation
---

Validation

validate_structure()

result = formatter.validate_structure()

Returns: Dictionary with validation results

{
    'valid': bool,
    'errors': [
        {
            'type': 'heading_skip',
            'line': 45,
            'message': 'Heading level jumps from H2 to H4'
        }
    ],
    'warnings': [
        {
            'type': 'duplicate_heading',
            'line': 120,
            'message': 'Heading "Introduction" appears multiple times'
        }
    ]
}

Code Blocks

format_code_blocks()

content = formatter.format_code_blocks(
    add_language_tags=True,
    default_language='text'
)

Returns: Markdown with formatted code blocks

Converts:

    code here

To:

```text
code here
```

Cross-References

auto_link_headings()

content = formatter.auto_link_headings()

Returns: Markdown with heading IDs and cross-reference links

Generates GitHub-style anchors:

# Getting Started → <a id="getting-started"></a>
Links "see Getting Started" → [Getting Started](#getting-started)

Spacing

fix_spacing()

content = formatter.fix_spacing()

Returns: Markdown with consistent spacing

Applies rules:

2 blank lines before H1
1 blank line before H2-H6
1 blank line around code blocks
1 blank line around lists

Flavor Conversion

convert_to_flavor()

content = formatter.convert_to_flavor(target='jekyll')

Parameters:

target (str): 'github', 'commonmark', 'jekyll', or 'hugo'

Returns: Converted markdown string

Export

export()

formatter.export(
    output_path='formatted.md',
    include_toc=True,
    include_frontmatter=True,
    target_flavor='github'
)

Parameters:

output_path (str): Output file path
include_toc (bool): Add TOC at beginning
include_frontmatter (bool): Preserve/add frontmatter
target_flavor (str): Target markdown flavor

CLI Usage

Generate TOC

python scripts/markdown_formatter.py \
    --input document.md \
    --toc \
    --toc-depth 3 \
    --toc-style github \
    --output formatted.md

Add Frontmatter

# From command line
python scripts/markdown_formatter.py \
    --input document.md \
    --frontmatter title="My Doc" author="John Doe" date="2024-01-15" \
    --output formatted.md

# From file
python scripts/markdown_formatter.py \
    --input document.md \
    --frontmatter-file metadata.yaml \
    --output formatted.md

Validate Structure

python scripts/markdown_formatter.py \
    --input document.md \
    --validate \
    --format json

Output:

{
  "valid": false,
  "errors": [
    {
      "type": "heading_skip",
      "line": 45,
      "message": "Heading level jumps from H2 to H4"
    }
  ],
  "warnings": []
}

Full Formatting

python scripts/markdown_formatter.py \
    --input document.md \
    --toc \
    --frontmatter title="My Doc" \
    --auto-link \
    --fix-spacing \
    --flavor github \
    --output formatted.md

Batch Processing

# Format all markdown files in directory
for file in docs/*.md; do
    python scripts/markdown_formatter.py \
        --input "$file" \
        --toc \
        --fix-spacing \
        --output "formatted/$file"
done

CLI Arguments

Argument	Description	Default
`--input`, `-i`	Input markdown file	Required
`--output`, `-o`	Output file path	stdout
`--toc`	Generate table of contents	False
`--toc-depth`	Max TOC depth (1-6)	3
`--toc-style`	TOC style (github/numbered/bullets)	github
`--frontmatter`	Key=value pairs for frontmatter	-
`--frontmatter-file`	YAML file with frontmatter	-
`--auto-link`	Auto-link headings	False
`--fix-spacing`	Fix spacing and formatting	False
`--flavor`	Target markdown flavor	github
`--validate`	Validate structure only	False
`--format`	Output format for validation (json/text)	text

Examples

Example 1: Auto-Generate TOC

formatter = MarkdownFormatter(file_path='guide.md')
toc = formatter.generate_toc(max_depth=3, style='github')

print(toc)
# ## Table of Contents
# - [Introduction](#introduction)
# - [Setup](#setup)
#   - [Installation](#installation)
#   - [Configuration](#configuration)

Example 2: Add Jekyll Frontmatter

formatter = MarkdownFormatter(file_path='post.md')

formatter.add_frontmatter({
    'layout': 'post',
    'title': 'Getting Started with Markdown',
    'date': '2024-01-15',
    'categories': ['tutorial', 'markdown'],
    'tags': ['beginner', 'documentation']
}, format='yaml')

formatter.export('_posts/2024-01-15-getting-started.md')

Example 3: Validate Document Structure

formatter = MarkdownFormatter(file_path='documentation.md')
result = formatter.validate_structure()

if not result['valid']:
    print("Errors found:")
    for error in result['errors']:
        print(f"Line {error['line']}: {error['message']}")

    print("\nWarnings:")
    for warning in result['warnings']:
        print(f"Line {warning['line']}: {warning['message']}")
else:
    print("Document structure is valid!")

Example 4: Fix Common Issues

formatter = MarkdownFormatter(file_path='messy.md')

# Fix spacing issues
formatter.fix_spacing()

# Format code blocks
formatter.format_code_blocks(default_language='python')

# Add heading IDs
formatter.auto_link_headings()

# Export cleaned version
formatter.export('clean.md', target_flavor='github')

Example 5: Convert for Hugo Static Site

formatter = MarkdownFormatter(file_path='article.md')

# Add Hugo frontmatter
formatter.add_frontmatter({
    'title': 'My Article',
    'date': '2024-01-15T10:00:00Z',
    'draft': False,
    'tags': ['hugo', 'static-site'],
    'categories': ['web-development']
}, format='toml')

# Generate TOC
toc = formatter.generate_toc(max_depth=2)

# Convert to Hugo flavor
formatter.convert_to_flavor('hugo')

# Export
formatter.export(
    output_path='content/posts/my-article.md',
    include_toc=True,
    target_flavor='hugo'
)

Example 6: Batch Validation

# Validate all markdown files
for file in docs/**/*.md; do
    echo "Validating $file..."
    python scripts/markdown_formatter.py \
        --input "$file" \
        --validate \
        --format json > "${file}.validation.json"
done

# Find files with errors
jq -r 'select(.valid == false) | input_filename' docs/**/*.validation.json

Dependencies

markdown>=3.5.0
pyyaml>=6.0.0
beautifulsoup4>=4.12.0
pandas>=2.0.0

Install dependencies:

pip install -r scripts/requirements.txt

Limitations

Link Validation: External link checking requires network requests (not performed by default)
Markdown Parsing: Uses Python-Markdown library; some edge cases may differ from other parsers
Flavor Differences: Not all flavor-specific features are converted (e.g., Hugo shortcodes)
Heading Anchors: Anchor generation follows GitHub algorithm but may differ from other platforms
Code Language Detection: Automatic language detection is limited; manual tags recommended
Large Files: Very large files (>10MB) may be slow to process
Unicode: Some unicode characters in heading anchors may cause issues
Nested Lists: Complex nested list structures may not format perfectly
HTML in Markdown: Raw HTML blocks are preserved but not validated
Math Equations: LaTeX math equations are not parsed or validated

Markdown Flavor Notes

GitHub Flavored Markdown (GFM)

Task lists: - [ ] Task / - [x] Done
Tables with alignment
Strikethrough: ~~text~~
Automatic link detection

CommonMark

Strict specification adherence
No extensions (no task lists, no tables)
Predictable parsing

Jekyll

Liquid templating: {{ variable }}
Includes: {% include file.html %}
Frontmatter required

Hugo

Shortcodes: {{< shortcode >}}
TOML frontmatter preferred
Taxonomies (tags, categories)
Nested sections

Install Skill

SKILL.md

Markdown Content Formatter

Workflow

Quick Start

Formatting Operations

1. Table of Contents Generation

2. Frontmatter Management

3. Structure Validation

4. Code Block Formatting

5. Cross-Reference Linking

6. Spacing and Consistency

7. Flavor Conversion

Validation Checks

API Reference

MarkdownFormatter

Table of Contents

generate_toc()

Frontmatter

add_frontmatter()

Validation

validate_structure()

Code Blocks

format_code_blocks()

Cross-References

auto_link_headings()

Spacing

fix_spacing()

Flavor Conversion

convert_to_flavor()

Export

export()

CLI Usage

Generate TOC

Add Frontmatter

Validate Structure

Full Formatting

Batch Processing

CLI Arguments

Examples

Example 1: Auto-Generate TOC

Example 2: Add Jekyll Frontmatter

Example 3: Validate Document Structure

Example 4: Fix Common Issues

Example 5: Convert for Hugo Static Site

Example 6: Batch Validation

Dependencies

Limitations

Markdown Flavor Notes

GitHub Flavored Markdown (GFM)

CommonMark

Jekyll

Hugo