doc: fix word wrapping for api stability boxes

[saadq]

Checklist

• documentation is changed or added
• commit message follows commit guidelines

Affected core subsystem(s)

doc

---

This is meant to fix the issue that was opened here originally.

Fixes: nodejs/nodejs.org#1337

Before:

After:

[silverwind]

Is there a reason why these boxes are <pre>? Doesn't seem semantically correct to me, and the fact that they inherit rules targeting code blocks isn't ideal either.

I'd change them to <div> and add padding: 1em to them.

[refack]

Is there a reason why these boxes are <pre>? Doesn't seem semantically correct to me, and the fact that they inherit rules targeting code blocks isn't ideal either.

I think it's because it's rendered markdown. A simple style change might be to replace the ``` with >

or exclude pre[lang=txt] from the css

[silverwind]

@refack nope, they are generated by our own code:

node/tools/doc/html.js

Line 403 in 314217f

`<pre class="${classNames}"><a href="${docsUrl}">$1 $2</a>$3</pre>`

[refack]

Mostly enjoying the new code line quoting 👐

@refack nope, they are generated by our own code:

AFAICT that's the header for each API endpoint:

node/tools/doc/html.js

Line 33 in 314217f

const STABILITY_TEXT_REG_EXP = /(.*:)\s*(\d)([\s\S]*)/;

node/tools/doc/html.js

Lines 397 to 406 in 314217f

	function parseAPIHeader(text) {
	const classNames = 'api_stability api_stability_$2';
	const docsUrl = 'documentation.html#documentation_stability_index';
	text = text.replace(
	STABILITY_TEXT_REG_EXP,
	`<pre class="${classNames}"><a href="${docsUrl}">$1 $2</a>$3</pre>`
	);
	return text;
	}

That maps:

node/doc/api/crypto.md

Lines 678 to 684 in 2e7ccc2

	### ecdh.setPublicKey(publicKey[, encoding])
	<!-- YAML
	added: v0.11.14
	deprecated: v5.2.0
	-->
	> Stability: 0 - Deprecated

to:

---

Anyway let's do both: replace the markup and the rendering code

[silverwind]

@refack I'm still pretty sure that <pre> comes from there, the changelog (.api_metadata) is generated elsewhere.

Anyways, my suggestion to @saadq would be to replace the <pre> with a <div> in html.js and add padding: 1em to .api_stability in CSS.

[saadq]

I agree that pre probably wasn't that semantically correct, so I changed it to div as you suggested. However, this cause some stylistic issues:

After changing pre -> div

The font-weight became a lot bolder and the line-height became smaller, so I added a couple of styles to make it look like it did when it was still using pre.

After adding/removing some additional styles

Does this look alright to everyone?

[silverwind]

Looking fine to me, thanks.

[TimothyGu]

Are these (esp. the font and wrapping ones) still necessary now that the container has been switched to a <div>?

[saadq]

Ahh, you're right. Since it's not pre anymore, the wrapping is no longer an issue. The padding and line-height are still necessary though.

[saadq]

I reverted the wrapping changes. Just to clarify, I don't know if the line-height is strictly "necessary", I just added it because that was what the pre had originally. I'm not sure if you all think it looks fine without it.

Without line-height:

With line-height:

[silverwind]

I think I like it more with the extra space. Another option would be to make it a <p> which already sets 1.5em line-height and a similar margin-bottom, so you save two declarations.

[silverwind]

Thought, it might be unexpected to have <p> and those boxes share CSS. So, LGTM as-is.

A bunch of other people are looking at this more closely and with more expertise than I bring to CSS etc. Plus, my review is from a version of this PR that is now several iterations old. Dismissing my review and letting the knowledgable folks handle it instead. Thanks!

[silverwind]

Thought, it might be unexpected to have <p> and those boxes share CSS. So, LGTM as-is.

[tniessen]

Landed in eab2bea.