no flashing when reloading in light or dark mode

fixes #1325

introduces a new script before the body
which runs immediately, enabling or disabling dark mode

both stylesheets are loaded, one is disabled in JS

the default stylesheet is loaded second, in case JS is disabled

Author: gordonwoodhull

news/changelog-1.7.md

@@ -45,6 +45,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.)
 
 ## `pdf` format
 

src/command/render/pandoc-html.ts

@@ -130,7 +130,7 @@ export async function resolveSassBundles(
       // Note that the other bundle provides light
       targets[0].attribs = {
         ...targets[0].attribs,
-        ...attribForThemeStyle("light", defaultStyle),
+        ...attribForThemeStyle("light"),
       };
 
       // Provide a dark bundle for this
@@ -144,14 +144,19 @@ export async function resolveSassBundles(
         bundle.key = bundle.key + "-dark";
         return bundle;
       });
-      targets.push({
+      const darkTarget = {
         name: `${dependency}-dark.min.css`,
         bundles: darkBundles as any,
         attribs: {
           "append-hash": "true",
-          ...attribForThemeStyle("dark", defaultStyle),
+          ...attribForThemeStyle("dark"),
         },
-      });
+      };
+      if (defaultStyle === "dark") {
+        targets.push(darkTarget);
+      } else {
+        targets.unshift(darkTarget);
+      }
 
       hasDarkStyles = true;
     }
@@ -256,6 +261,18 @@ export async function resolveSassBundles(
   }
 
   // Resolve generated quarto css variables
+  if (hasDarkStyles && defaultStyle !== "dark") {
+    // Put dark stylesheet first if light is default (for NoJS)
+    extras = await resolveQuartoSyntaxHighlighting(
+      inputDir,
+      extras,
+      format,
+      project,
+      "dark",
+      defaultStyle,
+    );
+  }
+
   extras = await resolveQuartoSyntaxHighlighting(
     inputDir,
     extras,
@@ -265,8 +282,8 @@ export async function resolveSassBundles(
     defaultStyle,
   );
 
-  if (hasDarkStyles) {
-    // Provide dark variables for this
+  if (hasDarkStyles && defaultStyle === "dark") {
+    // Put dark stylesheet second if dark is default (for NoJS)
     extras = await resolveQuartoSyntaxHighlighting(
       inputDir,
       extras,
@@ -303,7 +320,7 @@ async function resolveQuartoSyntaxHighlighting(
   extras = cloneDeep(extras);
 
   // If we're using default highlighting, use theme darkness to select highlight style
-  const mediaAttr = attribForThemeStyle(style, defaultStyle);
+  const mediaAttr = attribForThemeStyle(style);
   if (style === "default") {
     if (extras.html?.[kTextHighlightingMode] === "dark") {
       style = "dark";
@@ -559,28 +576,23 @@ const kVariablesRegex =
   /\/\*\! quarto-variables-start \*\/([\S\s]*)\/\*\! quarto-variables-end \*\//g;
 
 // Attributes for the style tag
-// Note that we default disable the dark mode and rely on JS to enable it
 function attribForThemeStyle(
   style: "dark" | "light" | "default",
-  defaultStyle?: "dark" | "light",
 ): Record<string, string> {
-  const colorModeAttrs = (mode: string, disabled: boolean) => {
+  const colorModeAttrs = (mode: string) => {
     const attr: Record<string, string> = {
       class: `quarto-color-scheme${
         mode === "dark" ? " quarto-color-alternate" : ""
       }`,
     };
-    if (disabled) {
-      attr.rel = "prefetch";
-    }
     return attr;
   };
 
   switch (style) {
     case "dark":
-      return colorModeAttrs("dark", defaultStyle !== "dark");
+      return colorModeAttrs("dark");
     case "light":
-      return colorModeAttrs("light", false);
+      return colorModeAttrs("light");
     case "default":
     default:
       return {};

src/format/html/format-html.ts

@@ -24,6 +24,7 @@ import {
   kFigResponsive,
   kFilterParams,
   kHeaderIncludes,
+  kIncludeBeforeBody,
   kIncludeAfterBody,
   kIncludeInHeader,
   kLinkExternalFilter,
@@ -501,28 +502,33 @@ export async function htmlFormatExtras(
       renderEjs(
         formatResourcePath("html", join("hypothesis", "hypothesis.ejs")),
         { hypothesis: options.hypothesis },
-      ),
+      )
     );
     includeInHeader.push(hypothesisHeader);
   }
 
-  // after body
+  // before and after body
+  const includeBeforeBody: string[] = [];
   const includeAfterBody: string[] = [];
 
   // add main orchestion script if we have any options enabled
   const quartoHtmlRequired = Object.keys(options).some((option) =>
     !!options[option]
   );
   if (quartoHtmlRequired) {
-    // html orchestration script
-    const quartoHtmlScript = temp.createFile();
-    const renderedHtml = renderEjs(
-      formatResourcePath("html", join("templates", "quarto-html.ejs")),
-      options,
-    );
-    if (renderedHtml.trim() !== "") {
-      Deno.writeTextFileSync(quartoHtmlScript, renderedHtml);
-      includeAfterBody.push(quartoHtmlScript);
+    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)),
+        options,
+      );
+      if (renderedHtml.trim() !== "") {
+        Deno.writeTextFileSync(quartoHtmlScript, renderedHtml);
+        dest.push(quartoHtmlScript);
+      }
     }
   }
 
@@ -636,6 +642,7 @@ export async function htmlFormatExtras(
   const metadata: Metadata = {};
   return {
     [kIncludeInHeader]: includeInHeader,
+    [kIncludeBeforeBody]: includeBeforeBody,
     [kIncludeAfterBody]: includeAfterBody,
     metadata,
     templateContext,