Skip to content

fix: unreadable text in markdown code blocks (light mode)#234

Merged
backnotprop merged 2 commits intobacknotprop:mainfrom
dgrissen2:fix/markdown-codeblock-highlighting
Mar 7, 2026
Merged

fix: unreadable text in markdown code blocks (light mode)#234
backnotprop merged 2 commits intobacknotprop:mainfrom
dgrissen2:fix/markdown-codeblock-highlighting

Conversation

@dgrissen2
Copy link
Contributor

Problem

Text in ```markdown ``` code blocks appears "washed out" in light mode. Large sections become nearly invisible — italic, faded, and hard to read.

Root cause: highlight.js's markdown grammar tokenizes underscores, asterisks, and backticks as formatting spans (.hljs-emphasis, .hljs-strong, .hljs-code). The github-dark theme assigns these tokens colors designed for dark backgrounds:

Token Theme color Appearance in light mode
.hljs-emphasis #c9d1d9 + italic Faded italic text — worst offender, since underscores in variable names like data_quality_good get parsed as emphasis, wrapping entire paragraphs
.hljs-strong #c9d1d9 + bold Faded bold text (**QUANT.** etc.)
.hljs-code #8b949e Gray text for `backtick` inline code markers

The existing light-mode overrides in index.css correctly handle keywords, strings, comments, and numbers — but these three tokens were missed.

Fix

Added CSS overrides (14 lines in packages/editor/index.css) that force the three affected tokens to inherit the base code color, which is already correctly set for light mode by .light pre code.hljs:

pre code.hljs .hljs-emphasis {
  color: inherit !important;
  font-style: normal !important;
}
pre code.hljs .hljs-strong {
  color: inherit !important;
}
pre code.hljs .hljs-code {
  color: inherit !important;
}
  • !important is needed because Tailwind v4's CSS cascade layers give the unlayered github-dark theme higher priority than the layered user styles
  • .hljs-emphasis also removes font-style: italic since underscores in variable names are not actual emphasis
  • .hljs-strong keeps font-weight: 700 (only color is overridden)
  • Follows the existing override pattern already used in the file for .light .hljs-keyword, .light .hljs-string, etc.

Scope

  • One file changed: packages/editor/index.css
  • No JS/TS changes
  • No behavioral changes — only visual fix for light-mode code block readability
  • Dark mode is unaffected (inherit resolves to the same #c9d1d9 base color)

Testing

Tested locally by loading a markdown file containing dense variable names with underscores, bold markers, and backtick code spans in a ```markdown ``` code block. Verified in Chrome DevTools that getComputedStyle returns inherited colors and font-style: normal for affected elements.

Before:
Text between underscores rendered as faded italic, **bold** markers nearly invisible, backtick code gray on light background.

After:
All code block text renders at uniform readable weight and color in both light and dark modes.

highlight.js's markdown grammar tokenizes underscores, asterisks, and
backticks as emphasis/strong/code spans. The github-dark theme assigns
these tokens colors (#c9d1d9, #8b949e) that are nearly invisible against
light backgrounds, making large sections of markdown code blocks appear
"washed out."

The existing light-mode overrides in index.css cover keywords, strings,
comments, and numbers — but not .hljs-emphasis, .hljs-strong, or
.hljs-code. This patch forces those three token types to inherit the
base code color, which is already correctly overridden for light mode.

Tokens fixed:
- .hljs-emphasis: underscores in variable names (e.g. data_quality_good)
  were parsed as italic emphasis — now inherits color, removes italic
- .hljs-strong: **bold** markers used #c9d1d9 — now inherits color
- .hljs-code: `backtick` inline code markers used #8b949e — now inherits

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Copy link

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Adjusts highlight.js token styling so markdown code blocks remain readable in light mode when the github-dark theme is used.

Changes:

  • Add overrides for .hljs-emphasis, .hljs-strong, and .hljs-code inside pre code.hljs to inherit the base code color (and disable italics for emphasis).

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment on lines +148 to +160
/* Fix: hljs markdown grammar applies github-dark token colors that are unreadable
in light mode. Emphasis/strong/code tokens use #c9d1d9 or #8b949e which wash out
against light backgrounds. Force them to inherit the base code color. */
pre code.hljs .hljs-emphasis {
color: inherit !important;
font-style: normal !important;
}
pre code.hljs .hljs-strong {
color: inherit !important;
}
pre code.hljs .hljs-code {
color: inherit !important;
}
Copy link

Copilot AI Mar 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These overrides are not scoped to light mode (no .light prefix), so they will also apply in dark mode and globally remove .hljs-emphasis italics via font-style: normal !important. This conflicts with the stated scope (“light mode”, “dark mode unaffected”) and may affect any highlighted language that emits .hljs-emphasis/.hljs-strong/.hljs-code tokens. Consider scoping the selectors to light mode (and optionally to markdown only, e.g. code.hljs.language-markdown / language-md) so the fix is limited to the intended case.

Copilot uses AI. Check for mistakes.
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@dgrissen2 thoughts on this?

Ill test soon!

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the dark/light mode is a bit of red herring. I built this with claude (naturally) and was using light mode at the time. I tested with both light and dark and it worked fine. I uploaded a test file to the branch that you can see as well: test-markdown-highlighting.md.

Contains a ```markdown code block with underscores in variable names,
**bold** markers, and `backtick` code — all patterns that trigger the
washed-out text rendering this PR fixes.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@backnotprop backnotprop merged commit 4c87a8d into backnotprop:main Mar 7, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants