Report Rendering

Render the report

A report that only exists as markdown in a repo has not been delivered. It has been left where the author was working. The reader either lacks a checkout, or has one and must open several files in the right order and imagine the figures in place.

Ship one file that opens by double-clicking it.

Must always

• One self-contained HTML file. Embed every figure as a data: URI rather than linking a path. A document that breaks when moved is not a deliverable. Inline the CSS for the same reason.
• Concatenate the sections in reading order, with a table of contents and each source path shown beside its section, so a reader can find the file behind any claim.
• Add print styles. page-break-before on each top-level section, and unstick any position: sticky table headers, which otherwise repeat or vanish across page boundaries. Without this the PDF is unusable even though the HTML looks correct.
• Produce the PDF from the same HTML, so the two cannot disagree.
• Commit both, and say where they are. A rendered report that lives only in a temp directory has the same problem as the markdown did.

Must never

• Hand back a list of markdown paths in response to "show me the report."
• Link figures by relative path in a document intended to be sent anywhere.
• Reach for pandoc, LaTeX, or a new dependency when the machine already has a browser. The recipe below needs nothing else.
• Render a report whose numbers have not passed their own gate. Rendering makes a claim easier to circulate, which is a reason to be more careful about what is in it, not less. See [[principle-report-the-disqualifier]].

The recipe

Markdown to self-contained HTML to PDF, with no toolchain beyond a browser:

import base64, markdown
from pathlib import Path

md = markdown.Markdown(extensions=["tables", "fenced_code", "toc", "sane_lists"])
parts = []
for title, path in SECTIONS:
    md.reset()
    parts.append(f"<section><h1>{title}</h1>{md.convert(Path(path).read_text())}</section>")

fig = base64.b64encode(Path(FIGURE).read_bytes()).decode()
parts.append(f'<figure><img src="data:image/png;base64,{fig}"/></figure>')
Path("report.html").write_text(TEMPLATE.format(body="".join(parts)))

google-chrome --headless --disable-gpu --no-sandbox \
  --print-to-pdf=report.pdf --print-to-pdf-no-header report.html

md.reset() between sections matters: the toc extension accumulates state across calls, so without it later sections inherit earlier anchors.

Grounding

• Single-file, self-contained documents as a distribution format → the MHTML and data: URI approach; RFC 2397, "The 'data' URL scheme" (1998) https://doi.org/10.17487/RFC2397.
• Literate and reproducible reporting, where the document and the analysis that produced it are one artifact → Donald E. Knuth, "Literate Programming," The Computer Journal 27(2), 97-111 (1984) https://doi.org/10.1093/comjnl/27.2.97; Roger D. Peng, "Reproducible Research in Computational Science," Science 334(6060), 1226-1227 (2011) https://doi.org/10.1126/science.1213847.
• Delivering a result in the form the reader can act on, rather than the form the author worked in: no known prior art as a stated principle; it is ordinary practice rather than a named result.

Related: [[principle-report-the-disqualifier]] (what the report must contain before it is worth rendering).