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: 手動ブランチデプロイ

# サイトをビルド
Rscript -e "pkgdown::build_site()"

# gh-pagesブランチが存在しない場合は作成
git checkout --orphan gh-pages
git rm -rf .
cp -r docs/* .
git add .
git commit -m "Deploy pkgdown site"
git push origin gh-pages

# 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 - リリース時にサイトの再ビルドをトリガーする