Open gadenbuie opened 2 years ago
What if the yaml lived _pkgdown.yml
and generated some top-level "gallery" item in the navbar?
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.
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).
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:
This feature would be built into pkgdown and would require Bootstrap 5.
The listing template would be a pandoc template (or partial?) that creates Bootstrap cards for a listing.
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.
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.
@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.)
- 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?
@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.
Some initial exploration at https://github.com/rstudio/learnr/pull/815
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:
This doesn't feel quite solid enough in my mind yet, so I'm going to push to the next release.
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:
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):
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
chunkAnother 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.