FR: Content selectors for websites

[kmasiello]

Documentation sites have frequent need to show different content based on user preference / input. Examples:

• Language selectors such as Quarto's main page "Hello, Quarto" section for choosing between Python, R, Julia, or Obserable
• Desired workflow, such as Command Line vs. API
• Documentation version (perhaps related to (Version selector for websites and html books #474)
• Role, region, or other characteristic

Quarto's support for selectively displaying content is currently limited to panel tabsets, which is not visually appropriate for modifying the content of an entire page.

A Quarto-native content selector would give users the ability to customize the page (or site) based on their preference or need.

(ref internal threads 1 and 2)

[cderv]

For reference purposes,

• Example from @chendaniely about a selector for language at the website level
  https://www.algorithm-archive.org/contents/split-operator_method/split-operator_method.html

• Another example at code cell level from @AshleyHenry15
  https://docs.stripe.com/receipts?payment-ui=direct-api&lang=ruby

  Example

  

• Mkdoc related feature from @aronatkins
  https://squidfunk.github.io/mkdocs-material/reference/content-tabs/#linked-content-tabs

[mcanouil]

For reference using tabset grouping:

---
title: "Quarto Playground"
format: html
---

## Step 1

{{< lipsum 1 >}}

::: {.panel-tabset group="language"}

## Python

```python
print("Hello, Python!")
```

## R

```r
print("Hello, R!")
```

## Bash

```bash
echo "Hello, Bash!"
```

:::

## Step 2

{{< lipsum 1 >}}

::: {.panel-tabset group="language"}

## Python

```python
print("Goodbye, Python!")
```

## R

```r
print("Goodbye, R!")
```

## Bash

```bash
echo "Goodbye, Bash!"
```

:::

[kmasiello]

Tabset grouping is definitely a plus here. It works well for situations where it might be useful to compare between the different options.

However, it can be visually disruptive to have tabset panels throughout a page to toggle content. The Stripe example from @AshleyHenry15 is a good one here: https://docs.stripe.com/receipts?payment-ui=payment-links
It would be frustrating to read this document if it was peppered with tabset panels.

Tabsets / tabset groups also don't fit the need well when the entire page contents might be different based on the selector, such as:

Screen.Recording.2024-03-27.at.12.51.55.PM.mov

It's an unexpected and awkward visual presentation to have the entire page, or majority of the page, within a tabset.

An ideal solution would have tabset group functionality that could be extended across multiple pages, and the visual element is a button/toggle rather than panels.

[cscheid]

However, it can be visually disruptive to have tabset panels throughout a page to toggle content.

I think I disagree - the tabset at least offers discoverability of the alternatives. In the stripe example, it is hard to know what part of the text would be distinct. It's very slick visually, but I honestly don't think it's readable formatting.

[cscheid]

An ideal solution would have tabset group functionality that could be extended across multiple pages

The problem here is that there's no clean solution that works with localStorage, since AFAIUI that feature is, by design, isolated to each unique URL.

[aronatkins]

Tabsets are really handy at showing that there are alternatives available. In technical writing, seeing that the code you're looking at is also available in three other languages is helpful. Unfortunately, code in each tabset isn't same-height, so you have lots of reflow problems if you use groups to toggle the whole page at once.

I almost want a way of selecting the "default" tab across a page (using tab group) but then want to be free to peek at other tabs for specific tabsets without changing the selection elsewhere.

Maybe the default is page-level, but I'm still able to toggle individual tabs in isolation.

[mcanouil]

I almost want a way of selecting the "default" tab across a page (using tab group) but then want to be free to peek at other tabs for specific tabsets without changing the selection elsewhere.

• Allow to set the active tab in .panel-tabset #7260

Tabsets are really handy at showing that there are alternatives available. In technical writing, seeing that the code you're looking at is also available in three other languages is helpful. Unfortunately, code in each tabset isn't same-height, so you have lots of reflow problems if you use groups to toggle the whole page at once.

::: {.panel-tabset group="language" style="height: 200px;"}

Isn't it what you want?

[cderv]

Another example at code cell level
docs.stripe.com/receipts?payment-ui=direct-api&lang=ruby

Just wanted to mention that when I referred to stripe example here, it was about the cell selector

[AshleyHenry15]

Apologies for the confusing brain dump -

I think that the tablets and the toggle selectors would both be valuable - but may not be completely 1:1 comparable to a cell selector/toggle.

The stripe example would be ideal for code/examples/distributions throughout a page so you don't have "rows" of tabs. It would also be good for pages that aren't written to be consumed fully/top-to-bottom (reference pages/configuration examples) - example of multiple rows of tabs: https://docs.posit.co/ide/server-pro/getting_started/installation/installation.html#download-and-install

We use the tabsets on this page: https://docs.posit.co/licensing/licensing-faq/#license-file-in-container
In this case, it is helpful, efficient, and visually appealing to have the tabs grouping/condense information and automatically display them throughout based on the selection.

For an entire page or large chunks of content, I don't think that the tabs are that helpful anymore (I would probably break the page into multiple pages) or have a toggle available that would change the entire page's contents based on the selection, almost like a version selector. At this point, you wouldn't need to know where the content starts/ends because the entire page/guide is specific to your selection.

I'd also argue that most users will only be interested in one language. It may be nice for them to know that we offer other options/examples; having a cell selector/toggle would be less distracting. Regardless, we are making a lot of assumptions here.

An ideal solution would have tab set group functionality that could be extended across multiple pages

I'm afraid I actually have to disagree with this. If we want a "project-level" option, I would say that it should be a drop-down/toggle in the nav bar that changes the entire project vs. having "linked pages" without the user understanding what is going on with the behavior.

I also want us to think about how we are maintaining the content/writing the content and how we can minimize duplication while still offering unique examples and procedures.

MadCap Flare has conditional formatting - we kind of offer this with quarto - but not quite (profiles isn't really the solution for this). If we had toggles and the ability to "tag" inline-content/words throughout the page by language, then we could have a ssot document that displays certain words/text/examples based on the toggle. This would minimize duplication, allow us to easily add language-specific / unique content to the page, etc.

https://www.madcapsoftware.com/blog/tips-and-tricks-applying-formatting-to-conditions-in-outputs/