簡単な Web サイトを手間なく作ろうとしたとき、皆さんならどうやって作りますか？ デザインにこだわる時間はないし、とにかく早く Web サイトを公開しなければならない、というユースケースにおいて、 MkDocs というツールは非常に強力です。
今回は MkDocs を使って、 Markdown から静的 Web サイトを作る方法について、 Windows 環境で解説します。 超初心者向けの最初の一歩となる内容ですので、すでに詳しい方はそっと閉じていただけると助かります。
環境
環境構築
Python のインストール
以下のサイトからインストーラーをダウンロードします。
今回は Windows 10 64bit 環境で行うので、 Windows 64bit 用のインストーラーを以下からダウンロードします。
https://www.python.org/downloads/windows/
インストーラーを起動したら、 Python をコマンドラインから使いやすくするために [Add Python 3.9 to PATH] にチェックを入れてインストールしましょう。
pip の更新
続いて Python のパッケージマネージャーである pip の更新をします。 コマンドプロンプトを管理者権限で起動し、以下のコマンドを実行します。
pip install --upgrade pip
mkdocs のインストール
続いて pip を使って、 mkdocs というパッケージをインストールします。 コマンドプロンプトを起動して、以下のコマンドを実行します。
pip install mkdocs
パッケージのダウンロードが実行されます。 コマンドの実行完了後、以下のように mkdocs のバージョン確認ができればインストール完了です。
C:\Windows\system32>mkdocs --version mkdocs, version 1.2.1 from c:\users\<ユーザー名>\appdata\local\programs\python\python39\lib\site-packages\mkdocs (Python 3.9)
プロジェクトの作成
プロジェクトルートとなるディレクトリを適当に作成しましょう。 コマンドプロンプトで作成したディレクトリに移動し、以下のコマンドを実行します。
mkdocs new .
コマンド中の「.」は、カレントディレクトリをルートディレクトリとしてプロジェクトを作成することを表しています。 「.」の代わりにディレクトリ名を入れることもできます。 その場合、カレントディレクトリに設定した名前のディレクトリが生成され、その中にプロジェクトが生成されます。
Markdown の編集
mkdocs new コマンドでプロジェクトを作成すると、以下のようにファイルやディレクトリが生成されます。
プロジェクトルート
├ mkdocs.yml
└ docs
└ index.md
docs ディレクトリの中に Markdown ファイルを配置していきましょう。 今回はサンプルなので、特に編集はしません。
なお Markdown の編集には、 Visual Studio Code が非常に便利です*1。
mkdocs.yml とは
mkdocs.yml ファイルは、このプロジェクトの設定を行うためのファイルです。 開いてみると、以下のような設定が記載されています。
site_name: My Docs site_url: https://example.com/
最低限この 2 つの設定があれば、静的 Web サイトの生成を行うことができます。 site_url は、実際に静的 Web サイトを発行する先の URL を入力しておきます。 ただし、ローカル環境でテスト実行するのみであれば、特に設定は何でも構いません。
テスト実行
それでは作成したプロジェクトを使って、テスト実行をしてみましょう。 コマンドプロンプトで、先ほど作成したプロジェクトルートのディレクトリを開き、以下のコマンドを実行します。
mkdocs serve
すると、 mkdocs に組み込みの Web サーバーが起動して、ブラウザーから確認することができるようになります。 Markdown や mkdocs.yml に記載ミスがなければ、Web サーバーが起動し、コマンドプロンプトにその URL が表示されます。
c:\tsuna-can\repos\MarkdownSample>mkdocs serve INFO - Building documentation... INFO - Cleaning site directory INFO - Documentation built in 0.16 seconds INFO - [17:05:40] Serving on http://127.0.0.1:8000/
実際にブラウザーから表示されている URL を見に行くと、以下のように Markdown が 静的 Web ページに変換され、表示できてしまいます。
なおこの Web サーバーは、ホットリロードに対応しています。 Web サーバーが起動している状態で、 Markdown のファイルや mkdocs.yml を変更すると、即時ブラウザーに変更が反映されます。
Markdown を静的 Web サイトに変換する
先ほどはテスト用の Web サーバーを使用して、静的 Web サイトを参照しました。 Markdown から HTML に変換して、既存の Web サーバーに配置するためのファイル群を生成することもできます。 HTML などのファイル群を生成する場合は、以下のコマンドを実行します。
mkdocs build
ビルドが完了すると、カレントディレクトリの中に site ディレクトリが生成され、その中に Markdown を HTML に変換したファイル一式が生成されます。 このファイル群を Web サーバーに配置すると、先ほどテスト用サーバーで実行したものと全く同じサイトを閲覧できます。
プロジェクトのカスタマイズ
ここまでは mkdocs のチュートリアルみたいなものです。 mkdocs はかなり豊富な拡張パッケージがあります。 また mkdocs.yml に設定を行うことで、細かくカスタマイズを行うこともできます。
テーマを変更する
まずは生成する Web サイトのテーマを選定することから始めましょう。 テーマによって設定項目が大きく異なることがあるため、最初にテーマを決めることをお勧めします。
mkdocs には、デフォルトで2つのテーマが組み込まれています。 テーマの設定は、 mkdocs.yml に行います。 theme > name に使用するテーマの名前を指定します。 既定では mkdocs と readthedocs が使えます。 既定値は mkdocs です。
site_name: My Docs site_url: https://example.com/ theme: name: readthedocs
上記のような感じでテーマを設定すると、生成される Web サイトのデザインが、以下のように全く異なるものになります。
追加のテーマのインストールと設定
Material for MkDocs のインストール
mkdocs では、追加のテーマを入れて、さらなるカスタマイズを行うことができます。 最も有名なのが、 Material for mkdocs というテーマで、 Google の Material デザインを意識しています。
インストールは非常に簡単で、以下のコマンドを実行するだけです。
pip install mkdocs-material
テーマの設定
インストールが完了したら、 mkdocs.yml に、インストールしたテーマを利用するよう設定を行いましょう。 設定方法は先述したテーマの設定箇所と同じです。
site_name: My Docs site_url: https://example.com/ theme: name: material
このような設定を行うと、 Web サイトのデザインが Material デザインに変更されます。
言語の設定
Material for MkDocs を選択した場合、必ず最初にやっておいた方が良いのが言語の設定です。 theme > language に ja を設定しましょう。
site_name: My Docs site_url: https://example.com/ theme: name: material language: ja
これで Web サイトが日本語化されます。
今まで英語表記だった箇所が日本語翻訳されます。 また Web サイト自体の言語も日本語に設定されるため、 Chrome や Chromium Edge が翻訳を促す小窓を無駄に出してくることもなくなります。
その他の設定
Material for MkDocs には多種多様な設定項目があります。 ここではそのすべてを解説しきることができません。 詳細は本家のサイトをご覧ください。
なお、様々なカスタマイズ項目がある Material for MkDocs ですが、一部の設定項目はインサイダーと呼ばれる課金ユーザー向けのものになっています。 詳細は以下をご覧ください。
まとめ
今回は Markdown を使って静的 Web サイトを作成する方法について解説しました。 デザインはテーマ任せとなってしまいますが、そもそもデザイン作業自体が苦手な方や、記事の内容に注力したいケースでは、非常に使い勝手の良いツールであると思います。 Markdown だけである程度見た目の良い Web サイトを生成してくれるのは魅力的ですね。
*1:こちらについては今回特に必須ではないため解説しません。
