【Ruby】Middlemanのバージョンを3から4に更新する方法

Middlemanは、Rubyで書かれた静的サイトジェネレータです。本記事では、Middlemanのバージョンを3から4にアップデートする手順と、移行時に発生する変更点への対応方法を紹介します。

Rubyのバージョンアップ
middleman gemをバージョン4に更新
テンプレートコードの修正
ファイル名に出力拡張子を追加
アセットパイプラインを外部パイプラインに変更
ブログ機能の更新（Nokogiriの追加）
ビルド
デプロイ
まとめ

Rubyのバージョンアップ

Middlemanの最新バージョン（本記事執筆時点で4.6.2）ではRuby 2.7以上が必要です。2026年現在の推奨環境であるRuby 3.4系に更新します。

本記事ではRVMを使いますが、rbenvなど別のマネージャを使っている方は適宜コマンドを置き換えてください。

# Bash
rvm install 3.4.3
rvm use 3.4.3

middleman gemをバージョン4に更新

まず、最新のMiddleman gemをインストールします。

gem install middleman

Gemfile を以下の通り書き換えます。middleman-sync などの古い拡張ジェムは、バージョン4と互換性がない場合があるため注意してください。

Gemfileを以下の通りに書き換えます。

# Gemfile
source 'https://rubygems.org'

ruby '3.4.3'

gem "middleman", "~> 4.6"
gem "slim"
gem "middleman-blog"
gem "nokogiri" # v4のブログ機能で必要

バージョン3との主な差分：

# Diff
-source :rubygems
+source 'https://rubygems.org'

+ruby '3.4.3'
 
-gem "middleman", "~> 3.0.0"
-gem "middleman-sync", "~> 3.0.5"
+gem "middleman", "~> 4.6"
 gem "slim"
-#gem "middleman-smusher"
 gem "middleman-blog"

設定が終わったら、bundleを更新します。

# Bash
bundle update

注意： バージョン3でAWS S3等へのデプロイに middleman-sync を使っていた場合は、config.rb の :sync セクションを削除してください。現在はAWS CLI等の外部ツールを使ったデプロイが推奨されています（後述）。

サーバーが正常に立ち上がるか確認しましょう。

# Bash
bundle exec middleman server

テンプレートコードの修正

バージョン4では、一部のオブジェクトやメソッドが変更・削除されています。

1. data.page から current_page.data への変更

テンプレート（SlimやERB）内でページデータにアクセスする方法が変わりました。

# Diff
# source/layouts/layout.slim
-    meta name="description" content="#{data.page.description}"                                                                                                                                            
+    meta name="description" content="#{current_page.data.description}"

2. request.path の変更

現在のパスを取得する場合も current_page を使用します。

# Diff
- if request.path == 'index.html'
+ if current_page.path == 'index.html'

ファイル名に出力拡張子を追加

バージョン3では source/index.slim というファイル名でも動作しましたが、バージョン4では最終的な出力形式（.htmlなど）を明示する必要があります。指定がないとHTTP 404エラーになります。

# Bash
# ファイル名を変更
git mv source/index.slim source/index.html.slim
git mv source/about.slim source/about.html.slim

アセットパイプラインを外部パイプラインに変更

バージョン4では標準のアセットパイプライン（Sprockets）が分離され、「外部パイプライン（External Pipeline）」を使ってWebpackやViteなどの外部ツールと連携する仕組みが推奨されるようになりました。

ここでは、Webpackを使用する例を紹介します。

1. package.json の作成

プロジェクトのルートに package.json を作成し、必要なパッケージをインストールします。

# JSON
{
  "name": "your_project",
  "version": "1.0.0",
  "devDependencies": {
    "webpack": "^5.0.0",
    "webpack-cli": "^5.0.0"
  }
}

2. config.rb の設定

MiddlemanからWebpackを呼び出す設定を追加します。

activate :external_pipeline,
         name: :webpack,
         command: build? ?
         "./node_modules/.bin/webpack --mode production" :
         "./node_modules/.bin/webpack --watch --mode development",
         source: ".tmp/dist",
         latency: 1

※Webpack側でビルド結果を .tmp/dist に出力するように設定することで、Middlemanがそのファイルを認識できるようになります。

ブログ機能の更新

middleman-blog を使用していて、記事の要約（article.summary）を利用している場合、バージョン4からは Nokogiri gemが必須となります。

# Gemfileに追加
gem 'nokogiri'

<% page_articles.each do |article| %>
  <h2><%= link_to article.title, article %></h2>
  <p><%= article.summary %></p>
  <p><%= link_to '続きを読む', article %></p>
<% end %>

ビルド

静的サイトのビルドコマンドはバージョン3と同じです。

# Bash
bundle exec middleman build

build/ ディレクトリに意図した通りにファイルが出力されていれば成功です。

デプロイ

現在、AWS S3とCloudFrontでホスティングする場合、専用のRuby Gemを使うよりも AWS CLI を活用したシェルスクリプトでの運用が、高速かつシンプルでおすすめです。

デプロイスクリプト例 (deploy.sh)

#!/bin/bash

# 変数の設定
BUCKET_NAME="your_bucket_name"
DISTRIBUTION_ID="your_distribution_id"
LOCAL_PATH="./build"

echo "--- S3への同期を開始します ---"
aws s3 sync $LOCAL_PATH s3://$BUCKET_NAME --acl public-read --delete

echo "--- CloudFrontのキャッシュを削除します ---"
aws cloudfront create-invalidation --distribution-id $DISTRIBUTION_ID --paths "/*"

echo "--- 完了しました ---"

必要なIAMポリシーの例

デプロイを実行するユーザーやロールには、以下の権限が必要です。

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "S3SyncPermissions",
            "Effect": "Allow",
            "Action": [
                "s3:PutObject",
                "s3:DeleteObject",
                "s3:GetObject"
            ],
            "Resource": "arn:aws:s3:::bucket_name/*"
        },
        {
            "Sid": "S3ListPermissions",
            "Effect": "Allow",
            "Action": "s3:ListBucket",
            "Resource": "arn:aws:s3:::bucket_name"
        },
        {
            "Sid": "CloudFrontInvalidationPermissions",
            "Effect": "Allow",
            "Action": "cloudfront:CreateInvalidation",
            "Resource": "arn:aws:cloudfront::YOUR_ACCOUNT_ID:distribution/YOUR_DISTRIBUTION_ID"
        }
    ]
}

AWS S3とCloudFrontの詳しい設定は、WordPressを静的ウェブサイトに変換してAWSでホスティングする方法で紹介していますので、参考にしてみてください。

まとめ

Middleman 3から4への移行は、特にアセット周りとテンプレートの書き換えが中心となります。手順をまとめると以下の通りです。

Rubyのバージョンを更新（3.x系推奨）
Middleman gemを4.xに更新し、nokogiri を追加
テンプレートのメソッド修正（current_page への変更）
ファイル名への拡張子（.html）追加
外部パイプライン（Webpack等）への移行
ビルドとデプロイの動作確認

新しいMiddlemanはより柔軟に最新のフロントエンドツールと連携できるようになっています。ぜひ試してみてください。