Markdown is the lingua franca of developer documentation — READMEs, GitHub issues, Notion pages, Discord messages, dev.to posts. Most developers know the basics (headings, bold, links, lists). This guide covers the syntax you probably missed: tables, task lists, nested lists, fenced code blocks, and the common pitfalls that make your rendered docs look broken.
1. Fenced code blocks with language hints
Triple backticks create a code block. Adding a language identifier after the opening fence enables syntax highlighting on most renderers (GitHub, GitLab, VS Code, Notion):
```typescript
interface User {
id: string
email: string
}
const user: User = { id: "1", email: "ada@example.com" }
```Always specify the language. "ts" works, but "typescript" is more portable across renderers. Common short codes: js, ts, py, go, rust, bash, json, yaml, html, css, sql, diff.
2. Tables
Tables are one of Markdown’s most underused features. The syntax is simple once you see it:
| Tool | Category | Free |
|----------------|------------|:----:|
| QR Generator | generator | yes |
| JSON Formatter | developer | yes |
| Password Gen | generator | yes |The colons in the separator row control alignment: `:---` left, `---:` right, `:---:` center.
Writing tables by hand is error-prone. Use a Markdown Table Generator to build them visually — type your rows, adjust alignment, copy the output.
3. Task lists
GitHub, GitLab, and most modern renderers support checkboxes:
- [x] Set up the project
- [x] Write the API
- [ ] Add tests
- [ ] DeployIn GitHub issues and PRs, these render as interactive checkboxes — checking one updates the source markdown automatically. Great for tracking sub-tasks in a single issue.
4. Nested lists
Indent by 2 or 4 spaces (be consistent) to nest:
- Frontend
- React
- Vue
- Svelte
- Backend
- Node.js
- Python
- GoCommon pitfall: mixing tabs and spaces for indentation. Most renderers handle 2 or 4 spaces; tabs often break. Pick one and stick to it.
5. Links: inline, reference, and autolinks
Three ways to write links, each with a use case:
<!-- Inline: best for one-off links -->
[ToolKit Pro](https://atlas-ai-bot.vercel.app)
<!-- Reference: best when you reuse the same URL -->
See [the docs][docs] and [the API][docs].
[docs]: https://atlas-ai-bot.vercel.app/docs
<!-- Autolink: bare URL -->
https://atlas-ai-bot.vercel.app
<!-- Autolink with email (most renderers) -->
<support@example.com>6. Images with alt text and titles
The alt text matters for accessibility (screen readers) and SEO (image search). The optional title in quotes shows as a tooltip on hover.
7. Blockquotes (and nested blockquotes)
> This is a quote.
>
> > And this is a nested quote.
>
> Back to the first level.Use blockquotes for callouts, citations, or to highlight a key point. Most renderers style them with a left border and muted text.
8. Horizontal rules
---
or
***
or
___Three or more hyphens, asterisks, or underscores on a line create a horizontal rule. Useful for separating major sections in a long README.
9. Strikethrough, highlight, and other extensions
GitHub Flavored Markdown (GFM) adds several formatting extensions beyond base Markdown:
~~strikethrough~~
==highlight== (not in GFM, but supported in some renderers)
**bold** and _italic_ and ***both***
`inline code`10. Escaping special characters
To show a literal asterisk, underscore, or backtick, prefix with a backslash:
Use \* for a literal asterisk, not a bullet.
Use \_ for a literal underscore.
Use \` for a literal backtick.Common pitfall: "C:\Users\ada" in a Markdown doc. The backslashes disappear. Write "C:\\Users\\ada" or wrap it in inline code: `C:\Users\ada`.
11. Line breaks
Two trailing spaces at the end of a line create a hard line break (a <br> in HTML). One trailing space does nothing. An empty line between paragraphs creates a new paragraph. This trips people up constantly — soft-wrapped text in your editor does not produce line breaks in the rendered output.
12. Always preview before you publish
Markdown has dozens of dialects (CommonMark, GFM, MultiMarkdown, Pandoc, MDX). What renders perfectly on GitHub may break in Notion or your static site generator. Always preview your Markdown in the target renderer before publishing.
Use a Markdown Preview tool that renders side-by-side as you type — it catches broken tables, mismatched code fences, and missing line breaks before they hit production.
The takeaway
Markdown is more powerful than most developers realize. Tables, task lists, nested lists, reference links, and language-hinted code blocks transform a wall of text into structured documentation. Use the Markdown Table Generator for tables, the Markdown Preview tool to catch rendering issues before you publish, and you will ship cleaner docs with less effort.