Markdown basics for documentation

Markdown exists because most documents are prose with occasional structure, and wrapping prose in tags makes it harder to write and review. The core syntax is small: hash marks for headings, asterisks or underscores for emphasis, hyphens for lists, backticks for code, and square brackets with parentheses for links.

The extensions you will actually use

GitHub Flavored Markdown adds tables, fenced code blocks with language hints, task lists, strikethrough, and autolinks. These are the features most static site generators assume, so treating GFM as the baseline avoids surprises when content moves between tools.

Where Markdown stops

Attributes, ARIA roles, and component markup have no Markdown syntax. That is the moment to drop into raw HTML for one block rather than fighting the parser—and to check whether your renderer permits inline HTML at all.

Sanitisation is not optional

Because most renderers pass raw HTML through, Markdown from untrusted authors is an injection vector. Render through a sanitiser that strips script tags, event handlers, and dangerous URL schemes before the output reaches a page.

Reviewability is the real benefit

Markdown diffs cleanly line by line, which is why documentation lives better in a repository than in a rich-text editor. Keep one sentence per line if your team reviews prose closely.

Preview safely

Check rendering with Markdown Preview, escape markup with HTML Encode/Decode, and compare the two authoring formats in Markdown vs HTML.