mdformat-editorconfig

An mdformat plugin that applies EditorConfig indentation settings to Markdown formatting.

Motivation

mdformat uses opinionated defaults for indentation (2 spaces). This plugin allows you to configure indentation via .editorconfig files, making mdformat respect your project's or personal indentation preferences.

Installation

pip install mdformat-editorconfig

Or with pipx for command-line usage:

pipx install mdformat
pipx inject mdformat mdformat-editorconfig

Usage

Create an .editorconfig file in your project (or home directory):

# .editorconfig
root = true

[*.md]
indent_style = space
indent_size = 4

Then format your Markdown files as usual:

mdformat your-file.md

Example

With the above .editorconfig, nested lists will use 4-space indentation:

Before:

- Item 1
  - Nested item
- Item 2

After:

- Item 1
    - Nested item
- Item 2

EditorConfig Property Compatibility

Property	Status	Notes
indent_style	✅ Supported	Plugin applies space/tab indentation to lists
indent_size	✅ Supported	Plugin applies configured indent width to lists
trim_trailing_whitespace	✅ Always enabled	mdformat always trims trailing whitespace by design
insert_final_newline	✅ Always enabled	mdformat always adds final newline by design
end_of_line	⚪ See mdformat	Use mdformat's --end-of-line CLI option (lf, crlf)
tab_width	⚪ Inherited	Used when indent_size = tab
charset	⚪ N/A	File encoding is handled by editors, not formatters

Note: mdformat has opinionated defaults that align well with typical .editorconfig settings. The formatter always trims trailing whitespace and ensures files end with a newline—these behaviors cannot be disabled.

How It Works

The plugin overrides mdformat's list renderers to apply indentation settings from .editorconfig files. It:

1. Looks up .editorconfig settings based on the current working directory
2. Reads indent_style and indent_size properties
3. Applies the configured indentation to list continuation lines and nested content

CLI Usage

When using mdformat from the command line, the plugin looks up .editorconfig settings based on your current working directory. This means:

• Run mdformat from your project root to pick up project-level .editorconfig
• A global ~/.editorconfig (with root = true) will apply to all mdformat calls within your home directory

# Run from project root to use project's .editorconfig
cd /path/to/project
mdformat docs/*.md

Limitation

Due to mdformat's plugin architecture, the plugin cannot determine the actual file path being formatted. Instead, it uses the current working directory for .editorconfig lookup. This works well for the common case of running mdformat from a project root, but may not pick up the correct settings if you format files from a different directory.

Python API

When using the Python API directly, you can explicitly set the file context for more precise .editorconfig lookup:

import mdformat
from mdformat_editorconfig import set_current_file

# Set the file context for editorconfig lookup
set_current_file("/path/to/your/file.md")
try:
    result = mdformat.text(markdown_text, extensions={"editorconfig"})
finally:
    set_current_file(None)

Scope

This plugin currently handles indentation for:

• Bullet lists (unordered lists)
• Ordered lists

Code blocks and blockquotes follow CommonMark standard formatting (4-space indentation for indented code blocks).

Development

Setup

# Clone the repository
git clone https://github.com/jdmonaco/mdformat-editorconfig.git
cd mdformat-editorconfig

# Install development environment with uv
uv sync

Running Tests

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=mdformat_editorconfig

# Run tests verbosely
uv run pytest -v

License

MIT - see LICENSE file for details.