Skip to content

Deep dive

The case for semantic Markdown merging

Why manuals, handbooks, and long guides deserve more than concatenated source files.

MDLoom project7 min read

A folder of files is not yet a document

Long-form projects benefit from small source files, but readers need a deliberate sequence, consistent outline, resolved links, shared metadata, and one asset namespace. Those concerns belong to a composition model rather than destructive edits across every chapter.

The composition manifest is the source of assembly truth

The portable composition ZIP records inclusion, order, heading offsets, separators, front-matter policy, and profile alongside the source entries. Reordering changes the workbench composition, not imported files on disk; line-level generated-to-source mapping is not included.

Diagnostics should cross the file boundary

Duplicate anchors, reference labels, footnotes, and relative assets appear only when chapters meet. MDLoom reports those collisions at the composition level and attributes each warning to its original source file; line-level mapping is not claimed yet.

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  →