---

name: build-pkgdown-site description: > RパッケージのpkgdownドキュメントサイトをGitHub Pagesにビルドしてデプロイする。 _pkgdown.ymlの設定、テーマ、記事の構成、リファレンスインデックスのカスタマイズ、 デプロイ方法を網羅。新規または既存パッケージのドキュメントサイト作成、 レイアウトやナビゲーションのカスタマイズ、デプロイ済みサイトの404エラー修正、 またはデプロイ方法の移行時に使用する。 locale: ja source_locale: en source_commit: 33b561c9 fence_basis_commit: 33b561c9 translator: claude-opus-4-6 translation_date: 2026-03-16 license: MIT allowed-tools: Read Write Edit Bash Grep Glob metadata: author: Philipp Thoss version: "1.0" domain: r-packages complexity: intermediate language: R tags: r, pkgdown, documentation, github-pages, website

pkgdownサイトのビルド

Rパッケージのpkgdownドキュメントウェブサイトを設定してデプロイする。

使用タイミング

• RパッケージのドキュメントサイトをGitHub Pagesに作成する時
• pkgdownのレイアウト、テーマ、またはナビゲーションをカスタマイズする時
• デプロイ済みpkgdownサイトの404エラーを修正する時
• デプロイ方法を移行する時

入力

• 必須: roxygen2ドキュメントを持つRパッケージ
• 必須: GitHubリポジトリ
• 任意: カスタムテーマまたはブランディング
• 任意: 記事として含めるビネット

手順

ステップ1: pkgdownの初期化

usethis::use_pkgdown()

これにより_pkgdown.ymlが作成され、pkgdownが.Rbuildignoreに追加される。

期待結果： _pkgdown.ymlがプロジェクトルートに存在する。.Rbuildignoreにpkgdown関連のエントリが含まれる。

失敗時： install.packages("pkgdown")でpkgdownをインストールする。_pkgdown.ymlが既に存在する場合、関数は設定を上書きせずに.Rbuildignoreを更新する。

ステップ2: _pkgdown.ymlの設定

url: https://username.github.io/packagename/

development:
  mode: release

template:
  bootstrap: 5
  bootswatch: flatly

navbar:
  structure:
    left: [intro, reference, articles, news]
    right: [search, github]
  components:
    github:
      icon: fa-github
      href: https://github.com/username/packagename

reference:
  - title: Core Functions
    desc: Primary package functionality
    contents:
      - main_function
      - helper_function
  - title: Utilities
    desc: Helper and utility functions
    contents:
      - starts_with("util_")

articles:
  - title: Getting Started
    contents:
      - getting-started
  - title: Advanced Usage
    contents:
      - advanced-features
      - customization

重要: development: mode: releaseを設定すること。デフォルトのmode: autoはGitHub PagesでURLに/dev/が付加されて404エラーを引き起こす。

期待結果： _pkgdown.ymlがパッケージに適したurl、template、navbar、reference、articlesセクションを含む有効なYAMLを持つ。

失敗時： オンラインYAMLリンターでYAML構文を検証する。reference.contentsのすべての関数名が実際にエクスポートされた関数と一致しているか確認する。

ステップ3: ローカルでのビルド

pkgdown::build_site()

期待結果： docs/ディレクトリがindex.html、関数リファレンスページ、記事を含む完全なサイトで作成される。

失敗時： 一般的な問題：pandocの欠如（.RenvironでRSTUDIO_PANDOCを設定）、ビネット依存関係の欠如（推奨パッケージをインストール）、または壊れた例（修正するか\dontrun{}で囲む）。

ステップ4: サイトのプレビュー

pkgdown::preview_site()

ナビゲーション、関数リファレンス、記事、検索が正しく機能しているか確認する。

期待結果： サイトがlocalhostのブラウザで開く。すべてのナビゲーションリンクが機能し、関数リファレンスページがレンダリングされ、検索が結果を返す。

失敗時： プレビューが開かない場合、ブラウザでdocs/index.htmlを手動で開く。ページが欠如している場合、サイトをビルドする前にdevtools::document()が実行されたか確認する。

ステップ5: GitHub Pagesへのデプロイ

方法A: GitHub Actions（推奨）

pkgdownワークフローについてはsetup-github-actions-ciスキルを参照する。

方法B: 手動ブランチデプロイ

# Build site
Rscript -e "pkgdown::build_site()"

# Create gh-pages branch if it doesn't exist
git checkout --orphan gh-pages
git rm -rf .
cp -r docs/* .
git add .
git commit -m "Deploy pkgdown site"
git push origin gh-pages

# Switch back to main
git checkout main

期待結果： gh-pagesブランチがリモートにルートレベルのサイトファイルとともに存在する。

失敗時： プッシュが拒否される場合、リポジトリへの書き込みアクセスがあることを確認する。GitHub Actionsデプロイを使用する場合は、このステップをスキップしてsetup-github-actions-ciスキルに従う。

ステップ6: GitHub Pagesの設定

1. リポジトリの設定 > Pagesに移動する
2. ソースを「Deploy from a branch」に設定する
3. gh-pagesブランチ、/ (root)フォルダを選択する
4. 保存する

期待結果： 数分以内にhttps://username.github.io/packagename/でサイトが利用可能になる。

失敗時： サイトが404を返す場合、PagesのソースがデプロイメソッドにマッチしていることRを確認する（ブランチデプロイには「Deploy from a branch」が必要）。_pkgdown.ymlにdevelopment: mode: releaseが設定されているか確認する。

ステップ7: DESCRIPTIONへのURLの追加

URL: https://username.github.io/packagename/, https://github.com/username/packagename

期待結果： DESCRIPTIONのURLフィールドにpkgdownサイトURLとGitHubリポジトリURLの両方がカンマで区切られて含まれる。

失敗時： R CMD checkが無効なURLを警告する場合、URLを追加する前にpkgdownサイトが実際にデプロイされてアクセス可能であることを確認する。

バリデーション

• サイトがエラーなくローカルでビルドされる
• すべての関数リファレンスページが正しくレンダリングされる
• 記事/ビネットがアクセス可能で正しくレンダリングされる
• 検索機能が動作する
• ナビゲーションリンクが正しい
• サイトがGitHub Pagesに正常にデプロイされる
• デプロイ済みサイトに404エラーがない
• _pkgdown.ymlにdevelopment: mode: releaseが設定されている

よくある落とし穴

• デプロイ後の404エラー: ほぼ常にdevelopment: mode: auto（デフォルト）が原因。mode: releaseに変更する

• リファレンスページの欠如: 関数はエクスポートされてドキュメント化されていなければならない。最初にdevtools::document()を実行する

• 壊れたビネットリンク: 相互参照にはファイルパスではなくvignette("name")構文を使用する

• ロゴが表示されない: ロゴをman/figures/logo.pngに配置して_pkgdown.ymlで参照する

• 検索が機能しない: _pkgdown.ymlのurlフィールドが正しく設定されていることが必要

• ハイブリッドシステムでの誤った R バイナリ：WSL や Docker では、Rscript がネイティブ R の代わりにクロスプラットフォームラッパーに解決される場合があります。which Rscript && Rscript --version で確認してください。信頼性のために、ネイティブ R バイナリ（例：Linux/WSL では /usr/local/bin/Rscript）を優先してください。R パス設定については Setting Up Your Environment を参照してください。

関連スキル

• setup-github-actions-ci - 自動pkgdownデプロイワークフロー
• write-roxygen-docs - サイトに表示される関数ドキュメント
• write-vignette - サイトナビゲーションに表示される記事
• release-package-version - リリース時にサイトの再ビルドをトリガーする