March 15, 2025 · 8 min read · MDTools Team

Markdown Formatting Guide — Rules, Tips & Best Practices

Markdown is easy to learn but easy to use inconsistently. This guide covers the rules, common mistakes, and best practices that separate clean, professional Markdown from messy, hard-to-maintain documents.

Why Markdown Formatting Matters

Markdown's greatest strength is its readability as plain text. But poorly formatted Markdown is harder to read in source form, renders inconsistently across different parsers, and creates friction when collaborating via Git. Good Markdown formatting means your documents look right everywhere — GitHub, VS Code, Notion, your converter, and any tool that might render it in the future.

Unlike a word processor where formatting mistakes are hidden in binary data, Markdown formatting mistakes are visible in source. That makes them easy to fix — if you know what to look for.

The Golden Rules of Markdown Formatting

1. One blank line between elements — Separate paragraphs, headings, lists, and code blocks with a single blank line. Missing blank lines cause parsers to merge elements unexpectedly.
2. Consistent markers — Choose one list marker (-, *, or +) and use it throughout your document. Don't mix them.
3. Never skip heading levels — Don't jump from H1 to H3. Screen readers and table of contents generators rely on a logical heading hierarchy.
4. One H1 per document — The H1 is the document title. Using more than one H1 confuses both readers and SEO tools.
5. Always specify the language in code blocks — ```python not just ```. This enables syntax highlighting in every renderer.
6. Use reference-style links for repeated URLs — If you link to the same URL multiple times, define it as a reference to avoid repetition and make updates easier.

Heading Hierarchy — How to Use H1, H2, H3 Correctly

Headings communicate document structure. They should form a logical outline, not just visual emphasis.

Correct heading hierarchy

# Document Title (H1 — one per document)

## Major Section (H2)

### Sub-topic (H3)

#### Detail (H4 — use sparingly)

## Another Major Section (H2)

Common heading mistakes

# Title
#### Skipped H2 and H3 ← WRONG: jumped from H1 to H4

# Another Title ← WRONG: second H1 in same document

## Section
## **Bold Section** ← WRONG: don't bold headings — heading level provides emphasis

Rule: Use heading levels to represent document structure, not to control font size. If you want a different visual size, use CSS — not a lower heading level.

Formatting Text — Bold, Italic, Strikethrough

Text formatting in Markdown is powerful but often overused. Here are the rules:

Bold (**text**)

Use bold for genuinely critical information — warnings, key terms on first use, UI element names. Do not use bold for general emphasis or to make text "look important". Overusing bold trains readers to ignore it.

**Warning:** This action cannot be undone.
Click the **Save** button to apply changes.
The `config.php` file contains your **SITE_URL** constant.

Italic (*text*)

Use italic for titles of works, technical terms on first use, and subtle emphasis. Avoid using italic for entire paragraphs.

This technique is called *lazy loading*.
See the *Getting Started* section below.
The file format is *application/json*.

Inline Code (`text`)

Use inline code for all of the following — consistently:

• File names: `config.php`, `README.md`
• Command names: `npm install`, `git commit`
• Variable and function names: `SITE_URL`, `convertToDocx()`
• Technical values: `true`, `null`, `200 OK`
• Keyboard shortcuts: `Ctrl+V`, `Cmd+K`

Line Breaks and Paragraphs in Markdown

This is one of the most commonly misunderstood aspects of Markdown formatting:

A single line break
does NOT create a new paragraph.

A blank line DOES create a new paragraph.

To force a line break within a paragraph,  
add two spaces at the end of the line.  
Like this.

Or use a backslash at the end:\
Like this.

Best practice: Use blank lines between paragraphs. Avoid relying on trailing spaces for line breaks (they're invisible and easy to accidentally delete). Use a <br> tag if you need a forced line break in a sensitive document.

Formatting Code — Inline vs Block

The rule is simple: use inline code for short references within prose, and use fenced code blocks for anything that requires more than one line.

Always add a language identifier

```javascript   ← Good: enables syntax highlighting
const x = 1;
```

```             ← Avoid: no language = no highlighting
const x = 1;
```

Indented code blocks (4 spaces)

The old-style indented code block syntax still works but is discouraged in modern Markdown. It does not support language identifiers and conflicts with indented list content. Use fenced blocks exclusively.

Formatting Tables for Readability

Markdown tables are notoriously hard to read in source form. Here are two approaches:

Compact style (common in practice)

| Name | Role | Team |
|---|---|---|
| Alice | Developer | Engineering |
| Bob | Designer | Product |

Padded style (more readable in source)

| Name  | Role      | Team        |
|-------|-----------|-------------|
| Alice | Developer | Engineering |
| Bob   | Designer  | Product     |

Both render identically. The padded style is better for documents that will be reviewed in their raw form (e.g., via Git diff or in a terminal). Choose one style and apply it consistently throughout a document.

Tip: The VS Code extension "Markdown Table Formatter" auto-formats tables on save. Highly recommended.

Common Markdown Formatting Mistakes

1. Missing blank lines around lists

Some paragraph text.
- This list item
- May not render correctly

Some paragraph text.

- This list item
- Will always render correctly

2. Mixing list markers

- Item one
* Item two    ← WRONG: different marker
+ Item three  ← WRONG: different marker

- Item one
- Item two    ← Correct: consistent markers
- Item three

3. Incorrect nested list indentation

- Parent item
   - Child item  ← WRONG: 3 spaces (inconsistent)

- Parent item
  - Child item   ← Correct: 2 spaces for nesting

4. Unclosed code fences

```javascript
const x = 1;
            ← WRONG: missing closing ```

```javascript
const x = 1;
```          ← Correct

Markdown Formatting in Different Renderers

Markdown is not one standard — different tools implement different flavours. Here's what to watch for:

• GitHub — Uses GitHub Flavored Markdown (GFM). Supports task lists, tables, strikethrough, and autolinks. Renders @mentions and issue references.
• VS Code — Uses CommonMark with some GFM extensions. The built-in preview is close to GitHub's rendering but not identical.
• Notion — Supports a subset of Markdown for input and export, but some syntax (like nested blockquotes and definition lists) may not render as expected.
• MDTools converters — Use marked.js with GFM mode, which covers all standard Markdown plus tables, task lists, and strikethrough.

Safe bet: Stick to CommonMark-compatible syntax for maximum portability. Avoid renderer-specific extensions when possible.

Export Your Formatted Markdown

Once your Markdown is formatted correctly, MDTools can convert it to any professional format:

• Markdown to Word (.docx) — All formatting preserved as native Word styles
• Markdown to PDF — Clean, print-ready output
• Markdown to HTML — Ready for web publishing
• Markdown Table to Excel — Extract tables to spreadsheets

FAQ