respect-user-color-scheme enables checking of prefers-color-scheme media query

news/changelog-1.7.md

@@ -61,6 +61,7 @@ All changes included in 1.7:
 - ([#12277](https://github.com/quarto-dev/quarto-cli/pull/12277)): Provide light and dark plot and table renderings with `renderings: [light,dark]`
 - ([#11860](https://github.com/quarto-dev/quarto-cli/issues/11860)): ES6 modules that import other local JS modules in documents with `embed-resources: true` are now correctly embedded.
 - ([#1325](https://github.com/quarto-dev/quarto-cli/issues/1325)): Dark Mode pages should not flash light on reload. (Nor should Light Mode pages flash dark.)
+- ([#1470](https://github.com/quarto-dev/quarto-cli/issues/1470)): `respect-user-color-scheme` enables checking the media query `prefers-color-scheme` for user preference. This is only on page load, not dynamically. Author preference still influences stylesheet order and therefore NoJS experience. Defaults to `false`, leaving to author preference.
 - ([#12307](https://github.com/quarto-dev/quarto-cli/issues/12307)): Tabsets using `tabby.js` in non-boostrap html (`theme: pandoc`, `theme: none` or `minimal: true`) now correctly render reactive content when `server: shiny` is used.
 - ([#12356](https://github.com/quarto-dev/quarto-cli/issues/12356)): Remove duplicate id in HTML document when using `#lst-` prefix label for using Quarto crossref.
 

src/config/constants.ts

@@ -142,6 +142,7 @@ export const kHtmlTableProcessing = "html-table-processing";
 export const kHtmlPreTagProcessing = "html-pre-tag-processing";
 export const kCssPropertyProcessing = "css-property-processing";
 export const kBrandMode = "brand-mode";
+export const kRespectUserColorScheme = "respect-user-color-scheme";
 export const kUseRsvgConvert = "use-rsvg-convert";
 export const kValidateYaml = "validate-yaml";
 

src/format/html/format-html.ts

@@ -24,14 +24,15 @@ import {
   kFigResponsive,
   kFilterParams,
   kHeaderIncludes,
-  kIncludeBeforeBody,
   kIncludeAfterBody,
+  kIncludeBeforeBody,
   kIncludeInHeader,
   kLinkExternalFilter,
   kLinkExternalIcon,
   kLinkExternalNewwindow,
   kNotebookLinks,
   kNotebookViewStyle,
+  kRespectUserColorScheme,
   kTheme,
 } from "../../config/constants.ts";
 
@@ -343,6 +344,8 @@ export async function htmlFormatExtras(
   options.codeTools = formatHasCodeTools(format);
   options.darkMode = formatDarkMode(format);
   options.darkModeDefault = darkModeDefault(format.metadata);
+  options.respectUserColorScheme = format.metadata[kRespectUserColorScheme] ||
+    false;
   options.linkExternalIcon = format.render[kLinkExternalIcon];
   options.linkExternalNewwindow = format.render[kLinkExternalNewwindow];
   options.linkExternalFilter = format.render[kLinkExternalFilter];
@@ -502,7 +505,7 @@ export async function htmlFormatExtras(
       renderEjs(
         formatResourcePath("html", join("hypothesis", "hypothesis.ejs")),
         { hypothesis: options.hypothesis },
-      )
+      ),
     );
     includeInHeader.push(hypothesisHeader);
   }
@@ -516,10 +519,12 @@ export async function htmlFormatExtras(
     !!options[option]
   );
   if (quartoHtmlRequired) {
-    for(const {dest, ejsfile} of [
-      {dest: includeBeforeBody, ejsfile: "quarto-html-before-body.ejs"},
-      {dest: includeAfterBody, ejsfile: "quarto-html-after-body.ejs"}
-    ]) {
+    for (
+      const { dest, ejsfile } of [
+        { dest: includeBeforeBody, ejsfile: "quarto-html-before-body.ejs" },
+        { dest: includeAfterBody, ejsfile: "quarto-html-after-body.ejs" },
+      ]
+    ) {
       const quartoHtmlScript = temp.createFile();
       const renderedHtml = renderEjs(
         formatResourcePath("html", join("templates", ejsfile)),

src/resources/editor/tools/vs-code.mjs

@@ -16869,6 +16869,20 @@ var require_yaml_intelligence_resources = __commonJS({
           },
           description: "Enables smooth scrolling within the page."
         },
+        {
+          name: "respect-user-color-scheme",
+          schema: "boolean",
+          default: false,
+          tags: {
+            formats: [
+              "$html-doc"
+            ]
+          },
+          description: {
+            short: "Whether the `prefers-color-scheme` media query controls dark mode.",
+            long: "Whether to use the `prefers-color-scheme` media query to determine whether to show\nthe user a dark or light page. Otherwise the author preference (order of `light`\nand `dark` in `theme` or `brand`) determines what is shown to the user at first visit.\n"
+          }
+        },
         {
           name: "html-math-method",
           tags: {
@@ -22751,6 +22765,7 @@ var require_yaml_intelligence_resources = __commonJS({
         },
         "Control the <code>\\pagestyle{}</code> for the document.",
         "The paper size for the document.",
+        "The brand mode to use for rendering the Typst document,\n<code>light</code> or <code>dark</code>.",
         {
           short: "The options for margins and text layout for this document.",
           long: 'The options for margins and text layout for this document.\nSee <a href="https://wiki.contextgarden.net/Layout">ConTeXt\nLayout</a> for additional information.'
@@ -24043,7 +24058,10 @@ var require_yaml_intelligence_resources = __commonJS({
         "Manuscript configuration",
         "internal-schema-hack",
         "List execution engines you want to give priority when determining\nwhich engine should render a notebook. If two engines have support for a\nnotebook, the one listed earlier will be chosen. Quarto\u2019s default order\nis \u2018knitr\u2019, \u2018jupyter\u2019, \u2018markdown\u2019, \u2018julia\u2019.",
-        "The brand mode to use for rendering the Typst document,\n<code>light</code> or <code>dark</code>."
+        {
+          short: "Whether the <code>prefers-color-scheme</code> media query controls\ndark mode.",
+          long: "Whether to use the <code>prefers-color-scheme</code> media query to\ndetermine whether to show the user a dark or light page. Otherwise the\nauthor preference (order of <code>light</code> and <code>dark</code> in\n<code>theme</code> or <code>brand</code>) determines what is shown to\nthe user at first visit."
+        }
       ],
       "schema/external-schemas.yml": [
         {
@@ -24272,12 +24290,12 @@ var require_yaml_intelligence_resources = __commonJS({
         mermaid: "%%"
       },
       "handlers/mermaid/schema.yml": {
-        _internalId: 194259,
+        _internalId: 194479,
         type: "object",
         description: "be an object",
         properties: {
           "mermaid-format": {
-            _internalId: 194251,
+            _internalId: 194471,
             type: "enum",
             enum: [
               "png",
@@ -24293,7 +24311,7 @@ var require_yaml_intelligence_resources = __commonJS({
             exhaustiveCompletions: true
           },
           theme: {
-            _internalId: 194258,
+            _internalId: 194478,
             type: "anyOf",
             anyOf: [
               {

src/resources/editor/tools/yaml/yaml-intelligence-resources.json

@@ -9841,6 +9841,20 @@
       },
       "description": "Enables smooth scrolling within the page."
     },
+    {
+      "name": "respect-user-color-scheme",
+      "schema": "boolean",
+      "default": false,
+      "tags": {
+        "formats": [
+          "$html-doc"
+        ]
+      },
+      "description": {
+        "short": "Whether the `prefers-color-scheme` media query controls dark mode.",
+        "long": "Whether to use the `prefers-color-scheme` media query to determine whether to show\nthe user a dark or light page. Otherwise the author preference (order of `light`\nand `dark` in `theme` or `brand`) determines what is shown to the user at first visit.\n"
+      }
+    },
     {
       "name": "html-math-method",
       "tags": {
@@ -15723,6 +15737,7 @@
     },
     "Control the <code>\\pagestyle{}</code> for the document.",
     "The paper size for the document.",
+    "The brand mode to use for rendering the Typst document,\n<code>light</code> or <code>dark</code>.",
     {
       "short": "The options for margins and text layout for this document.",
       "long": "The options for margins and text layout for this document.\nSee <a href=\"https://wiki.contextgarden.net/Layout\">ConTeXt\nLayout</a> for additional information."
@@ -17015,7 +17030,10 @@
     "Manuscript configuration",
     "internal-schema-hack",
     "List execution engines you want to give priority when determining\nwhich engine should render a notebook. If two engines have support for a\nnotebook, the one listed earlier will be chosen. Quarto’s default order\nis ‘knitr’, ‘jupyter’, ‘markdown’, ‘julia’.",
-    "The brand mode to use for rendering the Typst document,\n<code>light</code> or <code>dark</code>."
+    {
+      "short": "Whether the <code>prefers-color-scheme</code> media query controls\ndark mode.",
+      "long": "Whether to use the <code>prefers-color-scheme</code> media query to\ndetermine whether to show the user a dark or light page. Otherwise the\nauthor preference (order of <code>light</code> and <code>dark</code> in\n<code>theme</code> or <code>brand</code>) determines what is shown to\nthe user at first visit."
+    }
   ],
   "schema/external-schemas.yml": [
     {
@@ -17244,12 +17262,12 @@
     "mermaid": "%%"
   },
   "handlers/mermaid/schema.yml": {
-    "_internalId": 194259,
+    "_internalId": 194479,
     "type": "object",
     "description": "be an object",
     "properties": {
       "mermaid-format": {
-        "_internalId": 194251,
+        "_internalId": 194471,
         "type": "enum",
         "enum": [
           "png",
@@ -17265,7 +17283,7 @@
         "exhaustiveCompletions": true
       },
       "theme": {
-        "_internalId": 194258,
+        "_internalId": 194478,
         "type": "anyOf",
         "anyOf": [
           {

src/resources/formats/html/templates/quarto-html-before-body.ejs

@@ -128,7 +128,12 @@
         return localAlternateSentinel;
       }
     }
-    const darkModeDefault = <%= darkModeDefault %>;
+    <% if (respectUserColorScheme) { %>
+      const darkModeDefault = window.matchMedia('(prefers-color-scheme: dark)').matches;
+    <% } else { %>
+      const darkModeDefault = <%= darkModeDefault %>;
+    <% } %>
+
     let localAlternateSentinel = darkModeDefault ? 'alternate' : 'default';
 
     // Dark / light mode switch

src/resources/schema/document-options.yml

@@ -84,6 +84,18 @@
     formats: [$html-doc]
   description: Enables smooth scrolling within the page.
 
+- name: respect-user-color-scheme
+  schema: boolean
+  default: false
+  tags:
+    formats: [$html-doc]
+  description:
+    short: "Whether the `prefers-color-scheme` media query controls dark mode."
+    long: |
+      Whether to use the `prefers-color-scheme` media query to determine whether to show
+      the user a dark or light page. Otherwise the author preference (order of `light`
+      and `dark` in `theme` or `brand`) determines what is shown to the user at first visit.
+
 - name: html-math-method
   tags:
     formats: [$html-doc, $epub-all, gfm]

tests/docs/playwright/html/dark-brand/project-dark/simple-respect-color-scheme.qmd

@@ -0,0 +1,55 @@
+---
+title: "dark brand - ggplot"
+format:
+  html:
+    respect-user-color-scheme: true
+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)
+}
+
+blue_theme <- brand_ggplot("blue-background.yml")
+red_theme <- brand_ggplot("red-background.yml")
+
+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))) +
+  blue_theme +
+  colour_scale
+ggplot(mtcars, aes(mpg, wt)) +
+  geom_point(aes(colour = factor(cyl))) +
+  red_theme +
+  colour_scale
+```

tests/docs/playwright/html/dark-brand/project-light/_quarto.yml

@@ -0,0 +1,5 @@
+project:
+  type: default
+brand:
+  light: blue-background.yml
+  dark: red-background.yml

tests/docs/playwright/html/dark-brand/project-light/blue-background.yml

@@ -0,0 +1,3 @@
+color:
+  background: "#ccddff"
+  foreground: "#336644"

tests/docs/playwright/html/dark-brand/project-light/red-background.yml

@@ -0,0 +1,3 @@
+color:
+  background: "#42070b"
+  foreground: "#cceedd"