Skip to content

Product principles

Why MDLoom starts with a rendering contract

The product decision behind one Markdown interpretation for preview, HTML, public pages, and canonical print.

MDLoom project6 min read

One source should not mean several interpretations

Markdown products often assemble an editor preview, website renderer, export engine, and print path from unrelated defaults. The document looks correct until the moment it matters: a table changes, an anchor shifts, or a diagram disappears from the PDF.

MDLoom routes browser preview, sanitized HTML export, public publication pages, and canonical PDF through the same profile and sanitizer configuration. Media-specific components—especially interactive browser Mermaid versus static PDF SVG—still have explicit transforms and separate tests.

Version the decisions that change meaning

The current implementation records the profile in local bundles, renderer identity on cloud revisions, and source/render/artifact hashes plus engine and style-contract information on rich server jobs. Some finer-grained extension and sanitizer version fields remain part of the production contract rather than a claim about every local snapshot.

Profile changes use a dry-run comparison and do not rewrite source. Full long-term replay across historical renderer builds remains a release gate; it is not implied merely by storing a profile label.

Rich converters still get a different promise

A Word document and an EPUB are not browser pages. Their exporters receive the declared source/profile contract, then the pinned Pandoc path makes destination-specific structural mappings. That is why MDLoom reserves the visual contract for canonical PDF and calls editable document output structural.

Put it into practice

Open a clean workspace for your next document.

Start anonymously, choose an explicit Markdown profile, and keep source, preview, and diagnostics together.

Open the editor  →