Dark mode creates a white “flash” when navigating between pages.

[ngrayluna]

Environment

• [X] Version of Docsy you are using: v0.11.0
• [X] How are you using Docsy? As a:
  • [X] Hugo module
  • [ ] NPM module
  • [ ] Git submodule
  • [ ] Other:
• [X] Version of Hugo you are using (output of hugo version): v0.139.3
• [X] OS:
  • [ ] Linux
  • [X] macOS
  • [ ] Windows
  • [ ] Other:

Problem

Docs site: https://docs.wandb.ai

Dark mode creates a white “flash” when navigating between pages. The pages that cause the flash are not the same. To replicate:

1. Select either “Auto” or “Dark” mode on the docs site
2. Click on several doc page links (e.g. on the left navbar).

Note that this is also independent of the default Mac OS theme appearance (System Settings → Themes → Dark, Light, or Auto).

The issue can be replicated on:

• MacBook Pro (~2019) AMD Intel, OS 12.x and 15.2
• MacBook Pro M1 Max, OS 12.x and 15.2
• MacBook Pro M3 / 14.4 / Chrome 131.0.6778.205
• Android Google Pixel 6 (Phone)

[chalin]

Yeah, I'd noticed that too. Will see if we can improve on the situation.

[chalin]

Thanks for filing this issue. I'm seeing the same flash from github.com, Google pages, etc. So I'm not sure that much can be done about it when we transition from light to dark or dark to light. I'm going to mark this as wont-fix, but I'm open to suggestions if some feel that it can be improved.

[ngrayluna]

@chalin makes sense. Thank you for investigating. Should I go ahead and close this issue?

[chalin]

We can keep it open for a little while in case others have comments.

[sftim]

If we reference the stylesheet using a Link: header (served ahead of the response body), does that help? It might.

If so, this ends up as guidance to people relying on the theme. Docsy and Hugo can't directly influence response headers.

[KivalovIlya]

had the same problem with a flash of the wrong theme before the page fully loaded. Adding this small snippet to layouts/partials/head.html solved it for me: <script> (function() { var theme = localStorage.getItem('td-color-theme') || 'light'; document.documentElement.setAttribute('data-bs-theme', theme); })(); </script>

This runs before the CSS is applied, so the correct theme is set immediately on page load, avoiding the flash.

[chalin]

Yeah, can across that fix too while working on something else, thanks. Will get this applied / properly fixed as soon as possible.

[chalin]

@ngrayluna - can you give this PR's preview a try? It is an initial partial solution:

• #2343

It seems better.

Edit: I added some JS, similar to what @KivalovIlya suggested. It seems to eliminate the flash. Can you confirm?

[chalin]

Actually, I'd say that this issue is fixed by:

• #2343

I'll consider further improvements outside the scope of this issue.

All: if you have any further feedback, share here or open another issue. Thanks!