mdBook固有の機能

コード行を非表示にする

mdBookには、行の先頭へ特定の接頭辞を付けて、コード行を非表示にする機能があります。

Rustでは、Rustdocと同様に、行の先頭へ# （#の後に空白）を付けると非表示にできます。この接頭辞は##でエスケープできます。文字列# で始まる行を、そのまま表示したい場合に使います（詳しくはRustdocの文書を参照してください）。

# fn main() {
    let x = 5;
    let y = 6;

    println!("{}", x + y);
# }

次のように表示されます。

fn main() {
    let x = 5;
    let y = 6;

    println!("{}", x + y);
}

コードブロックをタップしたり、マウスを重ねたりすると、非表示の行の表示を切り替える、目のアイコン（）が現れます。

既定では、rustと注釈を付けたコード例だけで使えます。ほかの言語では、book.tomlへ言語名と接頭辞の文字を指定し、コード行を非表示にする独自の接頭辞を定義できます。

[output.html.code.hidelines]
python = "~"

指定した接頭辞で始まる行が非表示になります。上のPythonの接頭辞を使うと、次のコードは、

~hidden()
nothidden():
~    hidden()
    ~hidden()
    nothidden()

次のように表示されます。

hidden()
nothidden():
    hidden()
    hidden()
    nothidden()

個々のコードで別の接頭辞を指定して、上書きできます。次の例は、上と同じ結果になります。

```python,hidelines=!!!
!!!hidden()
nothidden():
!!!    hidden()
    !!!hidden()
    nothidden()
```

Rust Playground

Rustのコードブロックには、コードを実行して結果を直下へ表示する、再生ボタン（）が自動で付きます。コードをRust Playgroundへ送る仕組みです。

#![allow(unused)]
fn main() {
println!("Hello, World!");
}

main関数がない場合、コードは自動でその中へ包まれます。

コードブロックの再生ボタンを無効にしたい場合は、次のようにnoplaygroundを指定できます。

```rust,noplayground
let mut name = String::new();
std::io::stdin().read_line(&mut name).expect("failed to read line");
println!("Hello {}!", name);
```

本のすべてのコードブロックで再生ボタンを無効にするには、次の設定をbook.tomlへ書けます。

[output.html.playground]
runnable = false

Rustのコードブロック属性

Rustのコードブロックでは、言語名の直後に、カンマ、空白、タブで区切って属性を追加できます。例を示します。

```rust,ignore
# This example won't be tested.
panic!("oops!");
```

これらの属性は、mdbook testでRustの例をテストする際に特に重要です。rustdocの属性と同じ属性を使い、いくつか追加されています。

• editable — エディターを有効にします。
• noplayground — 再生ボタンを取り除きますが、テストは行います。
• mdbook-runnable — 再生ボタンを必ず表示します。テストはせずに、読者が実行できるようにしたい例で、ignore属性と組み合わせるためのものです。
• ignore — テストを行わず、再生ボタンも表示しません。ただし、Rustの構文としてハイライトします。
• should_panic — 実行するとpanicを起こすべきコードです。
• no_run — テスト時にコンパイルしますが、実行しません。再生ボタンも表示しません。
• compile_fail — コンパイルが失敗するべきコードです。
• edition2015、edition2018、edition2021、edition2024 — 特定のRustエディションを指定します。本全体へ設定するには、rust.editionを参照してください。

ファイルを取り込む

次の構文で、ファイルを本へ取り込めます。

