インフラ特化テックノートを GitHub Pages + MkDocs Material で立ち上げた話

Dec 28, 2025· wan0ri· Category: Tech

TL;DR

インフラ領域の学習・業務で得た知見を素早く引ける「自分用の決定版カンペ」を作りました。
公開先: https://wan0ri.github.io/note （ソースは GitHub、デプロイは GitHub Pages）

採用の背景

当初は Google Cloud 上で Wiki.js をコンテナ化して運用する構成を検討しておりました。
理由としては、Terraform にもっと触れてスキルを上げたかったこと、また触れたことのない Google Cloud を扱ってみたかったことが大きな理由です。

しかし、個人用途では次が重くなりがちであることで開発自体に負担がかかっていました。

毎月のクラウドコスト（常時稼働ストレージ、監視などの積み上げ）
セキュリティ/パッチ適用、バックアップ、アップグレードなどの保守運用
アプリケーションのライフサイクルに自分が束縛される

一方で GitHub Pages + MkDocs は

0 円〜低コスト（Pages + Actions の範囲で完結）
変更は Git 管理 → PR ベースで安全に運用
書く → プレビュー → 公開までが速い（Docs-as-Code）

で構成できます。

結論として、 コスト/保守性/スピードのバランス から GitHub Pages + MkDocs Material を採用することにしました。

サイト構成（インフラ特化＋将来の言語枠）

インフラ特化のセクションを主軸に設計しました。

プラットフォーム: k8s / コンテナ / 仮想化
- コンテナを「基本コマンド / Dockerfile（image-build）/Compose」に分割
インフラ基盤: OS / ネットワーク / セキュリティ / ハードウェア
クラウド: 3 大クラウド / IaC / 可観測性
DevOps: CI/CD / 開発手法 / ツール（Git 等）
ミドルウェア
言語: Python / Golang（将来、Lambda やツール実装のために余白を確保）
エラー: Terraform/CLI の生ログをそのまま貼るラフメモ場
UI ポイント
- 上部タブナビ、ダーク/ライト切替
- ページ下部の「前へ/次へ」ナビは非表示（ノート用途での視線移動を最小化）
- 「編集/原文表示」ボタンも非表示（自分の運用に不要なため）

テーマと設定（MkDocs Material）

主要設定

主要設定（抜粋: mkdocs.yml）

theme:
  name: material
  language: ja
  features:
    - navigation.tracking
    - navigation.sections
    - navigation.indexes
    - navigation.tabs
    - navigation.tabs.sticky
    - navigation.path
    - navigation.expand
    - navigation.top
    - content.code.copy
    - content.code.annotate
    - content.tabs.link
    - toc.follow
  palette:
    - scheme: default
      primary: blue
      accent: indigo
      toggle:
        icon: material/weather-night
        name: ダークモード
    - scheme: slate
      primary: blue
      accent: indigo
      toggle:
        icon: material/weather-sunny
        name: ライトモード

Markdown 拡張とプラグイン（抜粋）

pymdownx.* を有効化（タブ、ハイライト、タスクリスト等）
glightbox（画像ライトボックス）
redirects（URL 変更時の救済）
git-revision-date-localized（更新日をローカライズ表示）
Social Cards（OG 画像の自動生成、後述）

OG 画像（サムネイル）対応：外部サイトへの連携向け

mkdocs-material の Social Cards 機能を使用（ビルド時に各ページの OG 画像を自動生成）。
依存追加（requirements.txt）

mkdocs.yml (plugins)

plugins:
  - social:
      cards: true
      cards_layout: default
      cards_layout_options:
        background_color: "#1565c0"
        color: "#ffffff"
        font_family: Roboto

メモ：
- 古いオプション（cards_color, cards_font）は非推奨。
- strict モードでは警告がエラー化するため、新オプションに統一。

ローカル環境（構築・プレビュー）

初回セットアップ

python -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -r requirements.txt

プレビュー

mkdocs serve
# http://127.0.0.1:8000

よくあるハマり

別ターミナルで仮想環境を有効化していない → No module named ‘material’
SPA キャッシュで見た目が変わらない → ハードリロード or ?v=YYYYMMDD を付けて再読込

デプロイ（GitHub Pages）

.github/workflows/gh-pages.yml を用意。main/master への push で自動ビルド →gh-pages へ反映。
手動で即時反映したい場合：

mkdocs build --strict
mkdocs gh-deploy --force

初回だけ GitHub Pages の公開ブランチを gh-pages に設定。

運用メモ（やってみての学び）

レイアウトの「強い」改修は極力しない
- Material のアップストリーム変更で崩れるコスト > 得られるメリット
- まずは features/CSS の最小変更で十分便利
Docs-as-Code の効果が大きい
- スニペットを手元で試し、そのままノート化 → 再利用性が高い
- 変更履歴とレビューが手に入る（PR でメモも強くなる）
コンテナ領域は分割が効いた
- 基本コマンド / Dockerfile / Compose は思考と検索の単位に合う
- 将来 k8s セクションと横断しやすい

今後の拡張

コンテンツの厚み（ネットワーク/セキュリティ周りの体系化）
言語（Python/Golang）での補助ツールや Lambda 用メモを追加
旧 URL の整理（増えてきたら redirects を活用）

リンク

テックノート: https://wan0ri.github.io/note
GitHub リポジトリ: https://github.com/wan0ri/note

Topへ戻る