Markdown Formatting

Provides patterns for creating well-formatted Markdown documents.

Basic Formatting

def bold(text: str) -> str:
    """Format text as bold."""
    return f"**{text}**"

def italic(text: str) -> str:
    """Format text as italic."""
    return f"*{text}*"

def code(text: str) -> str:
    """Format text as inline code."""
    return f"`{text}`"

def link(text: str, url: str) -> str:
    """Create a markdown link."""
    return f"[{text}]({url})"

def image(alt_text: str, url: str) -> str:
    """Create a markdown image."""
    return f"![{alt_text}]({url})"

Headers

def heading(text: str, level: int = 1) -> str:
    """
    Create a markdown heading.

    Usage:
        heading("Main Title", 1)  # "# Main Title"
        heading("Section", 2)     # "## Section"
    """
    return f"{'#' * level} {text}"

Lists

from typing import List, Union

def bullet_list(items: List[str], indent: int = 0) -> str:
    """
    Create a bullet list.

    Usage:
        bullet_list(["Item 1", "Item 2", "Item 3"])
    """
    prefix = "  " * indent
    return "\n".join(f"{prefix}- {item}" for item in items)

def numbered_list(items: List[str], start: int = 1) -> str:
    """
    Create a numbered list.

    Usage:
        numbered_list(["First", "Second", "Third"])
    """
    return "\n".join(f"{i}. {item}" for i, item in enumerate(items, start=start))

def task_list(items: List[tuple[str, bool]]) -> str:
    """
    Create a task list.

    Usage:
        task_list([("Done task", True), ("Pending task", False)])
    """
    return "\n".join(
        f"- [{'x' if done else ' '}] {item}"
        for item, done in items
    )

Tables

from typing import List, Dict, Any

def table(headers: List[str], rows: List[List[Any]], alignment: str = None) -> str:
    """
    Create a markdown table.

    Args:
        headers: List of column headers
        rows: List of row data (each row is a list)
        alignment: Alignment string (l=left, c=center, r=right) e.g., "lcr"

    Usage:
        table(
            ["Name", "Age", "City"],
            [["Alice", 30, "NYC"], ["Bob", 25, "LA"]],
            alignment="lcr"
        )
    """
    # Build header row
    header_row = "| " + " | ".join(str(h) for h in headers) + " |"

    # Build separator row
    if alignment:
        separators = []
        for i, a in enumerate(alignment):
            if a == "c":
                separators.append(":---:")
            elif a == "r":
                separators.append("---:")
            else:
                separators.append("---")
        # Pad if alignment string is shorter than headers
        while len(separators) < len(headers):
            separators.append("---")
    else:
        separators = ["---"] * len(headers)

    separator_row = "| " + " | ".join(separators) + " |"

    # Build data rows
    data_rows = [
        "| " + " | ".join(str(cell) for cell in row) + " |"
        for row in rows
    ]

    return "\n".join([header_row, separator_row] + data_rows)

def dict_to_table(data: List[Dict[str, Any]], columns: List[str] = None) -> str:
    """
    Convert list of dictionaries to markdown table.

    Usage:
        data = [{"name": "Alice", "age": 30}, {"name": "Bob", "age": 25}]
        dict_to_table(data)
    """
    if not data:
        return ""

    if columns is None:
        columns = list(data[0].keys())

    rows = [[row.get(col, "") for col in columns] for row in data]
    return table(columns, rows)

Code Blocks

def code_block(code: str, language: str = "") -> str:
    """
    Create a fenced code block.

    Usage:
        code_block("print('hello')", "python")
    """
    return f"```{language}\n{code}\n```"

Blockquotes

def blockquote(text: str) -> str:
    """Create a blockquote."""
    lines = text.split("\n")
    return "\n".join(f"> {line}" for line in lines)

Horizontal Rule

def horizontal_rule() -> str:
    """Create a horizontal rule."""
    return "---"

Helper Script

Use helper.py for the MarkdownDocument class to build complex documents programmatically.