prettymd

AI-powered Markdown formatter for developer workflows — Think of it as "Prettier for Markdown, powered by AI"

prettymd improves your Markdown files by fixing grammar, enhancing clarity, ensuring consistent formatting, and adapting tone — all from the command line. It's designed for developers who want their documentation to be as polished as their code.

✨ Features

🤖 AI-Powered Formatting - Uses GPT-4 to intelligently improve your Markdown
🎨 Multiple Styles - Choose between concise, technical, or friendly tones
📝 In-Place Editing - Update files directly or preview changes first
🔍 Diff View - See exactly what changes will be made with color-coded diffs
✅ CI-Ready - Check mode for integration with CI/CD pipelines
🧪 Mock Mode - Test without API keys using the built-in mock client
⚡ Fast & Efficient - Process individual files quickly from the command line

🚀 Installation

Option 1: Build from Source (Recommended)

# Clone the repository
git clone https://github.com/alexissan/prettymd
cd prettymd

# Build the release version
swift build -c release

# Install globally (optional)
sudo cp .build/release/prettymd /usr/local/bin/

Option 2: Swift Package Manager

Add to your Package.swift:

dependencies: [
    .package(url: "https://github.com/alexissan/prettymd", from: "0.1.0")
]

Requirements

macOS 13.0+ (Ventura or later)
Swift 5.9+
OpenAI API key (for AI features)

🎯 Quick Start

1. Set up your API key

export OPENAI_API_KEY="sk-..."

Add to your shell profile (~/.zshrc or ~/.bash_profile) to persist.

2. Format a Markdown file

# Preview changes (outputs to stdout)
prettymd fix README.md

# Apply changes in-place
prettymd fix README.md --in-place

# Use a specific style
prettymd fix README.md --style friendly

3. Test without an API key

# Use mock mode for testing
prettymd fix README.md --mock

📖 Usage

Basic Command Structure

prettymd fix <path> [options]

Available Options

Flag	Description	Example
`--in-place`	Write changes back to the file	`prettymd fix README.md --in-place`
`--style <style>`	Set tone: `concise`, `technical`, or `friendly`	`prettymd fix doc.md --style concise`
`--check`	Exit with error if changes needed (CI mode)	`prettymd fix *.md --check`
`--diff`	Show color-coded diff of changes	`prettymd fix README.md --diff`
`--mock`	Use mock client (no API required)	`prettymd fix test.md --mock`
`--model <model>`	OpenAI model (gpt-4o-mini, gpt-3.5-turbo)	`prettymd fix doc.md --model gpt-3.5-turbo`
`--help`	Show help information	`prettymd --help`

Output Modes

Standard Output (default): Prints formatted content to stdout
In-Place: Updates the file directly with --in-place
Diff View: Shows changes with --diff
Check Mode: Returns exit code 1 if changes needed with --check

Exit Codes

Code	Meaning	Use Case
`0`	Success - no changes needed or changes applied	Normal operation
`1`	Changes detected (with `--check` flag)	CI/CD pipelines
`2+`	Error occurred (file not found, API error, etc.)	Error handling

💡 Use Cases

1. Documentation Review

Perfect for polishing documentation before commits:

