GitHub のアラート記法に対応した #

仕様 #

引用の先頭行が [!NOTE]、[!TIP]、[!IMPORTANT]、[!WARNING]、[!CAUTION] のどれかひとつだけのとき、その引用をアラートとして扱う。マーカーは大文字小文字を区別せず、小文字に正規化して種類（kind）として持つ。GitHub に合わせて、以下のときは普通の引用のままにした。

• マーカーが先頭行でない（引用の途中に現れる）
• マーカーと同じ行に本文が続く
• 知らない種類（[!HINT] など）

書き間違いをアラートにしてしまうより、ただの引用に留めるほうが安全だからだ。

Note

先頭行にマーカーだけを置く。マーカー自身は描かれず、種類とタイトルになる。

pico.css v2 で足りるか #

実装の前に、素の pico.css v2 でこの見た目が組めるかを確認した。結論として、アラートやコールアウト相当のコンポーネントは pico v2 にはない。blockquote には先頭側に 0.25rem のバーを引くだけだ。

そこで描画は blockquote のままにしてクラスを足し、種類ごとの色とタイトルは site.css に書いた。色は GitHub のダークテーマのパレットをそのまま借り、タイトルのアイコンは octicons を data URI の mask で出している。mask にするとアイコンが background-color の色で描かれるので、5 種類を同じ形で扱える。

実装 #

tinymarkdown には Quote の隣に Alert{kind, children} というブロックを足した。引用として集めた行の先頭がマーカーなら、その行を外して残りを普通に解析する。つまりアラートの中身は引用と同じく何でも入る。Go 版、MoonBit 版、そこから生成される ts 版、全部に同じ形で入れ、テストもいつも通り case をミラーした。

Tip

記事を書く側は、いつもの引用の先頭に [!種類] を足すだけでよい。

デモ #

Note

流し読みの人にも知っていてほしい、補足の情報。

Tip

もっと上手く、もっと楽にやるための助言。

Important

目的を達成するために必要な、中心となる情報。

Warning

問題を避けるために、今すぐ注意してほしい情報。

Caution

ある操作がもたらしうる、リスクや悪い結果への忠告。

強さの目安は「NOTE が脚注的な補足、TIP が近道、IMPORTANT が本題、WARNING が注意、CAUTION が警告」くらいの順だろうか。

Important

マーカーを書かない引用は、これまで通りの見た目のまま。

おわりに #

「引用にちょっと色を付ける」だけの機能だが、記事中の注意書きが目に留まるようになった。octicons と GitHub のパレットを借りたおかげで、見た目もそれらしくなったと思う。