Most developers know the basics of Markdown: # for headers, ** for bold, * for italic, - for lists. But Markdown has features that many people use daily without ever discovering. I write everything in Markdown -- documentation, blog posts, project proposals, meeting notes -- and I still find syntax I had overlooked. Here are the features that made the biggest difference in my writing once I learned them.
Tables
Markdown tables look like ASCII art, but they render into clean HTML tables:
| Method | Endpoint | Description |
|--------|----------------|--------------------|
| GET | /api/users | List all users |
| POST | /api/users | Create a user |
| DELETE | /api/users/:id | Delete a user |
You can align columns by adding colons to the separator row:
| Left | Center | Right |
|:-------|:-------:|-------:|
| data | data | data |
Left-aligned is the default. A colon on the right gives you right-alignment. Colons on both sides give you center-alignment. This is particularly useful for numerical data where right-alignment makes columns scannable.
The cells do not need to line up perfectly in the source. This renders identically:
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/users | List all users |
But aligning them makes the source readable, which matters when other people edit the file.
Task lists
GitHub Flavored Markdown (GFM) supports interactive checkboxes:
- [x] Set up database
- [x] Create API endpoints
- [ ] Write integration tests
- [ ] Deploy to staging
These render as actual checkboxes in GitHub issues, PRs, and README files. On GitHub, you can click them directly in the rendered view to toggle their state. This is the simplest way to add a checklist to a pull request description or issue body.
Collapsible sections
HTML inside Markdown is valid in most renderers. The <details> and <summary> tags create collapsible sections:
<details>
<summary>Click to expand error log</summary>
Error: ECONNREFUSED 127.0.0.1:5432
at TCPConnectWrap.afterConnect [as oncomplete]
</details>
This is invaluable in bug reports and documentation where you need to include long logs, configuration files, or stack traces without overwhelming the reader. GitHub, GitLab, and most Markdown renderers support it.
Important: you need a blank line between the <summary> closing tag and the Markdown content inside for the Markdown to render correctly.
Footnotes
Not supported everywhere, but GitHub, Obsidian, and many static site generators handle footnotes:
DNS resolution typically takes 20-120ms[^1].
[^1]: Measured using dig against public resolvers from US-East.
The footnote reference renders as a superscript link, and the note itself appears at the bottom of the document. This keeps your paragraphs clean while still providing sources or additional context.
Definition lists
Some Markdown processors (including PHP Markdown Extra and Pandoc) support definition lists:
DNS
: Domain Name System. Translates domain names to IP addresses.
TTL
: Time To Live. How long a DNS record is cached.
This renders as a <dl> element with <dt> and <dd> tags. It is cleaner than using bold text and line breaks to simulate definitions.
Fenced code blocks with highlighting
Everyone knows triple backticks create code blocks. But specifying the language after the opening backticks enables syntax highlighting:
```
python
def fibonacci(n):
if n <= 1:
return n
return fibonacci(n - 1) + fibonacci(n - 2)
```
```
`
The language identifiers follow common conventions: `javascript` or `js`, `python` or `py`, `typescript` or `ts`, `bash` or `shell`, `sql`, `json`, `yaml`, `css`, `html`, `go`, `rust`, `java`, `csharp` or `cs`.
For command output or plain text where highlighting is wrong, use `text` or `plaintext`:
`
```markdown
```
text
BUILD SUCCESSFUL in 4s
3 actionable tasks: 3 executed
```
```
`
## Linking tricks
**Reference-style links** keep long URLs out of your prose:
```markdown
Read the [contributing guide][contrib] before submitting a PR.
[contrib]: https://github.com/org/repo/blob/main/CONTRIBUTING.md
```
The reference can be placed anywhere in the document. This makes paragraphs much more readable in the source.
**Automatic links.** Most renderers auto-link bare URLs, but wrapping them in angle brackets guarantees it:
```markdown
<https://example.com>
```
**Section links.** In GitHub Markdown, every heading gets an anchor. You can link to any section:
```markdown
See the [Installation](#installation) section below.
```
The anchor is the heading text, lowercased, with spaces replaced by hyphens and special characters removed. "Getting Started" becomes `#getting-started`.
## Images with sizing
Standard Markdown images have no size control:
```markdown
```
To control dimensions, use HTML:
```markdown
<img src="image.png" alt="Alt text" width="400">
```
GitHub renders this correctly. For centered images:
```markdown
<p align="center">
<img src="logo.png" alt="Logo" width="200">
</p>
```
## Common formatting mistakes
**Not leaving blank lines around block elements.** Headers, code blocks, lists, and block quotes need a blank line before and after them in most renderers. Without the blank line, the element may not render correctly:
```markdown
Some text.
# This heading might not render
More text.
```
**Nested list indentation.** Different Markdown processors require different amounts of indentation for nested lists. Two spaces work in some, four spaces in others. GitHub uses two. When in doubt, use four -- it works everywhere.
**Escaping characters.** If you need to display literal Markdown syntax characters, escape them with a backslash: `\*not italic\*`, `\# not a heading`.
For writing and previewing Markdown with real-time rendering, especially when working with tables, code blocks, and nested structures, I use a Markdown editor at [zovo.one/free-tools/markdown-editor](https://zovo.one/free-tools/markdown-editor/) that shows the rendered output side by side with the source.
Markdown's power is in its simplicity, but that simplicity goes further than most people explore. Learn the features beyond the basics and your documentation will be clearer, your issues will be more informative, and your README files will stand out.
---
I'm Michael Lip. I build free developer tools at zovo.one. 350+ tools, all private, all free.
Top comments (0)