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

It adds no blank line between a list marker that stands alone on its line and the fence that begins its item, because a list item may begin with at most one blank line: the blank line would leave the item empty and move the code block out of it. A code block that is never closed has no closing fence to follow with a blank line, and the rule does not ask for 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:

Some text.
<!-- prettier-ignore -->
```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, MD032 and MD058 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 (... :::), 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