type	report
title	llmrt
subtitle	Markdown-to-HTML renderer for LLM outputs
lang	en

GitHub: fchouteau/llm-report-templates

:::{.callout type="Note"} This README is written as an llmrt-compatible markdown document. For the rendered version, visit fchouteau.github.io/llm-report-templates. :::

1. The Problem

LLM sessions produce valuable artifacts — technical reports, conversation archives, session plans and reviews — but markdown alone lacks presentation quality, and copy-pasting into docs tools loses structure. What you want is single-file, self-contained HTML that looks good, prints well, and needs no build pipeline.

:::{.callout type="Scope"} llmrt takes markdown with YAML frontmatter and colon-fence directives and renders it into standalone HTML documents using opinionated templates. One command in, one .html file out. :::

2. Why Not a Static Site Generator?

Jekyll, Hugo, Astro, and others exist. llmrt deliberately reinvents a narrow slice of that wheel:

:::{.def-box} Single-file output : No asset directories, no site scaffolding. One .html file with everything inlined.

Designed for LLM output patterns : Human/assistant turns, thinking blocks, math, code, diagrams — first-class constructs, not afterthoughts.

Colon-fence directives : :::{.callout type="Note"} maps directly to presentation components. No shortcode plugins, no custom Liquid tags.

Zero configuration : Frontmatter selects the template, directives handle the rest.

Pipe-friendly : Reads from stdin — fits agent workflows where output is streamed. :::

3. Architecture

:::{.algorithm title="Rendering Pipeline"}

1. Parse frontmatter. Extract YAML metadata (type, title, subtitle, lang) from the document header using python-frontmatter.
2. Tokenize markdown. Feed the body to markdown-it-py with mdit-py-plugins for colon-fence directive support.
3. Extract directives. Walk the token stream and map :::{.name key="value"} blocks to structured component data.
4. Select template. Use the type field from frontmatter to choose the Jinja2 template (report, conversation, or session).
5. Render HTML. Pass parsed content and metadata into the Jinja2 template to produce a single self-contained HTML file.
6. Client-side rendering. Math (KaTeX), syntax highlighting (Highlight.js), and diagrams (Mermaid.js) are loaded via CDN and rendered in the browser. :::

:::{.arch-diagram} ┌─────────────┐ │ input.md │ └──────┬──────┘ │ ┌──────▼──────┐ │ frontmatter │ │ parsing │ └──────┬──────┘ │ ┌──────────▼──────────┐ │ markdown-it-py │ │ + colon-fence ext │ └──────────┬──────────┘ │ ┌──────▼──────┐ │ directive │ │ extraction │ └──────┬──────┘ │ ┌──────▼──────┐ │ Jinja2 │ │ template │ └──────┬──────┘ │ ┌──────▼──────┐ │ output.html │ │ (standalone)│ └─────────────┘ :::

flowchart LR
    A[input.md] --> B[Frontmatter\nParsing]
    B --> C[markdown-it-py\n+ directives]
    C --> D[Directive\nExtraction]
    D --> E[Jinja2\nTemplate]
    E --> F[output.html]

    style A fill:#f5f5f5,stroke:#8b2500
    style F fill:#f5f5f5,stroke:#8b2500

Loading

4. Document Types

Type	Use case	Typography	Accent
report	Technical documents, analyses	IBM Plex Serif (body)	Dark red #8b2500
conversation	Message archives, chat logs	IBM Plex Sans (body)	Dark red #8b2500
session	Plans, reports, reviews	IBM Plex Sans (body)	Blue / Green / Amber by kind

:::{.details summary="Session auto-detection"} Session documents support auto-detection: a raw markdown file with # Plan: ..., # Implementation Report: ..., or # Code Review: ... as the first heading is detected automatically without frontmatter.

The kind field determines the accent color:

Kind	Color	Hex
plan	Blue	#2e5a88
report	Green	#4a7c3f
review	Amber	#8b5e3c
:::

5. Directive Reference

Directive	Attributes	Templates	Purpose
:::{.callout}	type (Scope, Note, Important, Tip, Warning, Decision, Reviewed)	All	Highlighted admonitions
:::{.eq-block}	label	All	Labeled display equations
:::{.def-box}	—	All	Definition lists
:::{.arch-diagram}	—	All	Monospaced ASCII diagrams
:::{.fig}	caption	All	Figures with captions
:::{.algorithm}	title	All	Numbered procedural steps
:::{.details}	summary	All	Collapsible sections
:::{.references}	—	Report	Bibliography entries
:::{.human}	—	Conversation	Human message
:::{.assistant}	timestamp	Conversation	Assistant message
:::{.thinking}	duration	Conversation	Reasoning trace
```mermaid	—	All	Flowcharts, sequence diagrams

Directives use colon-fence syntax: :::{.name key="value"} ... :::. Nest with :::: (4-colon) outer containers around ::: (3-colon) inner directives.

6. Installation and Quick Start

Install from PyPI:

pip install llmrt

For development:

pip install -e .

Show an example document and render it:

# Pipe the built-in report example directly to the renderer
llmrt template report | llmrt render -

# Render a markdown file to HTML
llmrt render my-report.md -o report.html

# View example markdown for each document type
llmrt template report
llmrt template conversation
llmrt template session

7. Intended Usage

Human authoring. Write markdown with directives, render to HTML for sharing or archiving. The directive syntax is compact enough to write by hand and expressive enough to produce polished documents.

Agent authoring. LLM agents produce structured markdown (plans, reports, reviews) as part of their workflow. llmrt renders these for human consumption.

:::{.callout type="Tip"} A Claude Code skill at .claude/skills/llmrt-authoring.md teaches Claude how to author documents in this format. With this skill active, Claude can produce rendered reports, conversation archives, and session documents as part of its normal workflow. :::

8. Development

pip install -e .
python -m pytest tests/

9. Live Example

This README is itself a valid llmrt report document. The rendered version is available at docs/index.html.

:::{.callout type="Note"} To regenerate the rendered documentation:

just docs

This runs llmrt render README.md -o docs/index.html and produces the self-contained HTML file. :::

10. License

Apache 2.0 — see LICENSE.

All dependencies use permissive licenses compatible with Apache 2.0.

:::{.details summary="Third-party licenses"}

Dependency	License	Context
typer	MIT	CLI framework
markdown-it-py	MIT	Markdown parser
mdit-py-plugins	MIT	Colon-fence directives
Jinja2	BSD-3-Clause	Template engine
python-frontmatter	MIT	YAML frontmatter parsing
KaTeX	MIT	Math rendering (CDN)
Highlight.js	BSD-3-Clause	Syntax highlighting (CDN)
Mermaid.js	MIT	Diagram rendering (CDN)
IBM Plex	OFL-1.1	Typography (Google Fonts)
:::

Built with Claude

This project is written with the help of Claude Code (Opus 4.6) and developed primarily targeting Claude Code and claude.ai outputs.

:::{.references}

• Simon Willison, claude-code-transcripts — rendering Claude Code session JSON to HTML. llmrt takes a different approach: markdown-in, HTML-out, with templates for multiple document types beyond conversations.
• markdown-it-py — the markdown parser powering llmrt.
• Jinja2 — template engine for HTML generation. :::