2025年03月09日

MkDocs noteテンプレート設定ガイド¶

このガイドでは、MkDocs noteテンプレートのセットアップ方法と主要な設定項目について説明します。

1. 前提条件¶

始める前に、以下のソフトウェアがインストールされていることを確認してください：

Python 3.7以上
pip (Pythonパッケージマネージャ)
Git

2. インストール手順¶

リポジトリのクローン¶

git clone https://github.com/yourusername/mkdocs-note-template.git
cd mkdocs-note-template

依存関係のインストール¶

pip install -r requirements.txt

または必要なパッケージを個別にインストール：

pip install mkdocs mkdocs-material
pip install pymdown-extensions
pip install mkdocs-minify-plugin
pip install mkdocs-git-revision-date-localized-plugin
pip install mkdocs-blog-plugin
pip install mkdocs-rss-plugin
pip install mkdocs-pdf-export-plugin

3. 基本設定¶

mkdocs.ymlファイルを編集して、サイトの基本設定を行います：

site_name: あなたのサイト名
site_description: サイトの説明
site_author: あなたの名前
site_url: https://yourusername.github.io/notes/

# リポジトリ設定
repo_name: yourusername/notes
repo_url: https://github.com/yourusername/notes

4. テーマのカスタマイズ¶

色とフォントの変更¶

theme:
  palette:
    - media: "(prefers-color-scheme: light)"
      scheme: default
      primary: indigo   # プライマリカラー
      accent: pink      # アクセントカラー
      toggle:
        icon: material/brightness-7
        name: ダークモードに切り替え
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      primary: indigo
      accent: pink
      toggle:
        icon: material/brightness-4
        name: ライトモードに切り替え
  font:
    text: Noto Sans JP    # 本文フォント
    code: Source Code Pro # コードフォント

アイコンの変更¶

theme:
  icon:
    logo: material/notebook  # サイトロゴ
    repo: fontawesome/brands/github

5. ナビゲーションの設定¶

nav:
  - ホーム: index.md
  - ブログ: blog/index.md
  - カテゴリー:
    - 技術メモ: tech/index.md
    - 日々の記録: daily/index.md
    - プロジェクト: projects/index.md
  - 機能例:
    - Mermaid図表: examples/mermaid.md
    - インタラクティブ要素: examples/interactive.md
  - タグ: tags.md
  - 著者について: about.md

6. プラグインの設定¶

検索プラグイン¶

plugins:
  - search:
      lang: ja

ブログプラグイン¶

plugins:
  - blog:
      blog_dir: blog
      post_url_format: "{date}/{slug}"
      archive: true
      categories: true
      pagination: true

RSSフィード¶

plugins:
  - rss:
      abstract_chars_count: 160
      date_from_meta:
        as_creation: date

PDFエクスポート¶

plugins:
  - pdf-export

7. マークダウン拡張機能¶

markdown_extensions:
  # アドモニション（注意・警告ボックス）
  - admonition
  # 属性リスト
  - attr_list
  # 定義リスト
  - def_list
  # 脚注
  - footnotes
  # メタデータ
  - meta
  # HTML in マークダウン
  - md_in_html
  # 目次
  - toc:
      permalink: true
  # コードハイライト
  - pymdownx.highlight:
      anchor_linenums: true
  # コードブロック
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  # タブ
  - pymdownx.tabbed:
      alternate_style: true
  # 絵文字
  - pymdownx.emoji:
      emoji_index: !!python/name:materialx.emoji.twemoji
      emoji_generator: !!python/name:materialx.emoji.to_svg
  # タスクリスト
  - pymdownx.tasklist:
      custom_checkbox: true
  # 数式
  - pymdownx.arithmatex:
      generic: true
  # コンテンツ折りたたみ
  - pymdownx.details

8. Google Analytics 設定¶

extra:
  analytics:
    provider: google
    property: G-XXXXXXXXXX

9. ソーシャルリンク¶

extra:
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/yourusername
    - icon: fontawesome/brands/twitter
      link: https://twitter.com/yourusername
    - icon: fontawesome/brands/linkedin
      link: https://linkedin.com/in/yourusername

10. カスタムCSS¶

docs/stylesheets/extra.cssでスタイルをカスタマイズできます。主要な変更点：

:root {
  --note-text-color: #333;       /* テキスト色 */
  --note-background: #fff;       /* 背景色 */
  --note-accent-color: #6200ee;  /* アクセント色 */
  --note-border-color: #e0e0e0;  /* ボーダー色 */
  --note-card-shadow: 0 2px 4px rgba(0, 0, 0, 0.1); /* カードの影 */
}

11. ローカルプレビュー¶

設定変更後、以下のコマンドでローカルプレビューを実行します：

mkdocs serve

ブラウザでhttp://127.0.0.1:8000にアクセスしてサイトをプレビューできます。

12. デプロイ¶

GitHub Pagesへのデプロイ¶

mkdocs gh-deploy

カスタムドメインの設定¶

DNSプロバイダーでCNAMEレコードを設定
リポジトリの設定ページでカスタムドメインを入力
docs/CNAMEファイルを作成しドメイン名を記述

13. 高度なカスタマイズ¶

より高度なカスタマイズには以下のファイルを編集します：

docs/overrides/main.html: メインテンプレート
docs/overrides/partials/footer.html: フッターテンプレート
docs/javascripts/extra.js: カスタムJavaScript

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

よくある問題と解決策¶

プラグインエラー: 必要なパッケージがすべてインストールされているか確認
スタイルが適用されない: ブラウザのキャッシュをクリア
デプロイエラー: GitHub Actionsのログを確認

詳細なトラブルシューティングについては、MkDocsのドキュメントを参照してください。

Your Name

技術とデザインが好きなエンジニア。WebとAIについて発信しています。

最新ツイート