ServBay

日本語

English
简体中文
繁體中文
Español
العربية
Português
Русский
Deutsch
Français
Tiếng Việt
Türkçe
Italiano

日本語

English
简体中文
繁體中文
Español
العربية
Português
Русский
Deutsch
Français
Tiếng Việt
Türkçe
Italiano

Appearance

ServBay 環境での Jigsaw のインストールと設定 ​

概要 ​

このドキュメントは、強力なローカル Web 開発環境である ServBay において、Jigsaw 静的サイトジェネレーターをインストールおよび設定する方法を解説します。ServBay は PHP や Node.js など複数のテクノロジースタックの統合環境を提供しており、Jigsaw プロジェクトの構築を非常にシンプルにします。ServBay を使えば、Jigsaw プロジェクトのローカルドメイン、HTTPS、高性能 Web サーバーの設定も簡単で、サイト内容の開発に集中できます。

Jigsaw とは？ ​

Jigsaw は Tighten 社が開発した、Laravel コンポーネントをベースにした静的サイトジェネレーターです。Laravel の Blade テンプレートエンジンの強力さ・柔軟さを活用し、Markdown ファイルと組み合わせて純粋な静的 HTML サイトを生成します。Jigsaw はドキュメントサイト、ブログ、ランディングページ、そしてサーバーサイドのデータベースや動的処理を必要としないサイトに最適です。主なメリットは以下の通りです：

  • おなじみのツールを活用: Laravel や Blade に慣れていれば、Jigsaw はすぐに使いこなせます。
  • パフォーマンスとセキュリティ: 静的サイトは表示が高速で、サーバーサイドのコード実行がないため高いセキュリティ性を持ちます。
  • 柔軟なテンプレート: Blade テンプレートにより複雑なレイアウトやコンポーネントも簡単に。
  • Markdown サポート: コンテンツの執筆も手軽です。

利用シーン ​

Jigsaw は主に以下の用途で活用されています：

  • プロジェクトのドキュメントや API ドキュメント
  • 個人ブログや技術メモサイト
  • 企業やプロダクトのランディングページ
  • 小規模なポートフォリオサイト
  • パフォーマンスやセキュリティを重視し、コンテンツが比較的固定されたWebサイト

前提条件 ​

作業開始の前に、以下の条件を満たしていることをご確認ください。

  1. ServBay がインストール・起動済み: macOS に ServBay が正しくインストール・起動されている必要があります。ServBay には PHP、Composer、Node.js/npm が内蔵されており、Jigsaw のセットアップに不可欠です。
  2. 基本的なコマンドライン操作の知識: ターミナルを使ってコマンド実行ができることが必要です。
  3. Composer および npm の基本的な理解: Jigsaw のインストールに Composer、フロントエンドのビルドに npm を利用します。

インストールおよび設定手順 ​

ここからは、ServBay 環境において Jigsaw プロジェクトをインストール・設定する手順を詳しく解説します。

ステップ 1: プロジェクトディレクトリの作成 ​

まずターミナルを開き、推薦されている ServBay のウェブルート /Applications/ServBay/www に移動し、Jigsaw プロジェクト用の新しいサブディレクトリを作成します。

bash
cd /Applications/ServBay/www
mkdir servbay-jigsaw-demo
cd servbay-jigsaw-demo

ここではディレクトリ名を servbay-jigsaw-demo としています。以降、このディレクトリ下にプロジェクトの全ファイルを配置します。

ステップ 2: Composer で Jigsaw プロジェクトを作成 ​

ServBay には Composer があらかじめセットアップされていますので、任意のターミナルで composer コマンドを利用できます。先ほど作成したプロジェクトディレクトリ (/Applications/ServBay/www/servbay-jigsaw-demo) で、以下のコマンドを実行して Jigsaw プロジェクトを作成します：

bash
composer create-project tightenco/jigsaw .

このコマンドは Jigsaw の最新バージョンと必要な PHP 依存パッケージを現在のディレクトリ (.) にダウンロードします。コマンドの末尾の . は「現在のディレクトリに展開する」ことを意味し、サブディレクトリは作られません。

ステップ 3: ServBay サイトの設定 ​

