diff --git a/src/generators/metadata/utils/parse.mjs b/src/generators/metadata/utils/parse.mjs index d5b59059..eb8e6a62 100644 --- a/src/generators/metadata/utils/parse.mjs +++ b/src/generators/metadata/utils/parse.mjs @@ -35,6 +35,7 @@ export const parseApiDoc = ({ file, tree }) => { addYAMLMetadata, updateMarkdownLink, updateTypeReference, + updateUnixManualReference, updateLinkReference, addStabilityMetadata, } = createQueries(); @@ -127,6 +128,13 @@ export const parseApiDoc = ({ file, tree }) => { updateTypeReference(node, parent) ); + // Visits all Unix manual references, and replaces them with links + visit( + subTree, + createQueries.UNIST.isTextWithUnixManual, + (node, _, parent) => updateUnixManualReference(node, parent) + ); + // Removes already parsed items from the subtree so that they aren't included in the final content remove(subTree, [createQueries.UNIST.isYamlNode]); diff --git a/src/utils/parser/constants.mjs b/src/utils/parser/constants.mjs index 381b55d3..fb6f221c 100644 --- a/src/utils/parser/constants.mjs +++ b/src/utils/parser/constants.mjs @@ -3,6 +3,9 @@ // This is the base URL of the MDN Web documentation export const DOC_MDN_BASE_URL = 'https://developer.mozilla.org/en-US/docs/Web/'; +// This is the base URL of the Man7 documentation +export const DOC_MAN_BASE_URL = 'http://man7.org/linux/man-pages/man'; + // This is the base URL for the MDN JavaScript documentation export const DOC_MDN_BASE_URL_JS = `${DOC_MDN_BASE_URL}JavaScript/`; diff --git a/src/utils/parser/index.mjs b/src/utils/parser/index.mjs index b47cf7af..f964ba1f 100644 --- a/src/utils/parser/index.mjs +++ b/src/utils/parser/index.mjs @@ -10,6 +10,7 @@ import { DOC_TYPES_MAPPING_NODE_MODULES, DOC_TYPES_MAPPING_OTHER, DOC_TYPES_MAPPING_PRIMITIVES, + DOC_MAN_BASE_URL, } from './constants.mjs'; import createQueries from '../queries/index.mjs'; @@ -44,6 +45,21 @@ export const normalizeYamlSyntax = yamlContent => { .replace(/^[\r\n]+|[\r\n]+$/g, ''); // Remove initial and final line breaks }; +/** + * @param {string} text The inner text + * @param {string} command The manual page + * @param {string} sectionNumber The manual section + * @param {string} sectionLetter The manual section number + */ +export const transformUnixManualToLink = ( + text, + command, + sectionNumber, + sectionLetter = '' +) => { + return `[\`${text}\`](${DOC_MAN_BASE_URL}${sectionNumber}/${command}.${sectionNumber}${sectionLetter}.html)`; +}; + /** * This method replaces plain text Types within the Markdown content into Markdown links * that link to the actual relevant reference for such type (either internal or external link) diff --git a/src/utils/queries/index.mjs b/src/utils/queries/index.mjs index 6f8875e6..1b168c61 100644 --- a/src/utils/queries/index.mjs +++ b/src/utils/queries/index.mjs @@ -9,6 +9,7 @@ import { parseHeadingIntoMetadata, parseYAMLIntoMetadata, transformTypeToReferenceLink, + transformUnixManualToLink, } from '../parser/index.mjs'; import { getRemark } from '../remark.mjs'; import { transformNodesToString } from '../unist.mjs'; @@ -64,18 +65,17 @@ const createQueries = () => { }; /** - * Updates a Markdown text containing an API type reference - * into a Markdown link referencing to the correct API docs + * Updates a reference * - * @param {import('@types/mdast').Text} node A Markdown link node + * @param {import('@types/mdast').Text} node The current node * @param {import('@types/mdast').Parent} parent The parent node + * @param {string|RegExp} query The search query + * @param {Function} transformer The function to transform the reference + * */ - const updateTypeReference = (node, parent) => { + const updateReferences = (query, transformer, node, parent) => { const replacedTypes = node.value - .replace( - createQueries.QUERIES.normalizeTypes, - transformTypeToReferenceLink - ) + .replace(query, transformer) // Remark doesn't handle leading / trailing spaces, so replace them with // HTML entities. .replace(/^\s/, ' ') @@ -172,7 +172,20 @@ const createQueries = () => { addYAMLMetadata, setHeadingMetadata, updateMarkdownLink, - updateTypeReference, + /** @param {Array} args */ + updateTypeReference: (...args) => + updateReferences( + createQueries.QUERIES.normalizeTypes, + transformTypeToReferenceLink, + ...args + ), + /** @param {Array} args */ + updateUnixManualReference: (...args) => + updateReferences( + createQueries.QUERIES.unixManualPage, + transformUnixManualToLink, + ...args + ), updateLinkReference, addStabilityMetadata, updateStabilityPrefixToLink, @@ -195,6 +208,8 @@ createQueries.QUERIES = { stabilityIndexPrefix: /Stability: ([0-5])/, // ReGeX for retrieving the inner content from a YAML block yamlInnerContent: /^/, + // ReGeX for finding references to Unix manuals + unixManualPage: /\b([a-z.]+)\((\d)([a-z]?)\)/g, }; createQueries.UNIST = { @@ -217,6 +232,12 @@ createQueries.UNIST = { */ isTextWithType: ({ type, value }) => type === 'text' && createQueries.QUERIES.normalizeTypes.test(value), + /** + * @param {import('@types/mdast').Text} text + * @returns {boolean} + */ + isTextWithUnixManual: ({ type, value }) => + type === 'text' && createQueries.QUERIES.unixManualPage.test(value), /** * @param {import('@types/mdast').Html} html * @returns {boolean}