Gallery of articles, examples, etc.

[gadenbuie]

Overview

This issue is to lay out my thoughts about a gallery feature for pkgdown sites. The goal is to facilitate making pages similar to the existing learnr and flexdashboard examples pages.

The gallery I envision would require BS5 and would use Bootstrap's cards component. If a link is provided, the card image and title would be a clickable link.

Data Structure

At its core, the gallery would be created with a YAML list:

- title: "Setting Up R"
  image: images/tutorial-ex-setup-r.png
  link: https://learnr-examples.shinyapps.io/ex-setup-r/
  footer: >
    [Source](https://github.com/rstudio/learnr/tree/main/inst/tutorials/ex-setup-r/ex-setup-r.Rmd)
  description: >
    A tutorial featuring videos and interactive questions to guide a new **R** user
    through the installation and set up of everything they'll need to get
    started with **R**.

API

The primary question I'm facing is how a user would instantiate a gallery. Here are a few options I've thought of, but I'd love to hear your thoughts on the user-facing API.

With an R function

One option would be to call a function exported by pkgdown, that would read the data from this file (or optionally would accept an R list):

```{r gallery, echo=FALSE}
pkgdown::gallery("examples.yml")
```

The advantage is that this function is portable and its usage is straightforward, but I have two hesitations:

1. The function needs to ensure that BS5 is in use, so we'd have to either find the root DESCRIPTION file or ask that users include that as an argument. If the gallery were powered by functions called by build_article(), we could handle this internally.

2. Furthermore, pkgdown functions don't tend to make appearances in source code. All other exported functions are intended to be called interactively, but this one would start to appear in source code.

In the YAML front matter

Another option would be to put the gallery items in the YAML front matter as a named list of galleries and then insert the gallery with basic HTML or a special string (here are some brain-storming options)

---
gallery:
  examples:
    - title: "Setting Up R"
      image: images/tutorial-ex-setup-r.png
      link: https://learnr-examples.shinyapps.io/ex-setup-r/
---

<div class="gallery" id="examples"></div>

[]{.gallery #examples}

<!--gallery: examples -->

<gallery id="examples">

This above YAML structure for example might not be sufficient, we might have to have a very nested yaml list if we allow the gallery to have some options like number of columns or matching height rows.

Some advantages of this method are that we know everything we need to know at build time.

In a gallery chunk

Another option I've considered would be to introduce a gallery knitr engine that takes YAML and inserts the HTML as needed. We'd install the knitr engine in the pkgdown article format that could even implement different versions for BS5 and BS3 (if we want). We could use chunk options to set options specifically for individual galleries.

```{gallery ncol=3}
- title: "Setting Up R"
  image: images/tutorial-ex-setup-r.png
  link: https://learnr-examples.shinyapps.io/ex-setup-r/

- title: "Filtering Observations"
  image: images/tutorial-ex-data-filter.png
  link: https://learnr-examples.shinyapps.io/ex-data-filter/
```

[hadley]

What if the yaml lived _pkgdown.yml and generated some top-level "gallery" item in the navbar?

[gadenbuie]

What if the yaml lived _pkgdown.yml and generated some top-level "gallery" item in the navbar?

I like this idea if the desired feature is a single "Gallery" page. While I think having one page would be a reasonable compromise for most users of pkgdown, I was envisioning a solution that allows a little more flexibility.

In the learnr docs, for example, a small gallery appears on the home page with a more complete gallery in the Examples page. Personally I feel that it'd be better to break up learnr's examples page into two categories — complete example tutorials and tutorials that demonstrate learnr features — and I imagine that letting authors add some structure and text to galleries would improve overall documentation quality. For instance, I like that the Shiny Gallery divides the gallery into sections by industry in addition to example type.

Another option that has started to grow on me is that maybe we should leave this feature for a third-party package, like bs4cards. This approach would pair nicely with #1896, which gives article authors a bit more room for custom layouts in the article format.

[hadley]

Yeah, relying on a external package might be cleaner; then it would make sense to take as a strong dependency and you can just call the functions in your article etc.

Still might be nice to opt-in to an article or tutorial index that was a gallery inside of a list of articles. But that could just be a boolean flag in the _pkgdown.yml (assuming you set the desired images with the opengraph metadata).

[gadenbuie]

I still think this is valuable, and I think we could align (in some ways) with Quarto's custom listings feature for websites.

A quick sketch:

1. This feature would be built into pkgdown and would require Bootstrap 5.

2. The listing template would be a pandoc template (or partial?) that creates Bootstrap cards for a listing.

3. Authors would use the listing key in the YAML front-matter of the document where they want to include the listing (aka gallery). listing could take a listing item directly or an array of listing items (inspiration from Quarto docs).

   ---
   listing:
     id: examples
     contents:
       - title: "Setting Up R"
         image: images/tutorial-ex-setup-r.png
         link: https://learnr-examples.shinyapps.io/ex-setup-r/
   ---

   or

   ---
   listing:
     - id: examples
       contents:
         - title: "Setting Up R"
           image: images/tutorial-ex-setup-r.png
           link: https://learnr-examples.shinyapps.io/ex-setup-r/
   ---

   Quarto supports other properties that we wouldn't need to include, but we may want to include a template key in the listing item (sibling of id and contents) to allow users to customize the template for each listing.

   The template drives which properties are allowed in each content item.

4. The listing is placed in the document by id, e.g. <div id="examples"> or any markdown equivalent.

The workflow for pkgdown that I'm envisioning is to render the article, then render each listing as an HTML fragment using the listing template, and finally to use xml2 to splice the listing into the article HTML.

[hadley]

@gadenbuie what if instead of using YAML we used an R data structure? And instead of using a special quarto template, we just provided some code that you could call to generate the cards in an article? Something like this:

cards <- list(
  list(
    title = "Setting Up R",
    image = "images/tutorial-ex-setup-r.png",
    link = "https://learnr-examples.shinyapps.io/ex-setup-r/"
  )
)

pkgdown::render_gallery(cards)

Then you'd just use regular articles and customise their placement in the navbar. (And we could maybe make that a bit simpler by providing article: and reference: alternatives to text + href?)

(I also like the idea of automating this a bit for the articles index, so there would be some option like format: gallery and then it would automatically extract the title, image, and link from the article metadata.)

[gadenbuie]

• what if instead of using YAML we used an R data structure? And ... we just provided some code that you could call to generate the cards in an article?

I like it and it does sound considerably less complicated. For online-only articles, this is certainly uncomplicated.

For vignettes, would authors be able to hide the pkgdown::render_gallery() call from CRAN? The docs could include the boilerplate chunk option to only run the code when IN_PKGDOWN is set, but would the presence of pkgdown::render_gallery() cause issues?

[hadley]

@gadenbuie I think if you wanted to include it in a vignette you'd need to add pkgdown to suggests. That's not ideal as pkgdown is a rather heavy dep, but it's not the end of the world.

[hadley]

Some initial exploration at rstudio/learnr#815

[hadley]

Given that the R code is now quite simple (and maybe we could make it even simpler by including a helper in bslib?) I'm inclined to move back towards a simpler yaml based approach, allowing a site to add an optional gallery field to _pkgdown.yml. The structure would be a fusion of the existing learnr/flexdashboard yaml with the articles/references section structure so that you'd write something like this:

gallery:
- title: Complete Tutorials
  desc: >
    These tutorials were designed to showcase the features of the learnr 
    package --- and to teach learners how to use R! Try working through these 
    tutorials to get a sense of the look and feel of a learnr tutorial.
    Then check out the source code to see how these tutorials were made!

  contents:
  - title: Setting Up R
    image: images/tutorial-ex-setup-r.png
    link: https://learnr-examples.shinyapps.io/ex-setup-r/
    alt: Screenshot of a shiny app
    footer: [Source](https://github.com/rstudio/learnr/tree/main/inst/tutorials/ex-setup-r/ex-setup-r.Rmd)
    text: >
      A tutorial featuring videos and interactive questions to guide a new R user
      through the installation and set up of everything they'll need to get
      started with R.

To think about:

• Where would the images live?
• Do we want to give the user the ability to customise the title, or would it always be "Gallery"?

[hadley]

This doesn't feel quite solid enough in my mind yet, so I'm going to push to the next release.