Markdown で ``` で囲む書き方は、正式には フェンス付きコードブロック(fenced code block)と呼びます。後ろに付ける mermaid や sql は info string です。囲んだ中の HTML を「そのまま出す」書き方は、よく使われていそうなのに、実は標準がありません。ツールごとの書き方と、GitHub・Redmine で SVG の図を見せる方法をまとめます。
呼び方
- 呼び方は、Markdown の仕様(CommonMark・GitHub Flavored Markdown)の用語です。
```を柵(フェンス)に見立てています。~~~でも同じです。 - 仕様が決めているのは「中身をコードとして出す」ところまでです。info string を見て図に描き変えるのは、表示する側(GitHub・VS Code など)の機能です。だから、対応している info string はツールごとに違います。
よく知られている info string です。
| info string | 描かれるもの | 主な対応 |
|---|---|---|
mermaid | フローチャート・シーケンス図など | GitHub・GitLab・Obsidian など |
math | 数式(LaTeX の書き方) | GitHub・GitLab・Obsidian |
plantuml | UML の図 | GitLab・Confluence・VS Code の拡張 |
dot | グラフ(Graphviz) | GitLab・VS Code の拡張 |
geojson・stl | 地図・3D のモデル | GitHub |
diff | 差分(+ は緑、- は赤) | ほぼどこでも(色付け) |
HTML をそのまま出す書き方は、ツールごとに違う
図の SVG のように「この部分は HTML としてそのまま出してほしい」ことはよくあります。このブログの下書きでは、```html-raw で囲み、記事にするときに WordPress の「カスタム HTML」ブロックに変えています。同じことをしたい人は多いはずですが、書き方はツールごとにバラバラです。
| ツール | 書き方 |
|---|---|
| Markdown の標準(CommonMark) | 囲まずに、HTML をそのまま書く |
| Pandoc・Quarto・R Markdown | ```{=html} で囲む |
| MyST(Jupyter Book・Sphinx) | ```{raw} html で囲む |
| kramdown(Jekyll) | {::nomarkdown} と {:/} で囲む |
| このブログの下書き | ```html-raw で囲む(自作の決まり) |
標準の「そのまま書く」には弱点があります。HTML の途中に空行があると、そこで HTML が終わった扱いになり、残りが Markdown として読まれて崩れます。長い SVG では起きやすいので、各ツールが「囲む」書き方を用意しています。
どの書き方も、対応していないツールではただのコードとして表示されます。「どのツールでも図として出る書き方」はありません。
GitHub と Redmine で SVG の図を見せる
| 書き方 | GitHub の README | Redmine の Wiki |
|---|---|---|
本文に <svg> を直接書く | ✕ 安全のためタグが取り除かれる | ✕ HTML は通らない |
| SVG ファイルを画像として読み込む | ○  | △ 添付の !figure.svg! は出ないことが多い |
```mermaid | ○ | プラグインが必要 |
- GitHub で SVG を見せるなら、ファイルにして画像として読み込むのが唯一の方法です。背景が透明だとダークモードで文字が見えなくなるので、白い背景の四角を 1 枚敷いておきます。
- Redmine は、添付ファイルを「画像かどうか」を拡張子で決めていて、SVG はその一覧に入っていません。SVG の中にはスクリプトを書けるので、XSS(悪いスクリプトを動かされる攻撃)を防ぐためです。確実に見せるなら PNG に書き出して貼ります。
あとから直すことが多い図は、PNG より Mermaid か SVG で持つのがおすすめです。文字なので直しやすく、git で差分も見られます。見せる場所に合わせて、Mermaid のまま・SVG ファイル・PNG に書き出す、を使い分けます。
なぜ「HTML をそのまま出す」書き方に標準がないのかは、Markdown で SVG や HTML をそのまま出す書き方に、標準がない理由に書きました。
