# MD031 - Code blocks need blank lines around them
Aliases: `blanks-around-fences`
## What this rule does
Ensures code blocks (```) have blank lines before and after them for proper spacing.
## Why this matters
- **Readability**: Blank lines visually separate code from surrounding text
- **Rendering**: Some Markdown processors require blank lines for proper code block display
- **Consistency**: Uniform spacing makes documents look professional
## Examples
### ✅ Correct
````markdown
Here's some text explaining the code.
```python
def hello():
print("Hello, world!")
```
And here's more text after the code.
````
### ❌ Incorrect
````markdown
Here's some text explaining the code.
```python
def hello():
print("Hello, world!")
```
And here's more text after the code.
````
### 🔧 Fixed
````markdown
Here's some text explaining the code.
```python
def hello():
print("Hello, world!")
```
And here's more text after the code.
````
## Configuration
```toml
[MD031]
list-items = true # Also require blank lines in lists (default: true)
```
### Example with list-items
When `list-items` is true (default):
````markdown
1. First item
```python
code_in_list()
```
1. Second item
````
When `list-items` is false:
````markdown
1. First item
```python
code_in_list()
```
1. Second item
````
## Automatic fixes
This rule automatically adds blank lines:
- Before code blocks that don't have one
- After code blocks that don't have one
## HTML comments
A line holding nothing but an HTML comment counts as a blank line, so a comment
directly above or below a code block satisfies this rule and `rumdl fmt` leaves
the document alone:
````markdown
Some text.
```python
print("hello")
```
````
This keeps a directive comment attached to what it applies to: inserting a blank
line there would turn the directive off.
The comment has to have the line to itself. `Some text. <!-- note -->` is a
paragraph, so a code block written under it is still missing its blank line. A
comment spanning several lines counts at both ends, and the convention holds
inside a blockquote. [MD022](md022.md), [MD032](md032.md) and [MD058](md058.md)
read blank lines the same way.
## Azure DevOps / Colon Fences
Under the `azure_devops` flavor, MD031 also enforces blank lines before and
after colon-style fences (`:::lang ... :::`), which Azure DevOps wikis use for
Mermaid diagrams and other block content.
### ❌ Incorrect
````markdown
Some text
::: mermaid
sequenceDiagram
Alice->>Bob: Hello
:::
More text
````
### ✅ Correct
````markdown
Some text
::: mermaid
sequenceDiagram
Alice->>Bob: Hello
:::
More text
````
Under any other flavor, colon fences are not recognized and MD031 ignores them.
See [Azure DevOps Flavor](flavors/azure_devops.md) for the full colon fence
specification.
## Learn more
- [CommonMark code blocks](https://spec.commonmark.org/0.31.2/#fenced-code-blocks) - Technical specification
- [Markdown Guide - Code](https://www.markdownguide.org/extended-syntax/#fenced-code-blocks) - Code block best practices
## Related rules
- [MD032](md032.md) - Lists should be surrounded by blank lines
- [MD040](md040.md) - Code blocks should have a language specified
- [MD046](md046.md) - Code block style should be consistent