npm package: @rewdy/md-formatter
Description: A fast, opinionated Markdown formatter written in Rust
Latest version: 0.4.1

# md-formatter

![The mad formatter](./md-formatter.png)

The md-formatter ("mad formatter") is a fast, opinionated Markdown formatter written in Rust.

## Why/Approach

Many now use modern tools for linting and formatting node code (biome, oxlint, etc), but these do not support formatting markdown. This tools is meant to provide a rust-based formatter for markdown only. The approach it takes is to parse the markdown with Rust's `pulldown-cmark`, then pump it back out with opinionated formatting. For simplicity, it explicitly ignores code blocks (for now), tables are handled minimally, and otherwise is pretty rudimentary.

## Quick Start

**Fast** - Formats 360KB of Markdown in 4ms (~90MB/s)  
**Opinionated** - Minimal configuration (`--width`, `--wrap`, `--ordered-list`)  
**Idempotent** - `format(format(x)) == format(x)` guaranteed  
**Safe** - Uses hard breaks to preserve structure across re-parsing  
**Complete** - All CommonMark + GFM elements supported

## Installation

### Rust (CLI)

```bash
# Install from crates.io
cargo install md-formatter

# Or build from source
cargo build --release
./target/release/mdfmt --help
```

### Node.js

```bash
# npm
npm install @rewdy/md-formatter

# pnpm
pnpm add @rewdy/md-formatter

# bun
bun add @rewdy/md-formatter
```

## Usage

### CLI (Rust)

```bash
# Format all markdown files in current directory (prints to stdout)
mdfmt .

# Format all markdown files in-place
mdfmt . --write

# Check if all files are formatted (for CI)
mdfmt . --check

# Format a specific file
mdfmt README.md

# Format multiple files or directories
mdfmt src/ docs/ README.md

# Custom line width
mdfmt . --width 100

# Read from stdin
cat file.md | mdfmt -
```

### Glob Patterns

```bash
# Use glob patterns
mdfmt "**/*.md"

# Format files in a specific directory
mdfmt docs/

# Multiple paths
mdfmt src/ tests/ README.md
```

### Exclusions

By default, `mdfmt` excludes common directories: `node_modules`, `target`, `.git`, `vendor`, `dist`, `build`.

```bash
# Add additional exclusions
mdfmt . --exclude my-vendor --exclude tmp

# Include everything (no default exclusions)
mdfmt . --no-default-excludes
```

### Prose Wrapping

Control how prose (paragraph text) is wrapped with the `--wrap` option:

```bash
# Reflow prose to fit line width (default: 80)
mdfmt . --wrap always

# Unwrap prose into single lines per paragraph
mdfmt . --wrap never

# Keep existing line breaks (default)
mdfmt . --wrap preserve
```

| Mode | Description |
|------|-------------|
| `always` | Reflow text to fit within line width |
| `never` | Unwrap each paragraph to a single long line |
| `preserve` | Leave existing line breaks unchanged (default) |

### Ordered Lists

Control how ordered list items are numbered with the `--ordered-list` option:

```bash
# Renumber items sequentially (default)
mdfmt . --ordered-list ascending

# Use 1. for all items
mdfmt . --ordered-list one
```

| Mode | Description |
|------|-------------|
| `ascending` | Renumber items sequentially: 1, 2, 3, ... (default) |
| `one` | Use `1.` for all items |

### Integration

```bash
# Pre-commit hook
mdfmt . --check

# CI pipeline
mdfmt . --check || exit 1

# Format only changed files
git diff --name-only -- '*.md' | xargs mdfmt --write
```

### Node.js Integration

The npm package includes the `mdfmt` binary, making it easy to add markdown formatting to your existing Node.js toolchain alongside Biome, ESLint, or other tools.

#### package.json Scripts

```json
{
  "scripts": {
    "format": "biome format --write . && mdfmt . --write",
    "format:check": "biome format . && mdfmt . --check",
    "format:md": "mdfmt . --write",
    "format:md:check": "mdfmt . --check",
    "lint": "biome lint .",
    "check": "biome check . && mdfmt . --check"
  }
}
```

