コンテンツにスキップ

MkDocsデザイン改善ガイド

このガイドでは、MkDocs MaterialテーマでモダンなUIを実現する方法を詳しく解説します。

前提条件

mkdocsを使ったGitHub Pagesの作成方法を完了していることを前提とします。

1. 最新のMkDocs Material機能

1.1 ダークモード対応

ユーザーのシステム設定に応じた自動切り替えと手動切り替えを実装：

# mkdocs.yml
theme:
  palette:
    # Light mode
    - media: "(prefers-color-scheme: light)"
      scheme: default
      primary: teal
      accent: deep orange
      toggle:
        icon: material/brightness-7
        name: ダークモードに切り替え
    # Dark mode
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      primary: teal
      accent: deep orange
      toggle:
        icon: material/brightness-4
        name: ライトモードに切り替え

1.2 ナビゲーション機能強化

現代的なSPAライクな動作を実現：

theme:
  features:
    # Navigation
    - navigation.instant          # インスタントローディング
    - navigation.instant.prefetch # プリフェッチ機能
    - navigation.tabs            # タブナビゲーション
    - navigation.tabs.sticky     # スティッキータブ
    - navigation.sections        # セクション表示
    - navigation.expand          # 自動展開
    - navigation.path            # パンくずリスト
    - navigation.top             # トップに戻るボタン
    # Search
    - search.highlight           # 検索ハイライト
    - search.suggest             # 検索サジェスト
    # Header
    - header.autohide           # ヘッダー自動非表示
    # Content
    - content.code.copy          # コードコピーボタン
    - content.code.select        # コード選択機能
    - content.tooltips           # ツールチップ

1.3 アイコンとビジュアル強化

GitHubアイコンとフォント設定：

theme:
  icon:
    repo: fontawesome/brands/github
  font:
    text: 'Noto Sans JP'
    code: 'Roboto Mono'

2. カスタムCSS実装

2.1 基本設定

docs/stylesheets/extra.cssを作成：

/* 日本語フォントの設定 */
:root {
  --md-text-font: "Noto Sans JP", "Hiragino Sans", "Hiragino Kaku Gothic ProN", "Yu Gothic UI", "Meiryo UI", sans-serif;
  --md-code-font: "SFMono-Regular", "Consolas", "Liberation Mono", "Menlo", monospace;
}

/* Google Fontsから日本語フォントを読み込み */
@import url('https://fonts.googleapis.com/css2?family=Noto+Sans+JP:wght@300;400;500;700&display=swap');

/* カスタムカラー変数 */
:root {
  --md-accent-fg-color: #ff6f00;
  --md-accent-fg-color--transparent: #ff6f001a;
}

2.2 ナビゲーション改善

/* ナビゲーションの改善 */
.md-nav__title {
  font-weight: 600;
}

.md-nav__link {
  border-radius: 0.1rem;
  transition: background-color 125ms;
}

.md-nav__link:hover {
  background-color: var(--md-accent-fg-color--transparent);
}

2.3 コンテンツエリア改善

/* 3列グリッドレイアウト */
.md-content ul {
  display: grid;
  grid-template-columns: repeat(3, 1fr);
  gap: 1rem;
  list-style: none;
  padding: 0;
  margin: 1rem 0;
}

.md-content ul li {
  background: var(--md-default-bg-color);
  border: 1px solid var(--md-default-fg-color--lighter);
  border-radius: 0.5rem;
  padding: 1rem;
  transition: all 0.3s ease;
  box-shadow: 0 2px 8px rgba(0,0,0,0.08);
  min-height: 3rem;
  display: flex;
  align-items: center;
}

.md-content ul li:hover {
  transform: translateY(-2px);
  box-shadow: 0 4px 16px rgba(0,0,0,0.12);
  border-color: var(--md-accent-fg-color);
}

2.4 レスポンシブ対応

/* レスポンシブ対応 */
@media screen and (max-width: 76.1875em) {
  .md-content ul {
    grid-template-columns: repeat(2, 1fr);
  }
}

@media screen and (max-width: 44.9375em) {
  .md-content ul {
    grid-template-columns: 1fr;
  }
}

2.5 アニメーション追加

/* ページ遷移アニメーション */
.md-content {
  animation: fadeIn 0.3s ease-in-out;
}

@keyframes fadeIn {
  from { opacity: 0; transform: translateY(0.5rem); }
  to { opacity: 1; transform: translateY(0); }
}

/* コードブロック改善 */
.md-typeset pre > code {
  border-radius: 0.5rem;
}

