---

name: build-pkgdown-site locale: wenyan-ultra source_locale: en source_commit: 82c77053 fence_basis_commit: 82c77053 translator: "Julius Brussee homage — caveman" translation_date: "2026-04-19" description: > Build and deploy a pkgdown documentation site for an R package to GitHub Pages. Covers _pkgdown.yml configuration, theming, article organization, reference index customization, and deployment methods. Use when creating a documentation site for a new or existing package, customizing layout or navigation, fixing 404 errors on a deployed site, or migrating between branch-based and GitHub Actions deployment methods. 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 包造文站
• 客 pkgdown 布、題、導
• 修已發 pkgdown 站之 404 誤
• 移發法

入

• 必：含 roxygen2 文之 R 包
• 必：GitHub 庫
• 可：客題或品牌
• 可：涵為篇之 vignette

行

一：初 pkgdown

usethis::use_pkgdown()

此造 _pkgdown.yml 且加 pkgdown 至 .Rbuildignore。

得： _pkgdown.yml 存案根。.Rbuildignore 含 pkgdown 相條。

敗： 以 install.packages("pkgdown") 裝 pkgdown。若 _pkgdown.yml 已存→函更 .Rbuildignore 而不覆配。

二：配 _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 之 404，因附 /dev/ 於 URL。

得： _pkgdown.yml 含有效 YAML 附 url、template、navbar、reference、articles 段合包。

敗： 以網上 YAML 解器驗法。確 reference.contents 之諸函名合實導函。

三：本地構

pkgdown::build_site()

得： docs/ 目已造附全站含 index.html、函引頁、篇。

敗： 常題：pandoc 缺（於 .Renviron 設 RSTUDIO_PANDOC）、vignette 依缺（裝薦包）、例破（修或以 \dontrun{} 包）。

四：預覽站

pkgdown::preview_site()

驗導、函引、篇、搜正。

得： 站於 localhost 開於瀏。諸導連行、函引頁渲、搜返結。

敗： 預覽不開→手開 docs/index.html。頁缺→察 devtools::document() 構前已行。

五：發至 GitHub Pages

法 A：GitHub Actions（薦）

詳 setup-github-actions-ci 技之 pkgdown 流。

法 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。

六：配 GitHub Pages

1. 至庫 Settings > Pages
2. 設 Source 為「Deploy from a branch」
3. 擇 gh-pages 枝、/ (root) 目
4. 存

得： 站於數分內於 https://username.github.io/packagename/ 可達。

敗： 站返 404→驗 Pages 源合發法（枝發需「Deploy from a branch」）。察 _pkgdown.yml 設 development: mode: release。

七：加 URL 至 DESCRIPTION

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

得： DESCRIPTION URL 欄含 pkgdown 站 URL 與 GitHub 庫 URL，逗分。

敗： R CMD check 警 URL 無效→先驗 pkgdown 站實發且可達而後加 URL。

驗

• 站於本地無誤構
• 諸函引頁正渲
• 篇/vignette 可達且正渲
• 搜功行
• 導連正
• 站成發至 GitHub Pages
• 已發站無 404 誤
• _pkgdown.yml 設 development: mode: release

忌

• 發後 404 誤：幾皆因 development: mode: auto（默）。改 mode: release。
• 函引頁缺：函必導出且錄。先行 devtools::document()。
• vignette 連破：交引中用 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）以穩。詳 Setting Up Your Environment。

參

• setup-github-actions-ci — 自動 pkgdown 發流
• write-roxygen-docs — 現於站之函文
• write-vignette — 現於站導之篇
• release-package-version — 發時觸站重構