The Comma That Leaked Styles Across an Entire IDE

The smallest diffs are sometimes the most fun. ~ myself

Not every bug crashes. Some just sit quietly in a stylesheet, doing exactly what you told them to — which turns out to be the problem. This is the story of a single missing class name that reached out of a markdown preview and gently restyled every heading in an entire IDE.

Finding the thread

I'd been scrolling Eclipse Theia's issue tracker filtered by good first issue. Theia is the framework a huge amount of "VS Code in the browser" tooling is built on, so I knew anything I fixed there wouldn't stay in one quiet corner — it could ripple out to every editor built on top of it.

Then a title caught my eye: "Markdown preview header styles leak." Leak? How does a preview panel leak anything? I had to know.

The scene of the crime

The report pointed at exactly one file — packages/preview/src/browser/markdown/style/markdown.css — and a few lines in, there it was:

.markdown-preview h1,
h2,
h3 {
  font-weight: normal;
}

Read that out loud in English and it sounds perfectly reasonable: "make h1, h2, and h3 inside the markdown preview normal weight." That's clearly what the original author meant.

But CSS doesn't read English.

What the browser actually sees

Here's the twist that makes this such a satisfying little bug. A comma in a CSS selector doesn't continue the previous scope — it starts a brand-new, independent selector. So the browser doesn't see one scoped rule. It sees three:

.markdown-preview h1 → headings inside the preview ✅
 h2 → every <h2> in the whole application ❌
 h3 → every <h3> in the whole application ❌

The .markdown-preview prefix only ever attached to that first line. The other two escaped into the global stylesheet and went wandering. Every section heading across Theia — the Welcome page, the Extensions view, Settings — was being quietly forced to font-weight: normal, stripped of the bold it was supposed to have.

Nothing threw an error. Nothing broke. It just looked subtly wrong everywhere, and obviously wrong nowhere. My favorite kind of mystery.

The one-line fix (times three)

The fix is almost anticlimactic — give each selector the scope it was always supposed to have:

.markdown-preview h1,
.markdown-preview h2,
.markdown-preview h3 {
  font-weight: normal;
}

Now all three rules are anchored to .markdown-preview. The preview keeps its normal-weight headings; the rest of the IDE gets its boldness back.

Trust, but verify

A CSS one-liner is exactly the kind of change you're tempted to eyeball and ship. I didn't want to guess, so I built and ran Theia locally:

npm run compile
npm run build:browser
npm run start:browser

Then I opened a markdown preview (headings still normal-weight — correct), and jumped over to the Welcome page and Extensions view to confirm their h2 h3 headings were bold again. Before the fix they'd been washed out; after, they stood up the way the rest of the UI expected. Watching the regression vanish in the actual running app is a completely different kind of confidence than "the diff looks right."

First-time Eclipse contributor? Don't skip the DCO

Every Eclipse commit needs a Developer Certificate of Origin sign-off, and the ECA bot will block your PR without it. It's a single flag:

git commit -s -m "fix(preview): scope markdown header styles to .markdown-preview"

The -s appends a Signed-off-by: line from your git user.name / user.email — and that email must match the one on your signed Eclipse Contributor Agreement, or the check still fails.

Shipping it

I opened PR #17824, signed the commit off for the Eclipse DCO git commit -s, and wrote a conventional-commit subject describing the scope fix. Maintainer colin grant work reviewed, approved, and merged it into master — and it shipped as part of Theia 1.74.0.

One comma's worth of misunderstanding, one prefix repeated twice, and an IDE's headings stand up straight again.

On to the next issue.