131d0d8e8a
This would cause dangling links since the target, being internal, would not exist in the docs. PR Close #24000
82 lines
3.5 KiB
JavaScript
82 lines
3.5 KiB
JavaScript
const visit = require('unist-util-visit-parents');
|
|
const is = require('hast-util-is-element');
|
|
const textContent = require('hast-util-to-string');
|
|
|
|
/**
|
|
* Automatically add in a link to the relevant document for code blocks.
|
|
* E.g. `<code>MyClass</code>` becomes `<code><a href="path/to/myclass">MyClass</a></code>`
|
|
*
|
|
* @property docTypes an array of strings.
|
|
* Only docs that have one of these docTypes will be linked to.
|
|
* Usually set to the API exported docTypes, e.g. "class", "function", "directive", etc.
|
|
*
|
|
* @property customFilters array of functions `(docs, words, wordIndex) => docs` that will filter
|
|
* out docs where a word should not link to a doc.
|
|
* - `docs` is the array of docs that match the link `word`
|
|
* - `words` is the collection of words parsed from the code text
|
|
* - `wordIndex` is the index of the current `word` for which we are finding a link
|
|
*
|
|
* @property codeElements an array of strings.
|
|
* Only text contained in these elements will be linked to.
|
|
* Usually set to "code" but also "code-example" for angular.io.
|
|
*/
|
|
module.exports = function autoLinkCode(getDocFromAlias) {
|
|
autoLinkCodeImpl.docTypes = [];
|
|
autoLinkCodeImpl.customFilters = [];
|
|
autoLinkCodeImpl.codeElements = ['code'];
|
|
return autoLinkCodeImpl;
|
|
|
|
function autoLinkCodeImpl() {
|
|
return (ast) => {
|
|
visit(ast, 'element', (node, ancestors) => {
|
|
// Only interested in code elements that are not inside links
|
|
if (autoLinkCodeImpl.codeElements.some(elementType => is(node, elementType)) &&
|
|
ancestors.every(ancestor => !is(ancestor, 'a'))) {
|
|
visit(node, 'text', (node, ancestors) => {
|
|
// Only interested in text nodes that are not inside links
|
|
if (ancestors.every(ancestor => !is(ancestor, 'a'))) {
|
|
|
|
const parent = ancestors[ancestors.length-1];
|
|
const index = parent.children.indexOf(node);
|
|
|
|
// Can we convert the whole text node into a doc link?
|
|
const docs = getDocFromAlias(node.value);
|
|
if (foundValidDoc(docs)) {
|
|
parent.children.splice(index, 1, createLinkNode(docs[0], node.value));
|
|
} else {
|
|
// Parse the text for words that we can convert to links
|
|
const nodes = textContent(node).split(/([A-Za-z0-9_.-]+)/)
|
|
.filter(word => word.length)
|
|
.map((word, index, words) => {
|
|
// remove docs that fail the custom filter tests
|
|
const filteredDocs = autoLinkCodeImpl.customFilters.reduce((docs, filter) => filter(docs, words, index), getDocFromAlias(word));
|
|
return foundValidDoc(filteredDocs) ?
|
|
createLinkNode(filteredDocs[0], word) : // Create a link wrapping the text node.
|
|
{ type: 'text', value: word }; // this is just text so push a new text node
|
|
});
|
|
|
|
// Replace the text node with the links and leftover text nodes
|
|
Array.prototype.splice.apply(parent.children, [index, 1].concat(nodes));
|
|
}
|
|
}
|
|
});
|
|
}
|
|
});
|
|
};
|
|
}
|
|
function foundValidDoc(docs) {
|
|
return docs.length === 1 &&
|
|
!docs[0].internal &&
|
|
autoLinkCodeImpl.docTypes.indexOf(docs[0].docType) !== -1;
|
|
}
|
|
|
|
function createLinkNode(doc, text) {
|
|
return {
|
|
type: 'element',
|
|
tagName: 'a',
|
|
properties: { href: doc.path, class: 'code-anchor' },
|
|
children: [{ type: 'text', value: text }]
|
|
};
|
|
}
|
|
};
|