md-report-builder

Build formal reports from local Markdown with one command. The same source produces native Word documents, paginated PDFs, and self-contained HTML with a cover, contents, numbered headings, tables, figures, equations, footnotes, and references. No account, API key, Pandoc, or network service is required.

The example source includes three tables, two chart blocks, a fragment, a footnote, equations, task lists, and figure/table/section references. Generated examples: Word, PDF, HTML.

Install

Python 3.11 or newer is required. DOCX and HTML need no system renderer.

git clone https://github.com/GuoHaoyu1688/md-report-builder.git
cd md-report-builder
python3 -m venv .venv
. .venv/bin/activate
pip install -e .

For PDF on Ubuntu, install Pango and the open-source Noto CJK fonts. WeasyPrint subsets and embeds the installed fonts in its PDF output.

sudo apt-get update
sudo apt-get install -y libpango-1.0-0 libpangoft2-1.0-0 fonts-noto-cjk
pip install -e '.[pdf]'

On macOS, install Pango with brew install pango and the Noto CJK fonts from the official Noto repository. If dynamic libraries are not found, set export MDR_LIBRARY_DIR="$(brew --prefix)/lib". This explicit hint also works when a virtual environment's shell launcher strips DYLD_* variables. No font or library is downloaded by mdr.

The default CJK families are Noto Serif CJK SC and Noto Sans CJK SC. Install them on machines opening a DOCX for consistent appearance. A reference template can instead select locally licensed Song, FangSong, Hei, or another installed font. Missing fonts may be substituted by the document viewer; inspect the result.

Related MCP server: mdgraph

Quick start

After installation, these three commands build the included example:

mdr lint examples/report.md --json
mdr build examples/report.md --to docx --out data/reports --json
mdr build examples/report.md --to html --out data/reports --json

With the PDF extra and libraries installed:

mdr build examples/report.md --to pdf --out data/reports --json --progress

Outputs are report.docx, report.html, and report.pdf in the chosen directory. Repeated builds atomically replace that source's output in that directory. Longer builds send progress to stderr; stdout remains one JSON object.

Four templates

mdr templates --json lists them. --template accepts a built-in name or a local directory containing style.yaml and an optional reference.docx. The reference contributes styles and section settings; its body is cleared. See template settings for fonts, named sizes such as 小四, spacing, margins, and numbering. Front matter can override numbering, cover, and contents. CLI template selection takes precedence over front matter.

Source format

---
title: Example operations review
subtitle: Capacity results and next cycle actions
author: Example Analyst
date: 2026-01-15
classification: Example document
template: business
numbering: technical
cover: true
toc: true
language: en
---

Author can be empty. Dates default to the current date in Asia/Shanghai. language: zh enables Chinese figure/table labels and the Word page footer 第 X 页 共 Y 页. The tool and documentation remain English.

A directory input merges its top-level .md files in filename order. The first front-matter value for each key wins. !include fragments/section.md expands a local Markdown fragment relative to its containing file. Images resolve there as well. Cycles, excessive depth, oversized sources, and resources escaping the source root are rejected. {{date}}, {{author}}, and scalar metadata variables are expanded; unknown variables are retained with warnings.

Supported content includes headings, emphasis, links, three-line tables with repeated headers, raster images, quotations, code, lists, tasks, and footnotes. Markdown HTML is escaped. Local images are embedded; remote images are rejected. See the full format for precise syntax and bounds.

Figures, tables, and references

# Summary {#summary}

