mmdfmt 0.1.0 → 0.2.0

package/README.ja.md

@@ -12,7 +12,7 @@ Markdown ファイルのほかの部分は、1 バイトも変えません。
 Prettier の Mermaid プラグインである
 [`prettier-plugin-mmd`](../prettier-plugin-mmd) を使って
 [Prettier](https://prettier.io/) で整形するため、
-[Prettier を知っている方へ](#prettier-を知っている方へ)の 2 つの場合を除き、
+[Prettier を知っている方へ](#prettier-を知っている方へ)の場合を除き、
 プラグインと同じ結果になります。
 
 [mermaid-js](https://mermaid.js.org/) とは関係のない第三者のプロジェクトです。
@@ -113,33 +113,46 @@ npm install --global mmdfmt
 ## 使い方
 
 ```sh
-mmdfmt --write <pattern>...
+mmdfmt --write [--check | --list-different] <pattern>...
 mmdfmt --check <pattern>...
+mmdfmt --list-different <pattern>...
 mmdfmt --stdin-filepath <path>
 ```
 
-| オプション                | 動作                                                             |
-| ------------------------- | ---------------------------------------------------------------- |
-| `--write`                 | ファイルを直接整形し、変わったものを標準出力に挙げます。         |
-| `--check`                 | 何も変えず、`--write` が変えるファイルを標準出力に挙げます。     |
-| `--stdin-filepath <path>` | 標準入力を `<path>` のファイルとして整形し、標準出力に書きます。 |
-| `-h`, `--help`            | 使い方を標準出力に書きます。                                     |
-| `-v`, `--version`         | バージョンを標準出力に書きます。                                 |
-
-`--write` か `--check` のどちらかにパターンを付けるか、
-`--stdin-filepath` を単独で指定します。
+| オプション                | 動作                                                                           |
+| ------------------------- | ------------------------------------------------------------------------------ |
+| `-w`, `--write`           | ファイルを直接整形し、整形した各ファイルを所要時間とともに標準出力に挙げます。 |
+| `-c`, `--check`           | 整形済みか確認し、要約と整形されていないファイルを報告します。                 |
+| `-l`, `--list-different`  | 何も変えず、`--write` が変えるファイルを標準出力に挙げます。                   |
+| `--stdin-filepath <path>` | 標準入力を `<path>` のファイルとして整形し、標準出力に書きます。               |
+| `-h`, `--help`            | 使い方を標準出力に書きます。                                                   |
+| `-v`, `--version`         | バージョンを標準出力に書きます。                                               |
+
+`--write`、`--check`、`--list-different` の少なくとも 1 つにパターンを付けます。
+`--write` は `--check` か `--list-different` のどちらかと組み合わせられます。
+`--write --check` はファイルを書き換え、チェックの要約と警告を出力します。
+`--write --list-different` はファイルを書き換えて、変わったものだけを挙げます。
+`--check` と `--list-different` は組み合わせられません。
+`--no-write`、`--no-check`、`--no-list-different` は、そのオプションを外します。
+`--stdin-filepath` はパターンを取らず、
+一緒に使うと `--write` はファイルを書きません。
 `--help` と `--version` は、
 表のほかのオプションを一緒に付けても出力するだけです。
-ほかの組み合わせはエラーです。
 引数がまったくないときは、`mmdfmt` は使い方を標準エラー出力に書き、
 `2` で終了します。
 
+`--write` 単独では Prettier と同じく、整形したファイルごとに 1 行出力します。
+その名前と整形にかかった時間を、`docs/flow.mmd 12ms` のように書き、
+変わらなかったファイルには、その後ろに `(unchanged)` を付けます。
+色を出せる端末では、変わらなかったファイルの名前は灰色です。
+変わったファイルだけを挙げるには、`--write --list-different` を付けます。
+`mmdfmt` が出力するファイルの名前は、実行するディレクトリからの相対パスで、
+Windows でも Prettier と同じく、区切りは `/` です。
+
 ほかのオプションはありません。
 整形オプションも、独自の設定ファイルも、
 無視ファイルを指定するオプションもありません。
-値を取らないオプションでは、
-引数のライブラリ [gunshi](https://gunshi.dev) の読み方に従い、
-`=` の後ろの値を無視します。
+値を取らないオプションは、`=` の後ろの値を無視します。
 `--write=false` は `--write` と同じに読みます。
 
 `head` が必要な行数を読み終えたときのように、標準出力の読み手がいなくなると、
@@ -165,7 +178,7 @@ mmdfmt --stdin-filepath <path>
 `.mermaid` で終わるものを、いくつのパターンが選んでも 1 回ずつ整形します。
 そのどれも選ばないパターンはエラーです。
 そのようなファイルのないプロジェクトでは `mmdfmt --check .` は失敗し、
-ほかの語尾のファイルを名前で指定しても同じです。
+ほかの拡張子のファイルを名前で指定しても同じです。
 Prettier の CLI と同じく、
 `!` のパターンによって選んだファイルがすべて取り除かれるパターンもエラーです。
 `.gitignore` が挙げるファイルだけを選ぶパターンはエラーではありません。
@@ -213,11 +226,32 @@ CI で依存パッケージをインストールして（`npm ci`）、次を実
 npx mmdfmt --check .
 ```
 
-整形されていないファイルがあると、`--check` は標準出力に挙げ、`1` で終了します。
-すべて整形済みなら、何も出力せず `0` で終了します。
 依存パッケージをインストールしていないと、
 `npx` は固定したバージョンではなく最新版を実行してしまいます。
 
+`--check` は、`Checking formatting...` を標準出力に書き、
+変わるファイルごとに `[warn] <name>` を標準エラー出力に書き、
+最後に要約を 1 つ書きます。
+変わるファイルがあれば、要約は標準エラー出力に書き、終了コードは `1` です。
+
+```txt
+[warn] Code style issues found in the above file. Run mmdfmt with --write to fix.
+```
+
+該当するファイルが複数なら、`in the above file` は `in <n> files` になります。
+色を出せる端末では、`warn` の語は黄色です。
+変わるファイルがなければ、
+要約は標準出力の `All diagrams in the matched files use Prettier code style!`
+で、終了コードは `0` です。
+`--list-different` は、変わるファイルの名前だけを標準出力に書き、
+終了コードは同じです。
+
+`--write --check` では、ファイルを書き換え、
+要約は `[warn] Code style issues fixed in the above file.` で、
+複数なら末尾が `in <n> files.` になり、終了コードは `0` です。
+エラーがあれば、終了コードは `2` です。
+そのときの要約は、[エラーと終了コード](#エラーと終了コード)に書いてあります。
+
 mermaid.js が拒否する図のある `.mmd` や `.mermaid` ファイルは、
 `2` でチェックに失敗します。
 Markdown 内の図を mermaid.js が拒否しても、警告にとどまります。
@@ -244,9 +278,9 @@ husky や simple-git-hooks などの Git フックマネージャーがコミッ
 }
 ```
 
-glob はこの 4 つの語尾に限ってください。
+glob はこの 4 つの拡張子に限ってください。
 `mmdfmt` には Prettier の `--ignore-unknown` のようなオプションはなく、
-ほかの語尾のファイルはエラーです。
+ほかの拡張子のファイルはエラーです。
 lint-staged が渡す絶対パスを、`mmdfmt` は受け付けます。
 
 ## エディターやほかのツールから使う
@@ -262,7 +296,7 @@ mmdfmt --stdin-filepath docs/guide.md
 
 そのパスのファイルは、読み書きしません。
 相対パスは `mmdfmt` を実行するディレクトリを基準に解決します。
-パスの語尾がテキストを図として読むか Markdown として読むかを決め、
+パスの拡張子がテキストを図として読むか Markdown として読むかを決め、
 ディレクトリがどの `.editorconfig` と Prettier の設定を適用するかを決めます。
 
 - Markdown のテキストは、整形したか、すでに整形済みかにかかわらず全体を出力し、
@@ -273,28 +307,230 @@ mmdfmt --stdin-filepath docs/guide.md
 - `node_modules` やバージョン管理のディレクトリの下にあるパス、
   または `mmdfmt` を実行するディレクトリの `.gitignore` が挙げるパスでは、
   テキストをそのまま返します。
-- ほかの語尾のパスはエラーです。
+- `--check` や `--list-different` では、テキストを出力しません。
+  変わるなら、`--write` も付けたときを除き、標準出力に `(stdin)` を書き、
+  終了コードは `1` です。
+  それ以外は何も書かず、終了コードは `0` です。
+  警告の位置は、読んだときのテキストの中の位置です。
+- ほかの拡張子のパスはエラーです。
+
+## スクリプトから使う
+
+エディターの拡張機能や言語サーバーなど、Node.js 向けに書かれたツールは、
+`mmdfmt` コマンドを実行しなくても、
+コマンドと同じようにファイルの図を整形できます。
+Node.js 向けに書かれていないツールは、
+[`--stdin-filepath`](#エディターやほかのツールから使う)を付けて、
+コマンドを実行できます。
+新しいバージョンでは図の整形が少し変わることがあるため、
+ツールの依存パッケージに `mmdfmt` を追加するときは、
+[インストール](#インストール)と同じようにバージョンを固定します。
 
-## インデント
+```sh
+npm install --save-exact mmdfmt
+```
+
+Node.js `^22.13.0 || >=24` が必要です。
+`mmdfmt` から、関数 `resolveConfig`、`format`、
+`clearConfigCache` をインポートして使います。
+引数と戻り値は Prettier の同じ名前の関数にそろえてあり、
+違う点は関数ごとの節で説明します。
+次の例は、`docs/notes.md` の図を整形します。
+
+```js
+import { readFile } from "node:fs/promises"
+import { format, resolveConfig } from "mmdfmt"
+
+const filepath = "docs/notes.md"
+const source = await readFile(filepath, "utf8")
+const config = await resolveConfig(filepath)
+const formatted = await format(source, { ...config, filepath })
+```
 
-図のインデントは空白 2 つです。
+`formatted` には、
+コマンドが `docs/notes.md` を整形して書き出すのと同じテキストが入ります。
+図は整形され、ほかの部分は書かれたままです。
+ファイルに書き込むかどうかは、ツールが決めます。
+
+### `resolveConfig(fileUrlOrPath)`
+
+`resolveConfig` は、
+ファイルに適用される Prettier の設定ファイルと `.editorconfig` を、
+コマンドと同じように `overrides` も含めて探します（[設定](#設定)を参照）。
+引数には、ファイルのパスかファイル URL を渡します。
+相対パスは現在のディレクトリを基準に解決されるため、
+言語サーバーでは絶対パスか URL を渡します。
+ファイルそのものは読まないので、存在しないファイルのパスでもかまいません。
+
+`resolveConfig` は Promise を返します。
+ファイルに適用される設定があれば、
+Promise は `format` に渡すオプションのオブジェクトで解決され、
+なければ `null` で解決されます。
+`null` を展開しても何も加わらないため、
+`{ ...config, filepath }` はどちらの場合にも使えます。
+オブジェクトが持つのは、`mmdfmt` が設定から読む 8 つのオプションのうち、
+設定が指定しているものだけです。
+8 つのオプションの一覧は、[設定](#設定)にあります。
+たとえば、設定が `tabWidth` を指定していなければ、
+`{ tabWidth: 4, ...config, filepath }` の `tabWidth` は 4 のままです。
+TypeScript では、このオブジェクトの型は `ReadOptions` です。
+設定ファイルを読めないときは、Promise は拒否されます。
+
+`resolveConfig` は、コマンドと同じく `.editorconfig` も読みます。
+Prettier の CLI も既定では読みますが、Prettier の `resolveConfig` が読むのは、
+`editorconfig: true` を渡したときだけです。
+
+### `clearConfigCache()`
+
+`resolveConfig` は、Prettier の `resolveConfig` と同じく、
+一度読んだ設定ファイルの内容をプロセスが終わるまで覚えています。
+そのため、後で設定ファイルが変わっても、`resolveConfig` の結果は変わりません。
+エディターのファイル監視などで、
+Prettier の設定ファイルや `.editorconfig` が変わったことをツールが知ったときは、
+`clearConfigCache` を呼び出します。
+すると、次に `resolveConfig` を呼び出したときに、設定ファイルを読み直します。
+`clearConfigCache` は、
+覚えていた内容を消し終えたときに解決される Promise を返します。
+
+### `format(source, options)`
+
+`format` は、Prettier の `format` と同じようにテキストを整形します。
+ただし Markdown では、Mermaid のコードブロックだけを整形し、
+ほかは書かれたまま残します。
+ファイルも設定も読みません。
+
+- `source`: ファイルのテキスト。
+- `options.filepath`: ファイルのパスで、必須です。
+  パスのうち使うのは拡張子だけで、
+  拡張子が `.mmd` か `.mermaid` ならテキストを 1 つの図として、
+  `.md` か `.markdown` なら Markdown として読みます。
+  ファイルは存在しなくてもかまいません。
+- ほかのオプション: 同じパスについて `resolveConfig` が返したものを渡します。
+  設定の `overrides` は、パスによって適用されるかどうかが変わるためです。
+  使えるのは、[設定](#設定)に挙げた 8 つのオプションです。
+  Markdown では、`printWidth` はファイル全体の行の幅です。
+  リスト項目や引用の中の図は、その幅から、
+  図の各行の前にあるものの幅を引いた幅で整形します。
+  詳しくは、[コードブロックの詳細](#コードブロックの詳細)を参照してください。
+- `filepath` とこの 8 つ以外のオプション（`parser`、`endOfLine`、
+  `semi` など）は、TypeScript では型エラーになり、JavaScript では無視されます。
+  TypeScript では、`format` のオプションの型は `FormatOptions` です。
+
+`format` は、整形したテキストで解決される Promise を返します。
+改行コードとバイトオーダーマークは、テキストに書かれたまま残ります。
+詳しくは、[コードブロックの詳細](#コードブロックの詳細)を参照してください。
+
+Markdown では、`format` は次の 3 種類のブロックを書かれたまま残し、
+どれも報告しません。
+
+- mermaid.js が拒否する図。
+- インデントにあるタブの一部がインデント、残りが図と読まれるブロック。
+- 開きフェンスが脚注のラベルの行にあるブロック。
+
+後の 2 種類は、[コードブロックの詳細](#コードブロックの詳細)で説明しています。
+Prettier も、整形できない埋め込みのコードブロックを同じように残します。
+mermaid.js が拒否する図を見つけるには、
+[`@mmd-toolkit/parser`](../parser) で解析するか、
+[`@mmd-toolkit/eslint-plugin`](../eslint-plugin) でファイルを lint します。
+
+Promise は、次のときに拒否されます。
+
+- `.mmd` か `.mermaid` のテキストを mermaid.js が拒否するときは、
+  `SyntaxError` で拒否されます。
+  このエラーは、
+  Prettier が `prettier-plugin-mmd` でテキストを整形するときに投げるものです。
+  エラーの `loc.start` と `loc.end` は、
+  エラーの範囲の始まりと終わりを `line` と `column` で示します。
+  `line` と `column` は、どちらも 1 から数えます。
+  改行の位置のエラーのように、エラーの範囲が後の行の始まりまで続くときは、
+  `loc.end` はありません。
+- オプションに Prettier が受け付けない値があるときは、
+  Prettier のエラーで拒否されます。
+  たとえば `printWidth: "wide"` なら、
+  エラーは `Invalid printWidth value. …` です。
+  `.mmd` か `.mermaid` のテキストでは、
+  mermaid.js が図を拒否するかどうかにかかわらず、そうなります。
+  Markdown のテキストでも、
+  `mmdfmt` が図を整形するコードブロックを 1 つでも持てば、
+  その図を mermaid.js が拒否するかどうかにかかわらず、そうなります。
+  どのブロックの図を整形するかは、
+  [コードブロックの詳細](#コードブロックの詳細) にあります。
+  そのようなブロックのない Markdown のテキストは、そのまま返します。
+  `mermaid` や `mmd` のコードブロックがないものと、
+  そのようなブロックがどれも書かれたまま残されるものです。
+  書かれたまま残されるのは、次のブロックです。
+  - `<!-- prettier-ignore -->` の後のブロック。
+  - `<!-- prettier-ignore-start -->` と、
+    `<!-- prettier-ignore-end -->` の間のブロック。
+  - 開きフェンスが脚注のラベルの行にあるブロック。
+  - 字下げのタブの一部が図と読まれるブロック。
+- `options.filepath` の拡張子が `.md`、`.markdown`、`.mmd`、
+  `.mermaid` のどれでもないときは、エラーで拒否されます。
+
+### 整形するファイル
+
+コマンドが整形するのは、拡張子が `.md`、`.markdown`、`.mmd`、
+`.mermaid` のファイルだけです。
+また、`node_modules` やバージョン管理のディレクトリの下にあるパスと、
+実行するディレクトリの `.gitignore` が挙げるパスは飛ばします。
+詳しくは、[ファイルの除外](#ファイルの除外)を参照してください。
+`format` は、ほかの拡張子のパスを拒否しますが、それ以外は、
+パスがどこにあっても整形します。
+コマンドと同じファイルを飛ばしたいツールは、
+`format` を呼び出す前にパスを調べます。
+
+## 設定
+
+図のインデントは空白 2 つで、行の幅は Prettier の 80 です。
 ファイルに `.editorconfig` や Prettier の設定が適用されるときは、
-そのインデントを使います。
-`.editorconfig` の `indent_style`、`indent_size`、`tab_width`、
-または [Prettier の設定ファイル](https://prettier.io/docs/configuration)の
-`useTabs` と `tabWidth` で、
+`mmdfmt` はそのうち 8 つのオプションを読みます。
 `overrides` も含めて Prettier の CLI と同じように探します。
+`.editorconfig` の `indent_style`、`indent_size`、`tab_width`、
+`max_line_length` と、Prettier の設定ファイルのオプションです。
+設定ファイルについては、
+[Prettier の文書](https://prettier.io/docs/configuration) を参照してください。
 コードブロックでは、そのファイルは Markdown ファイルです。
 読めない設定ファイルはエラーです。
-たとえば、この `.editorconfig` は図に空白 4 つのインデントを付けます。
+たとえば、この `.editorconfig` は図に空白 4 つのインデントを付け、
+行を 100 桁まで許します。
 
 ```ini
 [*.{md,mmd,mermaid}]
 indent_style = space
 indent_size = 4
+max_line_length = 100
 ```
 
-設定のほかの項目は使いません。
+読む 8 つのオプションは次のとおりです。
+
+- `printWidth` は行の幅です。
+  行の幅が図の中で決めるのは、2 つです。
+  1 行に書いたデータブロック `@{ … }` を複数行で印字するかどうかと、
+  Gantt のセクションのタスクの `:` をそろえるかどうかです。
+  詳しくは、
+  [フォーマッターのオプション](https://mmd-toolkit.github.io/mmd-toolkit/ja/formatter/options.html#行の長さ)
+  を参照してください。
+  `max_line_length = off` は制限なしです。
+  リスト項目や引用の中のコードブロックでは、`printWidth` は、
+  各行の前に `mmdfmt` が書くものの幅を引いた幅です。
+  詳しくは、[コードブロックの詳細](#コードブロックの詳細)を参照してください。
+- `tabWidth` と `useTabs` は、図のインデントを決めます。
+- `embeddedLanguageFormatting`、`singleQuote`、`bracketSpacing`、`proseWrap`、
+  `trailingComma` は、図の YAML frontmatter に効きます。
+  Prettier が `prettier-plugin-mmd` で整形する場合と同じです。
+  `embeddedLanguageFormatting: "off"` は frontmatter を書かれたまま残します。
+
+`mmdfmt` はこれ以外のオプションを読みません。
+後の版の Prettier が足すオプションも読みません。
+範囲（`rangeStart` と `rangeEnd`）、`cursorOffset`、
+プラグマのオプション（`requirePragma`、`insertPragma`、`checkIgnorePragma`）、
+`filepath`、ほかの言語のオプションは使いません。
+`plugins` と `parser` も使いません。
+`mmdfmt` は常に `prettier-plugin-mmd` で整形するので、
+設定が挙げるプラグインは読み込みません。
+`endOfLine` は使いません。
+ファイルの改行コードを残すからです。
+詳しくは、[コードブロックの詳細](#コードブロックの詳細)を参照してください。
 
 ## エラーと終了コード
 
@@ -311,29 +547,42 @@ notes.md:6:1: warning: Unexpected end of text
 Markdown のコードブロックでは警告です。
 `--write` と `--stdin-filepath` では、警告の位置は整形後のテキストの位置です。
 それより前の図の行が増減していても、実行後に開くテキストのブロックを指します。
-何も書き換えない `--check` では、整形前のファイル内の位置です。
+`--write` のない `--check` と `--list-different` では、
+整形前のファイル内の位置です。
 行と桁は 1 から数え、
 桁は多くのエディターと同じく UTF-16 のコード単位で数えます。
 どの図が拒否されるかは、
 [フォーマッターの互換性](https://mmd-toolkit.github.io/mmd-toolkit/ja/formatter/compatibility.html)
 で説明しています。
 
-| コード | 意味                                                     |
-| ------ | -------------------------------------------------------- |
-| `0`    | エラーがなく、`--check` ではどのファイルも整形済みです。 |
-| `1`    | `--check` で、変わるファイルがあり、エラーはありません。 |
-| `2`    | エラーです。                                             |
+| コード | 意味                                                                                                 |
+| ------ | ---------------------------------------------------------------------------------------------------- |
+| `0`    | エラーがなく、`--check` と `--list-different` では変わるファイルがないか、`--write` が付いています。 |
+| `1`    | `--write` のない `--check` か `--list-different` で、変わるファイルがあり、エラーはありません。      |
+| `2`    | エラーです。                                                                                         |
 
 エラーとは、`.mmd` や `.mermaid` ファイル内の拒否された図、
 読めないか書けないファイル、ファイルを選ばないパターン、読めない設定、
 オプションの誤った使い方です。
 エラーがあれば、変わるファイルがあっても終了コードは `2` です。
 
+`.mmd` や `.mermaid` ファイルの図を mermaid.js が拒否するときのように、
+ファイルを整形できないとき、`--check` の要約は、
+標準出力の `Error occurred when checking code style in the above file.` で、
+複数なら末尾が `in <n> files.` になります。
+Prettier の `--check` と同じく、要約は整形できないファイルだけを数えます。
+読めないファイルと、ファイルを選ばないパターンは、エラーとして報告しますが、
+要約はそれらがないときと同じです。
+パターンがファイルを 1 つも選ばないときもそうです。
+書けないファイルは、問題を修正したファイルとして数え、
+`--write` と `--write --list-different` でも名前を挙げます。
+
 ## Prettier を知っている方へ
 
 図は Prettier と `prettier-plugin-mmd` で整形するので、
 プラグインの規則が適用されます。
-Markdown に Prettier とプラグインを使う場合とは、結果が 2 点で異なります。
+Markdown と `.mmd` ファイルに Prettier とプラグインを使う場合とは、
+結果が 5 点で異なります。
 
 - Prettier は、コードブロックの最後の行の末尾の空白を、
   mermaid.js が図の一部として読む場合も、
@@ -343,10 +592,99 @@ Markdown に Prettier とプラグインを使う場合とは、結果が 2 点
   Markdown のコードブロックを Markdown 文書として整形し、
   その中のコードブロックの図も整形します。
   `mmdfmt` はほかのコードブロックをすべてそのまま残します。
+- Prettier はリスト項目や引用で行の前にあるものを自分で印字しますが、
+  `mmdfmt` は書かれたまま残します。
+  詳しくは[コードブロックの詳細](#コードブロックの詳細)を参照してください。
+  リスト項目では、Prettier はマーカーを印字して内容を `tabWidth` にそろえます。
+  引用では、`> ` を印字し、`>` とフェンスの間の空白とタブを取り除きます。
+  内容の桁が違うと、項目や引用の中の図に残る行の幅がその差だけ違い、
+  幅の近くにある 1 行のブロックを、一方は分け、他方は分けないことがあります。
+- リスト項目や引用の中では、Prettier は Gantt のセクションのコロンを、
+  行の前にあるものを数えずにそろえるので、
+  そろえた行が行の幅を超えることがあります。
+  `mmdfmt` はそれを数えるので、幅の近くでは、Prettier はセクションをそろえ、
+  `mmdfmt` はそろえないことがあります。
+  そのとき `mmdfmt` はコロンをそろえるために名前を空白で埋めず、
+  各コロンの前の空白は書かれたままです。
+  行の幅より広く書かれた行も、そのままです。
+  タスクは、どの Gantt の図でも同じ字下げに直すので、書かれた字下げが違うと、
+  コロンは行といっしょに動きます。
+- Prettier は、次の 4 つの設定のもとで、図を書かれたまま残します。
+  `requirePragma: true` は、ファイルの先頭に、
+  `<!-- @format -->` か `<!-- @prettier -->` のコメントがない Markdown
+  ファイルを残します。
+  frontmatter があるときは、その後ろが先頭です。
+  `checkIgnorePragma: true` は、そこに、
+  `<!-- @noformat -->` か `<!-- @noprettier -->` のコメントがある Markdown
+  ファイルを残します。
+  ファイル全体を覆わない範囲は、Markdown ファイルも `.mmd` ファイルも残します。
+  `embeddedLanguageFormatting: "off"` は、
+  Markdown ファイルのすべてのコードブロックを残します。
+  `mmdfmt` は、この 4 つのどれのもとでも図を整形します。
+  最初の 3 つは読みません。
+  どのファイルを整形するかは自分で決め（パターンと `.gitignore`）、
+  図全体を整形するからです。
+  `embeddedLanguageFormatting` は図の frontmatter にだけ読み、
+  そのときは frontmatter を書かれたまま残します。
 
 コマンドも Prettier の CLI とは異なります。
 `.prettierignore` は読まず、`--ignore-path`、`--ignore-unknown`、
-整形オプションはなく、設定からはインデントだけを使います。
+独自の整形オプションはなく、設定は図のためだけに読みます。
+`mmdfmt` が読まないオプションに、Prettier が拒む値を書いても、
+ここではエラーになりません。
+Prettier の CLI はそれをエラーにします。
+たとえば、`semi: "yes"` です。
+
+チェックの成功時には、
+Prettier の `All matched files use Prettier code style!` の代わりに、
+`All diagrams in the matched files use Prettier code style!` と書きます。
+`mmdfmt` は図のほかを整形しないので、
+Markdown ファイルの残りの部分はその形式とは限らないためです。
+警告は `mmdfmt --write` の実行を案内します。
+`prettier --write` では Markdown ファイル全体が整形され、
+プラグインが設定されていないと図は整形されないためです。
+
+Prettier は `--write=false` を false と読みます。
+`mmdfmt` は、値を取らないオプションでは `=` の後ろの値を無視し、
+`--write` と読みます。
+`--check=false` と `--list-different=false` も同じです。
+また、
+Prettier は `--write` の後ろに書いた `true` や `false` をその値と読みますが、
+`mmdfmt` はパターンと読みます。
+そのため、`mmdfmt --write false notes.md` は `notes.md` を整形し、
+`false` に合うファイルがないと報告します。
+
+`--check --list-different` はどちらでもエラーです。
+`mmdfmt` は、ほかのオプションの誤った使い方と同じく `2` で終了し、
+書く誤りの文は、
+`mmdfmt: error: Optional argument '--check' conflicts with '--list-different'`。
+Prettier は `[error] Cannot use --check and --list-different together.` を書き、
+`1` で終了します。
+`mmdfmt` は、一緒に使えるオプションかを確かめるとき、
+`--no-` の形もそのオプションを付けたと数えます。
+そのため、`--check --list-different` と同じく、
+`--no-check --list-different` もエラーになります。
+Prettier は `--no-check --list-different` を受け付けます。
+
+標準入力で `--check` や `--list-different` を使うとき、
+Prettier は読めないテキストでも `0` で終了しますが、`mmdfmt` は、
+ほかの場合と同じく、
+拒否された図では `2` で終了します（[エラーと終了コード](#エラーと終了コード)）。
+`.mmd` や `.mermaid` のファイルの拒否された図を、`mmdfmt` は、
+`docs/flow.mmd:3:1: error: Unexpected end of text` のように、
+位置を付けた 1 行で報告します。
+Prettier は `[error] docs/flow.mmd: SyntaxError: Unexpected end of text`
+を書き、続けてその場所の前後の行を、それぞれ `[error]` の後に書きます。
+Markdown のファイルの中の拒否された図では、
+`mmdfmt` は `notes.md:6:1: warning: Unexpected end of text` のような警告を 1
+行書き、Prettier は何も書きません。
+どちらも、これをエラーとはしません。
+
+Prettier は、`CI` の環境変数があるときや Windows では、
+出力先が端末でなくても `warn` の語を黄色にし、
+変わらなかったファイルの名前を灰色にします。
+`mmdfmt` がそれらに色を付けるのは、色を出せる端末か、
+`FORCE_COLOR` があるときだけで、`--color` や `--no-color` はありません。
 
 ## コードブロックの詳細
 
@@ -389,6 +727,23 @@ Markdown に Prettier とプラグインを使う場合とは、結果が 2 点
 引用は `>` の後ろの空白 1 つをマーカーの一部として読むので、そうしないと、
 空白で始まる図の行がその空白を失います。
 
+リスト項目や引用の中の図の行の幅は、ファイルの行の幅から、
+`mmdfmt` が各行の前に書くものの幅を引いた幅で、幅は 1 以上です。
+前に書くものは、1 文字を 1 桁と数えます。
+タブだけは次の `tabWidth` の倍数の桁まで進み、
+`tabWidth` が 0 のときは幅を持ちません。
+たとえば、行の幅が 40 のとき、行が空白 2 つで始まるリスト項目の中の図は、
+38 桁として整形します。
+`tabWidth` が 4 のとき、行が `>` とタブで始まる引用の中の図は、
+タブが 4 桁目まで進むので、36 桁として整形します。
+Prettier は、コンテナの中のデータブロックから、
+自分が行の前に印字するものの幅を同じように引きますが、
+印字するものが `mmdfmt` の書くものと違うことがあります。
+詳しくは、
+[Prettier を知っている方へ](#prettier-を知っている方へ)を参照してください。
+Gantt のセクションのコロンは例外で、Prettier はそろえるとき、
+行の前にあるものを数えません。
+
 閉じていないブロックは、リスト項目、引用、またはファイルの終わりまで続き、
 ほかと同じく整形します。
 改行なしでファイルを終えるときは、最後の行も改行なしのままです。
@@ -422,7 +777,7 @@ Markdown ファイルでは、変わる図の行だけを書きます。
 ## 文書
 
 - [フォーマッターのオプション](https://mmd-toolkit.github.io/mmd-toolkit/ja/formatter/options.html):
-  図にインデントをどう適用するか。
+  図にインデントと行の幅をどう適用するか。
 - [フォーマッターの互換性](https://mmd-toolkit.github.io/mmd-toolkit/ja/formatter/compatibility.html):
   拒否される図、mermaid.js との違い、整形が保証すること。