Merge pull request #1933 from spotify/rugvip/noabs

docs: avoid absolute links to docs + verify with script

docs/overview/what-is-backstage.md

@@ -14,15 +14,15 @@ to create a streamlined development environment from end to end.
 
 Out of the box, Backstage includes:
 
-- [Backstage Service Catalog](https://github.com/spotify/backstage/blob/master/docs/features/software-catalog/index.md)
-  for managing all your software (microservices, libraries, data pipelines,
+- [Backstage Service Catalog](/docs/features/software-catalog/index.md) for
+  managing all your software (microservices, libraries, data pipelines,
   websites, ML models, etc.)
-- [Backstage Software Templates](https://github.com/spotify/backstage/blob/master/docs/features/software-templates/index.md)
-  for quickly spinning up new projects and standardizing your tooling with your
+- [Backstage Software Templates](/docs/features/software-templates/index.md) for
+  quickly spinning up new projects and standardizing your tooling with your
   organization’s best practices
-- [Backstage TechDocs](https://github.com/spotify/backstage/tree/master/docs/features/techdocs)
-  for making it easy to create, maintain, find, and use technical documentation,
-  using a "docs like code" approach
+- [Backstage TechDocs](/docs/features/techdocs) for making it easy to create,
+  maintain, find, and use technical documentation, using a "docs like code"
+  approach
 - Plus, a growing ecosystem of
   [open source plugins](https://github.com/spotify/backstage/tree/master/plugins)
   that further expand Backstage’s customizability and functionality

docs/verify-links.js

@@ -17,12 +17,21 @@
 
 const { resolve: resolvePath, dirname } = require('path');
 const fs = require('fs-extra');
-const fetch = require('node-fetch');
 const recursive = require('recursive-readdir');
 
 const projectRoot = resolvePath(__dirname, '..');
 
 async function verifyUrl(basePath, url) {
+  // Avoid having absolute URL links within docs/, so that links work on the site
+  if (
+    url.match(
+      /https:\/\/github.com\/spotify\/backstage\/(tree|blob)\/master\/docs\//,
+    ) &&
+    basePath.match(/^(?:docs|microsite)\//)
+  ) {
+    return { url, basePath, problem: 'absolute' };
+  }
+
   url = url.replace(/#.*$/, '');
   url = url.replace(
     /https:\/\/github.com\/spotify\/backstage\/(tree|blob)\/master/,
@@ -39,7 +48,7 @@ async function verifyUrl(basePath, url) {
       : resolvePath(dirname(resolvePath(projectRoot, basePath)), url);
     const exists = await fs.pathExists(path);
     if (!exists) {
-      return { url, basePath };
+      return { url, basePath, problem: 'missing' };
     }
   }
 
@@ -76,8 +85,14 @@ async function main() {
 
   if (badUrls.length) {
     console.log(`Found ${badUrls.length} bad links within repo`);
-    for (const { url, basePath } of badUrls) {
-      console.error(`Unable to reach ${url}, linked from ${basePath}`);
+    for (const { url, basePath, problem } of badUrls) {
+      if (problem === 'missing') {
+        console.error(`Unable to reach ${url}, linked from ${basePath}`);
+      } else if (problem === 'absolute') {
+        console.error(`Link to docs/ should be replaced by a relative URL`);
+        console.error(`  From: ${basePath}`);
+        console.error(`  To: ${url}`);
+      }
     }
     process.exit(1);
   }