Setting Up the Animint2 Website

Published

June 28, 2023

Modified

August 21, 2023

This webpage summarizes how I set the animint2 website up. Originally, I wrote this for the animint2 repository. But at some point, I realized that future animint2 contributors won’t care about how I set things up. They’ll just care about how to maintain the website. So I moved this here.

This summary is idealized and historically inaccurate. An accurate account would be much more chaotic and contain several swear words.

Get Ready

I first set my working directory to the animint2 repository. cd whatever/my/path/is/animint/animint2 gets me there. If I were using RStudio, I could instead use the CTRLSHIFTH keyboard shortcut and select the animint2 repository from there.

Making the README

I generated a README.md file using GitHub-flavored Markdown. The README should have, at minimum:

  • A section that briefly summarizes what the package is about,
  • A section that teaches the reader how to install both the CRAN and development versions of the package, and
  • A section that briefly demonstrates how to do basic things with the package or links to another page that does.

In my README, I included:

  • An About section with a GIF of someone using animint2,
  • An Installation section,
  • A Use section that linked to a quick start guide,
  • A Similar Packages section about other packages that created interactive data visualizations, and
  • A Problems? section asking users to report bugs if they find any.

There was already a README.org, but Toby asked me to create a new README and delete the old one.

GitHub Tokens

I needed to access GitHub’s API to set up the website. Instead of using my username and password, I had to use my username and a temporary PAT I generated. I guess it’s like a better but less convenient password. Luckily, it’s easy:

usethis::create_github_token()

This function opened a GitHub webpage. I logged in, generated the token, and saved that somewhere. I then ran

gitcreds::gitcreds_set()

and entered the token when asked.

Build the Site

pkgdown makes this easy. I configured the repository to use pkgdown:

usethis::use_pkgdown()

Then I built the whole site with this:

pkgdown::build_site()

This generated HTML files from our .Rd files, and it’s this line of code that I run when I need to re-render the website.

With another line of code, I created a _pkgdown.yml file, which influences how the site looks:

usethis::use_pkgdown_github_pages()

I haven’t used this since.

Organize the Site

By default, the home page is just a mirror image of what’s on the animint2 repository, and the references are in alphabetical order. Not great.

I rearranged the reference pages by adding a reference section to the _pkgdown.yml. Then I added all of animint2’s functions. This took a while due to the sheer number of functions. A couple of tricks that helped me:

  • I used data() to pull up all the datasets that animint2 has. (Thirty-three!) Then I copy/pasted the list into a Dataset section in _pkgdown.yaml.
  • I used ggplot2’s YAML file as a reference. animint2 is a fork of ggplot2, so there’s lots of similarities. However, I find parts of ggplot2’s reference website confusing, so I’ve elected to organize the functions a little bit differently.

I also made a typo early on. Whoops. Turns out whitespace is relevant in YAML.

Change Appearances

There are lots of ways to customize the website. I made typeface changes in the _pkgdown.yml file via template > bslib. Roboto Condensed and Roboto Mono look nice.

To make finer and subtler modifications, I created an extra.css file in pkgdown/ and edited the appearance of the site that way. I began with broad changes, like modifying the margins between headings and changing the link color. But I’ve also made subtler changes to the side bar and to the quick start guide.

Throw it Online

Using GitHub Pages, there are two ways to make this happen:

  1. Upload the docs/ directory to the GitHub repository.
  2. Get a GitHub Actions workflow going that re-generates the website every time you push a commit.

I don’t know how to do the second thing, so I did the first. pkgdown adds docs/ to .gitignore by default, so I edited the latter to remove the former. Then I pushed docs/ to my repository.

Maintain the Website

The panacea for website maintance is a two-step process:

  1. Run pkgdown::build_site(), then
  2. Push the changes to the animint2 repository.

But build_site() can take a while.1 For quicker and more precise changes, I usepkgdown’s other functions, like pkgdown::init_site().

  • 1 By which I mean minutes, not hours. If it’s taking hours, something is wrong!

    • See Also

    Some documentation that was helpful to me when generating the site: