---

name: build-pkgdown-site locale: wenyan 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 之錯
• 遷於諸交法間

入

• 必要：R 包附 roxygen2 之文
• 必要：GitHub 庫
• 可選：自訂主題或品牌
• 可選：含為文之 vignette

法

第一步：初 pkgdown

usethis::use_pkgdown()

此建 _pkgdown.yml 而加 pkgdown 於 .Rbuildignore。

得： _pkgdown.yml 存於項目根。.Rbuildignore 含 pkgdown 相關之條。

敗則： 以 install.packages("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 錯——其於 URL 附 /dev/。

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

敗則： 以線上 YAML linter 驗語。確 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

甲法：GitHub Actions（薦）

見 setup-github-actions-ci 技之 pkgdown 工作流。

乙法：手分支之交

# 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 站與 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") 之語，非檔路
• logo 不現：置 logo 於 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 為 R 路之設

參

• setup-github-actions-ci - 自動化 pkgdown 交之工作流
• write-roxygen-docs - 於站現之函文
• write-vignette - 現於站航之文
• release-package-version - 發版時觸站重建