Interactive Guide to GitHub & pkgdown

A Data Scientist's Interactive Guide

An interactive, step-by-step guide to pushing your R package to GitHub and publishing a `pkgdown` site with GitHub Pages. Choose your preferred method for each step.

1. Push Your R Package to GitHub

This first major step involves getting your local R package code into a remote repository on GitHub. You can use the R-native `usethis` package for a streamlined workflow, or standard `git` commands if you're more comfortable in the terminal. Select your preferred method below to see the corresponding instructions.

Step 1.1: Install Helper Packages

First, ensure you have `usethis`, `gitcreds`, and `pkgdown` installed. Run this once in your R console.

# Run this once
install.packages(c("usethis", "gitcreds", "pkgdown"))

Step 1.2: Initialize Git & Set Up GitHub Token

Initialize a git repository if you haven't already, then create a Personal Access Token (PAT) on GitHub and store it locally.

# Initialize Git (if not already done)
usethis::use_git()

# Create and store a GitHub Personal Access Token (PAT)
usethis::create_github_token()  # Opens a browser window to create the token
gitcreds::gitcreds_set()         # Paste the token when prompted

Step 1.3: Create Repo on GitHub and Push

This single command will create the repo on GitHub, link your local project to it, and push your code.

usethis::use_github(protocol = "https", private = FALSE)

Step 1.1: Initialize Repository and Commit

In your terminal, navigate to your project's root folder. Initialize the repository, add all files, and make your first commit.

# Initialize the git repository and make the first commit
git init
git add .
git commit -m "Initial commit"
git branch -M main

Step 1.2: Link to GitHub and Push

First, create a new, empty repository on GitHub.com. Then, copy its URL and use it in the command below to link your local repo and push your code.

# Add the remote repository and push your code
git remote add origin https://github.com/USERNAME/your-repo-name.git
git push -u origin main

2. Publish a `pkgdown` Site to GitHub Pages

With your code on GitHub, the next step is to build and deploy your package documentation website using `pkgdown`. The "Simple" method involves building the site locally and pushing the output. The "Automatic" method uses GitHub Actions to build and deploy the site for you every time you push an update, which is the recommended approach for continuous integration.

Step 2.1: Set up `pkgdown`

These commands configure your project for `pkgdown` and tell GitHub Pages where to find your site files.

# Set up pkgdown and GitHub Pages
usethis::use_pkgdown()         # Creates a _pkgdown.yml config file
usethis::use_github_pages()    # Configures the repo to serve from /docs on main

Step 2.2: Build and Push the Site

First, run the R command to build the website into the `docs/` folder. Then, use git to commit and push this new folder.

# Build the site into the docs/ folder
pkgdown::build_site_github_pages(new_process = FALSE, install = TRUE)

# Commit and push the docs folder
git add docs
git commit -m "Build pkgdown site"
git push

Step 2.3: Configure GitHub Pages

On your GitHub repository, go to Settings → Pages. Under "Source", select Deploy from a branch. Choose the main branch and the /docs folder. Save your changes.

Step 2.1: Create the Workflow File

Create the directory structure and an empty YAML file for the GitHub Actions workflow.

# Create the .github/workflows directory
mkdir -p .github/workflows
# Add the workflow file to this directory
touch .github/workflows/pkgdown.yaml

Step 2.2: Add Workflow Content

Paste the following content into the .github/workflows/pkgdown.yaml file you just created.

name: pkgdown
on:
  push:
    branches: [ main, master ]
  release:
    types: [published]
  workflow_dispatch:
jobs:
  pkgdown:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v4
      - uses: r-lib/actions/setup-pandoc@v2
      - uses: r-lib/actions/setup-r@v2
        with:
          use-public-rspm: true
      - 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 = TRUE)
      - name: Deploy to GitHub Pages (gh-pages)
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs

Step 2.3: Commit and Push Workflow

Add the new workflow file to git, commit it, and push to GitHub to activate it.

git add .github/workflows/pkgdown.yaml
git commit -m "Add pkgdown deploy workflow"
git push

Step 2.4: Configure GitHub Pages

The first time the action runs, it will create a new gh-pages branch. Go to Settings → Pages on GitHub. Under "Source", select Deploy from a branch. Choose the gh-pages branch and the / (root) folder.

To keep your repository clean and your package build efficient, it's crucial to tell git and R which files to ignore. The `.gitignore` file prevents temporary files from being tracked, while `.Rbuildignore` ensures that development-only files aren't included in the final package bundle.

.gitignore

Add these lines to your .gitignore file to prevent tracking of user-specific files and session data.

.Rproj.user
.Rhistory
.RData
.Ruserdata

.Rbuildignore

Ensure your .Rbuildignore file contains these patterns to exclude website files and other artifacts from the package build.

^docs$
^README\.Rmd$
^LICENSE\.md$
^\.github$

Even with a smooth workflow, you might run into platform-specific issues. Here are a couple of common problems and their solutions.

If you encounter "Access is denied" or file-lock issues on Windows/OneDrive, move your project outside the OneDrive sync folder (e.g., to C:/Users/you/Documents/your-project).
If you see a "Quarto Unknown command -V" message during R CMD check, it is harmless. If it bothers you, you can run checks with the environment variable QUARTO_DISABLE=1 set.

Here is a quick recap of the entire process:

Use usethis::use_github() to quickly create and push your repository.
Use pkgdown to build your site. For the simplest setup, enable GitHub Pages to serve from the docs/ folder on your main branch.
For a more robust and automated workflow, add the provided GitHub Actions configuration to build and deploy your site automatically.
After a successful push and deployment, your site will be live at https://USERNAME.github.io/your-repo-name/.

This final section walks you through the process of taking *this* HTML file and making it a live, publicly accessible website using GitHub Pages. The steps are slightly different from the R package workflow but are just as straightforward.

Step 5.1: Create a New GitHub Repository

You'll need a place on GitHub to store your file. Go to github.com/new and log in. Give it a descriptive name (e.g., `interactive-guide`) and ensure it's **Public**. Do not initialize it with a `README` file.

Step 5.2: Upload the HTML File with Git

Open your terminal and navigate to the folder containing your HTML file. Run the following commands to upload it to your new repository.

# Initialize a new Git repository
git init

# Add your HTML file to be committed
git add interactive_github_guide.html

# Commit the file
git commit -m "Initial commit of interactive guide"

# Connect your local repo to the one on GitHub (replace USERNAME and REPO-NAME)
git remote add origin https://github.com/USERNAME/REPO-NAME.git

# Push the file to the main branch
git branch -M main
git push -u origin main

Step 5.3: Enable GitHub Pages

The last step is to turn on GitHub Pages to serve your file as a website. On your GitHub repository page, navigate to **Settings** and then **Pages** in the sidebar. Select **Deploy from a branch**, choose the **main** branch, and select the **`/ (root)`** folder. Click **Save**. Your site will be live in a few minutes at `https://USERNAME.github.io/REPO-NAME/`.