Web ブラウザで Jigsaw サイトへアクセスするには、ServBay でローカルサイトとしてプロジェクトを登録する必要があります。

  1. ServBay UI を開く: ServBay のアプリアイコンをダブルクリックするか、メニューバーのアイコンからコンソールパネルを開きます。
  2. 「サイト」セクションへ移動: 左側のナビゲーションで「サイト」タブをクリック。
  3. 新規サイトを追加: 画面下部の「+」ボタンを押し「サイト追加」を選択。
  4. サイト情報の設定:
    • 名前 (Name): 例 ServBay Jigsaw Demo のような分かりやすい名前を入力。
    • ドメイン (Domain): ローカルで利用するドメイン名を入力しましょう。実在ドメインとの衝突回避のため、.servbay.demo サフィックス推奨（例: jigsaw-demo.servbay.demo）。.servbay.demo ドメインは ServBay が自動的にローカル解決します。
    • サイトタイプ (Site Type): PHP を選択（Jigsaw のビルドには PHP が必要）。
    • PHP バージョン (PHP Version): インストール済みの PHP バージョンのうち、なるべく新しい安定版を推奨。
    • サイトルート (Site Root): ここが重要です。Jigsaw がビルドした静的ファイルはデフォルトで build_local ディレクトリに生成されますので、このパスをサイトルートに指定します： /Applications/ServBay/www/servbay-jigsaw-demo/build_local
  5. 保存・適用: 設定完了後、「保存」をクリックします。変更の適用を求められるので「確認」を押してください。ServBay が Web サーバー（Caddy または Nginx）の設定を自動更新し、HTTPS も自動構成します。

ステップ 4: フロントエンド依存のインストール ​

Jigsaw プロジェクトでは通常、npm を利用してフロントエンド資産（CSS プリプロセッサ SASS、JavaScript など）を管理・ビルドします。ServBay には Node.js と npm も同梱されています。

プロジェクトディレクトリ (/Applications/ServBay/www/servbay-jigsaw-demo) で、以下のコマンドを実行します：

bash
npm install

プロジェクトルートの package.json ファイルを元に、必要な Node.js モジュールが node_modules にインストールされます。

ステップ 5: Jigsaw サイトのビルド ​

すべての依存パッケージのインストール後、Jigsaw のビルドコマンドで静的サイトファイルを生成します。

対象ディレクトリ内で次のコマンドを実行：

bash
./vendor/bin/jigsaw build

この操作で行われること：

  1. source ディレクトリ内の Markdown ファイルと Blade テンプレートが処理されます。
  2. フロントビルドタスク（webpack.mix.js で設定。npm install で Laravel Mix を含む場合）を実行。
  3. 生成された静的 HTML/CSS/JS およびその他の資産は build_local ディレクトリに出力されます。

ステップ 6: サイトへアクセス ​

これで、Jigsaw で生成された静的ファイルが /Applications/ServBay/www/servbay-jigsaw-demo/build_local に保存されています。そして、ServBay のサイトルート設定もこのディレクトリを指していますので、Web ブラウザから設定済みのローカルドメインにアクセスすれば OK です。

ブラウザで、ステップ 3 で登録したドメイン（例: https://jigsaw-demo.servbay.demo）へアクセスしてください。ServBay は HTTPS 用ローカル証明書（ServBay User CA 発行）も自動的にセットアップします。Jigsaw の初期ウェルカムページが表示されるはずです。

カスタマイズと開発 ​

これで基本的な環境構築は完了。Jigsaw サイトのコンテンツやデザインのカスタマイズを始めましょう。

コンテンツおよびテンプレートの編集 ​

  • サイトのソースコードはプロジェクトルートの source ディレクトリにあります。
  • HTML レイアウトやコンポーネントは Blade テンプレートで記述し、source/_layouts や source/_partials 配下に格納されます。
  • ページコンテンツは Markdown で記載され、source またはそのサブディレクトリ（例：source/index.md, source/about.md）に配置します。
  • ブログ記事は通常 source/_posts ディレクトリに、YYYY-MM-DD-slug.md 形式で保存します。

新規ページ・記事の追加 ​

新しいページまたはブログ投稿を追加するには、source ディレクトリやサブディレクトリ（例：source/_posts）に新しい Markdown ファイルを作成するだけです。

例えば、source/about.md ファイルを作成：

markdown
---
title: "私たちについて"
description: "ServBay Jigsaw Demo の詳細情報"
---

