VitePressでドキュメントサイト構築してGitHub Pagesで公開してみた

# プロジェクトディレクトリ（今回は演習資料を格納するので「practice」という名前にしました）に移動
cd practice

# package.jsonの作成（まだない場合）
pnpm init

# VitePressのインストール
pnpm add -D vitepress

pnpm vitepress init

┌  Welcome to VitePress!
│
◇  Where should VitePress initialize the config?
│  ./  ← 設定ファイルをどこに作成するか。今回は現在のディレクトリを選択。
│
◇  Where should VitePress look for your markdown files?
│  ./  ← どのディレクトリに公開したいマークダウンファイルを置いてるか。今回は現在のディレクトリを選択。
│
◇  Site title:
│  Next.js入門ドキュメント  ← サイトのタイトルを入力。
│
◇  Site description:
│  Next.js入門のための演習教材  ← サイトの説明を入力。
│
◇  Theme:
│  Default Theme  ← テーマを選択。今回はデフォルトを選択。
│
◇  Use TypeScript for config and theme files?
│  Yes  ← コンフィグファイルでTypeScriptを使用するか。
│
◇  Add VitePress npm scripts to package.json?
│  Yes  ← 開発サーバーの起動コマンド(vitepress dev)等をpackage.jsonに記載するか。
│
◇  Add a prefix for VitePress npm scripts?
│  Yes  ← コマンドにプレフィックスを利用するか。「doc」のような任意のプレフィックスを付与可能。※次の設問参照
│
◇  Prefix for VitePress npm scripts:
│  doc  ← これにより doc:dev, doc:build などのコマンドになる（デフォルトだとdev, buildの形式）
│
└  Done! Now run pnpm run doc:dev and start writing.

// .vitepress/config.ts
import { defineConfig } from 'vitepress'

// https://vitepress.dev/reference/site-config
export default defineConfig({
  title: "Next.js入門ドキュメント",
  description: "Next.js入門のための演習教材",
  themeConfig: {
    // https://vitepress.dev/reference/default-theme-config
    nav: [
      { text: 'Home', link: '/' },
      { text: 'Examples', link: '/markdown-examples' }
    ],

    sidebar: [
      {
        text: 'Examples',
        items: [
          { text: 'Markdown Examples', link: '/markdown-examples' },
          { text: 'Runtime API Examples', link: '/api-examples' }
        ]
      }
    ],

    socialLinks: [
      { icon: 'github', link: 'https://github.com/yuta-ishii-cm/next-app-task-manager' }
    ]
  }
})

{
  "type": "module",
  "devDependencies": {
    "vitepress": "2.0.0-alpha.15"
  },
  "scripts": {
    "doc:dev": "vitepress dev",
    "doc:build": "vitepress build",
    "doc:preview": "vitepress preview"
  }
}

# 開発サーバーを起動
pnpm doc:dev

practice/
├── .vitepress/
│   └── config.ts        # VitePressの設定ファイル
├── index.md             # トップページ
├── phase1.md            # Phase 1: 基礎編
├── phase2.md            # Phase 2: UI構築編
├── phase3.md            # Phase 3: データ操作編
├── phase4.md            # Phase 4: 完成編
└── optional.md          # 発展課題集（Optional）

import { defineConfig } from 'vitepress'

export default defineConfig({
  title: "Next.js入門ドキュメント",
  description: "Next.js入門のための演習教材",
  lang: 'ja-JP',  // 日本語対応
  ignoreDeadLinks: [
    /localhost/  // 教材内のlocalhostリンクはチェック対象外
  ],
  themeConfig: {
    // ナビゲーション
    nav: [
      { text: 'ホーム', link: '/' },
      { text: 'はじめに', link: '/phase1' }
    ],

    // サイドバー
    sidebar: [
      {
        text: '演習',
        items: [
          { text: 'Phase 1: 基礎編', link: '/phase1' },
          { text: 'Phase 2: UI構築編', link: '/phase2' },
          { text: 'Phase 3: データ操作編', link: '/phase3' },
          { text: 'Phase 4: 完成編', link: '/phase4' },
          { text: '発展課題集', link: '/optional' }
        ]
      }
    ],

    // ローカル検索を有効化
    search: {
      provider: 'local'
    },

    socialLinks: [
      { icon: 'github', link: 'https://github.com/your-username/your-repo' }
    ]
  }
})

