新しいプロジェクトが始まるとき、最初にやることは何でしょうか。リポジトリの作成、CI の設定、開発環境の構築。やることは山ほどあります。

「ドキュメントサイトの構築」はその優先リストに入っていないことがほとんどです。README に書いておけばいい、Notion にまとめればいい。そう考えて後回しにしがちです。

しかし、プロジェクトの Day 1 からドキュメントサイトを立てておくと、その後のチーム内のナレッジ共有が驚くほどスムーズになります。セットアップ手順、アーキテクチャの設計判断、API 仕様、運用手順。これらをサイドバー付きの検索可能なサイトにまとめておくだけで、「あの情報どこだっけ」が激減します。

なぜ Private GitHub Pages なのか

GitHub Pages はリポジトリからドキュメントサイトを直接ホスティングできる機能です。GitHub Enterprise Cloud を利用している組織では、GitHub Pages の公開範囲を private に設定できます。

Private GitHub Pages を使う理由はシンプルです。

• アクセス制御が不要: リポジトリの読み取り権限を持つメンバーだけが閲覧できる。別途認証の仕組みを用意する必要がない
• デプロイが簡単: GitHub Actions で push するだけで自動デプロイされる。外部サービスとの連携設定も不要
• コードと同じリポジトリで管理: ドキュメントのソースコードがリポジトリに含まれるため、コードの変更とドキュメントの更新を同じ PR でレビューできる
• コストが追加で発生しない: GitHub Enterprise Cloud を契約している組織であれば、追加費用なしで利用できる

Notion や Confluence にもページの変更履歴機能はありますが、Git ベースの管理とは性質が異なります。Git なら diff で差分を確認でき、PR でレビューでき、コードの変更とドキュメントの更新を同じコミットに含められます。

なお、Private GitHub Pages は GitHub Enterprise Cloud 限定の機能です。Free、Pro、Team プランでは利用できません。Enterprise Cloud を契約していない組織では、GitHub Pages を public で運用しつつ、Cloudflare Access などで認証レイヤーを追加するといった代替手段を検討してください。

ビルドが速い 2 つの選択肢

ドキュメントサイトの SSG は数多くあります。ビルドの速さだけなら、Go 製の Hugo や Rust 製の mdBook がトップクラスです。Rust ベースのバンドラーを使う Rspress も高速です。

ただ、プロジェクトの技術スタックが TypeScript 中心であれば、ドキュメントサイトも同じエコシステムに揃えるほうがメンテナンスしやすくなります。設定ファイルの書き方、コンポーネントの拡張、ビルドツールチェーンの理解。すべてが既存の知識の延長線上にあるからです。

その観点で、TypeScript エコシステムの中からビルドが速い 2 つを選びました。

VitePress: Markdown でシンプルに

VitePress は Vite ベースの SSG で、Markdown ファイルをそのまま静的サイトに変換します。

特徴

• Markdown（.md）ベースのシンプルな構成
• Vite による高速なビルドとホットリロード
• デフォルトテーマがドキュメントサイトに最適化されている
• サイドバー、検索、ナビゲーションが設定ファイルだけで構成できる
• Vue コンポーネントを Markdown 内で使える

セットアップ

npm add -D vitepress
npx vitepress init

初期設定ウィザードに答えるだけで、ドキュメントサイトのひな形が完成します。

設定例

// docs/.vitepress/config.mts
import { defineConfig } from "vitepress";
 
export default defineConfig({
  title: "Project Docs",
  description: "Internal documentation",
  base: "/repo-name/",
  lang: "ja",
  themeConfig: {
    nav: [{ text: "Home", link: "/" }],
    sidebar: [
      {
        text: "Getting Started",
        items: [
          { text: "セットアップ", link: "/setup" },
          { text: "アーキテクチャ", link: "/architecture" },
        ],
      },
    ],
    search: { provider: "local" },
  },
});

実際のプロジェクトでは、VitePress のセットアップから GitHub Pages へのデプロイまで 1 つの PR で完了しました。ビルド時間は約 1 秒。既存の docs/ ディレクトリにある Markdown ファイルをそのまま活用できたため、コンテンツの移行も不要でした。

Starlight: MDX で多機能に

Starlight は Astro ベースのドキュメントテーマで、より多機能なドキュメントサイトを構築できます。

特徴

• Markdown（.md）と MDX（.mdx）の両方に対応
• 国際化（i18n）がビルトインでサポートされている
• Pagefind による静的検索（CJK 対応）
• カード、タブ、バッジ、ファイルツリーなどの組み込みコンポーネントが豊富
• Astro のエコシステム全体を活用できる

セットアップ

npm create astro@latest -- --template starlight

設定例

// astro.config.mjs
import { defineConfig } from "astro/config";
import starlight from "@astrojs/starlight";
 
export default defineConfig({
  site: "https://your-org.github.io",
  base: "/repo-name",
  integrations: [
    starlight({
      title: "Project Docs",
      defaultLocale: "ja",
      locales: {
        ja: { label: "日本語", lang: "ja" },
        en: { label: "English", lang: "en" },
      },
      sidebar: [
        {
          label: "Getting Started",
          items: [
            { slug: "ja/setup" },
            { slug: "ja/architecture" },
          ],
        },
      ],
    }),
  ],
});

実際のプロジェクトでは、約 100 ページのビルドが正常に完了し、Pagefind による CJK 対応の検索も動作しています。

GitHub Actions で自動デプロイする

