mkdocs を使用したドキュメント作成（導入~基本操作）

この記事では、mkdocs と mkdocs-material テーマを使ってドキュメントを作成するための基本的な手順についてまとめています。
mkdocsを使用することで、静的サイトとしてドキュメントを構築・管理することができ、ゲーム制作に関する手順や各種情報をドキュメントとしてまとめておくのに活用できます。

前提となる環境

この記事では、以下の環境を前提としています。

Windows 環境
Python (3.7 以降) がインストール済み (入手：https://www.python.org/downloads/)
エディタにはVisualStudioCodeを使用（他ソフトやコマンドプロンプトで代替可能です）

PythonやVSCodeの基本的なインストール方法については、以下の記事でも解説しています。

新規ドキュメントの作成と初期設定

作業用フォルダの作成

まずはドキュメントを構築していくためのフォルダを作成します。

VSCodeを使用する場合は、作成したフォルダを開いておきましょう。

VSCodeの場合、［ターミナル］＞［新しいターミナル］から、作業フォルダの位置でターミナルを開くことができます。

仮想環境の作成・起動

まずは他のPythonプロジェクトと依存関係を分離するため、以下コマンドで仮想環境（venv）を作成・起動します。
（分離が不要な場合は省略可能です）

python -m venv venv
venv\Scripts\activate

venv 動作コマンドの補足

解説：
python -m venv venv コマンドで、
venvの作成が完了すると、コマンドを実行したフォルダ直下に、venv環境が構成されます

venv>Scripts>activate
を実行することで、作成した仮想環境を起動します。

以下のような警告文が出る場合がありますが、実行するように回答すると、以下のように(venv)という表示で仮想環境の起動状態を確認できます。

パッケージのインストール

仮想環境を起動した状態で、以下コマンドで必要なパッケージ（mkdocs, mkdocs-material）をインストールします。

pip install mkdocs
pip install mkdocs-material

mkdocsプロジェクトの初期化

[ mkdocs new ]コマンドで、新規mkdocsプロジェクトを作成します
(今回は作業フォルダをそのままmkdocsプロジェクトとするため、　フォルダ名は「.」を指定します)

mkdocs new .

mkdocsプロジェクトの作成が完了すると、以下が作成されます。
　・mkdocs.yml：サイト設定ファイル
　・docs：ドキュメントページを構成していくフォルダ

Material テーマ設定

mkdocs.yml に以下設定を追記します。(site_name: ではサイトの名称を設定しています )
ここで使用するテーマ名を material に変更することで、インストールしたmkdocs-material テーマが適用されます。

site_name: My Docs
theme:
  name: material

Mkdocs基本操作

ここからは、ドキュメントを構築していくうえで基本となる操作についてまとめていきます。

仮想環境の起動

venvを使用して仮想環境を用意した場合は、mkdocsコマンド使用前に起動操作を行う必要があります。
「venv\Scripts\activate」で、ターミナルの先頭に(venv) の表示があることを確認しておきましょう。

ページの作成とナビゲーション設定

ページを作成するには、docs/ フォルダ内に Markdown ファイルを追加して、自由にコンテンツを書いていきます。
(デフォルトで、index.md というページも生成されています)

その後、mkdocs.yml に nav セクションを追加して、ナビゲーション（目次）を構築します。ページの構成を整理することで、読みやすいドキュメントになります。

nav:
  - ホーム: index.md
  - テストページ: test.md

(デフォルトの状態で、)追加したナビゲーションは以下のようなサイドツリーの形式で出力されます

ローカルでの動作確認

[mkdocs serve] コマンドで、ローカルサーバーを起動し、ブラウザでリアルタイムに変更を確認できます。
変更を保存すると、自動でリロードされるため、編集と確認がスムーズに行えます。
任意のブラウザで、「 http://127.0.0.1:8000」を開いて確認しましょう。

mkdocs serve

ターミナルが以下のような表示になっていれば、正常にローカルサーバーが起動できています。（Ctrl＋C　で終了）

閲覧用バッチファイルの作成

ローカル環境で使用する場合は、サーバーの立ち上げ～ブラウザ展開　までをバッチファイルで作成しておくと便利です。
例えば、「.bat 」ファイルで、以下のような構成になります。

@echo off
REM 仮想環境の有効化（必要な場合）
call venv\Scripts\activate.bat

REM MkDocs サーバーをバックグラウンドで起動
start /B cmd /C "mkdocs serve"

REM 少し待ってからブラウザを開く
timeout /t 2 > nul
start http://127.0.0.1:8000

このファイルを作成しておくことで、バッチファイルのダブルクリックのみでドキュメントの参照が可能になるはずです。

サイトのビルド(HTML出力)

[mkdocs build] コマンドで、ドキュメントを HTML に変換して、静的サイトとして出力します。
site/ ディレクトリに HTML ファイル一式が生成され、Webサーバーで公開可能な状態になります。

mkdocs build

おすすめのオプション/プラグイン

ここからは、個人的にお勧めなオプション/プラグインの導入と利用法についてまとめていきます。

ロゴ, ファビコン設定

theme内の、logo: favicon: でパスを指定することで、使用するアイコンを設定することができます。

導入方法

mkdocs.yml の theme に以下設定を追記(パスは、docs フォルダ内の任意のアイコンファイル)

theme:
  name: material

  logo: assets/hirameme_icon_nobg.svg     # ヘッダーロゴ画像
  
  favicon: assets/hirameme_icon_2.ico      # タブのアイコン

テーマカラー/ダークモードの設定

palette オプションを設定することで、テーマの切り替えや配色の設定が可能です。

導入方法

mkdocs.yml のtheme 内に、以下設定を追記

theme:
  name: material

  # カラーテーマ設定
  palette:
    - scheme: default   # デフォルト(ライト)テーマ
      primary: indigo   # 主要素(ヘッダー/リンク等)のカラー設定
      accent: indigo    # 強調色(ボタン/選択状態等)の設定
      toggle:           # ライト/ダークモード切替UI表示設定
        icon: material/weather-night  # 表示アイコン設定
        name: ダークモードに切り替え    # トグル時ラベル(ツールチップ)の表示設定

    - scheme: slate     # ダークモードテーマ
      primary: teal     # 主要素(ヘッダー/リンク等)のカラー設定
      accent: indigo    # 強調色(ボタン/選択状態等)の設定
      toggle:           # ライト/ダークモード切替UI表示設定
        icon: material/weather-sunny  # 表示アイコン設定
        name: ライトモードに切り替え    # トグル時ラベル(ツールチップ)の表示設定

ナビゲーション設定

theme > features: 内に、 navigation.* の形で、ナビゲーション設定を追加することができます。

機能	説明	動作イメージ
`navigation.tabs`	上部にタブ形式のナビゲーションを表示
`navigation.tabs.sticky`	スクロールしてもナビゲーションタブを固定表示
`navigation.top`	ページに「トップへ戻る」ボタンを表示
`navigation.sections`	サイドバーにセクション見出しを表示
`navigation.instant`	ページ間遷移を高速化（JavaScript によるプリフェッチ）	–
`navigation.footer`	前・次ページリンクをフッターに表示
`navigation.expand`	サイドバーのすべてのセクションを常に展開した状態にする	–

導入方法

前述の一覧を実装する場合、mkdocs.yml に以下設定を追記する形になります。

  features:
    # ナビゲーション設定
    - navigation.tabs         # 上部にタブ形式のナビゲーションを表示
    - navigation.tabs.sticky  # スクロールしてもナビゲーションタブを固定表示
    - navigation.top          # ページに「トップへ戻る」ボタンを表示
    - navigation.sections     # サイドバーにセクション見出しを表示
    - navigation.instant      # ページ間遷移を高速化（JavaScript によるプリフェッチ）
    - navigation.footer       # 前・次ページリンクをフッターに表示
    - navigation.expand       # サイドバーのすべてのセクションを展開した状態にする

より詳細な解説やその他設定可能な項目は、以下公式Docページから参照できます。

Setting up navigation - Material for MkDocs

Write your documentation in Markdown and create a professional static site in minutes – searchable, customizable, in 60+...

検索機能の設定

プラグイン：高度検索機能

mkdocsは、デフォルトで検索機能をサポートしていますが、専用のプラグインを追加インストールすることで、より精度の高い検索機能を実装することも可能です。

導入方法

① ターミナルで以下を実行し、プラグインをインストール

pip install mkdocs-material[search]

➁ mkdocs.yml に以下設定を追記（例：日本語, 英語　言語設定の場合）

plugins:
  - search:
      lang: [ja, en]

検索UIカスタマイズ

theme>features>search.*で、検索UIの設定を行うことができます。

導入方法

mkdocs.yml に以下設定を追記

  features:
    - search.highlight  # 検索結果ページで該当キーワードをハイライト表示
    - search.suggest    # 入力中にサジェストを表示
    - search.share      # 検索結果への共有リンクを生成可能にする

コードブロックのコピーボタン追加

theme> features: に、content.code.copy　を設定することで、コードブロックにコピーボタンを追加可能です。

導入方法

mkdocs.yml に以下設定を追記

theme:
  features:
    # コードブロック設定
    - content.code.copy       # コードブロック右上に「コピー」ボタンを表示

目次の表示設定

目次はデフォルトで画面右側に表示されていますが、theme> features: に、toc.integrate　を設定することで、メインコンテンツに埋め込むこともできます。

導入方法

mkdocs.yml に以下設定を追記

theme:
  features:
    # 目次設定
    - toc.integrate    # 目次（TOC）を右側ではなくメインコンテンツに統合表示