Markdown

Markdown の「フェンス付きコードブロック」と、HTML をそのまま出す書き方

Markdown で ``` で囲む書き方は、正式には フェンス付きコードブロック(fenced code block)と呼びます。後ろに付ける mermaid や sql は info string です。囲んだ中の HTML を「そのまま出す」書き方は、よく使われていそうなのに、実は標準がありません。ツールごとの書き方と、GitHub・Redmine で SVG の図を見せる方法をまとめます。

呼び方

```mermaid flowchart LR A --> B ``` フェンス + info string(言語) 中身 閉じるフェンス
  • 呼び方は、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
plantumlUML の図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 の READMERedmine の Wiki
本文に <svg> を直接書く✕ 安全のためタグが取り除かれる✕ HTML は通らない
SVG ファイルを画像として読み込む○ ![図](docs/figure.svg)△ 添付の !figure.svg! は出ないことが多い
```mermaid○プラグインが必要
  • GitHub で SVG を見せるなら、ファイルにして画像として読み込むのが唯一の方法です。背景が透明だとダークモードで文字が見えなくなるので、白い背景の四角を 1 枚敷いておきます。
  • Redmine は、添付ファイルを「画像かどうか」を拡張子で決めていて、SVG はその一覧に入っていません。SVG の中にはスクリプトを書けるので、XSS(悪いスクリプトを動かされる攻撃)を防ぐためです。確実に見せるなら PNG に書き出して貼ります。

あとから直すことが多い図は、PNG より Mermaid か SVG で持つのがおすすめです。文字なので直しやすく、git で差分も見られます。見せる場所に合わせて、Mermaid のまま・SVG ファイル・PNG に書き出す、を使い分けます。

なぜ「HTML をそのまま出す」書き方に標準がないのかは、Markdown で SVG や HTML をそのまま出す書き方に、標準がない理由に書きました。

スポンサーリンク
タイトルとURLをコピーしました