Skip to contents

Setup

Source: vignettes/Setup.qmd

General Setup

If you haven’t started a pkgdown site yet, initialize it.

usethis::use_pkgdown()

In _pkgdown.yml add the template package:

template:
  package: pkgdownconfig

Optional but highly recommended is to set development mode to auto. This will build a dev version of the site at /dev (see loo for example). Whether pkgdown treats a build as a development or release site is controlled by the version in DESCRIPTION (see pkgdown docs linked above).

development:
  mode: auto

Point to this repository in DESCRIPTION to download the theme automatically.

Config/Needs/website: stan-dev/pkgdown-config

Optionally, you can pin a specific version of the template with a tag or commit, but this isn’t reocmmended.

Config/Needs/website: stan-dev/pkgdown-config@v1.0.1
Config/Needs/website: stan-dev/pkgdown-config@COMMITHASH

For local development, you need to install the package before you can build the site:

pak::pak("stan-dev/pkgdown-config")
pkgdown::build_site()

If you’re getting an error about dependency resolution when using a GitHub Action (GHA) to automatically build your pkgdown site, remove the Config/Needs/website: line from DESCRIPTION and add the pacakge to this GHA step:

      - uses: r-lib/actions/setup-r-dependencies@v2
        with:
          extra-packages: any::pkgdown, local::., stan-dev/pkgdown-config

Example

Put together, here’s what a typical YAML might look like:

url: https://mc-stan.org/PKGNAME

destination: "."

development:
  mode: auto

template:
  package: pkgdownconfig

articles:
  - title: "Article 1"
    ...

reference:
  - title: "Function Group 1"
    ...

Roadmap

Opt in to a roadmap page built from your open GitHub milestones and issues (PRs, closed milestones and issues labelled internal*, wontfix or invalid are skipped; closed issues go last).

roadmap:
  enabled: true

Customize with roadmap.overrides.milestones / roadmap.overrides.issues (keyed by milestone/issue number; both take title and description, issues also take order, and milestones can add your own cards, each with a title, description, optional url and optional order). Cards are ordered by issue number with closed issues last, unless you set order; custom cards come last unless they set it and roadmap.exclude.labels / roadmap.exclude.issues. See the defaults in this package’s config. The introduction (roadmap.intro) and the closing section (roadmap.outro) are Markdown with {package} and {repo} placeholders, and you can replace them. The timeline is generated from the latest GitHub release and the open milestones, and milestones are listed next release first, ordered by version (milestones whose title is not a version come last).

The GHA generates the roadmap article (vignettes/articles/roadmap.Rmd, or roadmap.qmd with format: qmd) and adds the navbar link for you. The article is rewritten on every build, so add it to .gitignore. For local builds use pkgdownconfig::build_site() in place of pkgdown::build_site(); it does the same and forwards all arguments. Plain pkgdown::build_site() does not add the navbar link or hide the article, so with the roadmap enabled it fails on sites that define their own articles sections. The roadmap is fetched from the GitHub API at build time. The GHA uses its own token; for local builds set a GITHUB_PAT, otherwise GitHub’s unauthenticated limit of 60 requests per hour applies and the build can fail.

GHA

You can use the default GHA, or you can run pkgdownconfig::use_pkgdown_gha() to copy this package’s GHA. This GHA deploys pkgdown sites on (non-fork1) PRs to unique URLs (/prs/$PR-NUMBER). This means that PRs would have preview sites, /dev would track main, and the main site would track releases.

You could also configure the pkgdown GHA to only run when vignettes are modified, or only have the workflow_dispatch trigger so that you can build PR’s pkgdown sites as needed.

Common Issues

If for some reason the new favicons don’t get copied over, check if you are defining favicons in pkgdown/favicons. In most cases you can delete everything in that folder–just delete the logo and favicons if you are worried. The template will hook in the correct favicon and logo. If its not working, download logo.svg to /man/figures/logo.svg and run pkgdown::build_favicons() once to build the favicons. The navbar logo falls back to the Stan logo shipped with the template, so a package without man/figures/logo.svg still builds; a logo in your package takes precedence.

If you want the hex in your README (or if it isn’t working), make sure to edit the README.md or however you generate it. You can take a look at this package’s to get an idea of what you need to do (repeated below):

# pkgdownConfig <a href="https://mc-stan.org/pkgdown-config"><img src="man/figures/logo.svg" align="right" height="139" alt="pkgdownConfig website" /></a>

For any further concerns/help/anything, open an issue and/or ping @Visruth on the Stan Slack.