本を作成する

mdbookのCLIツールをインストールすると、本を作成して出力できます。

本を初期化する

mdbook initコマンドは、作業の出発点となる空の本を含む、新しいディレクトリを作成します。作成するディレクトリ名を指定してください。

mdbook init my-first-book

本を生成する前に、いくつかの質問が表示されます。回答したら、新しい本のディレクトリへ移動できます。

cd my-first-book

本を出力する方法はいくつかありますが、簡単な方法のひとつはserveコマンドです。本をビルドし、ローカルのウェブサーバーを起動します。

mdbook serve --open

--openオプションは、作成した本を表示するために既定のウェブブラウザーを開きます。本の内容を編集している間もサーバーを起動したままにできます。mdbookは出力を自動で再ビルドし、さらにウェブブラウザーの表示も自動で更新します。

ほかのmdbookコマンドやCLIオプションについては、CLIガイドを参照してください。

本を構成するもの

本は、設定や構成を定義する複数のファイルから作られます。

book.toml

本のルートには、ビルド方法を指定する設定ファイルbook.tomlがあります。このファイルはTOMLで記述します。通常、作業を始めるには既定の設定で十分です。mdBookのほかの機能やオプションを知りたい場合は、設定の章を参照してください。

基本的なbook.tomlは、次のように簡単に記述できます。

[book]
title = "My First Book"

SUMMARY.md

次に重要なのは、src/SUMMARY.mdにある目次ファイルです。本に含まれる全章の一覧を記述します。章を表示するには、先にこの一覧へ追加する必要があります。

次は、いくつかの章を含む基本的な目次ファイルです。

# Summary

[Introduction](README.md)

- [My First Chapter](my-first-chapter.md)
- [Nested example](nested/README.md)
    - [Sub-chapter](nested/sub-chapter.md)

エディターでsrc/SUMMARY.mdを開き、章をいくつか追加してみてください。章のファイルが存在しない場合は、mdbookが自動で作成します。

目次ファイルで指定できるほかの書式については、目次の章を参照してください。

ソースファイル

本の内容はすべてsrcディレクトリにあります。各章は独立したMarkdownファイルです。通常、章のタイトルを指定するレベル1の見出しから始めます。

# My First Chapter

Fill out your content here.

具体的なファイルの配置は自由に決められます。ファイル構成は生成されるHTMLファイルの構成に対応するため、ファイルの配置が各章のURLの一部になることに注意してください。

mdbook serveコマンドの実行中は、章のファイルを開いて編集できます。ファイルを保存するたびに、mdbookが本を再ビルドし、ウェブブラウザーの表示を更新します。

章の内容の書式については、Markdownの章を参照してください。

srcディレクトリにある、ほかのファイルもすべて出力に含まれます。画像などの静的ファイルがある場合は、srcディレクトリ内に配置してください。

本を公開する

本を書いたら、ほかの人が読めるように公開したくなるかもしれません。まず、本の出力をビルドします。book.tomlがあるディレクトリで、mdbook buildコマンドを実行してください。

mdbook build

本のHTMLを含むbookというディレクトリが生成されます。このディレクトリを任意のウェブサーバーに配置して公開できます。

公開やデプロイについて詳しくは、継続的インテグレーションの章を参照してください。