マークダウンの裏技：足りない機能を補うワークアラウンド集
マークダウンの裏技とは、下線付きテキストからクリックできる動画サムネイルまで、Markdownの基本仕様にない機能をHTMLスニペットや工夫した記法で実現するテクニックです。 ほぼすべての裏技は、レンダラーがインラインHTMLを受け入れるという1つの条件に依存します。CommonMarkは生のHTMLをデフォルトでそのまま通すため、VS Code、Obsidian、Typora、そして当サイトのエディタでは、これらのワークアラウンドが正しく表示されます。サニタイズを行うプラットフォームでは挙動が異なります。GitHubは固定のタグ許可リストで出力をフィルタリングし、すべてのstyle属性を削除します。RedditとDiscordはHTMLを完全に無視します。以下の各セクションで、記法と、それを保持または削除するレンダラーを紹介します。
markdown で下線を引く
Markdownには下線の記法がないため、テキストをHTMLの <ins> タグまたは <u> タグで囲みます。 <ins> タグは挿入されたテキストを示すもので、主要なブラウザすべてで下線付きで表示されます。GitHubのサニタイザーは <ins> を残して <u> を削除するため、READMEでは <ins> が移植性の高い選択肢です。
Submit the form <ins>before 30 June</ins> to qualify.
ObsidianとTyporaは両方のタグをレンダリングします。BearとSimplenoteはHTMLを使わず、独自の下線ショートカットを提供しています。RedditではパーサーがHTMLを破棄するため、タグはそのまま文字として表示されます。
段落をインデントする
Markdownは行頭のスペースを無視し、4スペースのインデントはコードブロックに変換してしまうため、段落の字下げには (ノーブレークスペース)エンティティを使います。 各エンティティは出力で1つの表示スペースとして残ります。4つ並べれば従来のタブ幅を再現できます。
The opening line of this paragraph sits four spaces in.
エンティティはタグではなく文字参照であるため、GitHubを含むほぼすべてのレンダラーを通過します。弱点は規模が大きくなったときに現れます。インデントした段落が何十もあるドキュメントはソースの可読性が下がるため、iA Writerのようにテンプレートを制御できるエディタの方が字下げをきれいに扱えます。
マークダウンで中央揃えにする
行を中央揃えにするには <center> タグを使うか、インラインCSSが有効な環境では <p style="text-align:center"> を使います。 <center> タグは1999年のHTML 4.01で非推奨になりましたが、ブラウザは今でも解釈し、ほとんどのMarkdownレンダラーもそのまま通します。
<center>Chapter 7</center>
<p style="text-align:center">Chapter 7</p>
GitHubはstyle属性を削除するため、2つ目の形式はGitHubでは機能しません。READMEの作者がロゴやバッジの中央揃えに <div align="center"> を使うのは、align属性がGitHubのサニタイザーを通過するからです。TyporaとVS CodeのプレビューはCSS版を記述どおりにレンダリングします。
markdown で文字色を変える
Markdownに文字色を指定する機能はありません。CSSが許可されている環境では <span style="color:#0969da"> を、古い <font color="red"> タグをまだ受け付けるレンダラーではそちらを使います。
<span style="color:#0969da">This sentence renders in blue.</span>
<font color="red">This sentence renders in red.</font>
<font> タグは1999年に非推奨となり、最近のサニタイザーは容赦なく削除します。GitHubはstyle属性もcolor属性も取り除くため、READMEではどちらの形式でも文字色は付きません。GitHubでの代替手段としてよく使われるのが、言語に diff を指定したコードブロックです。+ で始まる行は緑、- で始まる行は赤で表示されます。ObsidianとTyporaは <span> 版を解釈し、生のHTMLを通すHugoやJekyllのサイトでも機能します。
マークダウンのコメントを隠す
読者に見せたくないメモは、リンク参照を利用した [comment]: # の書き方か、標準のHTMLコメントで隠します。 どちらもテキストをソースファイルに残したまま、レンダリング後のページからは消します。
[everything in this line disappears from the output]: #
<!-- This note also stays hidden. -->
ブラケット記法はMarkdownのコア機能であるリンク参照定義を応用したもので、HTMLがブロックされる環境でも機能します。前後に空行を入れないと、隣接する段落が定義に取り込まれることがあります。HTMLコメントの方が読みやすい一方、生成されたページのソースには残るため、誰でも閲覧できます。GitHubは両方の方法に対応しています。
注意書きとコールアウトボックス
コールアウトボックスは、引用ブロックの中に絵文字と太字のラベルを入れて作るか、2023年に導入されたGitHubのアラート記法を使います。
> [!WARNING]
> This command overwrites all 14 archived backups.
> 💡 **Tip:** Blockquote callouts work in any renderer.
GitHubはNOTE、TIP、IMPORTANT、WARNING、CAUTIONの5種類のアラートに対応しています。github.com上ではそれぞれ固有のアイコンとアクセントカラー付きで表示されますが、他の環境ではこの記法はただの引用ブロックになります。Obsidianには > [!note] という独自のコールアウト形式があり、2022年のバージョン0.14で追加されました。MkDocsのMaterialテーマは !!! note の行を使います。どの環境でもそれなりに見えるのは、絵文字を使った引用ブロックだけです。
画像をリサイズする
Markdownの画像記法を <img> タグに置き換え、width と height 属性をピクセル単位で指定します。
<img src="diagram.png" alt="Deployment diagram" width="480" height="270">
GitHubは style="width:50%" を削除する一方でwidth属性とheight属性は残すため、READMEではピクセル指定が確実な方法です。寸法を固定しておくと、ページ読み込み中のレイアウトシフトも防げます。HTML非対応のレンダラーではタグがそのまま文字として表示されるので、Redditのようなプラットフォームでは通常の  形式を使い続けてください。
画像にキャプションを付ける
キャプションは <figure> と <figcaption> タグで付けるか、画像の直下に斜体の行を置きます。
<figure>
<img src="harbor.jpg" alt="Fishing boats at dawn">
<figcaption>Hobart's harbor, photographed in March 2025.</figcaption>
</figure>
*Hobart's harbor, photographed in March 2025.*
<figure> と <figcaption> はどちらもGitHubの許可リストに載っているため、セマンティックな書き方はREADMEで機能します。斜体の行はHTML非対応レンダラー向けのフォールバックです。スクリーンリーダーはこれをキャプションではなく本文として読み上げます。移植性と引き換えのトレードオフです。
リンクを新しいタブで開く
Markdownのリンクは新しいタブで開けないため、target="_blank" を付けた生のHTMLアンカーで書きます。
<a href="https://example.com/report" target="_blank" rel="noopener">2026 annual report</a>
rel="noopener" を付けて、開いた先のページが元のウィンドウをスクリプトで操作できないようにします。この裏技が使える場面は限られます。GitHubはサニタイズ時にtarget属性を削除するため、READMEのリンクはすべて同じタブで開きます。HTMLをそのまま通すHugoやJekyllのような静的サイトジェネレーターでは機能し、新しいタブで開く動作が本当に重要なのもそうした場面です。
記号と特殊文字
Markdownファイルはプレーンな Unicode テキストなので、記号は直接入力できます。キーボードから打ちにくい記号にはHTMLエンティティを使います。 © や → を文字参照のページからコピーしてファイルに貼り付ければ、そのまま表示されます。
| 記号 | HTMLエンティティ |
|---|---|
| © 著作権 | © |
| ® 登録商標 | ® |
| ™ 商標 | ™ |
| → 右矢印 | → |
| ° 度 | ° |
| € ユーロ | € |
エンティティはGitHubを含むほぼすべてのレンダラーで変換されます。唯一の落とし穴はコードブロックです。フェンス付きコードの中ではエンティティのデコードが無効になるため、© はそのまま文字として表示されます。
目次を作る
目次は、見出しのアンカーIDを指すリンクを箇条書きにして作ります。 GitHub、GitLab、その他ほとんどのレンダラーはすべての見出しにIDを生成します。テキストは小文字化され、スペースはハイフンになり、ほとんどの記号は削除されます。
- [Underline Text](#underline-text)
- [Resize Images](#resize-images)
- [Embed Videos](#embed-videos)
「Resize Images」という見出しには #resize-images というアンカーが付きます。GitHubは2021年からREADMEのヘッダーに自動目次ボタンを表示しているため、手動のリストが役立つのは、他のプラットフォーム上の長いドキュメントです。見出し名を変更するとリンクが静かに壊れるので、見出しを編集するたびにアンカーを確認し直してください。
動画を埋め込む
Markdownでは動画プレーヤーを埋め込めないため、クリックできるサムネイル画像を動画にリンクさせます。 YouTubeはすべての動画のサムネイルを予測可能なURLで公開しているので、このパターンは簡単に使えます。
[](https://www.youtube.com/watch?v=VIDEO-ID)
VIDEO-ID の部分を動画URLの11文字のコードに置き換えます。サムネイルは標準のMarkdownが動く場所ならどこでも表示され、クリックするとYouTubeで動画が開きます。プラットフォームが許可していれば、2つの上位手段があります。GitHubは2021年5月から、Issue、プルリクエスト、Discussion、Markdownファイルでの .mp4 と .mov の直接アップロードに対応しています。また、HTMLを完全にサポートするレンダラーなら、YouTubeの <iframe> 埋め込みコードを貼り付けても機能します。
よくある質問
マークダウンの裏技はGitHubで使えますか?
一部は使えます。GitHubは <ins>、<img> のwidth属性、<figure>、HTMLコメント、エンティティ、そして独自のアラート記法を保持しますが、すべてのstyle属性とtarget属性を削除します。 サニタイザーの許可リストは予告なく変わることがあるため、裏技に頼る前に下書きのGistでテストしてください。
レンダリングされたページからHTMLが消えたのはなぜですか?
RedditやDiscordのようにレンダラーがインラインHTMLを完全にブロックしているか、サニタイズの過程で使用したタグや属性が削除されたかのどちらかです。 プラットフォームのドキュメントで許可リストを確認し、削除された要素を許可されているものに置き換えてください。たとえばstyle属性の代わりに <div align="center"> を使います。
コメントには [comment]: # と <!-- --> のどちらが良いですか?
メモを完全に消したいときは [comment]: # を、ソースの読みやすさを優先するときは <!-- --> を使います。 ブラケット形式はMarkdownパーサーに消費されて出力に一切残りませんが、標準のHTMLコメントはページのソースを表示すれば誰でも見られます。