docs: dark brand

[gordonwoodhull]

Hi @cwickham, here is the first of my doc PRs for Quarto 1.7, covering Dark Brand.

I'll follow up with more commits covering the changes for Typst, and a separate PR for renderings.

(I will also need to check that my schema changes have made it into the reference documentation, hmm.)

Please let me know what you think - glad to edit, move content, etc.

Thanks!

[github-actions]

🚀 Deployed on https://deploy-preview-1614.quarto.org

[cwickham]

This all looks great. A few places that could use a bit more clarification.

I'll open a PR for the updates to the reference so you can take a look.

[cwickham]

Specify where? Is this a YAML option under theme? I'd probably put an example right after the first sentence.

[gordonwoodhull]

Good idea. It's a new HTML document option. Will do.

[gordonwoodhull]

Adding the example meant invalidating the reference to "above example" in the next sentence, so I changed it to "first example". Is this clear?

[github-actions]

🚀 Deployed on https://deploy-preview-1614.quarto.org

[github-actions]

🚀 Deployed on https://deploy-preview-1614.quarto.org

[gordonwoodhull]

I've added documentation for Typst brand-mode and resolved the other issues.

I also added minimal documentation for renderings. Note we can't demonstrate this feature until we enable dark mode for quarto.org.

@cwickham, please give this another read for clarity.

[github-actions]

🚀 Deployed on https://deploy-preview-1614.quarto.org

[github-actions]

🚀 Deployed on https://deploy-preview-1614.quarto.org

[github-actions]

🚀 Deployed on https://deploy-preview-1614.quarto.org

[github-actions]

🚀 Deployed on https://deploy-preview-1614.quarto.org

[github-actions]

🚀 Deployed on https://deploy-preview-1614.quarto.org

[gordonwoodhull]

I've also moved the document logo customization documentation out of the advanced Typst brand yml docs and into the main Brand page. This fixes quarto-dev/quarto-cli#12181.

I don't know if this belongs here, but it should be somewhere on the main site.

The remaining helpful info on the Advanced page has to do with typography, so I've added a link there.

I realized I had put the brand-mode section inside of the color documentation, so I made a Typst subsection under Dark Brand instead.

I think this completes my documentation tasks for 1.7 (aside from needing to return to renderings when we're able to demo that).

Glad to edit or expand any of this.

[github-actions]

🚀 Deployed on https://deploy-preview-1614.quarto.org

[github-actions]

🚀 Deployed on https://deploy-preview-1614.quarto.org

[github-actions]

🚀 Deployed on https://deploy-preview-1614.quarto.org

[cwickham]

Looks good! A few minor suggestions.

In terms of renderings:

• We definitely need some examples. Can we do screenshots for now? Not sure how big a job it is to implement dark mode on quarto.org.
• Where were you thinking of putting the examples? Maybe docs/computations/execution-options.html#figure-options?
• I think you might have mentioned you can construct light/dark variations of (e.g.) screenshots by constructing divs with the right classes. Is this something we want to document?

It's starting to feel like the dark mode details are spread all over the place and we might want a single page that describes implenting dark mode on a website: setting themes, brand and renderings.

[github-actions]

🚀 Deployed on https://deploy-preview-1614.quarto.org

[gordonwoodhull]

Light/dark renderings example

A problem with adding an example today is that we don't have the helper libraries... I'm trying to put the release and docs to bed so that I can get back to the user side.

(This might include syntactic sugar to avoid duplicate code, like the custom print function you came up with.)

So a minimal ggplot example is about 56 lines, but 34 lines of this (the first code cell) is the stuff that is supposed to in the helper library:

---
title: "knitr dark mode - ggplot"
brand:
  light: united-brand.yml
  dark: slate-brand.yml
execute:
  echo: false
  warning: false
---

```{r}
#| echo: false
#| warning: false
library(ggplot2)

ggplot_theme <- function(bgcolor, fgcolor) {
  theme_minimal(base_size = 11) %+%
    theme(
      panel.border = element_blank(),
      panel.grid.major.y = element_blank(),
      panel.grid.minor.y = element_blank(),
      panel.grid.major.x = element_blank(),
      panel.grid.minor.x = element_blank(),
      text = element_text(colour = fgcolor),
      axis.text = element_text(colour = fgcolor),
      rect = element_rect(colour = bgcolor, fill = bgcolor),
      plot.background = element_rect(fill = bgcolor, colour = NA),
      axis.line = element_line(colour = fgcolor),
      axis.ticks = element_line(colour = fgcolor)
    )
}

brand_ggplot <- function(brand_yml) {
  brand <- yaml::yaml.load_file(brand_yml)
  ggplot_theme(brand$color$background, brand$color$foreground)
}

united_theme <- brand_ggplot("united-brand.yml")
slate_theme <- brand_ggplot("slate-brand.yml")

colour_scale <- scale_colour_manual(values = c("darkorange", "purple", "cyan4"))
```

### no crossref, no caption

```{r}
#| renderings: [light, dark]
ggplot(mtcars, aes(mpg, wt)) +
  geom_point(aes(colour = factor(cyl))) +
  united_theme +
  colour_scale
ggplot(mtcars, aes(mpg, wt)) +
  geom_point(aes(colour = factor(cyl))) +
  slate_theme +
  colour_scale
```

I think it would be okay at 12 lines, and I agree it fits in docs/computations/execution-options.html#figure-options.

Non-computational light and dark

We can add this but I'm not sure where it goes. It's not really brand or theme but just the way our CSS works.

A minimal example without any resources would be

---
title: "light and dark with divs"
brand:
  light: united-brand.yml
  dark: slate-brand.yml
---

::: {.light-content}
This text will be shown in light mode.
:::

::: {.dark-content}
This text will be shown in dark mode.
:::

This example is self-explanatory but kind of useless. Would it be better with images?

EDIT: that example only works for HTML; the cross-format way to do this is currently to imitate cell output. Too ugly to document?

---
title: "light and dark with divs"
brand:
  light: united-brand.yml
  dark: slate-brand.yml
renderings: [light, dark]
---

::: {.cell}
::: {.cell-output-display}
This text will be shown in light mode.
:::

::: {.cell-output-display}
This text will be shown in dark mode.
:::
:::

[github-actions]

🚀 Deployed on https://deploy-preview-1614.quarto.org

[gordonwoodhull]

I think we should merge this and then continue with examples for renderings in a later PR.

Unless you want to reorganize to a single dark mode page?

I have an example at 22 lines, using your darkmode_theme() function ... it might be made shorter.

But we need to contribute the 40 lines of helpers.R to quarto-r (instead of using source() below). I should be able to do that this week.

---
title: "knitr dark mode - ggplot"
brand:
  light: united-brand.yml
  dark: slate-brand.yml
---

```{r}
#| echo: false
source("helpers.R")
united_theme <- brand_ggplot("united-brand.yml")
slate_theme <- brand_ggplot("slate-brand.yml")
darkmode_theme(united_theme, slate_theme)
colour_scale <- scale_colour_manual(values = c("darkorange", "purple", "cyan4"))
```

```{r}
#| renderings: [light, dark]
ggplot(mtcars, aes(mpg, wt)) +
  geom_point(aes(colour = factor(cyl))) +
  colour_scale
```