/* テーブル改善 */
.md-typeset table:not([class]) {
  border-radius: 0.5rem;
  overflow: hidden;
  box-shadow: 0 0.2rem 1rem rgba(0, 0, 0, 0.05);
}

/* 検索ボックス改善 */
.md-search__input {
  border-radius: 2rem;
}

2.6 ダークモード対応

/* ダークモード用の調整 */
[data-md-color-scheme="slate"] {
  --md-hue: 210;
  --md-default-bg-color: #1a1a1a;
  --md-default-fg-color: #e1e5e9;
}

3. mkdocs.ymlの完全設定

mkdocs.ymlにCSSファイルを追加：

extra_css:
  - stylesheets/extra.css

4. プラグイン設定

4.1 検索機能強化

plugins:
  - search:
      lang: ja
      separator: '[\s\-\.]+'

4.2 Markdownエクステンション

markdown_extensions:
  - admonition                    # 注意書き
  - pymdownx.details             # 折りたたみ
  - pymdownx.superfences         # コードブロック改善
  - pymdownx.highlight:          # シンタックスハイライト
      anchor_linenums: true
  - pymdownx.inlinehilite        # インラインコード
  - pymdownx.snippets            # コードスニペット
  - pymdownx.tabbed:             # タブ表示
      alternate_style: true
  - pymdownx.emoji:              # 絵文字
      emoji_generator: !!python/name:pymdownx.emoji.to_svg
  - pymdownx.keys                # キーボードキー
  - pymdownx.mark                # マーカー
  - pymdownx.tilde               # 取り消し線
  - attr_list                    # 属性リスト
  - md_in_html                   # HTML内Markdown

5. デプロイと確認

5.1 ローカル確認

# 開発サーバーで確認
mkdocs serve

# ビルドテスト
mkdocs build

5.2 GitHub Pagesへデプロイ

# 変更をコミット
git add .
git commit -m "UI改善: モダンデザイン実装"
git push origin main

# GitHub Pagesに反映
mkdocs gh-deploy

6. 実装例

6.1 カード型コンテンツ

!!! example "カード例"
    <div class="grid cards" markdown>

    - :material-clock-fast:{ .lg .middle } __高速__

        ---

        MkDocsは高速な静的サイトジェネレーター

    - :fontawesome-brands-markdown:{ .lg .middle } __Markdown__

        ---

        馴染みのあるMarkdown記法で書ける

    </div>

6.2 タブ表示

=== "Python"

    ``` python
    print("Hello, World!")
    ```

=== "JavaScript"

    ``` javascript
    console.log("Hello, World!");
    ```

6.3 注意書きの活用

!!! tip "ヒント"
    この機能を使うとユーザビリティが向上します。

!!! warning "注意"
    設定を変更する前にバックアップを取ってください。

!!! info "情報"
    最新バージョンではこの機能が追加されています。

7. パフォーマンス最適化

7.1 画像最適化

<!-- WebP形式の使用 -->
![画像説明](./images/image.webp){ loading=lazy }

<!-- 遅延読み込み -->
![画像説明](./images/image.png){ loading=lazy width=300 }

7.2 フォント最適化

/* フォント表示最適化 */
@font-face {
  font-family: 'Noto Sans JP';
  font-display: swap;
  src: url('...') format('woff2');
}

8. カスタマイズのベストプラクティス

  1. 段階的改善: 基本設定→CSS追加→高度な機能の順で実装
  2. レスポンシブ: モバイルファーストで設計
  3. パフォーマンス: 不要なCSSやJavaScriptは避ける
  4. アクセシビリティ: カラーコントラストと键盤操作を考慮
  5. メンテナンス性: CSSは論理的にグループ化

9. トラブルシューティング

よくある問題

CSSが反映されない

# キャッシュクリア
mkdocs build --clean

フォントが表示されない

# extra_cssの設定確認
extra_css:
  - stylesheets/extra.css

モバイルでレイアウトが崩れる

/* ビューポートの確認 */
@media screen and (max-width: 44.9375em) {
  /* モバイル用スタイル */
}

📚 関連記事・次のステップ

デザインの基本ができたら、さらなるカスタマイズに挑戦しましょう：

🚀 機能を拡張する

📝 基本をおさらいする

🛠️ 技術スキルを向上させる

デザイン改善の成果を確認

このサイト自体がデザイン改善の実例です。ホームページで3列グリッドレイアウトや、各ページでダークモード切り替えなどの機能を実際に確認できます。

参考リンク