Markdown 拡張機能

Markdown 拡張機能

標準 Markdown に加えて、BX Sites は bx-markdown のネイティブ Flexmark 拡張機能を デフォルトで 3 つ有効にします - Admonition、脚注、定義リストです - さらに独自の Mermaid ダイアグラム統合も備えています。この 4 つはすべて bxsites.json の markdown/mermaid キー から設定できます。

これらに加えて、BX Sites は Flexmark がまったく概念すら持たない、独自の拡張機能を さらに 3 つ実装しています - コンテンツタブ、数式、そしてフェンスコードの hl_lines/linenums/title アノテーションです。bx-sites は bx-markdown の パーサーをフォークできないため、それぞれが通常の Markdown 変換の前後に 挟まる前処理/後処理パスとして動作します - 詳細は下記の各セクションを参照してください。

flowchart LR
    A["生の Markdown"] --> B["前処理:\nタブの抽出、数式の保護、\nコードアノテーションの除去"]
    B --> C["Markdown()\n(bx-markdown)"]
    C --> D["後処理:\nタブの復元、数式の復元、\nコードアノテーションの適用"]
    D --> E["最終ページ HTML"]

Admonition

コールアウト/注意書きボックス - デフォルトで有効、bxsites.json の設定は不要です:

!!! note "ご注意"
    これは Admonition です。内容は通常の Markdown です - **太字**、
    `コード`、[リンク](../index.md)、リストなど、すべて普段どおりに使えます。

次のようにレンダリングされます:

型（上記の note）がボックスのアイコン/色になり、明示的な "タイトル" を 指定しない場合はその型自身の名前が大文字化されたものが使われます。多くの 一般的な同義語が、それぞれ独自のアクセントカラーを持つ同じ 12 の標準型に 解決されます:

本文は 4 スペース（またはタブ）でインデントしたままにする必要があります。 インデントされておらず、かつ空行でもない最初の行でブロックが終了します。 空行はブロック内では問題ありません - Markdown の他の場所とまったく同じく、 単に新しい段落が始まるだけです。

折りたたみ可能な Admonition

!!! の代わりに型の前に ??? を付けると折りたたみ可能なブロックになります - ??? は折りたたまれた状態で始まり、???+ は展開された状態で始まります。 どちらの場合も見出しをクリックして切り替えられます:

??? tip "クリックして展開"
    これは折りたたまれた状態で始まります。

???+ tip "クリックして折りたたむ"
    これは展開された状態で始まります。

{"markdown":{"enableAdmonition":false}} で Admonition を完全に無効にできます。

脚注

[^label] でインライン脚注を参照し、[^label]: text でドキュメント内の どこにでもそのテキストを定義できます:

これは裏付けが必要な主張です[^1]。

[^1]: これがその裏付けです。

これは裏付けが必要な主張です¹。

脚注の定義は、ソース内のどこに書かれていても、ページ下部に番号付きリストとして 集められてレンダリングされます。デフォルトでは無効です - {"markdown":{"enableFootnotes":true}} で有効にします。

定義リスト

用語行とそれに続く 1 つ以上の : 説明行が <dl> になります:

用語
:   その定義。

2 番目の用語
:   最初の定義。
:   2 番目の定義。

用語

その定義。

2 番目の用語

最初の定義。

2 番目の定義。

デフォルトでは無効です - {"markdown":{"enableDefinitionLists":true}} で 有効にします。

コンテンツタブ

異なる言語やプラットフォームの代替コンテンツを、クリック可能な一連のタブに まとめます。=== "タイトル" を使い、Admonition の本文と同じ方法で インデントします（4 スペースまたはタブ）:

=== "Java"
    ```java
    System.out.println( "Hi" );
    ```

=== "BoxLang"
    ```bx
    println( "Hi" )
    ```

次のようにレンダリングされます:

System.out.println( "Hi" );

println( "Hi" )

連続した === "..." ブロック（間に空行が最大 1 行まで）は 1 つのタブ グループを形成します。タブ自身の内容は完全な Markdown です - コードフェンス、 リスト、Admonition など、他のどこにでも書けるものが使えます。bxsites.json の設定は不要 - 常に有効です。

コードブロック

フェンスコードブロックはクライアントサイドで構文ハイライトされます （highlight.js）。設定は不要です - 開きの ``` の後の言語識別子でグラマーが 選択されます（例: ```json）。highlight.js 自身が同梱する言語に加えて、 BX Sites は bx/boxlang/bxs/bxm/cfscript 用に独自の軽量な BoxLang グラマーを登録しています:

class {

	numeric function add( required numeric a, required numeric b ) {
		var result = a + b
		var message = "The sum is #result#"
		return result
	}

}

行番号、ハイライト行、タイトル

フェンスの情報文字列に linenums、hl_lines、title を追加します （任意の組み合わせで、すべて省略可能です）:

```bx hl_lines="2" linenums="1" title="add.bx"
numeric function add( required numeric a, required numeric b ) {
	return a + b
}
```

次のようにレンダリングされます:

numeric function add( required numeric a, required numeric b ) {
	return a + b
}

linenums="N" はガターのカウントを N から開始します。hl_lines は スペース区切りの行番号や範囲（"2 4-6"）を受け取ってハイライトし、 linenums がどこから始まるかに関係なく、ブロックの先頭からカウントします。 title はブロックの上に小さなタイトルバーを追加します。bxsites.json の設定は不要 - 常に使用できます。

差分マーカーとターミナルフレーム