# Review all markdown files in docs/
for file in docs/*.md; do
  prettymd fix "$file" --in-place
done

2. Pre-Commit Hook

Add to .git/hooks/pre-commit:

#!/bin/bash
# Check if any staged .md files need formatting
for file in $(git diff --cached --name-only --diff-filter=ACM | grep '\.md$'); do
  if ! prettymd fix "$file" --check; then
    echo "❌ $file needs formatting. Run: prettymd fix $file --in-place"
    exit 1
  fi
done

3. CI/CD Integration

GitHub Actions example:

name: Markdown Lint
on: [pull_request]

jobs:
  lint:
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v3
      - uses: swift-actions/setup-swift@v1
      - run: |
          git clone https://github.com/alexissan/prettymd
          cd prettymd && swift build -c release
          cd ..
      - run: |
          export OPENAI_API_KEY=${{ secrets.OPENAI_API_KEY }}
          find . -name "*.md" -exec prettymd/prettymd fix {} --check \;

4. README Standardization

Ensure consistent README format across all projects:

# Create a style guide
export PRETTYMD_STYLE="technical"

# Format all READMEs
find ~/projects -name "README.md" -exec prettymd fix {} --in-place \;

5. Blog Post Polishing

# Polish a blog post with friendly tone
prettymd fix blog/my-post.md --style friendly --in-place

⚙️ Configuration

Environment Variables

Variable	Description	Default
`OPENAI_API_KEY`	Your OpenAI API key	Required
`PRETTYMD_STYLE`	Default style for formatting	`technical`
`PRETTYMD_MODEL`	Default OpenAI model	`gpt-4o-mini`

Style Options

technical (default): Precise, professional documentation style
concise: Minimal, direct communication
friendly: Approachable, conversational tone

📚 Examples

Before and After

Original:

# my project

this project does stuff with things.. its really cool!!!

- it has feature
-  another feature
- and   more stuff

After prettymd fix --style technical:

# My Project

This project provides comprehensive functionality for managing system resources. The implementation offers robust and reliable performance.

- Implements core feature set
- Provides extended functionality
- Includes additional capabilities

Diff Output Example

$ prettymd fix README.md --diff

--- original/README.md
+++ modified/README.md
@@ -1,3 +1,3 @@
-# my project
+# My Project

-this project does stuff
+This project provides comprehensive functionality

💰 API Usage & Costs

⚠️ Cost Considerations:

Default Model: Uses gpt-4o-mini (~$0.15 per 1M input tokens, ~$0.60 per 1M output tokens)
Cheaper Option: Use --model gpt-3.5-turbo for ~60% less cost
Token Usage: Average README uses ~500-2000 tokens (< $0.01 per file)
Free Testing: Use --mock mode to test without any API costs

Cost-saving tips:

# Use cheaper model for bulk processing
prettymd fix *.md --model gpt-3.5-turbo

# Test with mock mode first
prettymd fix README.md --mock --diff

# Check before processing to avoid unnecessary API calls
prettymd fix README.md --check

🔐 Privacy & Security

⚠️ Important Security Considerations:

API Transmission: Your Markdown content is sent to OpenAI's API for processing
Sensitive Data: Avoid processing files containing:
- API keys, passwords, or secrets
- Personal information (PII)
- Proprietary code or algorithms
- Confidential business information

Best Practices

Review files before processing
Use .prettymdignore (coming soon) to exclude sensitive files
Consider using mock mode for testing with sensitive content
Set up a dedicated API key with usage limits

🤝 Contributing

We welcome contributions! Here's how to get started:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Run tests: swift test
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Development Setup

# Clone your fork
git clone https://github.com/YOUR-USERNAME/prettymd
cd prettymd

# Open in Xcode
open Package.swift

# Or use your favorite editor
code .

Running Tests

# Run all tests
swift test

# Run with verbose output
swift test --verbose

# Test with mock client
.build/debug/prettymd fix Tests/Fixtures/sample.md --mock

🗺️ Roadmap

Version 0.2.0 (Coming Soon)

Support for multiple files/glob patterns
.prettymdrc configuration file
Batch processing with progress bar
Cache processed files to avoid redundant API calls

Version 0.3.0 (Planned)

Local LLM support (Ollama, llama.cpp)
Claude API integration
Custom style definitions
Markdown template generation (prettymd new)

Future Ideas

🐛 Troubleshooting

Common Issues

"API key is missing" error:

# Make sure your API key is set
export OPENAI_API_KEY="sk-your-actual-key-here"

"File too large" error:

Current limit is 100KB per file
Split large files or increase the limit in Sources/Core/FixManager.swift

Rate limiting:

Add delays between requests
Upgrade your OpenAI plan
Use mock mode for testing

Build errors:

# Clean and rebuild
swift package clean
swift build -c release

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

Built with Swift Argument Parser
Powered by OpenAI GPT-4
Inspired by Prettier

📮 Contact & Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Author: @alexissan

Made with ❤️ for better documentation

⬆ Back to Top

Name		Name	Last commit message	Last commit date
Sources		Sources
Tests/prettymdTests		Tests/prettymdTests
.gitignore		.gitignore
LICENSE		LICENSE
Package.resolved		Package.resolved
Package.swift		Package.swift
README.md		README.md

Latest commit

History

Folders and files

Repository files navigation