Mastering Markdown: Syntax, Tips, and Common Mistakes

· 8 min read

Markdown has become the lingua franca of developer documentation. From GitHub READMEs to Notion pages, from Slack messages to static site generators, Markdown's promise is simple: write plain text with minimal syntax, and it renders into clean, structured HTML. But despite its apparent simplicity, Markdown has enough quirks, inconsistencies, and platform-specific extensions that even experienced developers regularly produce broken or poorly rendered output.

This guide covers everything you need to write Markdown confidently: the core syntax, GitHub Flavored Markdown (GFM) extensions, the most common rendering mistakes and how to avoid them, and best practices for writing READMEs and technical documentation that people actually want to read.

Core Markdown Syntax

John Gruber created Markdown in 2004 as a lightweight markup language that prioritizes readability in its raw text form. The original specification is intentionally minimal — here is every element you need to know:

Headings

Headings use # symbols. The number of # characters determines the heading level (h1 through h6):

# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6

Always put a space after the # characters. Most parsers require this, and omitting it is the most common heading-related mistake. Also, use headings hierarchically — do not skip from ## to ####, as this breaks document outline structure and accessibility.

Emphasis and Strong

*italic text* or _italic text_
**bold text** or __bold text__
***bold and italic*** or ___bold and italic___
~~strikethrough~~ (GFM extension)

Prefer asterisks (*) over underscores (_) for emphasis. Underscores inside words (like some_variable_name) can be misinterpreted by some parsers, while asterisks never cause this issue.

Links and Images

