doc: fix code display in header glitch

[Trott]

Fixes: #31451

@GeoffreyBooth @nodejs/website

Before:

After:

Checklist

• make -j4 test (UNIX), or vcbuild test (Windows) passes
• commit message follows commit guidelines

[himself65]

I think the background-color be dark gray is better

[XhmikosR]

Not sure if this really fixes the linked issue since AFAICT it's about rendering code blocks differently.

That being said, not only padding but like most of the other properties could/should be removed. I don't have the time to dig into it more, but you should try:

style.cssh1code,h2code,h3code,h4code,h5code,h6code{- font-weight: 700; - line-height: inherit; - position: relative; - margin: 1.5rem 0 1rem; - padding: inherit; - text-rendering: optimizeLegibility}

which means separate the selectors like it was before your other patch.

[Trott]

I think the background-color be dark gray is better

That was intentionally omitted in headers, but now I can't remember why. I have a note-to-self to go back and see about making code blocks use a monospace font in headers, though.

[Trott]

Not sure if this really fixes the linked issue since AFAICT it's about rendering code blocks differently.

The main complaint there, I think, is the big jarring spacing. So it fixes that. Minimal incremental change.

[Trott]

I think the background-color be dark gray is better

That was intentionally omitted in headers, but now I can't remember why. I have a note-to-self to go back and see about making code blocks use a monospace font in headers, though.

I think it was omitted in headers because then every single method and property would have the background and it was kind of jarring in headers. There might have also been an accessibility/contrast issue, but I'm not sure. We can try it, but I'd really greatly prefer to have that be separate from this spacing issue. The spacing issue should definitely be fixed immediately. The background color is a different thing and we can iterate that over time.

[Trott]

That being said, not only padding but like most of the other properties could/should be removed. I don't have the time to dig into it more, but you should try:

style.cssh1code,h2code,h3code,h4code,h5code,h6code{- font-weight: 700; - line-height: inherit; - position: relative; - margin: 1.5rem 0 1rem; - padding: inherit; - text-rendering: optimizeLegibility}

which means separate the selectors like it was before your other patch.

Happy to try that (and happier to have someone who knows what they're doing try that) but I'd really like to just get the spacing fixed with as few unanticipated side effects as possible, so I'd prefer this go in first and then someone (possibly me) can experiment with further revisions.

[Trott]

I think the background-color be dark gray is better

That was intentionally omitted in headers, but now I can't remember why. I have a note-to-self to go back and see about making code blocks use a monospace font in headers, though.

I think it was omitted in headers because then every single method and property would have the background and it was kind of jarring in headers. There might have also been an accessibility/contrast issue, but I'm not sure. We can try it, but I'd really greatly prefer to have that be separate from this spacing issue. The spacing issue should definitely be fixed immediately. The background color is a different thing and we can iterate that over time.

Oh, you know what? It might have been the padding had a grey background too so all the entries had this weird trail of grey background. So yeah, after this change, the background color change may work just fine.....

[XhmikosR]

The main complaint there, I think, is the big jarring spacing. So it fixes that. Minimal incremental change.

Either way, one should look into splitting the selectors and removing redundant properties at some point. Not super-important but it should be done eventually.

Just my 2 cents.

Happy to try that (and happier to have someone who knows what they're doing try that) but I'd really like to just get the spacing fixed with as few unanticipated side effects as possible, so I'd prefer this go in first and then someone (possibly me) can experiment with further revisions.

I can try to make a patch, I just don't have the time to build the docs so I can only quickly verify the changes in my browser.

[Trott]

I just don't have the time to build the docs so I can only quickly verify the changes in my browser.

FWIW, make doc-only should run reasonably quickly. Takes about 40 seconds on my 7-year-old laptop. (make doc on the other hand...that can take some time....)

[XhmikosR]

Yeah, my main dev VM is Windows. I know how to make it work, but I'd rather if things were truly cross-platform.

Regardless, this PR does fix the weird space issue which was caused by inheriting the padding, so LGTM.

An untested cleanup patch is here: https://github.com/XhmikosR/node/compare/master...XhmikosR-patch-1

[GeoffreyBooth]

Personally I expect a code block in a heading to look similarly to how GitHub renders them:

Heading with code

As in, code blocks in headings shouldn't be different from code blocks in body text, other than the font size.

[Trott]

Personally I expect a code block in a heading to look similarly to how GitHub renders them:

Heading with code

As in, code blocks in headings shouldn't be different from code blocks in body text, other than the font size.

Agreed. I'd prefer that be a subsequent enhancement.

[Trott]

Landed in d32a715