Merge pull request #3516 from backstage/rugvip/linkfix

scripts/verify-links: forbid relative links out of docs

docs/auth/index.md

@@ -93,6 +93,6 @@ sign-in methods.
 More details are provided in dedicated sections of the documentation.
 
 - [OAuth](./oauth.md): Description of the generic OAuth flow implemented by the
-  [auth-backend](../../plugins/auth-backend).
+  [auth-backend](https://github.com/backstage/backstage/tree/master/plugins/auth-backend).
 - [Glossary](./glossary.md): Glossary of some common terms related to the auth
   flows.

scripts/verify-links.js

@@ -74,6 +74,14 @@ async function verifyUrl(basePath, absUrl, docPages) {
     path = resolvePath(dirname(resolvePath(projectRoot, basePath)), url);
   }
 
+  if (
+    absUrl === url &&
+    basePath.match(/^(?:docs)\//) &&
+    !path.startsWith(resolvePath(projectRoot, 'docs'))
+  ) {
+    return { url, basePath, problem: 'out-of-docs' };
+  }
+
   const exists = await fs.pathExists(path);
   if (!exists) {
     return { url, basePath, problem: 'missing' };
@@ -148,6 +156,18 @@ async function main() {
         console.error(
           `Unable to reach ${url} from root or microsite/static/, linked from ${basePath}`,
         );
+      } else if (problem === 'out-of-docs') {
+        console.error(
+          'Links in docs must use absolute URLs for targets outside of docs',
+        );
+        console.error(`  From: ${basePath}`);
+        console.error(`  To: ${url}`);
+        console.error(
+          `  Likely replace with: https://github.com/backstage/backstage/blob/master/${url.replace(
+            /^[./]+/,
+            '',
+          )}`,
+        );
       } else if (problem === 'doc-missing') {
         const suggestion =
           docPages.get(url) ||