A complete reference guide to Markdown syntax, with best practices for READMEs, pull request descriptions, and technical documentation.
Every developer writes documentation. README files, pull request descriptions, Jira tickets, internal wikis, Notion pages: they all use Markdown. But most developers learn just enough syntax to get by and never discover the features that make their documentation stand out.
This guide covers everything from the basics to the professional patterns that make documentation easy to read, easy to maintain, and easy to find.
Markdown is the universal language of developer documentation. GitHub, GitLab, Bitbucket, Notion, Linear, Confluence, Jira, and Slack all render Markdown. When you write clear, well-structured documentation, your teammates can understand your work without asking you to explain it. That visibility compounds over time: a developer who writes good documentation gets noticed in ways that a developer who only writes good code does not.
Markdown has two key advantages over other formats. First, it is plain text, so it works in any editor, travels through version control without binary conflicts, and renders in any Markdown viewer. Second, the syntax is minimal enough to read without rendering: a file full of # and ** is still legible.
Headers create the structure and hierarchy of a document. They work exactly like the headings you see on any webpage: the browser (or Markdown renderer) makes them larger and bolder than body text, and each level is smaller than the one above it.
The number of # symbols sets the level: one # gives you the largest heading (H1), six ###### gives you the smallest (H6). Each extra # drops you one level down in the hierarchy.
In practice, most README files only use H1 through H3. H1 is the project name — there should only ever be one per document. H2 breaks the document into major sections like Installation, Usage, and Contributing. H3 breaks those sections into subsections. H4 through H6 exist but are rarely needed; if you find yourself using H5, the document probably needs restructuring rather than more nesting.
Bold and italic are the two formatting tools you will use most. Strikethrough is useful in task lists and changelogs.
| Format | Syntax | Result |
|---|---|---|
| Bold | **bold** | bold |
| Italic | *italic* | italic |
| Bold + italic | ***bold and italic*** | bold and italic |
| Strikethrough | ~~strikethrough~~ |
Separate paragraphs with a blank line. A single newline inside a paragraph is ignored. To force a line break within a paragraph, end the line with two spaces or a backslash (\).
The link syntax is [text](url). The text in brackets is what the reader sees and clicks — it can be anything, completely independent from the URL. You can also add a tooltip that appears on hover by putting a title in quotes after the URL: [text](url "Tooltip text").
Images use the same syntax as links but with a leading !. The text in brackets is the alt text, which is displayed when the image cannot be loaded and is read by screen readers.
Use -, *, or + as bullet markers. The marker must be followed by a space.
Use numbers followed by a period. Each item gets its own number.
Indent with two or four spaces to create nested items.
Task lists are one of the most useful features in GitHub Flavored Markdown. They render as interactive checkboxes in GitHub issues, pull requests, and project descriptions.
Wrap code in single backticks for inline formatting. Use it for variable names, file paths, commands, and short snippets.
Use triple backticks to create a code block. Add the language name after the opening backticks to enable syntax highlighting. This is one of the most visible improvements you can make to your documentation.
Supported languages include: python, javascript, typescript, bash, sql, json, yaml, go, rust, java, and many more.
Use diff as the language to show additions and removals. Prefix lines with + for additions and - for removals.
Diff blocks are most useful in pull request descriptions and changelogs. The clearer your commit messages, the more context your diffs carry. Git Commit Messages guide.
Tables use pipe characters (|) as column separators. The second row contains the alignment markers: --- for left (default), :---: for center, ---: for right.
You do not need to align the pipes manually. Markdown renderers ignore the extra whitespace.
Use > to create a blockquote. Blockquotes are useful for callouts, warnings, notes, and quoting other documents.
GitHub supports styled alert blockquotes using [!NOTE], [!WARNING], [!TIP], [!IMPORTANT], and [!CAUTION] inside the blockquote.
GitHub Flavored Markdown (GFM) extends standard Markdown with features specifically useful for developer workflows.
On GitHub, certain references are automatically linked without any Markdown syntax. This makes pull request descriptions and issue comments much more scannable.
| Syntax | Result |
|---|---|
#123 | Links to issue or PR #123 |
user/repo#123 | Links to issue or PR in another repo |
@username | Mentions a user |
SHA1 hash (7+ chars) | Links to a commit |
These references are most useful in pull request descriptions and review comments. code review comments guide.
Use the HTML <details> element to create collapsible sections. This is useful for long outputs, stack traces, or configuration examples that would clutter the main text.
Footnotes are useful for adding references or clarifications without cluttering the main text.
Badges are the fastest way to communicate project health at a glance. Browse all available badges at shields.io/badges.
A README is the front door of your project. When someone lands on your repository, they spend about 30 seconds scanning the README before deciding whether to read further. Here is the structure that makes those 30 seconds count.
Once your README skills are solid, the same principles apply to longer technical documents. Writing a design doc in English.
| Syntax | Result |
|---|---|
# H1 / ## H2 / ### H3 | Headers |
**text** | Bold |
*text* | Italic |
~~text~~ | Strikethrough |
[text](url) | Link |
 | Image |
- item | Unordered list item |
1. item | Ordered list item |
- [x] task | Checked task list item |
- [ ] task | Unchecked task list item |
`code` | Inline code |
```lang\ncode\n``` | Code block with syntax highlighting |
> text | Blockquote |
| col | col | | Table row |
--- | Horizontal rule |
GitHub renders Mermaid diagrams natively inside Markdown code blocks. That means you can add flowcharts, sequence diagrams, and state diagrams to your README with nothing but code — no image exports, no external tools. Here are four examples from a real project:
The full course covers exactly how to add diagrams like these to your READMEs — including the syntax, the diagram types, and how to make them look good.

Written by
Roxana LafuenteLingua-e's founder
Roxana Lafuente is a software engineer with 8+ years of experience. At the beginning of her career, even though she had already passed the First Certificate in English, she still froze every time she had to speak up in the daily standup. That was a gap nobody was fixing. After 2,000+ standups, she figured out what actually builds fluency: practice that looks like your real work. She built Lingua-e so other developers wouldn't have to take the long road to feel confident working in an international development environment.
To improve your experience and analyze site usage. Privacy Policy