# 私たちについて

こちらは Jigsaw で構築した「About」ページです。

ここに会社概要やチーム紹介などを記載できます。

スタイルやスクリプトのカスタマイズ ​

Jigsaw プロジェクトでは多くの場合、Laravel Mix (webpack.mix.js) を利用しフロントエンド資産をコンパイルします。

  • スタイルファイル（通常は SASS/SCSS）は source/_assets/sass ディレクトリ内。
  • JavaScript ファイルは source/_assets/js 内。

プロジェクトディレクトリで npm スクリプトを使ってファイルをコンパイルします：

  • npm run dev：開発用資産のビルド（ソースマップ含む・非圧縮）。
  • npm run watch：開発用ビルド＆ファイル変更時に自動再ビルド。開発時に便利。
  • npm run prod：本番用のビルド（最適化・圧縮）。

例えば、source/_assets/sass/main.scss を編集した後、npm run dev または npm run watch で CSS を再生成します。

サイトの再ビルド ​

重要: source ディレクトリ内の Markdown コンテンツ または Blade テンプレート を編集した場合は、必ず下記コマンドで Jigsaw のビルドを再実行し、変更を反映しましょう。

bash
./vendor/bin/jigsaw build

フロントエンド資産 (SASS, JS) を変更した場合は、npm run dev または npm run watch を使用して再コンパイルが必要です。通常、Jigsaw の build コマンドでも Mix の処理は走りますが、切り分けて理解しておくとデバッグ時に便利です。

注意点 ​

  • ビルド出力ディレクトリ: Jigsaw のデフォルト出力は build_local（開発用）および build_production（本番用）ディレクトリです。ServBay のサイトルートが目的のディレクトリ（通常は build_local）を指していることを確認してください。
  • Web サーバー: ServBay では Caddy または Nginx が Web サーバーとして動作し、build_local 内の静的ファイルを高速に配信します。Jigsaw の jigsaw serve コマンドは簡易プレビュー用なので、ServBay の本格 Web サーバーを利用しましょう。
  • HTTPS: ServBay は .servbay.demo ドメインに自動で HTTPS を適用し、ServBay User CA で署名済み証明書を利用します。警告回避のため、ユーザー CA 証明書の信頼設定をしておきましょう。
  • クリーンビルド: もしビルド結果が不安定な場合は、./vendor/bin/jigsaw build --clean で一度クリーンビルドを試してください。

よくある質問 (FAQ) ​

Q: Markdown ファイルを修正したのに、ブラウザで変化が反映されません。

A: コンテンツやテンプレートに修正を加えた際は、ターミナルで ./vendor/bin/jigsaw build を実行し再ビルドが必要です。

Q: SCSS ファイルを編集したのに、スタイルが変わりません。

A: フロント資産の編集後には、プロジェクトディレクトリで npm run dev または npm run watch を実行し再ビルドしてください。

Q: ローカルドメインへアクセスできない・ファイルが見つからないと表示されます。

A: 以下の点をチェックしましょう：

  1. ServBay が起動中であるか。
  2. ServBay サイト設定が正しいか：ドメイン名、サイトルートが /Applications/ServBay/www/servbay-jigsaw-demo/build_local になっているか。
  3. ./vendor/bin/jigsaw build コマンドは正常終了したか。また、build_local に index.html 等のファイルが生成されているか。

Q: Jigsaw サイトを本番公開したい場合は？

A: Jigsaw は静的ファイルを生成します。手順は以下の通りです。

  1. ./vendor/bin/jigsaw build production で本番環境用ファイルを生成（最適化あり）。
  2. build_production ディレクトリ内すべてを、Netlify、Vercel、GitHub Pages、各種クラウドストレージ等、静的サイトホスティングに適したサービスにアップロードします。

まとめ ​

ServBay を活用すれば、macOS 上で Jigsaw 静的サイトジェネレーターのインストールと設定がスムーズかつ効率的に行えます。必要な実行環境（PHP, Composer, Node.js, npm）や高機能なローカル Web サーバーがワンパッケージなので、手軽に Jigsaw プロジェクトをスタートできます。本ガイドに沿って進めることで、ローカル開発体験を最適化しつつ、Jigsaw サイト制作に専念できるでしょう。