0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@hamukun8686

GitHub Actions と VitePress による GitHub Pages へのデプロイ最小構成

0
Last updated at Posted at 2026-01-24

リポジトリ内の Markdown を VitePress で静的サイトに変換し、GitHub Actions により GitHub Pages へ自動デプロイする手順を説明します。

目的

  • docs 配下の Markdown をサイトとして公開
  • main ブランチへの push を契機として GitHub Pages を更新
  • 環境変数により base をローカル環境と CI 環境で自動的に切り替え

利点

  • Markdown のみでオリジナルのドキュメントサイトを作成
  • Git でコンテンツのバージョン管理
  • GitHub にコミットするだけで自動的にサイトが更新
  • VitePress により、検索機能やナビゲーションが自動生成
  • 追加のサーバやホスティングサービスが不要

前提条件

  • Node.js 18 以上を使用（VitePress 1.x の要件）
  • GitHub Actions では Node.js 20（LTS）を使用（安定性とサポート期間を考慮）
  • GitHub リポジトリのデフォルトブランチは main
  • GitHub アカウントとリポジトリが作成済みであることを前提

GitHub Pages の種類と base 設定

GitHub Pages の公開 URL 形式により必要な設定が変化します。
まず公開 URL 形式を確認してください。

種類 公開 URL base 設定 BASE_PATH 環境変数
Project Pages https://<user>.github.io/<repo>/ /<repo>/ 設定する
User Pages / Organization Pages https://<user>.github.io/ / 設定しない

base は VitePress が生成する HTML、CSS、JavaScript の参照パスの先頭を定義します。
base が公開 URL のパス部分（/<repo>/ または /）と一致しない場合、404 エラーや CSS の読み込み失敗が発生します。

本記事のサンプルコードは Project Pages を前提としています。
User Pages または Organization Pages を使用する場合は、workflow の BASE_PATH 設定を削除してください。

構成

以下のファイル構成を準備してください。

.
├─ docs/
│  ├─ .vitepress/
│  │  └─ config.ts
│  ├─ index.md
│  └─ guide/
│     └─ index.md
├─ .github/
│  └─ workflows/
│     └─ deploy-pages.yml
├─ package.json
└─ package-lock.json

手順

1. VitePress の導入

以下のコマンドで VitePress をインストールしてください。

npm install -D vitepress

package.json に以下の scripts を定義してください。

{
  "name": "my-docs",
  "private": true,
  "scripts": {
    "docs:dev": "vitepress dev docs",
    "docs:build": "vitepress build docs",
    "docs:preview": "vitepress preview docs"
  },
  "devDependencies": {
    "vitepress": "^1"
  }
}

name はプロジェクト名に変更してください。private: true は npm への誤公開を防止します。

package-lock.json をコミットしてください。
GitHub Actions の npm ci は package-lock.json を必要とします。

動作確認：開発サーバの起動

以下のコマンドで開発サーバを起動し、VitePress が正常にインストールされたことを確認してください。

npm run docs:dev

ブラウザで http://localhost:5173 を開き、VitePress のデフォルトページが表示されれば成功です。
確認後、Ctrl + C で開発サーバを停止してください。

2. サイトの本文の作成

docs 配下に Markdown ファイルを配置してください。
以下は基本的な配置例です。

  • docs/index.md
  • docs/guide/index.md

3. VitePress の設定

docs/.vitepress/config.ts を作成してください。
環境変数 BASE_PATH が存在する場合は値を base として使用し、存在しない場合は / を使用します。

import { defineConfig } from "vitepress";

function resolveBasePathForGitHubPages(): string {
  const basePathFromEnvironment = process.env.BASE_PATH;
  if (typeof basePathFromEnvironment === "string" && basePathFromEnvironment.length > 0) {
    return basePathFromEnvironment;
  }

  return "/";
}

export default defineConfig({
  title: "サイトタイトル",
  description: "サイトの説明",
  lang: "ja",
  base: resolveBasePathForGitHubPages(),
  themeConfig: {
    nav: [
      { text: "Home", link: "/" },
      { text: "Guide", link: "/guide/" }
    ],
    sidebar: [
      {
        text: "Guide",
        items: [{ text: "はじめに", link: "/guide/" }]
      }
    ]
  }
});

base の設定値は GitHub Pages の種類により異なります。詳細は「GitHub Pages の種類と base 設定」セクションを参照してください。

