このサイトの構築について

Publii + GitHub + Azure Static Web Apps でサイトを公開した記録

Publii で作ったサイトを、GitHub 経由で Azure Static Web Apps (SWA) に自動デプロイし、独自ドメイン docs.pakue.cloud で公開しました。この記事では、その構成と手順、途中でつまずいた点をまとめます。

作業は役割を分けて進めました。Publii の操作は私が行い、GitHub と Azure の操作は Claude Code(AI コーディングエージェント)に任せました。

全体構成

Publii (ローカル)
   │  Sync (Manual deployment)
   ▼
ローカルの Git リポジトリ 
   │  git push (main)
   ▼
GitHub (Private リポジトリ PakueDocs)
   │  GitHub Actions
   ▼
Azure Static Web Apps (Free)  ──  docs.pakue.cloud (Azure DNS の CNAME)

手順

1. 事前確認

gh(GitHub CLI)と az(Azure CLI)にログイン済みであることを確認しました。あわせて、Azure DNS の pakue.cloud ゾーンに docs のレコードが無いことも確認しました。既存の設定を上書きしないための確認です。

2. GitHub リポジトリの作成

Private リポジトリを作成し、ローカルにクローンしました。

gh repo create <アカウント>/PakueDocs --private --clone

既定ブランチは main にしました。

3. Azure Static Web Apps の作成

GitHub との連携は Azure に任せず、SWA を先に単体で作成しました。ワークフローの内容を自分で管理するためです。

az staticwebapp create -n pakuedocs -g pakuecloud -l eastasia --sku Free

デプロイトークンは GitHub のシークレット AZURE_STATIC_WEB_APPS_API_TOKEN に直接登録しました。画面やログには出していません。

az staticwebapp secrets list -n pakuedocs -g pakuecloud --query "properties.apiKey" -o tsv \
  | gh secret set AZURE_STATIC_WEB_APPS_API_TOKEN --repo <アカウント>/PakueDocs

4. GitHub Actions ワークフロー

main への push で自動デプロイします。ポイントは 3 つです。

• 公開元は Publii の出力フォルダ(site/pakue-docs-files)
• ビルドは不要なので skip_app_build: true
• SWA の設定ファイルは Publii が消してしまうことがあるため、リポジトリのルートに置き、デプロイ時にコピーする

name: Deploy to Azure Static Web Apps

on:
  push:
    branches: [main]
  pull_request:
    types: [opened, synchronize, reopened, closed]
    branches: [main]
  workflow_dispatch:

jobs:
  build_and_deploy:
    if: github.event_name != 'pull_request' || github.event.action != 'closed'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Copy SWA config into site
        run: cp staticwebapp.config.json site/pakue-docs-files/staticwebapp.config.json
      - name: Remove files not needed on the public site
        working-directory: site/pakue-docs-files
        run: |
          rm -f files.publii.json
          rm -f assets/css/editor.css assets/css/main.css
          rm -f assets/js/scripts.js assets/js/svg-fix.js assets/js/svg-map.js
      - name: Deploy
        uses: Azure/static-web-apps-deploy@v1
        with:
          azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
          repo_token: ${{ secrets.GITHUB_TOKEN }}
          action: upload
          app_location: site/pakue-docs-files
          api_location: ""
          skip_app_build: true

  close_pull_request:
    if: github.event_name == 'pull_request' && github.event.action == 'closed'
    runs-on: ubuntu-latest
    steps:
      - uses: Azure/static-web-apps-deploy@v1
        with:
          azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
          action: close

5. SWA の設定ファイル

ルートの staticwebapp.config.json で、404 ページとセキュリティヘッダーを設定しました。

{
  "responseOverrides": {
    "404": { "rewrite": "/404.html" }
  },
  "globalHeaders": {
    "X-Content-Type-Options": "nosniff",
    "X-Frame-Options": "SAMEORIGIN",
    "Referrer-Policy": "strict-origin-when-cross-origin"
  }
}

6. 独自ドメインの設定

Azure DNS に CNAME を追加し、SWA のデフォルトホスト名を指すようにしました。

az network dns record-set cname set-record -g pakuecloud -z pakue.cloud \
  -n docs -c <SWAのデフォルトホスト名>.azurestaticapps.net

続いて、ドメインを SWA に紐付けました。検証方法は CNAME です。

az staticwebapp hostname set -n pakuedocs -g pakuecloud \
  --hostname docs.pakue.cloud --validation-method cname-delegation

紐付け直後の状態は Validating でした。数分で Ready になり、そのあと HTTPS でつながるようになりました。SSL 証明書は SWA が自動で発行する無料のマネージド証明書で、更新も自動です。CNAME が SWA を指している間だけ更新されるので、レコードを消したり変えたりしないよう注意が必要です。

7. Publii の設定

• サーバー設定の方式は Manual deployment
• 出力先は、リポジトリ内の site フォルダ
• サイト URL は https://docs.pakue.cloud

サイト URL を間違えると、リンクや画像のパスが壊れます。

Publii で「Sync your website」を押すと、出力先にファイルが書き出されます。あとは commit と push をすると、自動でデプロイされます。

つまずいた点

出力先の下にサイト名のフォルダができる

出力先を site にしたところ、実際の出力は site/pakue-docs-files/ の下に作られました。Publii が、サイト名のフォルダを作るためです。そこで、ワークフローの公開元を site/pakue-docs-files に変えました。

Publii 用の管理ファイルが公開されてしまう

出力の中には、サイトの表示に使われないファイルも含まれていました。参照関係を検索して、どこからも読み込まれていないものを洗い出しました。

リポジトリには Publii の出力をそのまま残し、デプロイの直前のステップで、これらだけを削除しています。Publii で再出力しても、同じ結果になります。

Git のユーザー情報が未設定だった

初回のコミットで Author identity unknown になりました。このリポジトリだけのローカル設定として、名前とメールアドレスを設定しました。

動作確認

公開後に、次を確認しました。

• トップ、記事、タグ、著者ページ、CSS、JS、フィード、サイトマップが 200 で返る
• 存在しない URL は 404 になり、404.html が使われる
• 取り除いたファイルは 404 になる
• セキュリティヘッダーが付いている

運用の流れ

1. Publii で記事を書いて、「Sync your website」を押す
2. site/ の変更を commit して main に push する
3. GitHub Actions が自動でデプロイする(数十秒〜数分)

注意点

• 「参照されていないファイル」という判断は、出力ファイル内の参照を検索して決めました。ブラウザで全ページを見て確認したわけではありません。
• Publii のテーマを変えたり更新したりすると、使われるファイルが変わることがあります。そのときは、削除するファイルの一覧を見直します。
• Publii 自体のデータ(記事の元データ)は、このリポジトリには入っていません。別にバックアップが必要です。