MultiVersion pkgdown docs action

Github Action to generate multiple versions of pkgdown docs for R packages.

This Github Actions works under the following assumptions:

• R package documentation is generated by the R function pkgdown::build_site
• Documentation is published to the gh-pages branch of the package repository and Github Pages is enabled at the root level of the branch
• The version of pkgdown used to generate the documentation is >= v2.0.0
• The pkgdown documentation uses Bootstrap 5
• The URL field in the package DESCRIPTION file contains a reference to the pkgdown site URL (see step 1 here)

An example of the output of the action can be seen below:

Action type

Composite

Inputs

• path:

  Description: Path to package's root

  Required: false

  Default: .

• default-landing-page:

  Description: The default branch or tag on gh-pages that corresponds to the landing page. For instance, if your root index page on gh-pages is built using the 'main' branch, then the root page of the website will correspond to this page. If 'latest-tag' is selected, then the latest version will become the default.

  Required: false

  Default: main

• branches-or-tags-to-list:

  Description: Which branches or tags should be listed under the 'Versions' dropdown menu on the landing page? This input should be a regular expression in R.

  Required: false

  Default: ^main$|^devel$|^pre-release$|^latest-tag$|^develop$|^v([0-9]+\\.)?([0-9]+\\.)?([0-9]+)$

• insert-after-section:

  Description: After which section in the navbar should the 'Versions' dropdown be added? Choose between 'Reference' and 'Changelog' for the surest of choices.

  Required: false

  Default: Changelog

• version-tab:

  Description: Configuration of how the drop-down list should appear for multiple versions. It should be set as an ASCII text representation of an R list object. Example:

    list(config = list(
      tooltip = list(
        main = "Tooltip for main branch"
      ),
      text = list(
        main = "main branch"
      )
    ))

  String should be quoted with " sign

  Required: false

  Default: ``

• refs-order:

  Description: The order in which refs should appear in the drop-down list. Versions not in the vector will appear below refs listed here.

  If docs have never been generated for the ref, the ref will not appear in the drop-down. Similarly, if docs have been generated for the ref, but the ref is not listed in the vector, it will not appear in the drop-down.

  Example: c("main", "devel", "pre-release", "latest-tag")

  Required: false

  Default: c("main", "devel", "pre-release", "latest-tag")

• latest-tag-alt-name:

  Description: An alternate name for the 'latest-tag' item

  Required: false

  Default: ''

Outputs

None.

Usage

Please refer to this example workflow to see how this action is used in an end-to-end documentation publishing workflow.