MD058 - Add blank lines around tables

September 11, 2026 · View on GitHub

Aliases: blanks-around-tables

What this rule does

Ensures tables have blank lines before and after them for better readability and proper rendering.

Why this matters

Clear visual separation: Tables stand out better with surrounding space
Parser compatibility: Some Markdown parsers require blank lines to recognize tables
Improved readability: Easier to scan documents and find information
Consistent formatting: Maintains uniform spacing throughout documents

Examples

✅ Correct

Here's our team structure:

| Name    | Department | Role      |
| ------- | ---------- | --------- |
| Alice   | Sales      | Manager   |
| Bob     | IT         | Developer |

As you can see, we have a diverse team.

❌ Incorrect

Here's our team structure:
| Name    | Department | Role      |
| ------- | ---------- | --------- |
| Alice   | Sales      | Manager   |
| Bob     | IT         | Developer |
As you can see, we have a diverse team.

🔧 Fixed

Here's our team structure:

| Name    | Department | Role      |
| ------- | ---------- | --------- |
| Alice   | Sales      | Manager   |
| Bob     | IT         | Developer |

As you can see, we have a diverse team.

Configuration

[MD058]
minimum-before = 1  # Blank lines before table
minimum-after = 1  # Blank lines after table

Examples with different settings

[MD058]
minimum-before = 2  # Require 2 blank lines before
minimum-after = 1  # Require 1 blank line after

Under flavors that support block attribute lists (hugo, mkdocs, kramdown), a standalone attribute line directly after a table (for example {class="a" id="b"} or a kramdown IAL {:.class}) describes the table and is not treated as content needing a blank line:

| Column 1 | Column 2 |
|:---------|:---------|
| Row 1    | Row 1    |
{class="a" id="b"}

Set the flavor globally (flavor = "hugo") or per file. In plain CommonMark such a line is literal text, so this exemption does not apply to the standard flavor. See Hugo Flavor.

Automatic fixes

This rule can automatically fix issues by:

Adding blank lines before tables (unless at document start)
Adding blank lines after tables (unless at document end)
Adding the exact number of blank lines specified in configuration

HTML comments

A line holding nothing but an HTML comment counts as a blank line, so a comment directly above or below a table satisfies this rule and rumdl fmt leaves the document alone:

Some text.
<!-- prettier-ignore -->
| Name | Role |
| ---- | ---- |
| Ada  | Lead |

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.  is a paragraph, so a table 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, MD031 and MD032 read blank lines the same way.