Skip to content

Conversion

What Markdown conversion can—and cannot—preserve

Understand exact source, visual, structural, best-effort, and extractive conversion before choosing an output format.

MDLoom documentation8 min read

Five contracts are more honest than “lossless”

Exact source means the Markdown text is retained. A visual contract covers the deterministic Print Proof and canonical PDF. Structural conversion maps headings, paragraphs, lists, tables, links, and other supported semantics into an editable destination. Best-effort and extractive outputs make narrower promises.

The destination decides what can survive

DOCX has styles and sections that Markdown does not. Markdown has source-level conventions that a PDF cannot expose as editable structure. EPUB readers intentionally reflow pages. Converters must map between these models rather than pretending they are interchangeable containers.

  • Choose PDF when fixed visual pages are the requirement.
  • Choose DOCX or ODT when recipients must edit familiar document structures.
  • Choose EPUB for reflowable long-form reading.
  • Keep a Markdown bundle as the portable source of record.

A conversion report is part of the output

A complete report should identify the source hash, selected profile, engine versions, mapped features, warnings, omissions, asset decisions, and artifact validation result. The workbench now provides a downloadable JSON report for a server artifact, and batch ZIPs include a manifest, diagnostics, human-readable summary, and bounded per-item reports. A destination-specific feature-by-feature mapping is still limited to what each converter actually reports; MDLoom does not invent loss data the engine cannot prove.

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  →