mdfy

mdfy is a Python library that makes creating markdown documents as simple as writing Python code. Generate reports, documentation, and structured content with an intuitive, object-oriented API.

🚀 Quick Start

Installation

pip install mdfy

Usage

from mdfy import Mdfier, MdHeader, MdText, MdTable
# Create markdown content
content = [
    MdHeader("My Report"),
    MdText("This quarter's sales were [excellent:bold]!"),
    MdTable([
        {"Product": "Laptop", "Sales": 1200, "Growth": "+15%"},
        {"Product": "Phone", "Sales": 800, "Growth": "+8%"}
    ])
]
# Generate markdown file
Mdfier("report.md").write(content)

📖 Documentation

Basic Features

Basic Usage

import mdfy as m

# Create content
content = [
    m.header("My Report"),
    m.text("This quarter's sales were [excellent:bold]!"),
    m.table(
        [
            {"Product": "Laptop", "Sales": 1200, "Growth": "+15%"},
            {"Product": "Phone", "Sales": 800, "Growth": "+8%"},
        ]
    ),
]

# Generate markdown file
m.Mdfier.from_filepath("report.md").write(content)

Output:

# My Report

This quarter's sales were [excellent:bold]!

| Product | Sales | Growth |
| --- | --- | --- |
| Laptop | 1200 | +15% |
| Phone | 800 | +8% |

🎨 Core Elements

Headers & Text

MdHeader("Title", level=1)                    # # Title
MdText("[Bold:bold] and [italic:italic]")     # **Bold** and *italic*

Data & Lists

MdTable(data, precision=2)                    # Convert dicts/lists to tables
MdList(items, numbered=True)                  # • Bullet or 1. Numbered lists

Code & More

MdCode("print('hello')", syntax="python")     # Syntax-highlighted code blocks

You can use a shortened syntax for convenience:

import mdfy as m
# Create a header
header = m.header("My Report", level=1)        # # My Report
text = m.text("This quarter's sales were [excellent:bold]!")
table = m.table([
    {"Product": "Laptop", "Sales": 1200, "Growth": "+15%"},
    {"Product": "Phone", "Sales": 800, "Growth": "+8%"}
])

💡 Real-world Examples

Dynamic Reports

import mdfy as m

def generate_sales_report(sales_data):
    total = sum(item['amount'] for item in sales_data)
    return [
        m.header("Sales Report"),
        m.text(f"Total Revenue: [${total:,}:bold]"),
        m.table(sales_data, precision=2)
    ]

m.Mdfier.from_filepath("sales.md").write(generate_sales_report(quarterly_data))

Data Analysis

# Convert pandas DataFrame to markdown table
df_summary = df.describe()
table = MdTable(df_summary.to_dict(), precision=3)

# Create analysis report
analysis = [
    MdHeader("Data Analysis Report"),
    MdText("Dataset contains [1,000:bold] records with [95%:bold] completeness."),
    MdTable(df_summary.to_dict(), precision=3)
]

🔧 Advanced Features

• Nested Content: Organize content hierarchically
• Custom Formatting: Flexible text styling with [text:style] syntax
• Table Customization: Headers, row labels, precision control, transposition
• Independent Elements: Each element can be used standalone
• Type Safety: Full type hints for better IDE support
• ""Table of Contents**: Automatically generated from headers

🤝 Contributing

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

# Development setup
git clone https://github.com/argonism/mdfy.git
cd mdfy
uv sync --all-groups

# Run tests
python -m pytest

Areas we'd love help with:

• 🐛 Bug reports and fixes
• 📚 Documentation improvements
• ✨ New element types
• 🎨 Styling and formatting features

📜 License

This project is licensed under the MIT License.