![Example chart {#chart}](chart.png)

Table: Example totals {#totals}

| Group | Count |
| --- | --- |
| A | 4 |

See [@fig:chart], [@tbl:totals], and [@sec:summary].

Captions are numbered automatically. DOCX uses SEQ/REF fields and bookmarks, with cached visible results. Heading prefixes are computed at build time; rebuild after changing Markdown. Word's contents and page fields update in a supporting editor; the initial contents also includes usable cached links. PDF contents contains page numbers and clickable links immediately.

Charts and equations

A chart fence accepts YAML with type: bar|line|pie, x labels, and y values or named series. It can also contain CSV with labels in the first column and numeric series in later columns. Matplotlib renders charts locally. Example:

```chart
type: bar
id: progress
title: Example completed checks
x: [First, Second, Third]
y: [82, 89, 96]
```

Inline $x^2$ and block $$...$$ equations use Matplotlib MathText and are embedded as sharp PNGs in all outputs. This supports common fractions, sums, symbols, and superscripts; it is not a full TeX engine and does not produce editable Word equations. Unsupported math returns a structured error. mermaid fences are preserved as code with an explicit warning.

CLI reference

Globals can appear before or after the command: --data-dir, --config, --json, --quiet, --progress, --version. JSON is the default. The data directory precedence is CLI, MDR_DATA_DIR, TOML config, ./data. The default database is data/cache.sqlite, reports data/reports/, backups data/backups/. Example TOML is in examples/config.toml.

All commands return {"ok":true,"data":...,"warnings":[]} on success. Errors return {"ok":false,"error":{"code":"...","message":"..."}}. Exit codes: 0 success; 1 operational error; 2 invalid input or lint findings; 3 missing input or optional dependency. Lint findings retain an ok:true result with valid:false and exit 2 so callers can inspect every diagnostic.

History records output paths, hashes, counts, template, and build time; it does not contain source text. A rerun of the same source content/metadata, output path, format, and template updates its existing row. History exports and backups do not back up Markdown, images, custom templates, or generated reports. Copy those files separately before overwriting them. CSV exports use UTF-8 BOM by default; all other text is UTF-8.

Python and MCP

from md_report_builder import build

result = build("examples/report.md", "docx", "business", "data/reports")
print(result["output"])

The Python API does not record history unless data_dir= is supplied. CLI and MCP call the same core. MCP uses the official Python SDK and exposes build_report, list_templates, and lint_markdown:

{
  "mcpServers": {
    "reports": {
      "command": "mdr",
      "args": ["--data-dir", "/workspace/data/md-report-builder", "mcp"]
    }
  }
}

See AGENTS.md for exact Linux setup, all commands, error handling, MCP schemas, and operational recipes. Generated schemas are in docs/mcp-tools.json.

Verification

pip install -e '.[dev,pdf]'
ruff check .
ruff format --check .
pytest -q --cov=md_report_builder

CI installs Pango and fonts-noto-cjk and tests Python 3.11 and 3.12. Tests reopen all four templates' DOCX files, check exact source table values, figure numbers, reference/TOC fields, header/footer, true footnote parts, and embedded images. They build all four PDFs and inspect text, outlines, links, and page content. Other tests cover Unicode, offline behavior, path restrictions, lint fixtures, atomic output, JSON/CSV/backup roundtrips, CLI and all three MCP tools. The sample Word and PDF documents were also rendered and visually inspected page by page.

FAQ and roadmap

Can I use arbitrary Markdown or HTML? CommonMark plus tables, footnotes, MathText and the documented extensions is supported. Raw HTML is escaped. Complex footnote formatting is flattened in DOCX. Raster PNG/JPEG/GIF/WebP images are supported; SVG and remote images are not. Included image paths should use simple Markdown inline image syntax without spaces in the target.

Will all Word viewers paginate identically? No. Font availability and layout engines affect page breaks. Word contents/page fields may need an update. PDF uses WeasyPrint's independent HTML layout rather than Word pagination.

Does gongwen guarantee a formal filing standard? It provides configurable Chinese font sizes and numbering, not certification for a particular authority. Confirm the requested font, margins, spacing, and template before issuing a report.

Can it render Mermaid or use LibreOffice for PDF? Mermaid currently remains visible source code. PDF uses WeasyPrint; a LibreOffice export adapter, editable math, stronger nested-list fidelity, font diagnostics, and a watch command are roadmap items. Pandoc is neither needed nor invoked.

MIT licensed. See LICENSE and CHANGELOG.md.