Markdown Tables in Python: pandas to_markdown, tabulate and Parsing

# pip install pandas tabulate
import pandas as pd

df = pd.DataFrame({
    "model": ["baseline", "small", "large"],
    "params_m": [0.0, 124.0, 1558.0],
    "accuracy": [0.71234, 0.83891, 0.91207],
    "latency_ms": [3.2, 18.75, 142.5],
})

print(df.to_markdown(index=False))

# Write straight to a file (buf accepts a path or a file object)
df.to_markdown("results.md", index=False)

# Per-column alignment: one entry per column (index=False means no index entry)
df.to_markdown(index=False, colalign=("left", "right", "right", "right"))

# Keep a meaningful index, e.g. after groupby
df.set_index("model").to_markdown()

# Other tabulate formats
df.to_markdown(index=False, tablefmt="github")   # pipe table without alignment colons
df.to_markdown(index=False, tablefmt="grid")     # Pandoc/reStructuredText grid table

s = pd.DataFrame({"value": [0.000012, 1234567.0, 3.5]})

print(s.to_markdown(index=False))                   # default "g": 1.2e-05, 1.23457e+06
print(s.to_markdown(index=False, floatfmt=",.2f"))  # 0.00, 1,234,567.00, 3.50
print(s.to_markdown(index=False, floatfmt=".6f"))   # 0.000012, 1234567.000000, 3.500000

df.to_markdown(index=False, floatfmt=".2f")

# One format per column (strings ignore it); "" keeps the default
df.to_markdown(
    index=False,
    floatfmt=("", ".0f", ".1%", ".1f"),
)

import pandas as pd

def markdown_safe(df: pd.DataFrame) -> pd.DataFrame:
    """Escape pipes and replace newlines in text columns so each row stays one table row."""
    out = df.copy()
    for col in out.select_dtypes(include=["object", "string"]).columns:
        out[col] = (
            out[col]
            .fillna("")
            .astype(str)
            .str.replace("|", r"\|", regex=False)
            .str.replace("\n", "<br>", regex=False)
        )
    return out

print(markdown_safe(df).to_markdown(index=False))

# tabulate's missingval only replaces None, and pandas passes NaN through as "nan".
clean = df.astype(object).where(df.notna(), None)
print(clean.to_markdown(index=False, missingval="n/a", floatfmt=".2f"))

import polars as pl

df = pl.DataFrame({
    "model": ["baseline", "small", "large"],
    "accuracy": [0.71234, 0.83891, 0.91207],
})

with pl.Config(
    tbl_formatting="MARKDOWN",
    tbl_hide_column_data_types=True,
    tbl_hide_dataframe_shape=True,
    tbl_rows=-1,          # don't truncate rows
    tbl_cols=-1,          # don't truncate columns
    fmt_str_lengths=1000, # don't shorten long strings
    float_precision=2,
):
    md = str(df)

print(md)

# Or convert and use pandas/tabulate for colalign and floatfmt
print(df.to_pandas().to_markdown(index=False))

# pip install tabulate
from tabulate import tabulate

rows = [["Ada", 92.5], ["Grace", 88]]
print(tabulate(rows, headers=["Name", "Score"], tablefmt="pipe", floatfmt=".1f"))

import json
from tabulate import tabulate

with open("users.json") as f:
    records = json.load(f)   # a list of objects

# headers="keys" uses the union of all keys; missing values become empty cells
print(tabulate(records, headers="keys", tablefmt="pipe"))

import pandas as pd

nested = [{"id": 1, "user": {"name": "Ada", "email": "ada@example.com"}, "tags": ["ml", "infra"]}]

flat = pd.json_normalize(nested)            # user.name, user.email columns
flat["tags"] = flat["tags"].str.join(", ")  # lists -> text
print(flat.to_markdown(index=False))

def to_markdown(rows: list[dict]) -> str:
    """Minimal Markdown table from a list of dicts, no dependencies."""
    headers = list(dict.fromkeys(k for row in rows for k in row))

    def cell(value) -> str:
        text = "" if value is None else str(value)
        return text.replace("|", r"\|").replace("\n", "<br>")

    lines = [
        "| " + " | ".join(headers) + " |",
        "| " + " | ".join("---" for _ in headers) + " |",
    ]
    lines += ["| " + " | ".join(cell(row.get(h)) for h in headers) + " |" for row in rows]
    return "\n".join(lines)

from IPython.display import Markdown, display

display(Markdown(df.to_markdown(index=False, floatfmt=".2f")))

import io
import pandas as pd

md = """
| Name   | Team     |  Score | Joined     |
| :----- | :------- | -----: | :--------- |
| Ada    | Platform |   92.5 | 2024-03-01 |
| Grace  | Compiler |     88 | 2023-11-15 |
| Hedy   | Radio    |    100 | 2025-01-20 |
"""

df = pd.read_csv(
    io.StringIO(md.strip()),
    sep="|",
    skipinitialspace=True,
    skiprows=[1],        # the | --- | delimiter row
).iloc[:, 1:-1]          # empty columns created by the outer pipes

df.columns = df.columns.str.strip()
for col in df.select_dtypes(include=["object", "string"]).columns:
    df[col] = df[col].str.strip()

print(df.dtypes)         # Score is float64; Name, Team, Joined are text
print(df["Score"].mean())  # 93.5

import re
import pandas as pd

def parse_markdown_table(md: str) -> pd.DataFrame:
    """Parse the first pipe table in md. Handles escaped pipes and missing outer pipes."""
    rows = []
    for line in md.strip().splitlines():
        line = line.strip()
        if "|" not in line:
            if rows:
                break        # the first non-table line after the table ends it
            continue
        if line.startswith("|"):
            line = line[1:]
        if line.endswith("|") and not line.endswith("\\|"):
            line = line[:-1]
        cells = [c.strip().replace("\\|", "|") for c in re.split(r"(?<!\\)\|", line)]
        rows.append(cells)

    header, delimiter, *body = rows
    if not all(re.fullmatch(r":?-+:?", c) for c in delimiter):
        raise ValueError("second line is not a | --- | delimiter row")
    width = len(header)
    body = [(r + [""] * width)[:width] for r in body]  # pad short rows, drop extra cells
    return pd.DataFrame(body, columns=header)

df = parse_markdown_table(open("README.md").read())
df["Score"] = pd.to_numeric(df["Score"])   # every cell is text; convert what you need

# pip install markdown
import markdown
html = markdown.markdown(md, extensions=["tables"])

# pip install markdown-it-py
from markdown_it import MarkdownIt
html = MarkdownIt("commonmark").enable("table").render(md)