Markdown整形ツールでできること
Markdown は書き方の自由度が高い言語です。箇条書きは -、*、+ のどれでも書け、強調は * でも _ でも、見出しはイコール記号の行でも # でも書けます。入力するときは便利ですが、複数人で編集したファイルはすぐにいろいろなスタイルが混ざります。表の列はずれ、空行は抜け、差分は見づらくなります。
このツールは、ソースをひとつの一貫したスタイルで書き直します。多くの JavaScript プロジェクトがドキュメントの整形に使っている Prettier をもとにしているので、VS Code やコマンドラインで Prettier を使った場合と同じ結果になります。
使い方
- 左のボックスに Markdown を貼り付けるか、ファイルを開く で
.mdファイルを読み込みます。貼り付けるとすぐに整形されます。 - 先に例を見たいときは サンプル を押します。
- インデント、行の幅、折り返し の方法（そのまま、行の幅で折り返す、段落ごとに1行）を選びます。
- 何かを変更した後にもう一度実行するには、整形（または Ctrl+Enter）を押します。
- コピー か ダウンロード で結果を取り出します。クリア を押すと入力が空になります。
一度整形すると、その後は入力に合わせて出力が更新されます。
整形前と整形後
いろいろなスタイルが混ざった短いファイルです。
Project Notes
=============
* Install the tools
* Run the build
+ Deploy
|Name|Role|
|-|-|
|Ada|Admin|
|Linus|Editor|
Some *emphasis* and __bold__ text.整形ツールの出力です。
Project Notes
=============
- Install the tools
- Run the build
* Deploy
| Name | Role |
| ----- | ------ |
| Ada | Admin |
| Linus | Editor |
Some _emphasis_ and **bold** text.いくつかの変化がありました。見出しの後に空行が入りました。最初のリストは - を使うようになりました。太字は **、斜体は _ になりました。表の列には余白が加えられ、プレーンテキストのままでも列がそろっています。「Deploy」が分かれたままになっている点に注目してください。別の記号を使っていたため Markdown では2つ目のリストとして扱われ、整形ツールは別の記号を付けることでその意味を保っています。
表の列そろえでは、日本語のような全角文字は半角2文字分の幅として数えられるので、日本語を含む表もプレーンテキストの状態で縦の線がそろいます。
長い段落の折り返し
折り返し を 行の幅で折り返す にして、行の幅を 60 にすると、次の段落は
Markdown files are easier to review when each paragraph follows the same rule for line length, because a diff then shows only the sentence that changed.こうなります。
Markdown files are easier to review when each paragraph
follows the same rule for line length, because a diff then
shows only the sentence that changed.段落ごとに1行 は逆の処理で、折り返された行を1行に戻します。チームの方針がわからないときは、そのまま が安全な初期設定です。なお、折り返しはスペースの位置で行われるため、スペースを含まない日本語だけの段落は、行の幅で折り返す を選んでも1行のまま残ります。
変更しないもの
このツールが変えるのはレイアウトで、意味は変えません。次のものには意図的に手を加えません。
- コードブロック：フェンスで囲んだブロック内のコードは書いたとおりに残ります。
jsと指定したブロックにconst a={b:1}が入っていても整形されません。それには JavaScript整形ツール を使ってください。 - 番号付きリスト：すべての項目が
1.で始まっていれば、すべての行で1.のままにします。1、2、3 と番号を振っていれば、その番号を残します。 - 正しい構文になっていないテキスト：スペースのない
#Titleは CommonMark では見出しにならないので、通常の段落のまま残ります。スペースを入れれば見出しになります。 - インライン HTML：Markdown の中の HTML タグはそのまま残ります。
ヒント
- コミットする前に整形しましょう。ファイルの書き方がそろっていれば、プルリクエストの差分には本当の編集だけが表示されます。
- 折り返しのルールはリポジトリ全体でひとつに決めましょう。折り返したファイルとそうでないファイルが混ざっていると、誰かが初めて整形したときに大きな差分が出てしまいます。
- 表を手で作るのは手間がかかります。Markdown 表作成ツール なら、マス目に入力したり、スプレッドシートから貼り付けたりできます。
- Web ページや Word ファイルから Markdown を作りたいときは、HTML Markdown 変換ツール や Word Markdown 変換ツール を使い、その結果をここで整えてください。
Markdownを整形するほかの方法
- VS Code：Prettier 拡張機能を入れて
.mdファイルを開き、「ドキュメントのフォーマット」を実行します。このページと同じ結果になります。 - コマンドライン：
npx prettier --write README.mdでファイルをその場で整形します。段落を折り返すには--prose-wrap alwaysを追加します。 - リント：markdownlint は、見出しのレベルや行の長さなどのスタイルルールをチェックします。リンターは問題を報告し、フォーマッターはレイアウトを直してくれます。両方を使うプロジェクトも多くあります。
制限事項
このツールは、CommonMark と、表やタスクリストなどの GitHub 拡張に従います。カスタムコンテナや Wiki リンクなど、ほかのツール独自の拡張は通常のテキストとして扱われるため、そのツールが想定するのとは違うスペースの入れ方になることがあります。ファイル先頭のフロントマター（2本の --- 行に挟まれたブロック）は残ります。大きなファイルも扱えますが、処理はすべて端末内で行われるため、整形に時間がかかります。