MkDocsのインストール

ここでは、MkDocs のインストールを行い、サイトを表示するところまでを見ていきます。

MkDocs のインストール

MkDocsのインストールは、python と pip の環境があればすぐにできます。

> python --version
> pip --version

この2つを実行してエラーがでなければ、すぐにインストールできます。エラーが出るなら、python と pip のインストールを行いましょう。

インストールされていることが確認できたら、次を実行しましょう。

pip install mkdocs

MkDocs のインストールは、これでおしまいです。

> mkdocs --version

これを実行して、エラーが出ないことを確認しましょう。インストールに問題がなければ、MkDocs のバージョンが表示されます。

Windows の場合、インストール時にエラーが出る場合は、次のようにすればうまくいくかもしれません。

> python -m pip install mkdocs
> python -m mkdocs --version

1つ目がMkDocsのインストール、2つ目がバージョン表示です。

サイトの作成と表示

MkDocs のインストールが終わったら、サンプルサイトを作ってみましょう。

> mkdocs new my-project
> cd my-project

これだけで、サイトができます。「my-project」というフォルダの下は、次のような構成になっているでしょう。

mkdocs.yml
docs/
    index.md

サイトの設定が入ったmkdocs.yml、そして、docsフォルダの下にindex.mdができています。これが必要最低限のサイトの構成です。この状態でサイトを見てみます。次を実行してみましょう。

> mkdocs serve

これは、ローカルサーバーを立ち上げてサイトを表示する、という命令です。いくつかメッセージが現れます。メッセージが止まったら、http://127.0.0.1:8000 にアクセスしてみましょう。この URL は、メッセージの中にも表示されているはずです。

デフォルトでは、MkDocs の公式サイト と同じレイアウトで表示されます。なお、サーバーを止めるには、 Ctrl+C と入力します。

サイトを公開しよう

MkDocsでサイトを作成したら、公開用のファイルも作ってみましょう。

公開用のhtmlファイルを作るには、次のコマンドを実行します。

> mkdocs build

site というフォルダができ、その下にたくさんのフォルダやファイルができていることでしょう。

index.md に対応するファイルは、site フォルダの直下の index.html ファイルです。sample.md に対応するファイルは、sampleフォルダにあるindex.htmlファイルです。ブラウザからは、example.com/sample/でアクセスできます。

作成されるのは HTMLファイルだけでなく、css ファイルや js ファイル、sitemap.xml などもあります。search/search_index.json には、検索で使うデータが入っています。

これらを丸々公開サーバーに上げればおしまいです。

なお、記事を修正して再度 build を行った際、古いファイルが残ったままになります。古いファイルをすべて削除してから新しいファイルを再生成したい場合は、次のように clean オプションをつけます。

> mkdocs build --clean

おわりに

ここでは、MkDocs をインストールし、サイトの表示・公開までの流れを一通り見ました。ただ、まだ何も記事がないですね。次のページでは、記事を追加したり、サイトの設定を行う方法について見ていきます。