VitePress と Starlight の公式ドキュメントでは、GitHub Actions で main ブランチへの push 時に自動デプロイする構成が紹介されています。しかし、筆者のプロジェクトでは GitHub Actions のソースを Deploy from a branch に設定し、ビルド成果物を gh-pages ブランチに push する構成を採用しています。

理由は、GitHub の Organization レベルで提供されている Actions のポリシー機能との互換性です。このポリシーでは、ワークフロー内のアクション参照を commit SHA で pin することを強制できます。GitHub Actions ソースの場合、actions/deploy-pages などのアクションに依存しますが、SHA pinning ポリシーが有効な環境ではこれらの参照方法が制約を受け、Pages のデプロイが正常に動作しないことがあります。ブランチデプロイであればビルド成果物を git push するだけなので、この制約を回避できます。

VitePress の場合

# .github/workflows/deploy-docs.yml
name: Deploy Docs
 
on:
  push:
    branches: [main]
    paths:
      - "docs/**"
      - ".github/workflows/deploy-docs.yml"
  workflow_dispatch:
 
permissions:
  contents: write
 
concurrency:
  group: pages
  cancel-in-progress: false
 
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
        with:
          node-version: 24
          cache: npm
      - run: npm ci
      - run: npm run docs:build
      - name: Deploy to gh-pages
        run: |
          cd docs/.vitepress/dist
          git init
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add -A
          git commit -m "deploy: $(date -u '+%Y-%m-%d %H:%M:%S UTC')"
          git push -f "https://x-access-token:${{ github.token }}@github.com/${{ github.repository }}.git" HEAD:gh-pages

Starlight（Astro）の場合

# .github/workflows/deploy-docs.yml
name: Deploy Docs
 
on:
  push:
    branches: [main]
    paths:
      - "docs/**"
      - ".github/workflows/deploy-docs.yml"
  workflow_dispatch:
 
permissions:
  contents: write
 
concurrency:
  group: pages
  cancel-in-progress: false
 
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
        with:
          node-version: 24
          cache: npm
      - run: npm ci
      - run: npm run build
      - name: Deploy to gh-pages
        run: |
          cd dist
          touch .nojekyll
          git init
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add -A
          git commit -m "deploy: $(date -u '+%Y-%m-%d %H:%M:%S UTC')"
          git push -f "https://x-access-token:${{ github.token }}@github.com/${{ github.repository }}.git" HEAD:gh-pages

どちらもほぼ同じ構成です。違いはビルドコマンドと出力ディレクトリだけです。

デプロイ後、リポジトリの Settings > Pages > Source を Deploy from a branch にし、ブランチに gh-pages を指定すれば完了です。

VitePress と Starlight、どちらを選ぶか

2 つのツールはどちらもビルドが速く、ドキュメントサイトに必要な機能を備えています。選び方の基準を整理します。

VitePress を選ぶ場合: Markdown だけでシンプルにドキュメントを書きたい、設定ファイルを最小限にしたい、Vue エコシステムを活用したいとき。

Starlight を選ぶ場合: MDX でリッチなコンテンツを書きたい、多言語対応が必要、組み込みコンポーネント（カード、タブ、バッジなど）を活用したいとき。

どちらを選んでも、Day 1 のセットアップは 1 つの PR で完了します。迷ったら、Markdown の .md だけで十分なら VitePress、MDX や i18n が欲しいなら Starlight、という基準で選んでみてください。

Day 1 に書くべき最初のドキュメント

ドキュメントサイトを立てたら、まず何を書くべきでしょうか。筆者の経験から、初日に書いておくと効果が高いものを挙げます。

1. 開発環境のセットアップ手順: 新しいメンバーがリポジトリをクローンしてから開発を始められるまでの手順。これが README だけに書かれていると、情報が増えるにつれて埋もれていく
2. アーキテクチャの概要: 技術スタックの選定理由、ディレクトリ構成の説明。「なぜこの構成なのか」を書いておくと、後から参加するメンバーの理解が早まる
3. デプロイの手順と設定: CI/CD パイプラインの構成、環境変数の管理方法。口頭で伝えがちな情報をドキュメントに残す

完璧なドキュメントを書く必要はありません。最初は箇条書きでも構いません。重要なのは、ドキュメントを書く「場所」が初日から存在していることです。場所があれば、チームメンバーは自然とドキュメントを追加していきます。

まとめ

Private GitHub Pages で Day 1 からドキュメントサイトを構築しておくと、チーム内のナレッジ共有が加速します。

• Private GitHub Pages: リポジトリの読み取り権限を持つメンバーだけがアクセスできる。認証の仕組みを別途用意する必要がない
• VitePress: Markdown ベースでシンプル。設定が最小限で、ビルドも速い
• Starlight: MDX 対応、i18n ビルトイン、組み込みコンポーネントが豊富。多機能なドキュメントサイトに向いている
• どちらも: GitHub Actions で自動デプロイでき、1 つの PR でセットアップが完了する

ドキュメントは「後で書く」と言って、書かれないまま終わることがほとんどです。Day 1 にドキュメントサイトを立てておくことで、「書く場所がある」という状態を作る。それだけで、チームのドキュメント文化は大きく変わります。

以上、プロジェクト初日にドキュメントサイトを立てている現場からお送りしました。

参考情報

• VitePress 公式ドキュメント
• Starlight 公式ドキュメント
• GitHub Pages ドキュメント
• GitHub Pages のサイトの公開範囲を変更する
• Astro: GitHub Pages にデプロイする
• VitePress: Deploy Your VitePress Site