Markdown for Technical Documentation

The Formatting Frustration

You are writing documentation. You want a simple bulleted list. You spend 10 minutes fighting with a word processor's formatting.

You want to add a code example. The syntax highlighting is wrong. The font is wrong. The indentation is wrong.

Markdown solves this. You write in plain text. Simple symbols control formatting. It just works.

What is Markdown?

Markdown is a lightweight markup language. You write in plain text using simple symbols to indicate formatting.

It was created in 2004 by John Gruber. The goal was readability: a Markdown document should be publishable as-is, as plain text, without looking like it is marked up with tags or formatting instructions.

Today, Markdown is everywhere. GitHub, Reddit, Stack Overflow, Notion, and many more platforms support it.

Basic Markdown Syntax

Here are the most common formatting options:

Structure the Document

Start with one H1 for the title, H2 for major sections, and H3 for subsections. Do not skip levels: jumping from H2 to H4 confuses readers and breaks the table of contents.

Most renderers build a table of contents automatically from the headings, so descriptive headings make the TOC a usable map. I planned a 4,000-word API guide from an outline like this; it took twenty minutes and nothing drifted.

# Project Name
## Installation
### From npm
## Configuration
### Environment variables

• One H1 per document, reserved for the title
• Consistent levels: major sections H2, subsections H3
• Keep headings descriptive so the TOC is self-explanatory

Code Blocks with Language Hints

Fenced code blocks start and end with three backticks. Add the language right after the opening fence, like ```js or ```bash, and most renderers apply syntax highlighting automatically.

The hint matters even without highlighting; some platforms use it for linting or a copy button. Indentation inside the fence is preserved exactly, so keep the source tidy.

```js
const crypto = require('crypto');
const hash = crypto.createHash('sha256');
hash.update('message');
console.log(hash.digest('hex'));
```

• Close every fenced block; an unclosed fence swallows the rest of the document
• Leave a blank line before lists and code blocks
• Keep the table separator row directly under the header

Tables, Admonitions, and Images

Tables come from GitHub Flavored Markdown: a header row, a dashed separator row, and data rows. Colons in the separator row set left, center, or right alignment.

Admonitions, the colored note boxes in many docs, are not standard Markdown. GitHub renders `> [!NOTE]` and `> [!WARNING]`, and generators like Vitepress support similar callouts, but check the target platform first.

Images use link syntax with a leading exclamation mark: ![Alt text](path/to/image.png). Use descriptive alt text and relative paths, so images survive clones and branch switches.

> [!NOTE]
> This feature requires Node.js 18 or newer.
| Output | Bytes |
| --- | ---: |
| sha256 | 32 |
| sha512 | 64 |

Preview Locally Before You Publish

Renderers disagree in small ways, so look at the output. Paste the document into the Markdown Preview and check the result before it lands in a repo or CMS.

1. Write the document, one heading level at a time.
2. Open the Markdown Preview and paste the source.
3. Test the same source on the final platform, because renderers differ.

Why Use Markdown?

Markdown has several advantages over traditional word processors:

• Portable - Plain text works on every device, forever
• Version control friendly - Git can diff Markdown files easily
• Fast to write - No mouse needed, keep your hands on the keyboard
• Converts to anything - HTML, PDF, DOCX, slides, and more
• Future proof - Plain text never becomes obsolete
• Distraction free - Focus on content, not formatting

Markdown Flavors

There are many variations of Markdown, called 'flavors'. They add features to the original specification.

GitHub Flavored Markdown (GFM) adds tables, task lists, and strikethrough. It is the most popular flavor.

CommonMark is a standardized version that aims to resolve ambiguities in the original specification.

MultiMarkdown adds footnotes, citations, and mathematical formulas. Popular in academic writing.

FAQ

References

• CommonMark Specification: https://spec.commonmark.org/
• GitHub Flavored Markdown Spec: https://github.github.com/gfm/
• RFC 7764 – Guidance on Markdown: https://www.rfc-editor.org/info/rfc7764/
• MDN – Markdown writing guidelines: https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines/Howto/Markdown_in_MDN
• Original Markdown syntax (John Gruber): https://daringfireball.net/projects/markdown/syntax