Skip to content

Commit

Permalink
tools: flatten apidoc headers
Browse files Browse the repository at this point in the history
ensure optional parameters are not treated as markedown links by
replacing the children of headers nodes with a single text node
containing the raw markup;

Fixes issue identified in
#21490 (comment)

PR-URL: #21936
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
Reviewed-By: Minwoo Jung <minwoo@nodesource.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
  • Loading branch information
rubys authored and vsemozhetbyt committed Jul 25, 2018
1 parent e83126a commit 83474ae
Showing 1 changed file with 21 additions and 6 deletions.
27 changes: 21 additions & 6 deletions tools/doc/html.js
Original file line number Diff line number Diff line change
Expand Up @@ -175,9 +175,9 @@ function linkJsTypeDocs(text) {
return parts.join('`');
}

// Preprocess stability blockquotes and YAML blocks
// Preprocess headers, stability blockquotes, and YAML blocks.
function preprocessElements({ filename }) {
return (tree) => {
return (tree, file) => {
const STABILITY_RE = /(.*:)\s*(\d)([\s\S]*)/;
let headingIndex = -1;
let heading = null;
Expand All @@ -187,6 +187,22 @@ function preprocessElements({ filename }) {
headingIndex = index;
heading = node;

// Ensure optional API parameters are not treated as links by
// collapsing all of heading into a single text node.
if (heading.children.length > 1) {
const position = {
start: heading.children[0].position.start,
end: heading.position.end
};

heading.children = [{
type: 'text',
value: file.contents.slice(
position.start.offset, position.end.offset),
position
}];
}

} else if (node.type === 'html' && common.isYAMLBlock(node.value)) {
node.value = parseYAML(node.value);

Expand Down Expand Up @@ -331,10 +347,9 @@ function buildToc({ filename }) {

depth = node.depth;
const realFilename = path.basename(realFilenames[0], '.md');
const headingText = node.children.map((child) =>
file.contents.slice(child.position.start.offset,
child.position.end.offset)
).join('').trim();
const headingText = file.contents.slice(
node.children[0].position.start.offset,
node.position.end.offset).trim();
const id = getId(`${realFilename}_${headingText}`, idCounters);

const hasStability = node.stability !== undefined;
Expand Down

0 comments on commit 83474ae

Please sign in to comment.