Fix dark mode styling for code blocks in Book pages #2122

Subhajit-das21 · 2026-01-02T20:37:40Z

Book pages were missing proper dark-mode styling for inline and block
code elements due to existing .edition2 code rules overriding the
theme styles.

This change adds scoped dark-mode styles for .edition2 .book code
and pre elements using existing design tokens, aligning Book pages
with Docs styling and restoring proper contrast in dark mode.

Fixes #2120

dscho

Thank you for taking this on!

The form, however, needs a bit of TLC. The changes really need explanations, and there are none.

If you used AI to help you implement these changes, that's fine, but you have to understand those changes (in particular when they look both too narrow and broad almost at the same time) and be able to explain the rationale behind them, preferably in the commit message.

dscho · 2026-01-03T15:17:01Z

assets/sass/book.scss

    margin-right: 0;
  }
 }
+


Why not put this into dark-mode.scss just like everything else concerned with the dark mode?

This logic belongs into dark-mode.scss. I initially placed it in book.scss while iterating on the fix, but I agree that following the existing dark-mode structure is the correct approach.

dscho · 2026-01-03T15:18:28Z

assets/sass/book.scss

+   Fix: Dark mode styling for code blocks in Book pages
+   -------------------------------------------------- */
+
+html[data-theme="dark"] .edition2 .book code {


Why .edition2?

The .edition2 selector was added to match the specificity of the existing .edition2 code { background: #eee; } rule, which was overriding dark-mode styles on Book pages. This was confirmed via DevTools. However, I agree that the override should mirror the light-mode scope instead of introducing a new one. I will adjust the selectors accordingly.

Well, there is an .edition2 block. But it is in book2.scss, not in book.scss (and therefore the latter is doubly incorrect a location for these changes).

This issue convinces me that the changes in this PR need to be made more carefully, i.e. with a more thorough approach as to what to override and where.

This issue convinces me that the changes in this PR need to be made more carefully, i.e. with a more thorough approach as to what to override and where.

For example, I bet that you did not even see https://github.com/Subhajit-das21/git-scm.com/blob/424c22d46385f5b426cc444f31d829c3c655e90f/assets/sass/book2.scss#L614-L691 (which needs to be the location where to change this, using CSS variables instead of hard-coded values, and overriding those variables in dark mode).

FWIW if you want to fix the <code> colors, this would be the correct location to fix the dark-mode colors for <code> sections in the Book: again, by replacing the hard-coded colors with CSS variables (with those variables having different values depending on light/dark mode).

dscho · 2026-01-03T15:19:55Z

assets/sass/book.scss

+
+html[data-theme="dark"] .edition2 .book code {
+  background-color: var(--color-canvas-subtle);
+  color: var(--color-fg-default);


Why were those colors chosen? Which CSS do they override (it sure isn't .book code...)? Wouldn't it be better to use the same scope as light-mode for the override?

The colors were chosen from existing design tokens already used on Docs pages and in other dark-mode contexts. No new colors were introduced. I will clarify this and ensure the override aligns with existing patterns

dscho · 2026-01-03T15:20:15Z

assets/sass/book.scss

+  padding: 0.2em 0.4em;
+  border-radius: 4px;


Why is the padding and border radius in need of overriding in dark mode?

You are right — these do not need to be overridden specifically for dark mode. I will remove those overrides and rely on the existing light-mode styles.

dscho · 2026-01-03T15:21:35Z

assets/sass/book.scss

+  background-color: var(--color-canvas-inset);
+  color: var(--color-fg-default);


Same question as before about these color overrides: Which is the original CSS (in particular the original scope) that is overridden here? Shouldn't the same scope be used here, in particular skipping the questionable .edition2?

Oh, and why is it a different background color for code and pre?

Inline and block code are treated differently elsewhere (e.g. Docs and man-pages). I will rework this to follow the same approach as in commit f3771e3 for man-pages.

dscho · 2026-01-03T15:22:02Z

assets/sass/book.scss

+  background: none;
+  padding: 0;


Why do these have to be set specifically for dark mode?

They actually do not need to be set specifically for dark mode.

These overrides were added while iterating on the fix to avoid double backgrounds when testing, but on second thought they are unnecessary: the existing light-mode rules already handle padding and background
correctly for pre code .

I agree that dark mode should not override layout-related properties like padding or background resets here, and I will remove these lines and rely on the existing styles instead.

jnavila · 2026-01-03T15:34:30Z

please have a look at f3771e3 for how this was dealt with for man-pages

Subhajit-das21 · 2026-01-03T18:19:54Z

Thanks for the clarification — I’ve reworked the change accordingly.

The hard-coded code/pre colors in book2.scss are now replaced with CSS variables, and those variables are overridden in dark mode. This removes the need for selector-based overrides and lets the existing theme
mechanism handle light and dark appearances consistently.

Please let me know if this matches what you had in mind.

dscho · 2026-01-03T20:08:44Z

assets/sass/dark-mode.scss

-@include mode
-@include mode($mode: dark, $theme: '[data-theme="dark"]')
+@include mode;
+@include mode($mode: dark, $theme: '[data-theme="dark"]');

 @media screen and (prefers-color-scheme: dark) {
-    @include mode($mode: dark, $theme: ':not([data-theme="light"])')
-    @include mode($mode: light)
+    @include mode($mode: dark, $theme: ':not([data-theme="light"])');
+    @include mode($mode: light);


These changes unrelated to what you intended to change reminds me very much of the anti-pattern that is so indicative of AI-assisted (and not self-reviewed) PRs. Not a fan.

dscho

The essential part of this PR now looks good to me. To turn this into something I would be eager to merge, the following still would need to be done:

Instead of keeping commits with incorrect changes, this PR's commits should be squashed into a single one.
This commit would need to have a message that identifies the problem, talks about the missing parts (think of all the code.<some-letters> color definitions I pointed out in this PR, and why they are not touched), and explains what other approach was considered (and rejected, and why).
The commit would need to drop all unwanted changes.
The PR would need a "before/after" screenshot comparison.

dscho · 2026-01-03T20:10:47Z

assets/sass/book.scss

    margin-right: 0;
  }
-}
+}


That's another unintended change. It is always a good sign when contributors catch those problems before asking others to review their contributions.

dscho · 2026-01-03T20:12:29Z

assets/sass/dark-mode.scss

            #documentation #main div.verseblock pre.content {
                color: var(--light-font-color);
                background-color: #5e5951;
+


This is another left-over from an unwanted change that is first introduced in one commit, only to be (incompletely) reverted in another commit in the same PR. If anyone wants to learn from the commit history how to do things correctly (including AI assistants), this would mislead them.

Fix Book code styling in dark mode by replacing hard-coded colors with variables Book pages used hard-coded colors for inline and block code (e.g. `#eee`, `git#333`) in `book2.scss`, which prevented dark-mode styles from taking effect. As a result, code blocks in the Git Book did not adapt correctly when switching themes. This change replaces those hard-coded values with CSS variables (`--book-code-bg`, `--book-code-color`, `--book-code-border`), allowing dark mode to override Book code styling in the same way as other sections (e.g. man-pages). Not all `code.<language>` color rules are adjusted here, as they relate to syntax highlighting rather than theme contrast and require a separate, more holistic approach. An alternative approach—overriding Book code styles directly in `dark-mode.scss` using more specific selectors—was considered but rejected, as it would further increase selector complexity instead of fixing the root cause. Fixes git#2120

Subhajit-das21 · 2026-01-04T17:13:40Z

I squashed the PR into a single commit and removed all unintended changes, keeping only the variable-based fix for Book code styling.

Before: Book pages used hard-coded colors for <code> and <pre> elements (e.g. background: #eee; color: #333;) in book2.scss, which prevented dark mode from overriding them cleanly.

After: Those hard-coded values are replaced with CSS variables (--book-code-bg, --book-code-color, --book-code-border), allowing dark mode to override Book code styling via variables, consistent with the approach
used for man-pages.

The remaining code.<language> color rules were intentionally left untouched, as they relate to syntax highlighting and would require a broader change.

Please let me know if this looks ready to merge now.

michaelblyons · 2026-01-04T21:13:06Z

Would it be hard to show a real "after" screenshot? Like one that isn't just one single code span?

This corresponds to git#2122 Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>

dscho · 2026-01-05T11:15:08Z

The remaining code.<language> color rules were intentionally left untouched, as they relate to syntax highlighting and would require a broader change.

I don't think that it would be a good idea to leave this for later. It's probably a much better idea to first determine whether these definitions are actually used. To that end, downloading the build artifact from the latest deployment, extracting it, and then performing an analysis (e.g. via uncss), might be the best course of action.

If they aren't even used, add a commit to delete them, with a thorough description of the analysis and its results. However, if they are still used, generate a small page that has one element per style, and work on overriding the colors in dark mode with appropriate values. Personally, I'd probably upload screenshots of light/dark mode versions of some small manual page to Copilot and then ask it to generate appropriate dark mode versions of those colors.

Would it be hard to show a real "after" screenshot?

That's a very good suggestion. I say this because currently, this PR branch does not do what we want (see https://dscho.github.io/git-scm.com/book/en/v2/Git-on-the-Server-GitWeb):

I think the culprit is that the dark-mode override does need the .edition2 scope, otherwise it is weaker than the light-mode definition. I.e. something like this:

diff --git a/assets/sass/dark-mode.scss b/assets/sass/dark-mode.scss
index 6e226ca6e..b911ed3a2 100644
--- a/assets/sass/dark-mode.scss
+++ b/assets/sass/dark-mode.scss
@@ -84,9 +84,11 @@
             }
 
             /* Book pages: code colors */
-            --book-code-color: #{$fixed-width-font-color};
-            --book-code-bg: #{$no-changes-bg-color};
-            --book-code-border: #{$pre-border};
+            .edition2 {
+                --book-code-color: #{$fixed-width-font-color};
+                --book-code-bg: #{$no-changes-bg-color};
+                --book-code-border: #{$pre-border};
+            }
 
             img {
                 filter: brightness(.6) contrast(1.2);

dscho · 2026-01-06T21:21:31Z

With my proposed fixup, the before/after looks like this:

Before	After

This corresponds to git#2122 Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>

This branch was developed to generate before/after comparisons a là git#2122 (comment) Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>

dscho requested changes Jan 3, 2026

View reviewed changes

dscho reviewed Jan 3, 2026

View reviewed changes

Subhajit-das21 force-pushed the fix/book-dark-code branch from 66a00e7 to 8325191 Compare January 4, 2026 13:47

dscho added a commit to dscho/git-scm.com that referenced this pull request Jan 5, 2026

Merge branch 'fix/book-dark-code' into gh-pages

6421888

This corresponds to git#2122 Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>

dscho added a commit to dscho/git-scm.com that referenced this pull request Jan 6, 2026

Merge branch 'fix/book-dark-code' into gh-pages

a5fd96a

This corresponds to git#2122 Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>

dscho added a commit to dscho/git-scm.com that referenced this pull request Jan 6, 2026

Merge branch 'compare-screenshots'

7b279e7

This branch was developed to generate before/after comparisons a là git#2122 (comment) Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>

		background-color: var(--color-canvas-inset);
		color: var(--color-fg-default);

Fix dark mode styling for code blocks in Book pages #2122

Are you sure you want to change the base?

Fix dark mode styling for code blocks in Book pages #2122

Conversation

Subhajit-das21 commented Jan 2, 2026

Uh oh!

dscho left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Subhajit-das21 Jan 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dscho Jan 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Subhajit-das21 Jan 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jnavila commented Jan 3, 2026

Uh oh!

Subhajit-das21 commented Jan 3, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dscho left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Subhajit-das21 commented Jan 4, 2026

Uh oh!

michaelblyons commented Jan 4, 2026

Uh oh!

dscho commented Jan 5, 2026

Uh oh!

dscho commented Jan 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Subhajit-das21 Jan 3, 2026 •

edited

Loading

dscho Jan 3, 2026 •

edited

Loading

Subhajit-das21 Jan 3, 2026 •

edited

Loading