Updating docs

.github/dependabot.yml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly

.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
 
@@ -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.5.0
+        uses: JamesIves/github-pages-deploy-action@v4
         with:
           branch: gh-pages
           folder: docs
-          clean: true
+          clean: false
+          force: false

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 ──────────────────────────────────────────────────────────────────────

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,51 +54,20 @@ 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 (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
         with:
           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,30 @@ 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"
+    ...
 ```
 
+## 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 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.
 
 <!-- Note that logo should also be copied into your build directory and will be hooked in automatically. If you can't find the logo, you can download it from [here](https://github.com/stan-dev/logos/blob/master/hex_stickers/stan_hex_cut.svg) and follow the same steps above. -->
 
-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 <a href="https://mc-stan.org/pkgdown-config"><img src="man/figures/logo.svg" align="right" height="139" alt="pkgdownConfig website" /></a>