doc: mitigate marked bug

[vsemozhetbyt]

Checklist

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

Status quo

3cb8e64 + 647954d have fixed a method signature, but caused link rendering issues in 2 places of the HTML doc:

• see this nightly doc section or a screenshot with the issue in red frame.

• see this nightly doc section or a screenshot with the issue in red frame.

In the GitHub docs, both links are rendered properly: see here and here.

The cause

We have rather an old version of marked module and it seems it has a parsing bug for this pattern:

• link text in code backticks
• with two sibling pairs of square brackets
• with one or more nested square brackets in the first sibling.

Minimal reproduction:

'use strict';

const marked = require('tools/doc/node_modules/marked/');

const md = `
A [\`[[]][]\`][ref].

[ref]: #hash
`;

const tokens = marked.lexer(md);
console.log(tokens);

const html = marked.parser(tokens);
console.log(`\n${html}`);

[ { type: 'paragraph', text: 'A [`[[]][]`][ref].' },
  links: { ref: { href: '#hash', title: undefined } } ]

<p>A [<code>[[]][]</code>]<a href="#hash">ref</a>.</p>

In this case, marked renders the first link part as a code fragment in non-code square brackets, and then renders the second part as a link inferring both the text and the URL from it.

What can we do

The bug is fixed in marked master. Compare the output from the tip-of-tree:

[ { type: 'text', text: 'A [`[[]][]`][ref].' },
  { type: 'space' },
  links: { ref: { href: '#hash', title: undefined } } ]

<p>A <a href="#hash"><code>[[]][]</code></a>.</p>

But it seems we cannot update now as marked is still unstable, has possible new bugs and experiences turbulent renewal (see issue with a comment).

So we can use this workaround till marked 1.0 is released. See screenshots of fixed links and here and here.

If we should add any HTML comments in these places with PR URL or TODO instructions, please, suggest the wording and format.

cc @nodejs/documentation

[vsemozhetbyt]

Node.js Collaborators, please, add 👍 here if you approve fast-tracking.

[vsemozhetbyt]

CI-lite: https://ci.nodejs.org/job/node-test-commit-lite/804/

[trivikr]

Confirmed that links appear correctly in net.md in private branch

[BridgeAR]

@vsemozhetbyt just as a question: did you check intermediate versions as well?

[vsemozhetbyt]

@BridgeAR
For this bug, I've only checked master. But I've checked the last v0.3.19 skin-deep to find out if there were any breaking changes and if we can update painlessly, and there were some quirks. So I've decided to not bother them till 1.0 according to the response.

[vsemozhetbyt]

Landed in 536b1fb
Thanks for the reviews.