doc: mitigate `marked` bug
Checklist
-
make -j4 test
(UNIX), orvcbuild test
(Windows) passes -
documentation is changed or added -
commit message follows commit guidelines
Status quo
3cb8e64e + 647954d0 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