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

Resource	Description
Getting Started	Step-by-step tutorial for beginners
User Guide	Complete feature documentation
Examples	Real-world usage examples
API Reference	Complete API documentation

Basic Features

Feature	Description
Text styling	Format text with bold, italic, and more - even in the middle of text
Headers	Multiple levels for document structure
Links	Internal and external linking
Lists	Ordered and unordered with nesting support
Tables	From dictionaries and lists with formatting
Images	With alt text and titles
Code blocks	With syntax highlighting
Quotes	For emphasis and citations
Horizontal rules	For section separation
Table of Contents	Automatic generation from headers

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.