fix(theme): prevent theme flash by respecting system preference on initial load #3840

samarJ19 · 2025-11-16T10:19:12Z

Marked version:
(same version used in PR #3814)

Markdown flavor:
GitHub Flavored Markdown

Description

Fixes regression introduced after Modernize Docs UI with Tailwind, Dark Mode, and Improved Layout (Modernize Docs UI with Tailwind, Dark Mode, and Improved Layout #3814).
The website was not consistently respecting system theme preference on the first load.
The issue occurred because:
- The inline <script> in the <head> correctly applied dark/light mode before render.
- index.js later ran on DOMContentLoaded and reapplied the theme unconditionally via applyTheme(initialTheme).
- applyTheme() always removed the dark class first → causing:
  - A momentary flash
  - Theme being overridden incorrectly
  - Race condition between inline script and DOMContentLoaded logic

Solution

This PR updates the theme initialization logic so that applyTheme() only runs when necessary.

Specifically:

It now checks whether the current DOM theme already matches the resolved theme (system preference or saved preference).
applyTheme() is called only if a mismatch exists.
Prevents unnecessary DOM manipulation and eliminates:
- Flash of incorrect theme
- Double theme updates
- Race conditions between inline script and JS loader

Result

With this fix:

System preference is applied correctly on first visit.
User's saved preference (localStorage) still correctly overrides system settings.
Theme toggle button continues to work as expected.
No visual flashing between light/dark.

Contributor

No new tests required (the fix only adjusts initialization logic; existing theme behavior tests cover expected output).
Not a new feature — continuation/fix to prior merged work (Modernize Docs UI with Tailwind, Dark Mode, and Improved Layout #3814).

vercel · 2025-11-16T10:19:16Z

@samarJ19 is attempting to deploy a commit to the MarkedJS Team on Vercel.

A member of the Team first needs to authorize it.

gemini-code-assist · 2025-11-16T10:19:33Z

Summary of Changes

Hello @samarJ19, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request addresses a critical theme-related regression that caused an inconsistent and visually jarring experience for users on initial page load. By refining the theme application process to be more intelligent and only trigger updates when necessary, the PR ensures that the website consistently respects user preferences without any visual glitches. Additionally, it includes a comprehensive UI modernization effort across documentation and demo pages, enhancing their aesthetic and responsiveness.

Highlights

Theme Flash Fix: Resolved a regression where the website would momentarily display an incorrect theme or fail to respect the user's system preference on initial page load.
Optimized Theme Application: The theme initialization logic has been updated to only apply theme changes if the current DOM theme does not match the resolved preference (system or saved), preventing unnecessary DOM manipulation.
Improved User Experience: This change eliminates visual flashing, double theme updates, and race conditions between inline scripts and JavaScript-based theme application, leading to a smoother and more consistent theme experience.
UI Modernization: The documentation and demo pages have undergone significant styling updates, leveraging Tailwind CSS for a more modern layout, improved mobile responsiveness, and better dark mode integration.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

gemini-code-assist

Code Review

This pull request effectively resolves the theme flashing issue on initial load by introducing an inline script to set the theme before the first paint and refining the JavaScript logic to avoid unnecessary theme applications. The solution is robust, handling both user-saved preferences and system settings correctly. Beyond the primary fix, this PR includes a significant and welcome modernization of the entire documentation UI using Tailwind CSS, which greatly improves the visual design, responsiveness, and maintainability of the codebase. The refactoring of CSS and JavaScript is clean and follows modern best practices. I've included a few minor suggestions to further enhance code quality and robustness.

gemini-code-assist · 2025-11-16T10:20:39Z

docs/js/index.js

+      const code = pre.querySelector('code').innerText;
+      navigator.clipboard.writeText(code);


This line could potentially throw a runtime error if a <pre> tag exists without a nested <code> tag, as pre.querySelector('code') would return null. To make this more robust, it's good practice to check if the code element exists before accessing its innerText property. You could fall back to pre.innerText if the <code> tag is not found.

Suggested change

const code = pre.querySelector('code').innerText;

navigator.clipboard.writeText(code);

const codeElement = pre.querySelector('code');

const code = codeElement ? codeElement.innerText : pre.innerText;

navigator.clipboard.writeText(code);

gemini-code-assist · 2025-11-16T10:20:39Z

docs/_document.html

+      (function () {
+        try {
+          var theme = localStorage.getItem("theme");
+          var prefersDark =
+            window.matchMedia &&
+            window.matchMedia("(prefers-color-scheme: dark)").matches;
+          if (theme === "dark" || (!theme && prefersDark)) {
+            document.documentElement.classList.add("dark");
+          }
+        } catch (e) {}
+      })();
+    </script>


For better code consistency and to adhere to modern JavaScript standards, it's recommended to use const and let instead of var. Since theme and prefersDark are not reassigned, they can be declared as const.

Suggested change

(function () {

try {

var theme = localStorage.getItem("theme");

var prefersDark =

window.matchMedia &&

window.matchMedia("(prefers-color-scheme: dark)").matches;

if (theme === "dark" || (!theme && prefersDark)) {

document.documentElement.classList.add("dark");

}

} catch (e) {}

})();

</script>

(function () {

try {

const theme = localStorage.getItem("theme");

const prefersDark =

window.matchMedia &&

window.matchMedia("(prefers-color-scheme: dark)").matches;

if (theme === "dark" || (!theme && prefersDark)) {

document.documentElement.classList.add("dark");

}

} catch (e) {}

})();

styfle · 2025-11-17T02:41:24Z

@samarJ19 Please rebase from the main branch. I'm seeing 17 commits and 16 of those are merged already. I would expect to see only one commit with your change.

styfle

Please fix the merge conflicts

<<<<<<< HEAD

samarJ19

fix: three-mode theme system with live OS sync

First fixed git merge conflicts
Replaced binary toggle with tri-state (system/light/dark):
Added inline script in HTML head to apply theme before first paint (prevents FOUC)
Reads theme-preference from localStorage, defaults to 'system'
System mode actively tracks OS changes via matchMedia listener
Light/dark modes override and ignore OS changes
Toggle cycles: System 🌓 → Light ☀️ → Dark 🌙
Syncs theme to demo iframe on load/change
Normalized storage key to theme-preference, kept legacy theme for compat
Removed unused error params (linting fix)

First visit respects OS preference, manual toggle overrides, system mode auto-updates when OS theme changes.

vercel · 2025-11-21T15:52:08Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
marked-website	Ready	Preview	Comment	Nov 22, 2025 2:58pm

UziTech · 2025-11-21T15:55:36Z

The demo page is always in light mode now

samarJ19

Fixed the demo page CSS problem

gemini-code-assist bot reviewed Nov 16, 2025

View reviewed changes

samarJ19 force-pushed the systemPref-fix branch from d51b0ad to cc63a61 Compare November 20, 2025 10:59

styfle requested changes Nov 20, 2025

View reviewed changes

fix:system pref fix

90cfa99

samarJ19 force-pushed the systemPref-fix branch from cc63a61 to 90cfa99 Compare November 21, 2025 11:03

samarJ19 commented Nov 21, 2025

View reviewed changes

samarJ19 requested a review from styfle November 21, 2025 11:10

vercel bot deployed to Preview November 21, 2025 15:52 View deployment

fix: fixes demo page light mode error

fa7f616

samarJ19 commented Nov 21, 2025

View reviewed changes

vercel bot deployed to Preview November 22, 2025 14:58 View deployment

UziTech approved these changes Nov 24, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

fix(theme): prevent theme flash by respecting system preference on initial load #3840

fix(theme): prevent theme flash by respecting system preference on initial load #3840

samarJ19 commented Nov 16, 2025

Uh oh!

vercel bot commented Nov 16, 2025

Uh oh!

gemini-code-assist bot commented Nov 16, 2025

Uh oh!

gemini-code-assist bot left a comment

Uh oh!

gemini-code-assist bot Nov 16, 2025

Uh oh!

gemini-code-assist bot Nov 16, 2025

Uh oh!

styfle commented Nov 17, 2025

Uh oh!

styfle left a comment

Uh oh!

samarJ19 left a comment

Uh oh!

vercel bot commented Nov 21, 2025 •

edited

Loading

Uh oh!

UziTech commented Nov 21, 2025

Uh oh!

samarJ19 left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		const code = pre.querySelector('code').innerText;
		navigator.clipboard.writeText(code);

fix(theme): prevent theme flash by respecting system preference on initial load #3840

Are you sure you want to change the base?

fix(theme): prevent theme flash by respecting system preference on initial load #3840

Conversation

samarJ19 commented Nov 16, 2025

Description

Solution

Result

Contributor

Uh oh!

vercel bot commented Nov 16, 2025

Uh oh!

gemini-code-assist bot commented Nov 16, 2025

Summary of Changes

Highlights

Footnotes

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist bot Nov 16, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Nov 16, 2025

Choose a reason for hiding this comment

Uh oh!

styfle commented Nov 17, 2025

Uh oh!

styfle left a comment

Choose a reason for hiding this comment

Uh oh!

samarJ19 left a comment

Choose a reason for hiding this comment

Uh oh!

vercel bot commented Nov 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

UziTech commented Nov 21, 2025

Uh oh!

samarJ19 left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

vercel bot commented Nov 21, 2025 •

edited

Loading