MD046 - Use Consistent Code Block Style¶

Aliases: code-block-style

What this rule does¶

Ensures all code blocks in your document:

• Use the same style - either fenced (with backticks) or indented (with spaces)
• Are properly closed when using fenced style

Why this matters¶

• Readability: Mixing styles makes documents harder to scan and understand
• Maintainability: Consistent style makes code blocks easier to edit
• Tool compatibility: Some tools work better with one style over another
• Professional appearance: Consistency shows attention to detail

Examples¶

✅ Correct (Fenced style)¶

Here's how to use our API:

```javascript
const api = require('our-api');
api.connect();
```

And here's the response format:

```json
{
  "status": "success",
  "data": {}
}
```

❌ Incorrect (Mixed styles)¶

Here's how to use our API:

```javascript
const api = require('our-api');
api.connect();
```

And here's the response format:

    {
      "status": "success",
      "data": {}
    }

🔧 Fixed (Mixed styles)¶

Here's how to use our API:

```javascript
const api = require('our-api');
api.connect();
```

And here's the response format:

```json
{
  "status": "success",
  "data": {}
}
```

❌ Incorrect (Unclosed code block)¶

```javascript
const api = require('our-api');
api.connect();

Some text after the code that was meant to be outside the block.

🔧 Fixed (Unclosed code block)¶

```javascript
const api = require('our-api');
api.connect();
```

Some text after the code that was meant to be outside the block.

❌ Incorrect (Missing closing fence before new block)¶

```javascript
const api = require('our-api');
api.connect();

```python
print("hello")
```

🔧 Fixed (Missing closing fence before new block)¶

```javascript
const api = require('our-api');
api.connect();
```

```python
print("hello")
```

Configuration¶

[MD046]
style = "consistent"  # Options: "consistent", "fenced", "indented"

Style options¶

Automatic fixes¶

When enabled, this rule will:

• Convert all code blocks to match your configured style
• Preserve code content and language identifiers
• Maintain proper spacing around blocks
• Close fenced code blocks that are missing a closing fence
• Insert closing fences when a new code block opens before the previous one is closed

Style comparison¶

Fenced code blocks (recommended):

• Support syntax highlighting with language identifiers
• Easier to copy and paste
• More visible boundaries

Indented code blocks:

• Traditional Markdown style
• No language identifier support
• Must indent each line with 4 spaces or 1 tab

Special cases¶

• Empty code blocks are ignored
• HTML <pre> and <code> tags are not affected
• When using "consistent", the most prevalent style is used (in case of a tie, fenced style is preferred as it's more widely supported)
• Per CommonMark, fenced code block openers (``` or ~~~) can only have 0-3 spaces of indentation. With 4+ spaces, the fence markers become literal content in an indented code block
• Unclosed-block detection is skipped in documents containing markdown or md code blocks, since these often include fence examples that would be misdetected

Azure DevOps / Colon Fences¶

Under the azure_devops flavor, colon-style fences (... :::) are excluded from code block style detection. They are not counted toward the dominant style and are never flagged as style violations. This prevents false positives when a document mixes colon fences with backtick or tilde fences:

::: mermaid
sequenceDiagram
    Alice->>Bob: Hello
:::

```python
print("hello")
```

In this example, only the backtick fence counts for style detection. The colon fence is treated as opaque block content and ignored by MD046.

Under any other flavor, colon fences are not recognized and do not affect style detection.

See Azure DevOps Flavor for the full colon fence specification.

Markdown with Gherkin¶

Under the mdg flavor, MD046 always uses fenced. A Gherkin Doc String is only ever a backtick fence, so an indented block can never be one: consistent resolves to fenced rather than by prevalence, and a configured style = "indented" is not adopted — the rule enforces fenced anyway and prints one [config warning] line on stderr when the rule reaches relevant content.

A run of indented lines that consists entirely of Gherkin table rows — two to five whitespace characters, spaces or tabs, followed directly by a pipe — is withheld from indented-code detection, so a Data Table or Examples table is never converted into a fence. The decision is made per blank-line-delimited run, and the run must hold nothing else:

#### Examples:

    | start | eat |
    | ----- | --- |

    a note about the data

Here the table is left alone and only the note is fenced. Without the blank line the two would form a single run, which is fenced whole.

Closing an unclosed fence is a repair rather than a style conversion, so it still happens whatever style is configured.

See Markdown with Gherkin Flavor for the full flavor specification.

Learn more¶

• CommonMark fenced code blocks
• CommonMark indented code blocks
• GitHub Flavored Markdown

Related rules¶

• MD031 - Add blank lines around code blocks
• MD040 - Specify languages for code blocks
• MD048 - Use consistent fence markers (backticks vs tildes)