PRブランチ間のREADME変更を確認
PRブランチのREADME.mdがmainと比べて何が変わったかをすばやく見たい。でもGitHubを開いてレンダリングプレビューをスクロールし、3階層下の「Display the source diff」をクリックする気力はない。そんなときは2つの生ファイルをこのツールに貼り付けてください。見出し、コードフェンス、リンク先がはっきり浮かび上がります。PRが100個のソースファイルにも触れていてdocsの変更がノイズに埋もれているときに便利です。
元の Markdown
変更後の Markdown
Markdown差分: 2つのMarkdownファイルをオンラインで比較
2つのMarkdown文書を貼り付けるだけで、何が変わったかを行単位で確認できます。READMEファイル、リリースノート、MDX、frontmatter付きドキュメントに対応。差分はブラウザ内で実行されます。
Markdown差分ツールとは?
2つのMarkdown文書をソーステキストレベルで比較する、無料・ブラウザ完結のツールです。古いREADME.mdを左に、更新版を右に貼り付けると、変更された見出し、リスト項目、リンク、コードブロック、表のセルがすべて色付きで表示されます。データは端末から外に出ません。
差分は1文字ずつ行います。Markdownはプレーンテキストなので、これが正しいプリミティブです。レンダラーがどう解釈するかの推測ではなく、文書ソース上の実際の変更を確認できます。
一般的な散文比較にテキスト差分をすでに使っているなら、Markdownページは同じエンジンで、実際にドキュメントを書くときに出てくるケースに合わせた説明文になっています。Jekyll、Hugo、MkDocsの先頭にあるYAMLのfrontmatterブロックを比較するなら、YAMLページのほうがインデントに敏感な構造を扱うのに向いています。キー/値での厳密な構造化データはJSON差分が適任です。
差分の実際の動き
差分は文字レベルです。生の差分の後、意味的なクリーンアップ処理がハイライトを単語、リスト項目、リンク先などのまとまりに揃えます。インラインの`code span`を真ん中で切ったり、見出しの先頭##を本文から切り離したりしません。挿入は右側に緑、削除は左側に赤で表示されます。
これは描画後の出力ではなく、ソーステキストの差分です。Markdown作業ではこれが正しいプリミティブで、見た目以上に重要です。同じHTMLにレンダリングされる2つの文書でも、ソースは大きく異なる場合があります。**bold**と__bold__、*の箇条書きと-の箇条書き、入れ子リストの4スペースインデントとタブなど。レンダラーはこれらを同じ出力に潰してしまうので、信号が失われます。コントリビューターが本当に誤字を直しただけなのかを知りたいときは、ソース差分が答えてくれます。
Markdownは方言の家族でもあります。John Gruberによる原仕様(daringfireball.net)は意図的にゆるく、その後CommonMark、GitHub Flavored Markdown、Pandoc、MultiMarkdownがそれぞれ別方向に発展しました。表はGFMとPandocにはありますがCommonMarkにはありません。~~による打ち消し線や- [ ]のタスクリストはGFM拡張です。差分ツールは方言を気にせず、生のテキストをそのまま表示します。方言が問題になるのは、新しいdocsテーマで段落が正しくレンダリングされるかを問うときで、それは差分ではなくレンダラーの話です。
Markdownを3ステップで比較する
テキストペイン2つ、差分1つ。登録なし、アップロードなし、サーバーへの往復なし。
- 1
Markdownを貼り付けるかアップロード
左に古いバージョン、右に新しいバージョンを貼り付けます。あるいは、いずれかのペインでアップロードをクリックして
.md、.markdown、.mdxファイルを読み込みます。サンプルボタンを押すと両側に小さなREADMEの例が入り、自分の内容を貼り付ける前に差分の動作を確認できます。 - 2
必要なら改行コードを揃える
Windowsで編集したファイルはCRLFが多く、Linuxサーバーから来たファイルはLFです。文字レベルの差分はこれを別物として扱うため、全行が変更扱いになることがあります。差分が不自然に赤と緑で埋まっている場合は、まずエディタで両方のファイルを同じ改行コードに揃えてください。VS Codeでは下のステータスバーに現在の改行コードが表示されます。
- 3
差分を読む
削除は左に赤、挿入は右に緑で表示されます。2つのペインは同期してスクロールします。frontmatterブロック、コードフェンス、表の行、リスト項目はすべて差分エンジンから見ればただのテキストなので、その内部の変更も本文の変更と同じように表面化します。各ヘッダーの変更件数で、編集の重さをすぐに把握できます。
Markdown差分が適している場面
公開前にリリースノートのV1とV2を比較
リリースノートは公開までに何度も編集されます。下書きが並べ替えられ、箇条書きが統合され、バージョン番号が動きます。これまでに公開されたRELEASE_NOTES.mdと新しい下書きの差分を取れば、抜け落ちた項目や偶然できた重複を捕まえられます。レンダリングプレビューはこれが苦手で、よく似た行を目が滑ってしまいます。差分なら## Breaking changesセクションが本当にバージョン間で増えたかも簡単に確認できます。
CMSのエクスポートとソースリポジトリの差分
チームはGitリポジトリでMarkdownのドキュメントを書くが、公開サイトはMkDocs、Hugo、DocusaurusのようなCMSや静的サイトジェネレーターで生成している。ときどき公開ページがソースから乖離します。誰かがCMSのUIで生のページを編集してプッシュバックを忘れた、CIのステップがファイルを書き換えた、などです。公開ページをMarkdownとしてエクスポートして片方のペインに、リポジトリの.mdをもう片方のペインに置けば、ずれが数秒で目の前に出ます。
ブログ記事の下書きと編集者の修正
Markdownでブログ記事を編集者に送り、編集者がマーク付きの版を返してきました。2つの差分を取るほうが、段落ごとに読み直すよりずっと速くフィードバックを把握できます。とくに編集者がセクションの順番を変えたりイントロを書き直したりしている場合に有効です。ライターが編集パスを経て自分の声がどこまで残ったかを確認したいゴーストライティングでも同じように使えます。
MarkdownからMDXへの移行を監査
DocusaurusやAstroサイトを.mdから.mdxへ移行するのは無害な作業に見えるかもしれませんが、importが移動していたり、JSXコンポーネントがプレーンなMarkdown表を置き換えていたり、コードフェンスがカスタムコンポーネントで包まれていたりします。古いpage.mdと新しいpage.mdxをファイル単位で差分に取れば、移行の判断がレビュー可能になります。MDXは間違いだったとしてプレーンMarkdownに戻す場合でも、同じ流れが逆方向で使えます。
Markdownクイックリファレンス
このツールが最もよく表面化させる構文のエッジケースを短くまとめたものです。方言の列は機能を実際にサポートする方言を示します。レンダラー間のサプライズはほとんどここから生まれるためです。
| Topic | What this tool does |
|---|---|
| 方言間のずれ | Markdownは家族です。CommonMarkが事実上のベースラインです。GFMは表、タスクリスト、打ち消し線、自動リンクを追加します。PandocとMultiMarkdownは脚注、定義リストなどを追加します。同じソースでも方言間で大きく違って描画されることがあります。 |
| 表 | パイプ区切りの表はGFMとPandocに存在します。CommonMarkや原Markdownには含まれません。レンダラーがセルではなく生の|を表示する場合、パーサーがCommonMark厳密モードなので、GFM互換のパーサーが必要です。 |
| 打ち消し線 | ~~text~~はGFM拡張です。原MarkdownとCommonMarkはサポートしません。Pandocはstrikeout拡張を有効にすればサポートします。テキストにチルダがそのまま表示される場合、レンダラーがGFMを認識していません。 |
| タスクリスト | - [ ] todoと- [x] doneはGFM拡張です。CommonMarkではただの箇条書きとして括弧が文字どおり表示されます。GitHub、GitLab、現代的なdocsサイトの多くは対応しますが、素のMarkdownプロセッサーは通常対応しません。 |
| コードブロック: フェンスとインデント | フェンス付きコードブロック(三重バックティックまたはチルダ、任意の言語タグ付き)はCommonMarkで普及しています。原Markdownの仕様にはスペース4つでインデントするコードブロックしかなく、これはまだ動きますが言語ヒントを持てません。1つのファイルで両方を混ぜるのは合法ですが見栄えはよくありません。 |
| 強制改行 | 3つの選択肢があります。行末に2つの末尾スペースを置く、行末にバックスラッシュ\を置く(CommonMarkとGFM、原仕様にはなし)、もしくは段落区切りの空行を入れる、です。末尾スペースはほとんどのエディタで見えないため、強制改行は人が見つけられない差分でしばしば生き残ります。 |
| frontmatter | ファイル冒頭の---に挟まれたYAML、+++に挟まれたTOML、{ }に挟まれたJSONです。Markdownの仕様には含まれませんが、Jekyll、Hugo、MkDocs、Docusaurus、Astroで広く使われます。レンダラーは本文を解析する前にこれを取り除きます。 |
| インラインHTML | CommonMarkはMarkdown内に生のHTMLタグを許します。GFMも同様ですが、github.comでのレンダリング時にHTMLサニタイザを適用します。静的サイトジェネレーターによってサニタイズするもの、HTMLをそのまま通すもの、エスケープするものがあります。<div>や<iframe>のブロックを埋め込んだページの差分は、移行の監査でよく出てきます。 |
Markdown差分: よくある質問
これはレンダリング後の出力をプレビューしますか?
いいえ。このツールはMarkdownのソーステキストを差分にかけ、レンダラーが生成するHTMLは扱いません。これは意図的です。同じHTMLにレンダリングされる2つの文書でも、ソースには意味のある違いが残ることがあります。たとえば*と-の箇条書き、**と__の太字などです。ソースレベルの差分はこの信号を保ちます。レンダリング結果を見たい場合は、いつものプレビューア(GitHubのウェブUI、VS Code、お使いの静的サイトジェネレーター)に貼り付けてください。
レンダリング後のHTMLを比較するのとどう違いますか?
レンダリング後のHTML差分は読み手が見るものを教えてくれます。ソース差分はファイルで実際に何が変わったかを教えてくれます。答える質問が違います。Markdownの場合、ソース差分のほうがほぼ常に有用です。書き手の編集を忠実に映すからで、見出しレベルが##から###に変わった、コードフェンスの言語タグが切り替わった、相対リンクが絶対リンクになった、といった違いが見えます。HTMLレベルの比較が必要なら、両方のファイルを先にレンダラーに通してから出力を差分にかけてください。
CommonMarkとGitHub Flavored Markdownの曖昧さはどう扱いますか?
差分自体はMarkdownを解析しないので、方言は気にしません。表、タスクリスト、打ち消し線、自動リンクなどの拡張も、ただのテキストに見えるだけです。方言が問題になるのは、文書がまだ正しくレンダリングされるかを確認したいときです。CommonMarkはベースラインの仕様にいちばん近いもので、GitHub Flavored MarkdownはCommonMarkに表、タスクリスト、打ち消し線、自動リンクを足したものです。ターゲットのレンダラーが対応しているほうを選んでください。
YAMLやTOMLのfrontmatterはどう扱われますか?
frontmatterはファイル先頭にあるテキストにすぎず、YAMLは---、TOMLは+++で囲まれます。Hugo、Jekyll、MkDocsなどの静的サイトジェネレーターはこれをページのメタデータとして使います。差分はこのブロックを通常のテキストとして扱うので、title:、date:、tags:の変更も他の行と同じように表示されます。frontmatterが大きくインデントに敏感なら、そのブロック単独にはYAML差分ページのほうが向いています。
Markdown内のMDXやJSXでも動きますか?
はい。MDXはMarkdownにJSXコンポーネントを埋め込んだもので、JSXは差分から見ればただの追加テキストです。.mdxファイルをいずれかのペインに貼り付ければ、importの変更、コンポーネントのpropsの変更、周囲のMarkdownの変更を、.mdと同じように差分が浮かび上がらせます。ツールがしないのはJSXがコンパイル可能かの検証だけで、それはMDXコンパイラの仕事です。JSXの部分だけをコードとしてレビューしたいときは、テキスト差分に貼り付けてください。
改行コード(CRLFとLF)はどう扱われますか?
改行コードは文字なので、Windows形式のCRLFで保存されたファイルとUnix形式のLFで保存されたファイルは、行ごとに違うものとして差分が出ます。ペインが幻の変更だらけに見える場合、ほぼ常にこれが原因です。直し方は、貼り付ける前にエディタで両方のファイルを同じ改行コードに揃えることです。VS Codeなら下のステータスバーに現在の改行コードが出ていて、ワンクリックで切り替えられます。Gitのcore.autocrlf設定もマシン間で意外なCRLF差を生むことがあります。
プライバシーと仕組み
あなたのMarkdownはブラウザから外に出ません。エディタ、差分、フォーマッタはすべてあなたの端末で動きます。入力に対する解析もログもサーバー往復もありません。フォーマット自体の参考資料はWikipediaにあり、最新のCommonMark仕様はspec.commonmark.org/0.31.2、GitHubの方言はgithub.github.com/gfmにあります。