動作確認：ビルドの実行

以下のコマンドでビルドを実行し、エラーが発生しないことを確認してください。

npm run docs:build

ビルドが成功すると docs/.vitepress/dist ディレクトリに静的ファイルが生成されます。

以下のコマンドでビルド成果物をプレビューできます。

npm run docs:preview

ブラウザで http://localhost:4173 を開き、サイトが正しく表示されることを確認してください。

4. GitHub Actions の workflow 作成

.github/workflows/deploy-pages.yml を作成してください。

name: Deploy VitePress to GitHub Pages

on:
  push:
    branches: [main]
  workflow_dispatch:  # 手動実行を許可

permissions:
  contents: read      # リポジトリの読み取り
  pages: write        # GitHub Pages への書き込み
  id-token: write     # OIDC トークンの発行（Pages デプロイに必要）

concurrency:
  group: pages
  cancel-in-progress: true  # 実行中のデプロイをキャンセルして最新を優先

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm

      - name: Install dependencies
        run: npm ci

      - name: Build VitePress
        env:
          BASE_PATH: "/${{ github.event.repository.name }}/"
        run: npm run docs:build

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: docs/.vitepress/dist

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    needs: build
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

workflow は以下の処理の実行

  • 依存関係のインストール
  • VitePress のビルド（BASE_PATH 環境変数を設定）
  • ビルド成果物のアップロード（docs/.vitepress/dist ディレクトリ）
  • GitHub Pages へのデプロイ

workflow の主要な設定

  • workflow_dispatch: Actions タブから手動で workflow を実行
  • permissions: GitHub Pages へのデプロイに必要な権限を設定
    • pages: write と id-token: write は GitHub Pages デプロイに必須
  • concurrency: 複数の push が連続した場合、実行中のデプロイをキャンセルして最新のみをデプロイ

User Pages または Organization Pages を使用する場合の設定変更については「GitHub Pages の種類と base 設定」セクションを参照してください。

5. GitHub の Pages 設定の更新

GitHub リポジトリの設定画面で Pages の source を GitHub Actions に変更してください。

  1. GitHub リポジトリのページを開く
  2. Settings タブを選択
  3. 左メニューから Pages を選択
  4. Build and deployment セクションの Source を GitHub Actions に変更

設定が未完了の場合、workflow が成功してもサイトはデプロイされません。

6. デプロイ結果の確認

main ブランチへ push してください。
GitHub Actions が workflow を実行し、GitHub Pages へデプロイします。

workflow の実行状況を確認

  1. GitHub リポジトリのページを開く
  2. Actions タブを選択
  3. 最新の workflow 実行を選択
  4. すべてのジョブが緑色のチェックマークになっていれば成功

公開されたサイトの確認

  1. GitHub リポジトリの Settings タブを開く
  2. 左メニューから Pages を選択
  3. 「Your site is live at」に表示される URL をクリック
  4. サイトが正しく表示されることを確認

公開 URL の形式は https://<user>.github.io/<repo>/ です。

代表的な不具合と対処

404 または CSS が反映されない

base または BASE_PATH の設定値を確認してください。
ブラウザの開発者ツールで CSS や JavaScript の読み込みパスを確認し、「GitHub Pages の種類と base 設定」セクションの表と照合してください。

workflow は成功するがデプロイされない

GitHub Pages の source 設定を確認してください。
Settings > Pages > Build and deployment で Source が「GitHub Actions」になっていることを確認してください。

npm ci が失敗する

package-lock.json が存在することを確認してください。
存在しない場合、ローカル環境で npm install を実行し、生成された package-lock.json をコミットしてください。

まとめ

本記事では以下の構成で GitHub Pages へのデプロイを実現しました。

  • Markdown は docs 配下に配置
  • VitePress の base 設定は環境変数 BASE_PATH で自動切り替え
  • GitHub Actions が VitePress をビルドし GitHub Pages へデプロイ
  • GitHub Pages の source は GitHub Actions に設定

発展的なカスタマイズ

本記事は最小構成のため、以下の機能は含まれていません。必要に応じて VitePress 公式ドキュメントを参照してください。

  • 検索機能の有効化
  • カスタムテーマの適用
  • サイトマップの生成
  • 多言語対応

VitePress 公式ドキュメント: https://vitepress.dev/

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?