From 40879d516d1ccd191033261b091f828a90eb33e5 Mon Sep 17 00:00:00 2001 From: VisruthSK Date: Sat, 26 Sep 2026 16:55:53 -0700 Subject: [PATCH 1/5] Updated Setup vignette and GHA --- .github/dependabot.yml | 6 +++ .github/workflows/pkgdown.yaml | 4 +- vignettes/Setup.qmd | 86 +++++++--------------------------- 3 files changed, 24 insertions(+), 72 deletions(-) create mode 100644 .github/dependabot.yml diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..ca79ca5 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,6 @@ +version: 2 +updates: + - package-ecosystem: github-actions + directory: / + schedule: + interval: weekly diff --git a/.github/workflows/pkgdown.yaml b/.github/workflows/pkgdown.yaml index 8818468..843058a 100644 --- a/.github/workflows/pkgdown.yaml +++ b/.github/workflows/pkgdown.yaml @@ -24,7 +24,7 @@ jobs: permissions: contents: write steps: - - uses: actions/checkout@v6 + - uses: actions/checkout@v7 - uses: r-lib/actions/setup-pandoc@v2 @@ -46,7 +46,7 @@ jobs: - name: Deploy to GitHub pages 🚀 if: github.event_name != 'pull_request' - uses: JamesIves/github-pages-deploy-action@v4.5.0 + uses: JamesIves/github-pages-deploy-action@v4 with: branch: gh-pages folder: docs diff --git a/vignettes/Setup.qmd b/vignettes/Setup.qmd index ad2d9c5..58a6c78 100644 --- a/vignettes/Setup.qmd +++ b/vignettes/Setup.qmd @@ -18,14 +18,14 @@ If you haven't started a `pkgdown` site yet, initialize it. usethis::use_pkgdown() ``` -In `./_pkgdown.yml` add the contributed package: +In `_pkgdown.yml` add the template package: ```yaml template: package: pkgdownconfig ``` -Optional but highly recommended is to set development mode to auto and to build the site in root, like so: +Optional but highly recommended is to set [development mode](https://pkgdown.r-lib.org/reference/build_site.html#setting-development-mode) to auto and to build the site in root, in the `gh-pages` branch. This will build a dev version of the site at `/dev` (see [`loo`](https://mc-stan.org/loo/dev/) 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). ```yaml destination: "." @@ -40,11 +40,10 @@ Point to this repository in `DESCRIPTION` to download the theme automatically. Config/Needs/website: stan-dev/pkgdown-config ``` -Optionally, you should be able to pin a specific version of the template with a tag or commit: +Optionally, you can pin a specific version of the template with a tag or commit, but this isn't reocmmended. ```yaml Config/Needs/website: stan-dev/pkgdown-config@v1.0.1 - Config/Needs/website: stan-dev/pkgdown-config@COMMITHASH ``` @@ -55,7 +54,7 @@ pak::pak("stan-dev/pkgdown-config") pkgdown::build_site() ``` -If you're getting an error about dependency resolution when using a GitHub Action to automatically build your pkgdown site, remove the `Config/Needs/website:` line from DESCRIPTION and add use the R dependencies step like [here]("https://mc-stan.org/pkgdown-config/articles/GitHub Action"): +If you're getting an error about dependency resolution when using a GitHub Action to automatically build your pkgdown site, remove the `Config/Needs/website:` line from DESCRIPTION and add the pacakge to this GHA step: ```yaml - uses: r-lib/actions/setup-r-dependencies@v2 @@ -63,43 +62,12 @@ If you're getting an error about dependency resolution when using a GitHub Actio extra-packages: any::pkgdown, local::., stan-dev/pkgdown-config ``` -By default, the theme has a navbar item which has other Stan R packages--this is not smart and won't automatically drop the package you're using the theme in. If you don't want this, you should override that list in `_pkgdown.yml`. This example is taken from `loo`'s setup +## Example -```yaml -navbar: - title: "loo" - - structure: - left: [home, vignettes, functions, news, pkgs, stan] - right: [search, bluesky, forum, github, lightswitch] - - components: - pkgs: - text: Other Packages - menu: - - text: bayesplot - href: https://mc-stan.org/bayesplot - - text: cmdstanr - href: https://mc-stan.org/cmdstanr - - text: posterior - href: https://mc-stan.org/posterior - - text: projpred - href: https://mc-stan.org/projpred - - text: rstan - href: https://mc-stan.org/rstan - - text: rstanarm - href: https://mc-stan.org/rstanarm - - text: rstantools - href: https://mc-stan.org/rstantools - - text: shinystan - href: https://mc-stan.org/shinystan -``` -## Example (`shinystan`) - -Put together, here's what a reasonable YAML looks like (truncated, taken from `shinystan`): +Put together, here's what a typical YAML might look like: ```yaml -url: https://mc-stan.org/shinystan +url: https://mc-stan.org/PKGNAME destination: "." @@ -109,44 +77,22 @@ development: template: package: pkgdownconfig -navbar: - title: "shinystan" - - structure: - left: [home, vignettes, functions, news, pkgs, stan] - right: [search, bluesky, forum, github, lightswitch] - - components: - pkgs: - text: Other Packages - menu: - - text: bayesplot - href: https://mc-stan.org/bayesplot - - text: cmdstanr - href: https://mc-stan.org/cmdstanr - - text: "loo" - href: https://mc-stan.org/loo - - text: posterior - href: https://mc-stan.org/posterior - - text: projpred - href: https://mc-stan.org/projpred - - text: rstan - href: https://mc-stan.org/rstan - - text: rstanarm - href: https://mc-stan.org/rstanarm - - text: rstantools - href: https://mc-stan.org/rstantools - -# now you can add articles, references, etc. +articles: + - title: "Article 1" + ... + +reference: + - title: "Function Group 1" + ... ``` ## Common Issues -If for some reason the 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](https://github.com/stan-dev/logos/blob/master/logo.svg) to `/man/figures/logo.svg` and run `pkgdown::build_favicons()` once to build the favicons. +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](https://github.com/stan-dev/logos/blob/master/logo.svg) to `/man/figures/logo.svg` and run `pkgdown::build_favicons()` once to build the favicons. -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): +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): ```md # pkgdownConfig pkgdownConfig website From d05c0b5729d9c347c685f0b7d8ef2ad69e029404 Mon Sep 17 00:00:00 2001 From: VisruthSK Date: Sat, 26 Sep 2026 17:14:36 -0700 Subject: [PATCH 2/5] PR previews --- .github/workflows/pkgdown.yaml | 28 +++++++++++++++++++++++----- 1 file changed, 23 insertions(+), 5 deletions(-) diff --git a/.github/workflows/pkgdown.yaml b/.github/workflows/pkgdown.yaml index 843058a..e45833e 100644 --- a/.github/workflows/pkgdown.yaml +++ b/.github/workflows/pkgdown.yaml @@ -39,15 +39,33 @@ jobs: needs: website - name: Build site - run: >- - pkgdown::build_site_github_pages(clean = FALSE, new_process = TRUE, - install = FALSE) + id: pkgdown + run: | + pkgdown::build_site_github_pages(clean = FALSE, new_process = TRUE, install = FALSE) shell: Rscript {0} - - name: Deploy to GitHub pages 🚀 + - name: Get pkgdown destination + id: pkgdown-dest + run: | + echo "folder=$(Rscript -e 'cat(fs::path_rel(pkgdown::as_pkgdown(".")$dst_path))')" >> "$GITHUB_OUTPUT" + + - name: Deploy PR preview + if: > + github.event_name == 'pull_request' && + github.event.pull_request.head.repo.full_name == github.repository + uses: JamesIves/github-pages-deploy-action@v4 + with: + branch: gh-pages + folder: ${{ steps.pkgdown-dest.outputs.folder }} + target-folder: prs/${{ github.event.pull_request.number }} + clean: true + force: false + + - name: Deploy site if: github.event_name != 'pull_request' uses: JamesIves/github-pages-deploy-action@v4 with: branch: gh-pages folder: docs - clean: true + clean: false + force: false From 05355a147abada9e952286dfb328088d4fa47d70 Mon Sep 17 00:00:00 2001 From: VisruthSK Date: Sat, 26 Sep 2026 18:09:27 -0700 Subject: [PATCH 3/5] Updated setup vignette --- vignettes/Quirks.qmd | 4 ++-- vignettes/Setup.qmd | 10 +++++++++- 2 files changed, 11 insertions(+), 3 deletions(-) diff --git a/vignettes/Quirks.qmd b/vignettes/Quirks.qmd index d5b7391..a7b4eb1 100644 --- a/vignettes/Quirks.qmd +++ b/vignettes/Quirks.qmd @@ -28,11 +28,11 @@ template: My_cool_html ``` -I left the functionality in so that the website wouldn't fail silently and eat your input, but I hazard that you won't want to put anything before the logo. If you want to put things in `before_title` you should copy my `navbar.HTML` into your package's pkgdown configuration and edit it, putting HTML where it says `{{#includes}}{{{before_navbar}}}{{/includes}}`. +I left the functionality in so that the website wouldn't fail silently and eat your input, but I hazard that you won't want to put anything before the logo. If you want to put things in `before_title` you should copy my `navbar.HTML` into your package's `pkgdown` configuration and edit it, putting HTML where it says `{{#includes}}{{{before_navbar}}}{{/includes}}`. ## Logs Say Favicons Missing -Due to how pkgdown and this template package work, pkgdown will complain about missing favicons initially, but will copy them over soon after. They will appear in the built site properly, so you can safely ignore this error. Unfortunately, I don't see any clean way of suppressing this error. +Due to how `pkgdown` and this template package work, `pkgdown` will complain about missing favicons initially, but will copy them over soon after. They will appear in the built site properly, so you can safely ignore this error. Unfortunately, I don't see any clean way of suppressing this error. ``` ── Sitrep ────────────────────────────────────────────────────────────────────── diff --git a/vignettes/Setup.qmd b/vignettes/Setup.qmd index 58a6c78..bef2b17 100644 --- a/vignettes/Setup.qmd +++ b/vignettes/Setup.qmd @@ -54,7 +54,7 @@ pak::pak("stan-dev/pkgdown-config") pkgdown::build_site() ``` -If you're getting an error about dependency resolution when using a GitHub Action to automatically build your pkgdown site, remove the `Config/Needs/website:` line from DESCRIPTION and add the pacakge to this GHA step: +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: ```yaml - uses: r-lib/actions/setup-r-dependencies@v2 @@ -86,6 +86,14 @@ reference: ... ``` +## GHA + +You can use the default GHA, or you can copy [this package's GHA](https://github.com/stan-dev/pkgdown-config/blob/main/.github/workflows/pkgdown.yaml). This GHA deploys `pkgdown` sites on (non-fork[^1]) 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](https://docs.github.com/en/actions/how-tos/write-workflows/choose-when-workflows-run/trigger-a-workflow#using-filters-to-target-specific-paths-for-pull-request-or-push-events), or only have the `workflow_dispatch` trigger so that you can build PR's `pkgdown` sites as needed. + +[^1]:PRs from forks typically get a read-only `GITHUB_TOKEN` for security, so they wouldn't be able to deploy the site. + ## 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](https://github.com/stan-dev/logos/blob/master/logo.svg) to `/man/figures/logo.svg` and run `pkgdown::build_favicons()` once to build the favicons. From 4277549f44ca66e2da93e63f5c5da6542428b652 Mon Sep 17 00:00:00 2001 From: VisruthSK Date: Mon, 28 Sep 2026 15:19:53 -0700 Subject: [PATCH 4/5] Run automatically on labelled PRs only --- .github/workflows/pkgdown.yaml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/.github/workflows/pkgdown.yaml b/.github/workflows/pkgdown.yaml index e45833e..faa55c6 100644 --- a/.github/workflows/pkgdown.yaml +++ b/.github/workflows/pkgdown.yaml @@ -4,6 +4,7 @@ on: push: branches: [main, master] pull_request: + types: [opened, reopened, synchronize, labeled] release: types: [published] workflow_dispatch: @@ -14,6 +15,10 @@ permissions: read-all jobs: pkgdown: + # For PRs, only run when the PR has the build-website label. + if: >- + github.event_name != 'pull_request' || + contains(github.event.pull_request.labels.*.name, 'build-website') runs-on: ubuntu-latest # Only restrict concurrency for non-PR jobs concurrency: From 714839d3aa084f8b5b4b2ce8597409a4aa504eac Mon Sep 17 00:00:00 2001 From: VisruthSK Date: Mon, 28 Sep 2026 15:33:29 -0700 Subject: [PATCH 5/5] Small fixes --- .github/workflows/pkgdown.yaml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.github/workflows/pkgdown.yaml b/.github/workflows/pkgdown.yaml index faa55c6..b4939e0 100644 --- a/.github/workflows/pkgdown.yaml +++ b/.github/workflows/pkgdown.yaml @@ -55,6 +55,7 @@ jobs: echo "folder=$(Rscript -e 'cat(fs::path_rel(pkgdown::as_pkgdown(".")$dst_path))')" >> "$GITHUB_OUTPUT" - name: Deploy PR preview + # Forks cannot deploy the site if: > github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository @@ -62,7 +63,7 @@ jobs: with: branch: gh-pages folder: ${{ steps.pkgdown-dest.outputs.folder }} - target-folder: prs/${{ github.event.pull_request.number }} + target-folder: pr/${{ github.event.pull_request.number }} clean: true force: false