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