insert/delete を追加すると、追加/削除された行を示せます - hl_lines がすでに使っているのと同じ、スペース区切りの行番号/範囲構文です - 色付きの 行と +/– のガターマーカーとして表示されます:

```bx title="add.bx" insert="3-4" delete="7"
numeric function add( required numeric a, required numeric b ) {
	var sum = a + b
	var total = a + b
	log.info( "computed sum", total )
	return sum
}
```

次のようにレンダリングされます:

numeric function add( required numeric a, required numeric b ) {
	var sum = a + b
	var total = a + b
	log.info( "computed sum", total )
	return sum
}

意図的に省略せず書きます（ins/del ではありません）。一部のツールがやる ようなリテラルな +/- の行プレフィックスではなく属性として扱うため、 フェンス自身の内容は本物の、無加工でコピー＆ペースト可能なソースコードの ままです - 既存のコピーボタンから何かを取り除く必要もありません。 insert/delete は linenums ときれいに積み重なります - 両方が有効な 場合、ガターマーカーは行番号の列を避けて右にずれます。

frame="terminal" を追加すると、プレーンなタイトルバーの代わりに macOS 風のターミナルウィンドウ（3 つのステータスドット、中央揃えのタイトル）に なります:

```bash frame="terminal" title="user@boxlang"
box install bx-sites
```

次のようにレンダリングされます:

box install bx-sites

frame="code" は、今日のデフォルトであるプレーンなバーを明示的に指定する 名前です - デフォルトなので書く必要はありません。insert/delete も frame も、hl_lines/linenums/title と同様に bxsites.json の設定は 不要です。

本物の git diff

フェンスに diff を指定すると、実際の git diff/git show の出力を そのまま貼り付けられます - これは bx-sites 独自の構文ではまったくなく、 highlight.js 自身の diff グラマーが Unified diff 構文（+/-/@@ 行）を 自動的に認識しているだけです:

```diff
--- a/add.bx
+++ b/add.bx
@@ -1,4 +1,5 @@
 numeric function add( required numeric a, required numeric b ) {
-	var sum = a + b
-	return sum
+	var total = a + b
+	log.info( "computed", total )
+	return total
 }
```

次のようにレンダリングされます:

--- a/add.bx
+++ b/add.bx
@@ -1,4 +1,5 @@
 numeric function add( required numeric a, required numeric b ) {
-	var sum = a + b
-	return sum
+	var total = a + b
+	log.info( "computed", total )
+	return total
 }

ライブで試す（try.boxlang.io）

言語名の代わりにフェンスに tryboxlang を指定すると、静的なコードリストの 代わりに、ライブの埋め込み try.boxlang.io エディタ としてレンダリングされます - 読者はページ上でそのままサンプルを実行し、 自由にいじれます。設定は不要です:

```tryboxlang title="クロージャ"
user = { name: "Luis", getFullName: () => "Luis Majano" }
println( user.getFullName() )
```

次のようにレンダリングされます:

任意の属性（すべて tryboxlang と同じ行に記述します）:

フェンス自体の内容が、エディタの起点となる BoxLang ソースになります - これは圧縮され、try.boxlang.io 自身の code URL パラメータ経由でエディタに 渡されます。これは try.boxlang.io 自体の「シェア」リンクと同じ仕組みなので、 埋め込みの「Open in try.boxlang.io ↗」リンクを開くと、埋め込みが始まった 箇所からそのまま続けられます。

ダイアグラム

bxsites.json の mermaid キーでオプトイン:

{ "mermaid": true }

有効にすると、```mermaid フェンスコードブロックはコードリストの代わりに Mermaid のライブダイアグラムとしてレンダリング されます:

flowchart LR
    A[docs/*.md] --> B[bx-markdown]
    B --> C[Theme]
    C --> D[site/*.html]

Mermaid はフローチャート、シーケンス図、クラス図、ガントチャートなど、 多くの種類のダイアグラムをサポートしています。描画できる内容の全体像は Mermaid 独自の構文リファレンス を参照してください。

数式

bxsites.json の math キーでオプトイン:

{ "math": true }

有効にすると、KaTeX がインライン数式には $...$、 中央揃えのブロックには $$...$$ を組版します。どちらも Markdown 本文に 直接書きます:

オイラーの等式 $e^{i\pi} + 1 = 0$ は、5 つの定数を一行で結びつけます。

$$
\int_0^1 x^2 \, dx = \frac{1}{3}
$$

オイラーの等式 $e^{i\pi} + 1 = 0$ は、5 つの定数を一行で結びつけます。

$$ \int_0^1 x^2 \, dx = \frac{1}{3} $$

前後にすぐ空白が続く/先行する $ はそのまま扱われます（そのため 「$5 and $10」が数式と誤読されることはありません）- 組版される数式は 常に両方の区切り記号にぴったりと接しています。

上記のすべてに加えて、GitBook スタイルの ::: name ... ::: ブロック群 （展開可能セクション、カード、列、ステッパー、ファイル/埋め込み/ ページリンクカード、更新履歴（changelog）ブロック、再利用可能な コンテンツインクルード）については コンテンツブロック を参照してください。

キャプション、配置、フレーミング（プレーンなブロックレベル HTML であり、 bx-sites 独自の構文は一切不要です）については レスポンシブ画像 を参照して ください。

プラグイン拡張

Admonition、脚注、定義リストは一般的なユースケースをカバーしますが、 bx-markdown 自体はこの 3 つ以外について特に意見を持ちません - その他の Flexmark 拡張機能は、BX Sites とは独立に markdownRegisterExtension() を 使って直接登録できます。詳細は bx-markdown 自身の readme を参照してください。