Skip to content

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

Here's some text explaining the code.

```python
def hello():
    print("Hello, world!")
```

And here's more text after the code.

❌ Incorrect

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

🔧 Fixed

Here's some text explaining the code.

```python
def hello():
    print("Hello, world!")
```

And here's more text after the code.

Configuration

[MD031]
list-items = true  # Also require blank lines in lists (default: true)

Example with list-items

When list-items is true (default):

1. First item

   ```python
   code_in_list()
   ```

1. Second item

When list-items is false:

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 (... :::), which Azure DevOps wikis use for Mermaid diagrams and other block content.

❌ Incorrect

Some text
::: mermaid
sequenceDiagram
    Alice->>Bob: Hello
:::
More text

✅ Correct

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 for the full colon fence specification.

Learn more

  • MD032 - Lists should be surrounded by blank lines
  • MD040 - Code blocks should have a language specified
  • MD046 - Code block style should be consistent