mdrefine

What's new in 0.6 ​

mdrefine 0.6 covers what markdownlint and Prettier check in Markdown, reads their settings when a project has no mdrefine configuration, and makes bare format a check. This page shows the changes with examples; the changelog lists every change, and upgrading says what to do when you update from 0.5.

Highlights ​

  • The comparison with Prettier and markdownlint lists every markdownlint rule and every Prettier Markdown option with the mdrefine rule that covers it.
  • A project with only a markdownlint or Prettier configuration gets those settings, and mdrefine config convert --write turns them into an mdrefine configuration.
  • 24 new rules, two of them in recommended, and new options for fourteen existing rules.
  • format without --write, --check, or --diff fails when a file would change.

Your markdownlint or Prettier settings ​

Without an mdrefine configuration, lint and format read a markdownlint or Prettier configuration in the workspace, convert it, and say so on stderr. With a .markdownlint.jsonc that asks for * bullets:

jsonc
{
  "MD004": { "style": "asterisk" },
  "MD013": false,
}

lint reports a - bullet at markdownlint's severity, error:

text
mdrefine: no mdrefine configuration; using markdownlint settings from .markdownlint.jsonc (2 conversion note(s): mdrefine config explain <file>; opt out: --no-competitor-config)
notes.md:3:1: error style/list-marker: Use "*" as the bullet list marker.
1 file(s) linted; 1 error(s), 0 warning(s).

npx mdrefine config convert prints the converted configuration and notes on what it could not convert; --write saves it as mdrefine.config.jsonc. --no-competitor-config turns the fallback off. While it applies, markdownlint's inline configuration comments, Prettier's ignore comments, and Prettier's requirePragma apply too. The fallback lists the files it reads and leaves out.

format checks by default ​

Bare format prints the diff and exits 1 when a file would change, so it can run in CI as it is. format --diff prints the same diff and exits 0, format --check names the files, and format --write writes them; see exit codes.

style/quote-marker writes one space after each >, and style/lazy-continuation writes the > or the indentation on lines that continue a quote's or a list item's paragraph without it. Before:

markdown
>A quote whose text fills the line and goes on long enough to need a second line
when it is wrapped.

After:

markdown
> A quote whose text fills the line and goes on long enough to need a second
> line when it is wrapped.
  • style/table formats tables inside lists and block quotes.
  • style/heading removes a heading's indentation and writes one space after its hashes: ## Install becomes ## Install.
  • style/block-spacing puts a blank line around fenced code blocks and tables, as it does around headings and lists.
  • content/image-alt also reports an HTML <img> without an alt attribute.

Before:

markdown
Run it:
```sh
npm test
```
Then commit.

After:

markdown
Run it:

```sh
npm test
```

Then commit.

New rules in no preset ​

Enable these under rules in the configuration. Each rule's page has examples and options.

Style rules, which format fixes:

Problem rules, which report only:

New options ​

Fixes ​

0.6.0 also has fourteen fixes, most of them in how rules read constructs that VitePress, Forgejo, Gitea, GitHub, or Obsidian render their own way. The changelog lists them, and the GitHub release has the full notes.

In 0.6.1 ​

0.6.1 formats documents as 0.6.0 does. It reorganizes the documentation and smooths the command line:

  • The rules have a page each, with the common case first and edge cases under their own headings; links to the former single page still reach them.
  • Getting started shows what lint prints, compares the forms of format in a table, and covers running mdrefine without a Node.js project and with pnpm, Yarn, or Bun.
  • Upgrading gathers the steps for each release, and the glossary explains the terms that the pages use.
  • mdrefine rules lists the rules sorted by ID, in plainer words, and mdrefine without a command says so after its help.
  • Piping the output into a program that stops reading early, such as head, no longer ends with an error.

In 0.6.2 ​

0.6.2 updates minimatch for a pattern-amplification advisory. mdrefine does not enable the affected optimization mode. The update preserves conversion of Markdown patterns in Prettier and EditorConfig settings. No configuration or workflow changes are required.

In 0.6.3 ​

0.6.3 corrects configuration fallback and ignore matching:

  • With an explicit --root, converted ignore patterns, file selections and overrides resolve relative to that workspace.
  • Ignore matching follows Git for whole-component asterisk runs, and explaining a skipped input names the last matching rule. Prettier fallback keeps its settings when root Markdown files remain unignored.
  • Initial-heading and heading-spacing checks used through markdownlint fallback no longer report false findings around HTML comments.
  • Configuration discovery stops reading .prettierrc.jsonc, which Prettier does not support.

The style/list-indent rule also keeps a list on its footnote definition's first line stable when startIndented: true. No upgrading steps are needed.

In 0.6.4 ​

0.6.4 fixes heading checks and avoids refused formatting in several cases:

  • Markdownlint fallback recognizes HTML headings and permitted preambles, and reports required heading spacing above comments and inside list items. If checking an HTML block reaches the nested-directive work limit, it reports that the check could not complete and leaves the document unchanged.
  • VitePress wrapping handles body entities without false refusals and keeps code spans whose continuation indentation affects rendering. Spacing also keeps table text that belongs to an opaque component, while safe formatting nearby still applies.
  • With a syntax plugin, wrapping keeps paragraphs whose new lines would start one of the plugin's blocks, while safe paragraphs still wrap.
  • Parsing long list paragraphs with many unindented continuation lines avoids repeatedly searching the same accumulated events.

No configuration or upgrading steps are needed. The command structure and options are unchanged.

In 0.6.5 ​

0.6.5 speeds up deeply nested lists and corrects VitePress paragraph wrapping:

  • Deeply nested lists parse faster with the built-in syntax. Syntax plugins retain their existing deep-list performance limits.

  • VitePress body paragraphs beginning with --- can wrap when syntax plugins are enabled. Previously, the wrapping check could mistake them for front matter and keep the whole paragraph as written. For example:

    markdown
    Introduction.

--- A long paragraph in the document body can now wrap with syntax plugins enabled.

No configuration or upgrading steps are needed. Commands and options are unchanged.