カスタムコンポーネント

見出しや箇条書きだけでは足りないときのために、注意書きの囲みや、手順の一覧、カードといった部品が用意されています。書き方はどれも似ていて、コロンを並べた短い行で中身を挟むだけです。書いたそばからプレビューに反映されるので、仕上がりを見ながら組み立てられます。

書き方の決まり

部品には、中身を挟む形のものと、文章の途中に置く形のものがあります。

中身を挟むものは、::: に続けて名前を書いた行で始め、::: だけの行で閉じます。

:::note
ここが中身です。
:::

囲みには見出しを付けられます。名前のうしろに角かっこで書きます。

:::note[覚えておくこと]
ここが中身です。
:::

文章の途中に置くものは、コロン 1 つで始めて角かっこに文字を入れます。

この機能は :badge[NEW] です。

細かい指定がある部品では、名前のうしろに波かっこで書き足します。title="日報の書き方" のように、値に空白を含むときは引用符で囲みます。

注意書きの囲み

note、tip、info、warning、danger の 5 つがあります。名前が違うと色と記号が変わるだけで、書き方はどれも同じです。

:::note
ふつうの補足です。
:::

:::tip[知っておくと便利]
知らなくても困らないが、知っていると早い話です。
:::

:::warning
うまくいかないかもしれない、という注意です。
:::

:::danger
取り返しがつかないことが起きる、という強い警告です。
:::

info は説明の補足、danger はいちばん強い警告です。読む人の目に入る順番は色で決まるので、ほんとうに大事なところにだけ danger を使うと効きます。

手順の一覧

steps の中に置いた段落が、上から順に番号の付いた手順になります。段落と段落のあいだは空行で区切ります。

:::steps
必要なものをそろえます。

設定を書き換えます。

動かして確かめます。
:::

カードとカードの並び

card は、見出しの付いた四角い枠です。title は必ず書きます。

:::card{title="日報のテンプレート"}
毎日ここから書き始めます。
:::

書き足せる指定は次のとおりです。

title — 枠の見出しです。省略できません。
icon — 見出しの前に置く記号です。
href — 枠全体をリンクにしたいときの行き先です。
variant — 見た目です。default、highlight、outline から選びます。書かないときは default です。

card を横に並べるときは card-grid で囲みます。囲む側はコロンを 1 つ増やして :::: にします。中身のコロンと数が同じだと、どこで閉じたのか読み取れなくなるためです。

::::card-grid{cols=2}
:::card{title="はじめに"}
最初に読む内容です。
:::

:::card{title="次に"}
そのあとに読む内容です。
:::
::::

cols には 2、3、4 を指定できます。書かないときは 2 です。

図と説明文

figure は、中身をひとまとまりの図として扱い、下に説明文を付けます。中に置けるのは画像に限りません。表でも箇条書きでも構いません。

:::figure{caption="今期の売上の推移" align=center}
![売上のグラフ](../assets/sales.png)
:::

caption — 下に出す説明文です。
align — 置き場所です。left、center、right から選びます。

文中の小さな札

badge は、文章の途中に置く小さな色付きの札です。

この項目は :badge[NEW]{variant=success} です。
この書き方は :badge[非推奨]{variant=danger} になりました。

variant には default、success、warning、danger を指定できます。書かないときは default です。

画像の大きさと配置

画像は、うしろに波かっこを付けると大きさと置き場所を決められます。専用の部品ではなく、ふつうの画像の書き方に足すだけです。

![会議室の写真](../assets/room.png){w=1/2}

![会議室の写真](../assets/room.png){w=1/3 align=right}

![会議室の写真](../assets/room.png){w=2/3 align=center caption="3 階の会議室"}

w — 幅です。1/4、1/3、1/2、2/3、3/4、full、auto から選びます。まわりの幅に対する割合で決まります。
align — 置き場所です。left、center、right から選びます。
caption — 画像の下に出す説明文です。

画像そのものの入れ方は画像・添付ファイルにまとめています。

挿入ダイアログ

書き方を覚えていなくても、一覧から選んで入れられます。Mod+Shift+I を押すか、コマンドパレットで Insert component… を実行します。

上の入力欄に名前の一部を打つと、候補が絞り込まれます。ダイアログの中で / を押すと、この欄に戻れます。
左側の All、Admonition、Layout、Inline で種類を切り替えられます。
矢印キーで選び、Enter で決めます。マウスでタイルをクリックしても同じです。
Escape で閉じます。

選ぶと、カーソルの位置に骨組みだけが入ります。囲みなら、名前を書いた開始の行と content の行と閉じの行の 3 行が入り、カーソルは content の先頭に置かれます。文字を選んでから開いたときは、選んでいた部分が骨組みに置き換わります。

Mod+Shift+I は Settings → Shortcuts の一覧には出てこないので、別のキーに変えることはできません。

入力補完

エディタで : を打つと、その場に候補が出ます。名前を最後まで打たなくても選べます。

この動きは Settings → Editor の Enable Directive Autocomplete で切り替えられます。最初は入っています。

名前を間違えたとき

登録されていない名前を書くと、プレビューでその部分が赤い点線で囲まれ、Unknown directive に続けて打った名前が表示されます。:::note を :::not と打ったような取り違えが、そのまま気付かず残ることはありません。

Help

Help（機能を用途から探せる一覧）で Directives を選ぶと、部品の説明を読めます。部品ごとに、指定できる項目の表と、書き方の見本と、その見本を表示した結果が並びます。書き方を思い出したいときは、このページよりこちらのほうが早いこともあります。

開き方は 3 通りです。

アプリ上部の toolbar にある Help のボタンをクリックします。
Command Palette（Mod+K で開く、コマンドの検索窓）で Open Help を実行します。
Mod+Shift+/ を押します。

Mod+Shift+/ は Settings → Shortcuts の一覧には出てこないので、別のキーに変えることはできません。

デスクトップアプリでは Open as external window で Help を別ウィンドウにできます。本文と並べて書式を確かめられます。詳しくは困ったときはにまとめています。