llmrt

Markdown-to-HTML renderer for LLM outputs

GitHub: fchouteau/llm-report-templates

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.

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:

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

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.
                ┌─────────────┐
                │  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

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
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.

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.

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.

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.