mdreport

Convert Markdown into beautiful, themed HTML reports. Zero HTML/CSS required from the model — write Markdown, get a polished navigable report.

The problem

AI agents love writing Markdown. But raw .md files are unreadable for long reports, and asking models to write full HTML/CSS wastes hundreds of tokens on boilerplate that's the same every time.

The solution

1. Model writes normal Markdown + lightweight :::block annotations
2. mdreport report.md converts it to a polished, navigable HTML report
3. Themes handle all styling — the model never touches HTML or CSS

Install

npm install -g mdreport

Or use without installing:

npx mdreport report.md

Quick start

mdreport report.md                    # dark theme (default) → report.html
mdreport report.md -t light           # clean light
mdreport report.md -t executive       # formal serif / print-ready
mdreport report.md -t kawaii          # pixel cats and laser pointers
mdreport report.md --open             # open in browser immediately
mdreport report.md --watch            # watch for changes, auto-rebuild
mdreport --list-themes                # show all available themes

Multi-page reports

Pass a directory to convert all .md files into a linked multi-page report:

mdreport ./myreport/

Files are sorted alphabetically — prefix with numbers to control order:

myreport/
├── 01-overview.md
├── 02-architecture.md
└── 03-recommendations.md

The topbar shows all pages; the sidebar shows headings for the current page.

Themes

Classic

| Theme | Description | |-------|-------------| | dark | Dark professional with blue accents (default) | | light | Clean light with blue accents | | executive | Formal serif, print-ready, deep red accents | | paper | Warm sepia/academic, orange accents | | card | Card-based layout with soft shadows | | magazine | Editorial bold headers, high contrast |

Technical

| Theme | Description | |-------|-------------| | terminal | Green-on-black hacker aesthetic | | blueprint | Engineering blueprint — white on navy |

Wild

| Theme | Description | |-------|-------------| | cyberpunk | Neon cyan/magenta on near-black | | neon | Neon 80s hot pink and electric blue | | parchment | Aged paper, warm sepia ink | | lofi | Lo-fi cozy muted pastels |

Unhinged

| Theme | Description | |-------|-------------| | pixel | 8-bit pixel universe with a sprite parade across the bottom | | kawaii | Pastel kawaii — real pixel-art cats that walk on your headings, chase a laser pointer cursor, and float hearts | | haunted | Glitching, flickering, blood-dripping horror |

Semantic annotations

Drop these anywhere in your Markdown:

:::callout
A key insight or note
:::

:::warning
Something to be cautious about
:::

:::highlight
A headline stat: **42%** increase
:::

:::quote
"A notable pull quote"
— Attribution
:::

Charts

Use :::chart with a JSON Chart.js config:

:::chart
{
  "type": "bar",
  "data": {
    "labels": ["Q1", "Q2", "Q3", "Q4"],
    "datasets": [{ "label": "Revenue", "data": [120, 190, 300, 500], "backgroundColor": "#58a6ff" }]
  }
}
:::

Available types: bar, line, pie, doughnut, radar, polarArea, bubble, scatter.

Diagrams

Mermaid diagrams work natively in fenced code blocks:

```mermaid
graph TD
    A[Input] --> B[Process]
    B --> C[Output]
```

Frontmatter

Optional YAML at the top of any file:

---
title: Report Title
subtitle: Optional subtitle
author: Author Name
date: April 2025
accent: "#ff6b35"  # override theme accent color
---

For AI agents

See SKILL.md for the agent-facing prompt. Drop it in your Claude Code skills directory (~/.claude/skills/) or include it in your agent's system prompt.

The key insight: the model writes ~150 tokens of Markdown. The CLI turns it into a multi-page navigable HTML report with sidebar navigation, syntax highlighting, Mermaid diagrams, charts, and a polished theme — without the model spending a single token on presentation.

Contributing

Contributions are very welcome. Some ideas:

• New themes — got a vibe that's missing? Add an entry to lib/themes.js. Each theme is a self-contained object with CSS variables, optional extra CSS, and optional JS.
• New block types — extend parseCustomBlocks() in lib/converter.js with new :::type annotations
• Export formats — PDF via puppeteer, DOCX, etc.
• Watch mode improvements — live reload via WebSocket instead of polling
• CLI flags — --no-sidebar, --toc-depth, --pdf, etc.
• Accessibility — ARIA labels, keyboard nav, high-contrast variants

Open an issue or PR at the repo. If you have a wild theme idea or a feature you wish existed, open a discussion — ideas are just as welcome as code.

Credits

Cat sprites in the kawaii theme: Just a few cats by Vassago Labs, licensed under CC BY-SA 4.0.