# 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

<!-- rumdl-disable MD031 MD040 MD022 -->

````markdown
Here's some text explaining the code.
```python
def hello():
    print("Hello, world!")
```
And here's more text after the code.
````

<!-- rumdl-enable MD031 MD040 MD022 -->

### 🔧 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

## 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
