Fix: Support mapping links to full URLs from hint Github repo

Fix #933
Close #934

Author: sarvaje

helpers/update-site/documentation.js

@@ -524,22 +524,56 @@ const getFilesInfo = (files) => {
 };
 
 /** Updates the markdown links to other parts of the documentation, i.e.: start with "./" */
-const updateMarkdownlinks = (content, filePath) => {
+const updateMarkdownlinks = (file) => {
+    const content = file.content;
+    const filePath = file.orig || file.dest;
     /**
      * This regex should match the following examples:
      * * [link label]: ./somewhere.md → \s
      * * [link label]:./somewhere.md → :
      * * [link](./somewhere.md)  → \(
+     * * [link](https://github.com/webhintio/hint/blob/HEAD/path-to-file/file.md)
+     * * [link]: https://github.com/webhintio/hint/blob/HEAD/path-to-file/file.md
+     * * [link]:https://github.com/webhintio/hint/blob/HEAD/path-to-file/file.md
      *
      * The \.? allow us to also match "../"
      */
-    const mdLinkRegex = /(\s|:|\()\.?\.\/(\S*?)\.md/gi;
+    const mdLinkRegex = /(]:\s*|]\()(\.?\.\/|https:\/\/github.com\/webhintio\/hint\/blob\/HEAD\/(packages\/)?)(\S*?)\.md/gi;
     const isIndex = filePath.toLowerCase().endsWith('index.md');
     let transformed = content;
     let val;
 
     while ((val = mdLinkRegex.exec(content)) !== null) {
         /**
+         * Values:
+         *
+         * val[0]: Full string matched. E.g:
+         * * - `](./getting-started/architecture.md`
+         * * - `]: ../../user-guide/index.md`
+         * * - `](https://github.com/webhintio/hint/blob/HEAD/packages/hint/docs/user-guide/troubleshoot/summary.md`
+         *
+         * val[1]: First group matched (]:\s*|]\(). E.g:
+         * * - `](`
+         * * - `]: `
+         * * - `](`
+         *
+         * val[2]: Second group matched
+         *   (\.?\.\/|https:\/\/github.com\/webhintio\/hint\/blob\/HEAD\/(packages\/)?)
+         * E.g:
+         * * - `./`
+         * * - `../`
+         * * - `https://github.com/webhintio/hint/blob/HEAD/packages/`
+         *
+         * val[3]: Third group matched (packages\/). E.g:
+         * * - `undefined`
+         * * - `undefined`
+         * * - `packages/`
+         *
+         * val[4]: fourth group matched (\S*?). E.g:
+         * * - getting-started/architecture
+         * * - ../user-guide/index
+         * * - hint/docs/user-guide/troubleshoot/summary
+         *
          * Pages in the live site are `index.html` inside a folder with the name of the original page. E.g.:
          *
          * * `/user-guide/concepts/connectors.md` → `/user-guide/concepts/connectors/
@@ -564,14 +598,31 @@ const updateMarkdownlinks = (content, filePath) => {
             val[0].replace(/(index|readme)\.md/i, '') :
             val[0].replace('.md', '/');
 
+        /*
+         * An github url is found for a md file.
+         * In this case we need to replace it with the a valid
+         * url in the website.
+         */
+        if (val[2].startsWith('https://github.com/')) {
+            /*
+             * Documentation in the package hint has to be parsed in a diferent way
+             * because it already has the folder structure in place.
+             */
+            if (val[4].startsWith('hint/docs/user-guide')) {
+                replacement = `${val[1]}${val[4].substr(4)}`;
+            } else {
+                replacement =
+                    `${val[1]}/docs/${file.frontMatter.section}${file.frontMatter.tocTitle ? `/${file.frontMatter.tocTitle.replace(' ', '-')}` : ''}/${val[4].replace('/docs/', '/')}/`;
+            }
+        }
         /**
          * If val[0] contains './docs/ then, it is part of a multi-hint hint, so
          * we need to ignore it.
          * Later in the the `link-filter.js`, the link will be replaced for the final one.
          */
         if (!val[0].includes('./docs/')) {
             /**
-             * `val[1] is the first capturing group. It could be "\s", ":", or "("
+             * `val[1] is the first capturing group. It could be "]:\s", "]:", or "]("
              * and it's part of the matched value so we need to add it at the beginning as well. E.g.:
              *
              * * `[events](./events.md)` will match `(./events.md` that needs to be transformed into `(../events/`.
@@ -595,7 +646,7 @@ const updateLinks = (files) => {
             return;
         }
 
-        file.content = updateMarkdownlinks(file.content, file.orig || file.dest);
+        file.content = updateMarkdownlinks(file);
     });
 };