Writing Technical Docs in Markdown: A Style Guide

Quick answer

A technical documentation Markdown style guide is a short, enforced set of rules for how your docs use headings, code, lists, tables, and links. Follow it, and a doc written by one person reads the same as a doc written by five. The safest baseline is GitHub Flavored Markdown (GFM), a strict superset of CommonMark: every plain CommonMark file still renders correctly, plus you get tables, task lists, and strikethrough that technical docs actually need. This guide covers heading structure, code and tables, link conventions, the mistakes that break consistency across a team, and how to keep the whole thing manageable in an editor built for it.

Step-by-step

Heading hierarchy that scales

Reserve exactly one H1 for the document title and start body content at H2. Nest H3 under H2 for sub-points, and don't skip a level — going straight from H2 to H4 breaks the outline a reader (and a table-of-contents generator) relies on. Sentence-style capitalization ("Configuring the build cache," not "Configuring The Build Cache") keeps headings easy to scan and consistent from doc to doc.

If a section needs a fourth level of nesting, that's usually a sign the doc should split into two. For long references, keeping headings navigable matters more than cramming everything into one file.

Code fences over indentation

Always tag the language on a fenced code block:

git status

The tag turns on syntax highlighting and tells both readers and tooling what they're looking at — plain four-space indentation can't do either. Reserve single backticks for inline references: file names, command names, config keys, short code terms inside a sentence.

Tables and task lists

Tables and task lists are GFM extensions, not core CommonMark. Lean on them deliberately when a doc might render somewhere that only supports the plain CommonMark baseline. A GFM table needs a header row and a delimiter row of hyphens; colons in the delimiter row control column alignment:

| Command | What it does |
| --- | --- |
| `git status` | Shows changed files |
| `git diff` | Shows unstaged changes |

Task lists use - [ ] and - [x] inside a normal list. They're useful for a setup doc's checklist or a migration guide's steps, anywhere a reader wants to track progress inline.

Link text and cross-references

Match link text to the destination's actual title, and skip vague anchors like "click here" — a reader scanning a doc for the next step should be able to tell where a link goes from the words alone. Choose inline versus reference-style links based on length: inline links ([text](url)) are easiest to read for short URLs, while reference-style links keep a paragraph readable when the destination URL is long or reused across the doc.

Common problems and fixes

Ambiguous heading levels. Underline-style (Setext) headings only support two levels and are easy to misjudge at a glance. Standardize on ATX-style # headings instead — the level is explicit in the source, not inferred from how long the underline is.

Inconsistent list punctuation. A list where some items are full sentences with periods and others are fragments without them reads as sloppy, even when the content underneath is solid. Pick one rule per list: if any item is a complete sentence, punctuate every item; if all items are short phrases, drop the periods across the board.

Numbered lists that break on reorder. In a doc that changes often, renumbering every item after inserting a new step wastes time and produces noisy diffs. Use "lazy numbering" instead — repeat 1. for every item — and let the renderer number them sequentially.

Docs that drift apart across a team. The moment more than one person writes docs, small inconsistencies creep in: mixed heading styles, untagged code fences, mismatched link conventions. The fix isn't more review time. It's to lint your Markdown for consistency as part of the normal editing pass, the same way you'd run a formatter on code.

Doing this with Carets

A style guide only helps if the tool you're writing in makes it easy to follow. Carets is a native Markdown and plain-text editor for iPhone, iPad, and Mac, built for exactly this kind of writing: fenced code blocks with real syntax highlighting as you type, so a wrongly-tagged language stands out immediately instead of surfacing later in review. Docs live in files, projects, and tags, so a multi-file style guide — API reference, contributor guide, README — stays organized instead of scattered across apps.

Because Carets keeps everything in plain Markdown, your docs stay portable: no proprietary format to export from, no lock-in to one app's renderer. Get Carets on the App Store for iPhone, iPad, and Mac.

Frequently Asked Questions

Should I use CommonMark or GitHub Flavored Markdown for technical docs?

Use GFM as your baseline. It's a strict superset of CommonMark, so everything you write still renders correctly anywhere CommonMark is supported, and you additionally get tables, task lists, and strikethrough that most technical docs actually need.

How many heading levels should a technical doc use?

Reserve one H1 for the document title, then use H2 for major sections and H3 for sub-points, without skipping a level. Going past three levels usually means the doc should be split instead.

Do fenced code blocks need a language tag?

Yes. Declaring the language after the opening triple backticks turns on syntax highlighting and tells readers and tooling what they're looking at, which plain four-space indentation can't do.

What's the difference between inline and reference-style links in Markdown?

Inline links ([text](url)) keep the URL next to the text and are easiest to read for short links. Reference-style links ([text][1] with the URL defined elsewhere) keep long URLs from cluttering a paragraph, which matters more as a doc grows.