Markdown is plain text with a reading contract
A Markdown file stays useful without MDLoom. You can open it in a text editor, commit it to Git, or move it between operating systems. The renderer adds structure, but the source remains readable.
Portability depends on knowing the flavor. CommonMark defines a carefully tested core. GitHub Flavored Markdown adds tables, task lists, strikethrough, and autolinks. Other products may add their own syntax.
Build a clean heading outline
Use one level-one heading for the document title, then descend one level at a time. Heading levels describe structure, not visual size. A theme can change appearance without changing meaning.
Separate paragraphs with a blank line. Avoid relying on trailing spaces for hard line breaks unless the format truly needs them—they are difficult to see during review.
# Project handbook
## Getting started
A short opening paragraph.
### Install the tools
1. Clone the repository.
2. Install dependencies.
3. Run the checks.Prefer durable links and explicit image text
Relative links make a documentation bundle portable, but only when the referenced paths travel with it. Root-relative links depend on a particular website and may break in a PDF or ebook.
Write alternative text that communicates the image's purpose. Decorative images should be identified as decorative in the publishing workflow rather than receiving meaningless filler text.
- Use descriptive link labels instead of “click here.”
- Keep asset filenames stable and avoid case-only path differences.
- Check fragments after renaming headings because generated IDs can differ by renderer.
Use extensions deliberately
Fenced code blocks are widely understood and let you declare a language for highlighting. Tables and task lists are useful GFM extensions, but they are not part of core CommonMark.
When a table becomes too wide or contains paragraphs, lists, or merged cells, a sequence of headings and definition-style blocks is often more accessible than forcing the content into a grid.
- Indent nested list items consistently.
- Fence code that contains Markdown punctuation.
- Add a short introduction before complex tables.
- Preview with the same profile used by the destination.
A five-minute portability check
Before sharing a source file, inspect its profile, heading outline, links, assets, encoding, and line endings. The merger's portable composition ZIP can include assets you attach; the editor's general document bundle currently packages Markdown sources, not companion assets.
- The selected Markdown profile ID is recorded in the workspace or bundle manifest.
- The source does not depend on unsafe raw HTML or executable MDX.
- Every relative asset needed by a composition is attached and present in the merger's portable ZIP.
- Automated diagnostics are resolved and links, image text, and glyph coverage have also been reviewed manually.
- A rich server output has its warning and validator summary available with the job metadata.