Guide

Style rules for Markdown that becomes a printed document

Markdown for a README is not the same as Markdown for a client proposal. The rules below are for documents — proposals, reports, white papers — that will be exported, printed, signed.

By Elia Kuratli

Updated May 7, 2026·4 min read

Open the converter

Headings

One H1 per major section. In documents, H1 reads as "chapter."
H2 for subsections, H3 sparingly. Avoid H4+ — if you need four levels of nesting, the section is doing too much.
Capitalize headings as sentences, not as titles. "Hosting and infrastructure" not "Hosting And Infrastructure."
Turn on numbered headings for proposals, audits and contracts — so the reader can reference 2.3 in an email.

Paragraphs

One idea per paragraph. Two to four sentences. A paragraph longer than five sentences usually wants to be two paragraphs.
Lead with the result, then the supporting evidence. The first sentence of a paragraph is the only sentence the busy reader reads.

Lists

Use lists for genuinely list-shaped content (deliverables, risks, terms). Do not use lists to break up prose.
If three out of five list items are one word and the other two are paragraphs, you have prose pretending to be a list. Convert it back.
Numbered lists imply order or priority. Use them when order matters. Otherwise: bullets.

Emphasis

Bold for terms the reader needs to pick out at a glance. One bold per paragraph, max.
Italic for titles of works, foreign phrases, and emphasis on a specific word. Not for entire sentences.
Strikethrough is for tracked changes. In a final document, edit the source instead.

Tables

Header row + 2-10 body rows is the readable range.
Numeric columns auto-right-align in this tool. Don't fight it with whitespace tricks.
For pricing tables, make the last row a Total row (sidebar toggle). Anchor the bottom of the table.

Code blocks

Fenced with the language tag. The tag shows up as a small label in the top-right corner of the block in the PDF.
Inside a document, code blocks are quotations of running code or shell commands. Keep them under 14 lines so they don't split.