#### CI Example (GitHub Actions)

```yaml
- name: Check formatting
  run: |
    pnpm biome format .
    pnpm mdfmt . --check
```

#### With Husky/lint-staged

```json
{
  "lint-staged": {
    "*.{js,ts,json}": ["biome check --write"],
    "*.md": ["mdfmt --write"]
  }
}
```

#### Programmatic API

For advanced use cases, you can also use the formatter programmatically:

```javascript
import { formatMarkdown, checkMarkdown } from '@rewdy/md-formatter';

// Format a string
const formatted = formatMarkdown(input, {
  width: 80,
  wrap: 'preserve',
  orderedList: 'ascending'
});

// Check if formatted (returns boolean)
const isFormatted = checkMarkdown(input);
```

## Formatting Rules

### Supported Elements

- Paragraphs (line breaks controlled by `--wrap` mode)
- Headings (normalized to `# Heading` format)
- Lists (unordered `-`, ordered with `--ordered-list` mode, with nesting)
- Blockquotes (with `>` prefix per depth)
- Code blocks (fenced, language tags preserved)
- Inline code, emphasis, links
- Horizontal rules (normalized to `---`)
- Frontmatter (YAML blocks preserved)
- GFM strikethrough and autolinks

### Design Philosophy

Uses hard breaks (two spaces + newline) instead of soft breaks to ensure  
idempotence. This prevents Markdown parsers from reinterpreting wrapped lines as  
soft breaks on re-parsing.

## Performance

| Scenario | Time | Throughput |
| ----------------- | ------- | ---------- |
| 360KB file | 4ms | ~90MB/s |
| Average file (2KB)| <1ms | Instant |

## Architecture

```txt
Input Markdown
    ↓
Extract Frontmatter (if present)
    ↓
Parse to Event Stream (pulldown-cmark)
    ↓
Format Events (state machine with hard breaks)
    ↓
Prepend Frontmatter
    ↓
Output Markdown
```

The formatter never parses the output, so idempotence is guaranteed by design.

## CLI Options

```bash
Usage: mdfmt [OPTIONS] [PATH]...

Arguments:
  [PATH]...  Files or directories to format (supports glob patterns, use - for stdin)

Options:
  -w, --write                   Write formatted output to file in-place
      --check                   Check if files are formatted (exit with 1 if not)
      --stdin                   Read from stdin
      --width <WIDTH>           Line width for wrapping [default: 80]
      --wrap <MODE>             How to wrap prose: always, never, preserve [default: preserve]
      --ordered-list <MODE>     How to number ordered lists: ascending, one [default: ascending]
      --exclude <DIR>           Additional directories to exclude
      --no-default-excludes     Don't exclude any directories by default
  -h, --help                    Print help
  -V, --version                 Print version
```

**Default exclusions:** `node_modules`, `target`, `.git`, `vendor`, `dist`, `build`

## Testing

```bash
# Run all tests
cargo test --release --lib

# Run specific test
cargo test --release --lib test_idempotence -- --nocapture

# Build release binary
cargo build --release
```

**Current status:** 25 unit tests passing ✓

## Known Limitations

- **Autolinks** - Converted to regular links (parser limitation)
- **Configuration** - Only `--width`, `--wrap`, and `--ordered-list` options supported (by design)
- **MDX** - Not supported (different language)

## Project Structure

```bash
src/
├── main.rs       - CLI entry point and file I/O
├── cli.rs        - Argument parsing (clap)
├── formatter.rs  - Core formatting logic (~430 lines)
├── parser.rs     - Markdown parsing and frontmatter extraction
└── lib.rs        - Public API and unit tests (14 tests)
```

## Status

**Version:** 0.1.1  
**MVP:** Complete ✓  
**Tests:** 25/25 passing ✓  
**Idempotence:** Verified ✓  
**Performance:** Excellent ✓

See `STATUS.md` for detailed feature matrix and quality metrics.

## Contributing

As long as changes are conceptually in-line with the project, I welcome all contributions. 😄

## License

MIT