[Link text](https://example.com)
[Link with title](https://example.com "Title text")

![Alt text](image.png)
![Alt text](image.png "Optional title")

Always include meaningful alt text for images. For links, the visible text should describe the destination — avoid "click here" patterns. You can also use reference-style links to keep your source text cleaner when the same URL appears multiple times:

Read the [official docs][docs] for more details.
See also the [API reference][docs].

[docs]: https://example.com/documentation

Code

Inline code uses single backticks. Code blocks use triple backticks (fenced code blocks) with an optional language identifier for syntax highlighting:

Inline: Use `console.log()` for debugging.

Fenced block:
```javascript
function greet(name) {
  return `Hello, ${name}!`;
}
```

The language identifier after the opening backticks (javascript, python, bash, json, etc.) enables syntax highlighting on platforms that support it. Always include it — there is no good reason to omit it when you know the language.

Lists

Unordered (use -, *, or +):
- Item one
- Item two
  - Nested item (indent 2 spaces)
  - Another nested item

Ordered:
1. First item
2. Second item
3. Third item

For ordered lists, you can actually number every item as 1. and the renderer will auto-number them correctly. This makes reordering items easier since you do not need to renumber. However, using sequential numbers improves readability of the raw text.

Blockquotes

> This is a blockquote.
> It can span multiple lines.
>
> It can also have multiple paragraphs.

Horizontal Rules

---
***
___

All three produce an <hr> element. Use --- consistently. Be careful with --- directly after text — some parsers interpret this as a setext-style heading instead of a horizontal rule. Add a blank line before the --- to be safe.

GitHub Flavored Markdown (GFM) Extensions

GitHub Flavored Markdown adds several widely-adopted extensions to the original spec. Most modern Markdown renderers support these, but be aware that they are not part of the core specification and may not render on all platforms.

Tables

| Feature    | Status | Priority |
|------------|--------|----------|
| Dark mode  | Done   | High     |
| Export PDF | WIP    | Medium   |
| Analytics  | Planned| Low      |

Alignment:
| Left   | Center  | Right |
|:-------|:-------:|------:|
| data   | data    | data  |

Tables in Markdown are intentionally simple. For complex tables with merged cells, column spans, or nested content, you are better off embedding raw HTML.

Task Lists

- [x] Design database schema
- [x] Implement API endpoints
- [ ] Write integration tests
- [ ] Deploy to staging

On GitHub, these render as interactive checkboxes that collaborators can toggle. They are excellent for tracking progress in issues and pull request descriptions.

Autolinks and Mentions

GFM automatically converts bare URLs into clickable links. It also supports @username mentions, #123 issue references, and commit SHA references within the GitHub ecosystem.

Footnotes

This claim needs a source[^1].

[^1]: Smith, J. (2024). "The Source." Journal of Examples.

Write and preview your Markdown in real time with our free Markdown Preview tool — side-by-side editing with instant rendering.

Open Markdown Preview →

Common Markdown Mistakes

These are the issues that generate the most confusion and broken rendering:

1. Missing Blank Lines

Markdown requires blank lines to separate block-level elements. Without them, elements run together or are interpreted as inline text:

WRONG (heading merges with paragraph):
## My Heading
This paragraph starts immediately.

CORRECT:
## My Heading

This paragraph is properly separated.

This applies to headings, paragraphs, lists, code blocks, and blockquotes. When in doubt, add a blank line.

2. Incorrect List Indentation

Nested lists require consistent indentation, but the exact amount varies by parser. Some require 2 spaces, others 4. For maximum compatibility, use 2 spaces for unordered lists and 3 spaces (to align with content after 1. ) for ordered lists. Mixing tabs and spaces is a recipe for broken rendering.

3. Breaking Out of Code Blocks

If your code contains triple backticks, the fenced code block will close prematurely. The solution is to use a longer fence — four or more backticks:

````markdown
Here is a code block inside a code block:
```javascript
console.log("hello");
```
````

4. Special Characters in Links

Parentheses in URLs break the link syntax because Markdown uses () to delimit the URL. Encode parentheses as %28 and %29, or use angle bracket syntax:

BROKEN:
[Wiki](https://en.wikipedia.org/wiki/Markdown_(language))

FIXED (encoding):
[Wiki](https://en.wikipedia.org/wiki/Markdown_%28language%29)

FIXED (angle brackets):
[Wiki](<https://en.wikipedia.org/wiki/Markdown_(language)>)

5. HTML Entity Confusion

Characters like <, >, and & have special meaning in HTML. In most contexts Markdown handles these transparently, but inside inline code or when mixing Markdown with raw HTML, you may need to use HTML entities (&lt;, &gt;, &amp;) to render them correctly.

Writing Better READMEs

A README is often the first — and sometimes only — documentation a user reads. Here is a proven structure for project READMEs that covers what users actually need:

  1. Project title and one-line description. What is this, in one sentence?
  2. Badges (optional). Build status, version, license — keep them relevant and up to date.
  3. Quick start. The fastest path from zero to a working example. Ideally 3–5 commands.
  4. Installation. Prerequisites, package manager commands, environment setup.
  5. Usage. Code examples showing the most common use cases. Real-world examples are far more useful than API dumps.
  6. Configuration. Environment variables, config files, command-line flags.
  7. Contributing. How to set up a development environment, run tests, submit PRs.
  8. License. State the license clearly and link to the full text.

The key principle: optimize for the reader's time. Put the most-needed information first. Use headings so people can skip to what they need. Keep code examples copy-pasteable — a user should be able to select a code block, paste it into their terminal, and have it work.

Tips for Technical Documentation

Beyond READMEs, Markdown is the standard for documentation sites (Docusaurus, MkDocs, VitePress, GitBook). Here are practices that scale:

  • One topic per page. Long pages that cover multiple unrelated concepts are difficult to navigate, link to, and maintain.
  • Lead with the "why." Before explaining how a feature works, explain when and why someone would use it.
  • Use admonitions/callouts. Most doc platforms support special syntax for notes, warnings, and tips. Use them to highlight important information without cluttering the main text flow.
  • Keep code examples minimal but complete. Show enough code that someone can understand and run the example, but omit boilerplate that distracts from the point.
  • Link liberally. Cross-reference related pages. If you mention a concept that is explained elsewhere, link to it. Do not make readers search for definitions.
  • Test your examples. Nothing erodes trust in documentation faster than code examples that do not work. Automate testing of documentation code snippets where possible.

Markdown Tooling

A few tools that improve the Markdown writing experience significantly:

  • markdownlint — A linter that catches common mistakes like inconsistent heading levels, trailing whitespace, and missing blank lines. Available as a CLI tool and VS Code extension.
  • Prettier — Auto-formats Markdown files with consistent spacing, wrapping, and list indentation.
  • Live preview editors — Side-by-side editing and rendering lets you catch formatting issues immediately rather than after committing. TensorLocal's Markdown Preview provides this in the browser with no setup required.

Conclusion

Markdown's simplicity is what makes it universal, but that same simplicity means the difference between well-rendered and broken output often comes down to a single blank line or an extra space character. Learn the core syntax thoroughly, understand which extensions your target platform supports, and use a linter to catch the mechanical mistakes. Most importantly, focus on the content — clean formatting is worthless if the writing itself does not communicate clearly.

If you want to experiment with Markdown syntax and see results instantly, try our Markdown Preview tool. Paste your content, see the rendered output in real time, and iterate until it looks exactly right.