THE GITHTML FIELD GUIDE
HTML vs Markdown for technical documents: how to choose
Write in Markdown when the document is mostly prose, lists, and simple tables that teammates will edit often. Produce HTML when the reading copy needs controlled layout, spanning tables, inline styles, embedded diagrams, or must look the same outside a Markdown renderer. Many teams author in Markdown and commit a generated HTML reading copy for documents that travel.
What each format actually guarantees
Markdown is a source format. CommonMark defines a precise core syntax for headings, emphasis, lists, links, code, and block quotes, and lets raw HTML pass through. Tables, task lists, and strikethrough come from extensions such as GitHub Flavored Markdown. How a Markdown file finally looks depends on the renderer and the stylesheet it applies.
HTML is the output format browsers read. A complete HTML document carries its own structure, metadata, and styling, so it looks largely the same wherever a browser engine opens it. That control is useful for reports, and it is also why HTML is more verbose and less pleasant to edit by hand.
Where Markdown runs out
GFM tables have no syntax for merged cells, so a comparison that needs rowspan or colspan falls back to a raw HTML table. Styling is up to the host: GitHub sanitizes rendered Markdown, removing scripts, inline styles, and class or id attributes, so color-coded status labels or a custom layout will not survive there. The GFM tagfilter extension also neutralizes tags such as style, script, iframe, and textarea.
Some HTML passes through helpfully. GitHub documents the details and summary elements for collapsible sections inside Markdown, which is a good way to hide long logs or appendices without leaving the format.
A decision checklist
Answer these questions about the document in front of you, not about your documentation system in general. A single repository can reasonably contain both formats: Markdown for contributor notes and HTML for the quarterly architecture review that executives read on a phone.
- Will several people edit it weekly in pull requests? Favor Markdown for readable diffs.
- Does it need merged table cells, side-by-side panels, or precise typography? Favor HTML.
- Will it be read outside GitHub, offline, or on a phone app that renders HTML? Commit an HTML reading copy.
- Does it include generated output such as charts, coverage, or query plans? Produce HTML from the tool that generates it.
- Is the content short-lived meeting material? Keep the source format and skip conversion.
Use both without drift
If you author in Markdown and publish HTML, treat the HTML as a build output with a recorded source revision. Convert with a tool you can run locally, embed the stylesheet so the file stands alone, and regenerate it in the same commit as the source change. A provenance line at the top of the HTML makes stale copies obvious.
gitHtml reads the HTML file, not the Markdown source, so the conversion step is what makes a Markdown document available as a polished reading copy on iPhone or iPad.
pandoc docs/architecture.md \
--standalone --embed-resources \
--metadata title="Architecture overview" \
--css docs/reading.css \
-o docs/architecture.html
# Record the source revision inside the output, for example:
# <p class="provenance">Generated from docs/architecture.md at commit 3f9c2ab</p>Sources and further reading
- CommonMark Spec 0.31.2
- GitHub Flavored Markdown Spec
- github/markup: rendering and sanitization notes
- GitHub Docs: Organizing information with collapsed sections
AI-assisted writing with source-linked guidance and illustrative examples. Read our editorial approach or report a correction.