angular-cn/aio/tools/transforms/angular-base-package/post-processors/auto-link-code.js

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 }]
};
}
};