---
layout: home  # トップページ用のレイアウトを指定

hero:  # ページ上部のメインビジュアル部分
  name: "Next.js入門ドキュメント"      # 大きく表示されるサイト名
  text: "Next.js入門のための演習教材"   # サブタイトル
  tagline: Next.jsに入門してみよう  # キャッチコピー
  actions:  # CTAボタン
    - theme: brand      # メインボタン（強調色）
      text: Phase 1から始める
      link: /phase1
    - theme: alt        # サブボタン（控えめな色）
      text: GitHub
      link: https://github.com/yuta-ishii-cm/next-app-task-manager

features:  # ページ下部のカード形式で並ぶ特徴紹介セクション
  - title: Phase 1 - 基礎編
    details: App Routerの仕組み、ファイルベースルーティング、Server/Client Componentの違いを理解する
    link: /phase1           # カードクリックで遷移するリンク先
    linkText: 詳しく見る     # リンクテキスト（省略可）
  - title: Phase 2 - UI構築編
    details: コンポーネント設計、TypeScriptでの型定義、Tailwind CSSでカンバンボードUIを構築する
    link: /phase2
    linkText: 詳しく見る
  - title: Phase 3 - データ操作編
    details: useStateでの状態管理、フォーム作成、イベントハンドリング、Server Actionsの基礎を学ぶ
    link: /phase3
    linkText: 詳しく見る
  - title: Phase 4 - 完成編
    details: Prismaでデータベース構築、Server ActionsでCRUD操作、Vercelへデプロイする
    link: /phase4
    linkText: 詳しく見る
  - title: 発展課題集（Optional）
    details: ドラッグ&ドロップ、楽観的更新など、さらにスキルアップしたい人向けのチャレンジ課題
    link: /optional
    linkText: 詳しく見る
---

// .vitepress/config.ts
export default defineConfig({
  title: "Next.js入門ドキュメント",
  description: "Next.js入門のための演習教材",
  base: '/your-repo-name/',  // リポジトリ名に合わせて変更（今回は）
  // ...
})

# ワークフロー名（GitHub Actionsの画面に表示される）
name: Deploy VitePress site to Pages

# ワークフローの実行トリガー
on:
  push:
    branches: [main]  # mainブランチへのプッシュで自動実行
  workflow_dispatch:  # GitHub画面から手動実行も可能

# ワークフローに付与する権限
permissions:
  contents: read      # リポジトリの読み取り権限
  pages: write        # GitHub Pagesへの書き込み権限
  id-token: write     # OIDCトークンの発行権限（Pages認証に必要）

# 同時実行の制御
concurrency:
  group: pages                 # 同じグループのワークフローは同時実行しない
  cancel-in-progress: false    # 実行中のワークフローはキャンセルしない

jobs:
  # ========================================
  # ビルドジョブ: サイトをビルドしてアーティファクトを作成
  # ========================================
  build:
    runs-on: ubuntu-latest
    steps:
      # リポジトリのコードをチェックアウト
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0  # 全履歴を取得（lastUpdatedの表示に必要）

      # pnpmのセットアップ
      - name: Setup pnpm
        uses: pnpm/action-setup@v3
        with:
          version: 9

      # Node.jsのセットアップ（pnpmキャッシュも有効化）
      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: pnpm
          cache-dependency-path: practice/pnpm-lock.yaml

      # GitHub Pagesの設定を取得
      - name: Setup Pages
        uses: actions/configure-pages@v4

      # 依存パッケージのインストール
      - name: Install dependencies
        run: pnpm install
        working-directory: practice

      # VitePressでサイトをビルド（.vitepress/distに出力）
      - name: Build with VitePress
        run: pnpm doc:build
        working-directory: practice

      # ビルド成果物をアーティファクトとしてアップロード
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: practice/.vitepress/dist  # ビルド出力ディレクトリ

  # ========================================
  # デプロイジョブ: ビルド成果物をGitHub Pagesに公開
  # ========================================
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}  # デプロイ先URL
    needs: build           # buildジョブの完了を待つ
    runs-on: ubuntu-latest
    steps:
      # GitHub Pagesにデプロイ
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4