{{#include file.rs}}

ファイルのパスは、現在のソースファイルからの相対パスで指定します。

mdBookは、取り込んだファイルをMarkdownとして解釈します。includeコマンドは、コードや例を挿入するためによく使われるため、解釈せずにファイルの内容を表示するには、通常、コマンドを```で囲みます。

```
{{#include file.rs}}
```

ファイルの一部を取り込む

例に必要な行など、ファイルの一部だけが必要な場合があります。部分的な取り込みには、4つの方法があります。

{{#include file.rs:2}}
{{#include file.rs::10}}
{{#include file.rs:2:}}
{{#include file.rs:2:10}}

最初のコマンドは、file.rsの2行目だけを取り込みます。2番目は10行目までを取り込み、11行目から末尾までは除きます。3番目は2行目以降を取り込み、1行目を除きます。最後はfile.rsの2〜10行目を取り込みます。

取り込むファイルを変更したときに本が壊れないように、行番号の代わりにアンカーを使って、特定の節を取り込むこともできます。アンカーは、対応する2行の組です。開始行は正規表現ANCHOR:\s*[\w_-]+、終了行はANCHOR_END:\s*[\w_-]+に一致する必要があります。どのような形式のコメント行にも、アンカーを置けます。

取り込むファイルとして、次の例を考えます。

/* ANCHOR: all */

// ANCHOR: component
struct Paddle {
    hello: f32,
}
// ANCHOR_END: component

////////// ANCHOR: system
impl System for MySystem { ... }
////////// ANCHOR_END: system

/* ANCHOR_END: all */

本の中では、次のように書くだけです。

Here is a component:
```rust,no_run,noplayground
{{#include file.rs:component}}
```

Here is a system:
```rust,no_run,noplayground
{{#include file.rs:system}}
```

This is the full file.
```rust,no_run,noplayground
{{#include file.rs:all}}
```

取り込むアンカー内で、アンカーのパターンを含む行は無視されます。

ファイルを取り込み、最初は指定した行だけを表示する

rustdoc_includeヘルパーは、完全な例を含む外部のRustファイルからコードを取り込みます。ただし、includeと同じように行番号やアンカーを指定し、最初はその部分の行だけを表示します。

行番号の範囲やアンカーの間にない行も取り込まれますが、先頭に#を付けます。読者はコードを展開して完全な例を見ることができ、Rustdocはmdbook testの実行時に完全な例を使います。

たとえば、次のRustプログラムを含むfile.rsというファイルを考えます。

fn main() {
    let x = add_one(2);
    assert_eq!(x, 3);
}

fn add_one(num: i32) -> i32 {
    num + 1
}

次の構文で、最初は2行目だけを表示するコードを取り込めます。

To call the `add_one` function, we pass it an `i32` and bind the returned value to `x`:

```rust
{{#rustdoc_include file.rs:2}}
```

手作業でコードを挿入し、#を使って2行目以外を非表示にした場合と、同じ結果になります。

To call the `add_one` function, we pass it an `i32` and bind the returned value to `x`:

```rust
# fn main() {
    let x = add_one(2);
#     assert_eq!(x, 3);
# }
#
# fn add_one(num: i32) -> i32 {
#     num + 1
# }
```

つまり、次のように表示されます（残りのファイルを見るには「展開」アイコンをクリックします）。

fn main() {
    let x = add_one(2);
    assert_eq!(x, 3);
}

fn add_one(num: i32) -> i32 {
    num + 1
}

実行可能なRustファイルを挿入する

次の構文で、実行可能なRustファイルを本へ挿入できます。

{{#playground file.rs}}

Rustファイルのパスは、現在のソースファイルからの相対パスで指定します。

再生ボタンをクリックすると、コードがRust Playgroundへ送られ、コンパイル・実行されます。結果は返送され、コードの直下へ表示されます。

生成したコードの表示例です。

fn main() {
    println!("Hello World!");

    // You can even hide lines! :D
    println!("I am hidden! Expand the code snippet to see me");
}

ファイル名の後に渡した値は、コードブロックの属性として追加されます。たとえば、{{#playground example.rs editable}}は、次のようなコードブロックを生成します。

```rust,editable
# Contents of example.rs here.
```

editable属性は、Rustのコードブロック属性で説明したとおり、エディターを有効にします。

ページの<title>を指定する

章の先頭近くに{{#title ...}}を置くと、目次（サイドバー）の項目とは異なる<title>を指定できます。

{{#title My Title}}

mdBookが提供するHTMLクラス

class="left"と"right"

これらのクラスは、インラインHTMLで画像を左右に寄せるために、既定で用意されています。

<img class="right" src="images/rust-logo-blk.svg" alt="The Rust logo">

class="hidden"

hiddenクラスを付けたHTMLタグは表示されません。

<div class="hidden">This will not be seen.</div>

Font Awesomeのアイコン

mdBookには、Font Awesome Freeバージョン6の、MITライセンスのSVGファイルのコピーが含まれます。<i>構文を模倣し、結果をインラインSVGへ変換します。regular、solid、brandsのアイコンだけを含み、lightなどの有料機能は含みません。

たとえば、次のHTML構文に対して、

The result looks like this: <i class="fa-solid fa-print"></i>

次のように表示されます：

利用できるアイコンは、無料のアイコン集合を参照してください。