mdrefine 0.6.1

The documentation is reorganized for people new to mdrefine: rules have pages of their own, upgrading steps and release notes have theirs, and the site has a glossary. What's new in 0.6 summarizes 0.6.1. No upgrading steps are needed.

Changed

• mdrefine help with an unknown command ends with mdrefine: unknown command 'NAME', config with options but no command names its commands, lint with stdin and a path no longer mentions --write, which it does not take, and the conversion messages name markdownlint, Prettier, and # and underlined headings instead of competitors, ATX, and Setext (#830).

• A glossary defines the terms the pages use, and pages link it. Rule pages and the style/heading message say "# heading" and "underlined heading" instead of ATX and Setext. The pages name markdownlint and Prettier instead of calling them competitors, so the fallback's sections are now "Fallback to markdownlint and Prettier" and "Fallback notices", and so does the notice about their inline comments. The README and the home page say that the package is mdrefine and the repository keeps the original name (#817).

• The site has release notes, starting with What's new in 0.6, in a menu named after the documented version in the top bar. This changelog's 0.6.0 entry is shorter, with internal work under "Maintenance", and the 0.6.0 and 0.5.0 entries point to their upgrading steps (#813).

• The site's top bar has Guide and Reference menus and an Examples link, which the home page's second button also opens, and the sidebar's last group is named About. Issues about the documentation have their own form (#818).

• The Obsidian, dialect, integration, VitePress, benchmark, and command line pages describe what users need, and the details for maintainers, such as the list of every Obsidian protection and the parser work behind the benchmark limits, move to maintainer notes in the repository. The command line page gathers its file access and write safety details at its end (#812).

• Reference pages are easier to scan: the command line page explains the workspace root once and marks the options that only format takes, the configuration page numbers the search for a configuration file and patches one rule of recommended in its ruleUpdates example, the integration guide lists which .prettierignore entries leave Markdown to mdrefine, the library page has a table of the conversion exports, and the VitePress page explains srcDir with the usual layout (#816).

• Getting started covers running mdrefine without installing it, a global installation, pnpm, Yarn, and Bun, and what npm install does in a folder without package.json. The Obsidian page says how to install for a vault, the integration guide has hooks for the pre-commit framework and lefthook, and the configuration page warns that outside a repository the search for a configuration reaches parent folders such as the home directory (#815).

• The documentation has an Upgrading page with the steps for each release that needs them: the markdownlint and Prettier fallback and the exit code of bare format in 0.6.0, and the mdtools names removed in 0.5.0. Getting started, the command line, configuration, and library pages no longer carry migration notes, and the JSON report's example shows the current version (#810).

• The rules reference has one page per rule, at rules/<category>/<name>.html. Each page opens with what the rule does, its facts, an example, and its options; edge cases, dialect notes, and related rules follow under their own headings. The index lists the rules by category in plain words, and a link to a rule's section of the former single page, such as rules.html#stylewrap, continues to the rule's page (#811).

• The built-in rules' descriptions, which mdrefine rules prints, are the sentences of the rules index, in plain words. mdrefine rules lists the rules sorted by ID, plugin rules among them, also with --json. Without a command, mdrefine follows its help with mdrefine: no command given; try mdrefine lint, and mdrefine config alone names its commands. format --help describes --write as writing the formatting changes to the files (#819).

• Getting started picks presets from a table of renderers, shows what lint prints, and compares the forms of lint and format in a table. The configuration page lists what recommended does, and the README and the home page show only lint and format --write. The examples' commands use the installed npx mdrefine, after copying the examples from the package, and the examples' README lists vitepress.jsonc (#814).

Fixed

• Piping output into a program that stops reading early, such as mdrefine lint --json | head, no longer ends with an EPIPE stack trace and exit code 1: the rest of the output is dropped, and the run keeps its own exit code (#820).