MkDocs + Material 基本操作マニュアル

MkDocsは、Markdownで美しいドキュメントサイトを構築できる静的サイトジェネレーターです。

主な特徴

動作環境

• macOS: 10.15以降
• Windows: 10/11
• Linux: 主要ディストリビューション
• Python: 3.8以降

インストール

macOS

1. Homebrewをインストール（未インストールの場合）

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2. Pythonをインストール

brew install python

確認：

python3 --version
python3 -m pip --version

3. MkDocsをインストール

python3 -m pip install mkdocs

確認：

mkdocs --version

Windows

1. Pythonをインストール

Python公式サイトからダウンロード

⚠️ 重要: “Add Python to PATH” に必ずチェック

2. 確認

python --version
python -m pip --version

3. MkDocsをインストール

python -m pip install mkdocs

Linux

1. Pythonをインストール

Ubuntu/Debian:

sudo apt update
sudo apt install python3 python3-pip

Fedora/RHEL:

sudo dnf install python3 python3-pip

Arch Linux:

sudo pacman -S python python-pip

2. MkDocsをインストール

python3 -m pip install --user mkdocs

パスが通っていない場合、~/.bashrcに追加：

export PATH="$HOME/.local/bin:$PATH"

最初のサイトを動かす

mkdocs new mysite      # 新規プロジェクト作成
cd mysite              # ディレクトリ移動
mkdocs serve           # ローカルサーバー起動

ブラウザで http://127.0.0.1:8000 を開く

サーバー終了：Ctrl + C

Material テーマのインストール

macOS / Linux:

python3 -m pip install mkdocs-material

Windows:

python -m pip install mkdocs-material

mkdocs.yml の設定

基本設定

site_name: SAMPLE SITE

site_dir: 'public'

theme:
  name: material

  features:
    - content.code.copy

  palette:
    primary: teal
    scheme: slate

copyright: Copyright © 20xx SAMPLE SITE

ダークモード切り替え

theme:
  palette:
    # ライトモード
    - media: '(prefers-color-scheme: light)'
      scheme: default
      primary: indigo
      toggle:
        icon: material/brightness-7
        name: ダークモードに切り替え
    # ダークモード
    - media: '(prefers-color-scheme: dark)'
      scheme: slate
      primary: indigo
      toggle:
        icon: material/brightness-4
        name: ライトモードに切り替え

カラーパレット

利用可能なカラー: red, pink, purple, deep purple, indigo, blue, light blue, cyan, teal, green, light green, lime, yellow, amber, orange, deep orange, brown, grey, blue grey, black, white

theme:
  palette:
    primary: teal # ヘッダーやリンクの色
    accent: indigo # ボタンやハイライトの色

ナビゲーション設定

nav:
  - ホーム: index.md
  - はじめに: getting-started.md
  - チュートリアル:
      - 基礎編: tutorial/basics.md
      - 応用編: tutorial/advanced.md
  - リファレンス: reference.md

基本コマンド

テキストの編集

docs/フォルダ内の.mdファイルを編集します。

GitHub Pagesで公開

1. GitHubリポジトリを作成

git init
git add .
git commit -m "Initial commit"
git remote add origin https://github.com/ユーザー名/リポジトリ名.git
git push -u origin main

2. デプロイ

mkdocs gh-deploy

3. 公開URL

https://ユーザー名.github.io/リポジトリ名/

トラブルシューティング

参考リンク

• MkDocs Configuration
• Material for MkDocs
• MkDocs Themes一覧