From c9544afa010a7d36fe9db8e0d1604aab69244e12 Mon Sep 17 00:00:00 2001
From: Patrik Oldsberg <poldsberg@gmail.com>
Date: Tue, 1 Dec 2020 20:23:02 +0100
Subject: [PATCH 1/2] scripts/verify-links: forbid relative links out of docs

---
 docs/auth/index.md      |  2 +-
 scripts/verify-links.js | 20 ++++++++++++++++++++
 2 files changed, 21 insertions(+), 1 deletion(-)

diff --git a/docs/auth/index.md b/docs/auth/index.md
index 3f95efaf61..cf468c7bb7 100644
--- a/docs/auth/index.md
+++ b/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.
diff --git a/scripts/verify-links.js b/scripts/verify-links.js
index 0422352d4e..ac2941c1fd 100755
--- a/scripts/verify-links.js
+++ b/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 docks 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) ||

From 34bc80d8b2ddea41eb980d97c9358ce1602de96d Mon Sep 17 00:00:00 2001
From: Patrik Oldsberg <poldsberg@gmail.com>
Date: Thu, 3 Dec 2020 15:07:37 +0100
Subject: [PATCH 2/2] Apply suggestions from code review

---
 scripts/verify-links.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/scripts/verify-links.js b/scripts/verify-links.js
index ac2941c1fd..75e7a8c1d0 100755
--- a/scripts/verify-links.js
+++ b/scripts/verify-links.js
@@ -158,7 +158,7 @@ async function main() {
         );
       } else if (problem === 'out-of-docs') {
         console.error(
-          'Links in docks must use absolute URLs for targets outside of docs',
+          'Links in docs must use absolute URLs for targets outside of docs',
         );
         console.error(`  From: ${basePath}`);
         console.error(`  To: ${url}`);