mdreport

Build Markdown reports programmatically with a chainable API. Add headings, text, lists, callouts, figures, code blocks, templates, Polars DataFrames, and SVG diagrams.

Install

pip install mdreport

mdreport requires Python 3.12 or later.

Create a report

from mdreport import MarkdownReport

report = (
    MarkdownReport()
    .title("Q3 review")
    .heading("Revenue")
    .text("Revenue grew {{revenue_growth}}%.", params={"revenue_growth": 4})
    .bullet_list(["EMEA grew 6%", "APAC grew 2%"])
)

report.save("q3-review.md")

Each method adds content and returns the report. Chain methods when the sequence is clear, or call them one at a time.

Create a diagram and embed it in a report:

from mdreport import Diagram, DiagramTheme, MarkdownReport, NodeRole, title_node

diagram = Diagram("Ingest", width=466, height=89, theme=DiagramTheme.LIGHT)
title_node(diagram, 89, 17, 288, "Source", role=NodeRole.ROOT)

report = MarkdownReport().title("Ingest")
report.append(diagram.figure(caption="Source node"))
report.save("ingest.md")

Read the documentation

• Markdown
  • Add common content
  • Add a callout
  • Add figures
  • Add a DataFrame
  • Add template values
  • Add frontmatter
  • Add a table of contents
  • Link to headings
  • Render or save
• Diagrams
  • Draw one node
  • Embed the diagram
  • Join two nodes
  • Fit the node to the copy
  • Add a legend
  • Group the flow
  • Branch on a condition
  • Show a record and annotate it
  • Divide work into lanes
  • Name a node with an icon
  • Choose a theme
  • Palette keys
  • Brand the palette
  • Adjust border widths
  • Use gradients
  • Frame the canvas
  • Draw a shape the library does not have
  • Save or serialize
  • The scale
  • Component sizes
• API reference
  • Report
  • Blocks
  • Diagrams
  • Golden-ratio scale
  • Diagram components
  • Heading anchors
  • Extension protocols
  • Errors
  • Token builders
  • Template helpers
  • DataFrame helpers
  • Parser
• Extensions
  • Create a block
  • Add a block
  • Return tokens
  • Read the finished document

LLMs and coding agents

LLMs and coding agents can read the documentation in Markdown format:

• llms.txt — a linked index of every page.

• llms-full.txt — the whole documentation as a single Markdown file.