pkgdown-website

# pkgdown Website Development This skill covers creating comprehensive, professional package documentation websites using pkgdown with Bootstrap 5 theming, GitHub Pages deployment, and automated CI/CD workflows. ## Rules 1. **Always use Bootstrap 5** with modern theming capabilities including dark mode 2. **URLs must match** across DESCRIPTION, _pkgdown.yml, and GitHub Pages settings 3. **Use GitHub Actions** for automated deployment (don't build locally and commit) 4. **Organize documentation** with clear reference sections and article groupings 5. **Enable dark mode** using light-switch theme for better user experience 6. **Include social links** in navbar for package promotion and author contact 7. **Math rendering** should use KaTeX for fast, client-side rendering 8. **Custom fonts** via Google Fonts improve branding and readability 9. **Development mode** should be set to auto for version-appropriate messaging 10. **Test locally** with `pkgdown::build_site()` before deploying ## Complete _pkgdown.yml Configuration ### Full Template with All Features ```yaml url: https://username.github.io/packagename/ template: bootstrap: 5 theme: arrow-light bslib: base_font: {google: "Atkinson Hyperlegible"} heading_font: {google: "Fraunces"} code_font: {google: "JetBrains Mono"} bg: "#ffffff" fg: "#1e1e1e" primary: "#0054AD" secondary: "#767676" light-switch: true math-rendering: katex development: mode: auto version_label: danger version_tooltip: "Development version" home: title: "packagename: An Amazing R Package" description: > A comprehensive toolkit for doing amazing things in R. This package provides intuitive functions and robust workflows. links: - text: Ask a question href: https://github.com/username/packagename/discussions - text: Report a bug href: https://github.com/username/packagename/issues authors: Your Name: href: https://yourwebsite.com Another Author: href: https://github.com/anotherusername navbar: structure: left: [home, intro, reference, articles, news] right: [search, github, linkedin, twitter] components: home: icon: fas fa-home fa-lg href: index.html aria-label: Home intro: text: Get started href: articles/packagename.html reference: text: Reference href: reference/index.html articles: text: Articles menu: - text: "Getting Started" href: articles/packagename.html - text: "Advanced Usage" href: articles/advanced-usage.html - text: "Examples" href: articles/examples.html - text: ------- - text: "All Articles" href: articles/index.html news: text: News href: news/index.html github: icon: fab fa-github fa-lg href: https://github.com/username/packagename aria-label: GitHub linkedin: icon: fab fa-linkedin fa-lg href: https://www.linkedin.com/in/yourprofile/ aria-label: LinkedIn twitter: icon: fab fa-twitter fa-lg href: https://twitter.com/yourhandle aria-label: Twitter reference: - title: "Data Import and Export" desc: > Functions for reading and writing data files in various formats. contents: - read_data - write_data - import_csv - export_excel - title: "Data Manipulation" desc: > Core functions for transforming and cleaning data. contents: - clean_data - transform_variables - filter_rows - select_columns - title: "Statistical Analysis" desc: > Functions for statistical modeling and hypothesis testing. contents: - fit_model - test_hypothesis - calculate_statistics - generate_report - title: "Visualization" desc: > Create publication-quality plots and charts. contents: - plot_distribution - create_scatter - visualize_trends - export_plot - title: "Utilities" desc: > Helper functions and package configuration. contents: - validate_input - check_dependencies - packagename_options - print.packagename_object - title: "Internal Functions" desc: > Internal functions not intended for direct use. contents: - has_keyword("internal") articles: - title: "Tutorials" navbar: Tutorials contents: - packagename - getting-started - basic-workflow - title: "Advanced Topics" navbar: Advanced contents: - advanced-usage - performance-optimization - extending-packagename - title: "Case Studies" navbar: ~ contents: - case-study-1 - case-study-2 - real-world-examples footer: structure: left: developed_by right: built_with components: developed_by: "Developed by [Your Name](https://yourwebsite.com)" built_with: "Built with [pkgdown](https://pkgdown.r-lib.org/) and [Bootstrap 5](https://getbootstrap.com/)" ``` ### Minimal _pkgdown.yml Template ```yaml url: https://username.github.io/packagename/ template: bootstrap: 5 light-switch: true development: mode: auto ``` ## DESCRIPTION File URL Configuration The URL field in DESCRIPTION must match _pkgdown.yml: ``` Package: packagename Title: An Amazing R Package Version: 0.1.0 URL: https://username.github.io/packagename/, https://github.com/username/packagename BugReports: https://github.com/username/packagename/issues ``` **Note**: Multiple URLs are comma-separated. Package website comes first, then GitHub repo. ## Initial Setup with usethis ### Complete Setup Process ```r # 1. Initialize pkgdown structure usethis::use_pkgdown() # 2. Configure for GitHub Pages (recommended) usethis::use_pkgdown_github_pages() # This function: # - Adds URL to DESCRIPTION # - Creates _pkgdown.yml # - Adds GitHub Actions workflow # - Configures .gitignore for docs/ # - Sets up gh-pages branch ``` ### Manual Setup (if needed) ```r # Create basic structure usethis::use_pkgdown() # Build site locally pkgdown::build_site() # Preview in browser pkgdown::preview_site() # Build specific components pkgdown::build_reference() pkgdown::build_articles() pkgdown::build_home() pkgdown::build_news() ``` ## GitHub Actions Workflow ### Complete pkgdown.yaml Workflow Create `.github/workflows/pkgdown.yaml`: ```yaml # Workflow derived from https://github.com/r-lib/actions/tree/v2/examples # Need help debugging build failures? Start at https://github.com/r-lib/actions#where-to-find-help on: push: branches: [main, master] pull_request: branches: [main, master] release: types: [published] workflow_dispatch: name: pkgdown # Only allow one deployment at a time concurrency: group: pkgdown-${{ github.event_name != 'pull_request' || github.run_id }} permissions: contents: write jobs: pkgdown: runs-on: ubuntu-latest # Only restrict concurrency for non-PR jobs env: GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }} steps: - name: Checkout repository uses: actions/checkout@v4 - name: Setup Pandoc uses: r-lib/actions/setup-pandoc@v2 - name: Setup R uses: r-lib/actions/setup-r@v2 with: use-public-rspm: true - name: Install dependencies uses: r-lib/actions/setup-r-dependencies@v2 with: extra-packages: any::pkgdown, local::. needs: website - name: Build site run: pkgdown::build_site_github_pages(new_process = FALSE, install = FALSE) shell: Rscript {0} - name: Deploy to GitHub Pages if: github.event_name != 'pull_request' uses: JamesIves/github-pages-deploy-action@v4 with: folder: docs branch: gh-pages clean: true ``` ### Alternative: Simple Deployment Workflow ```yaml on: push: branches: [main] name: pkgdown permissions: contents: write jobs: pkgdown: runs-on: ubuntu-latest env: GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }} steps: - uses: actions/checkout@v4 - uses: r-lib/actions/setup-pandoc@v2 - uses: r-lib/actions/setup-r@v2 - uses: r-lib/actions/setup-r-dependencies@v2 with: extra-packages: any::pkgdown, local::. needs: website - name: Build and deploy run: | pkgdown::deploy_to_branch(new_process = FALSE) shell: Rscript {0} ``` ## Bootstrap 5 Theming ### Built-in Themes pkgdown includes several Bootstrap 5 themes: - `arrow-light` / `arrow-dark` (Tidyverse theme) - Standard Bootstrap 5 themes ```yaml template: bootstrap: 5 theme: arrow-light # or arrow-dark ``` ### Custom Color Scheme with bslib ```yaml template: bootstrap: 5 bslib: # Base colors bg: "#ffffff" # Background fg: "#212529" # Foreground text primary: "#0054AD" # Primary brand color secondary: "#6c757d" # Secondary color success: "#198754" info: "#0dcaf0" warning: "#ffc107" danger: "#dc3545" # Typography base_font: {google: "Roboto"} heading_font: {google: "Roboto Slab"} code_font: {google: "Fira Code"} font_scale: 1.0 # Spacing spacer: 1rem ``` ### Google Fonts Options Popular font combinations: ```yaml # Professional bslib: base_font: {google: "Atkinson Hyperlegible"} heading_font: {google: "Fraunces"} code_font: {google: "JetBrains Mono"} # Modern bslib: base_font: {google: "Inter"} heading_font: {google: "Inter"} code_font: {google: "Fira Code"} # Classic bslib: base_font: {google: "Lato"} heading_font: {google: "Merriweather"} code_font: {google: "Source Code Pro"} # Friendly bslib: base_font: {google: "Nunito"} heading_font: {google: "Nunito"} code_font: {google: "Ubuntu Mono"} ``` ## Reference Organization ### Grouping Functions by Purpose ```yaml reference: - title: "Core Functions" desc: "Main user-facing functions" contents: - has_concept("core") - title: "Data Processing" contents: - starts_with("process_") - starts_with("transform_") - title: "Plotting Functions" contents: - matches("plot|visualize|graph") - title: "S3 Methods" contents: - matches("\\.") - title: "Datasets" desc: "Example datasets included with the package" contents: - has_keyword("datasets") ``` ### Using Roxygen Concepts In your function documentation: ```r #' @concept core #' @concept data-import ``` Then in _pkgdown.yml: ```yaml reference: - title: "Core Functions" contents: - has_concept("core") - title: "Data Import" contents: - has_concept("data-import") ``` ## Articles Configuration ### Organizing Vignettes ```yaml articles: - title: "Getting Started" navbar: "Get Started" desc: "New to the package? Start here!" contents: - introduction - installation - quick-start - title: "Workflows" navbar: "Workflows" contents: - basic-workflow - advanced-workflow - batch-processing - title: "Reference" navbar: ~ # Don't show in navbar contents: - technical-details - algorithm-description ``` ## Common Pitfalls ### 1. URL Mismatch **Problem**: Website deploys but links are broken **Solution**: Ensure URLs match exactly in three places: ```r # DESCRIPTION URL: https://username.github.io/packagename/ # _pkgdown.yml url: https://username.github.io/packagename/ # GitHub Settings > Pages Source: gh-pages branch, / (root) ``` **Note**: Trailing slash matters! Be consistent. ### 2. GitHub Pages Not Enabling **Problem**: Workflow runs but site doesn't appear **Solution**: 1. Check GitHub repo Settings > Pages 2. Source should be "Deploy from a branch" 3. Branch should be "gh-pages" and "/ (root)" 4. Wait 2-3 minutes after first deployment 5. Check `https://username.github.io/packagename/` ### 3. Missing Dependencies **Problem**: Build fails with "package not found" **Solution**: Add to DESCRIPTION: ``` Suggests: pkgdown, knitr, rmarkdown ``` ### 4. Math Not Rendering