Merge pull request #1952 from spotify/rugvip/fixlinks

docs: update link checking script and fix broken links

docs/FAQ.md

@@ -17,7 +17,7 @@ brand.
 No, but it can be! Backstage is designed to be a developer portal for all your
 infrastructure tooling, services, and documentation. So, it's not a monitoring
 platform — but that doesn't mean you can't integrate a monitoring tool into
-Backstage by writing [a plugin](/docs/FAQ.md#what-is-a-plugin-in-backstage).
+Backstage by writing [a plugin](#what-is-a-plugin-in-backstage).
 
 ### How is Backstage licensed?
 
@@ -38,7 +38,7 @@ more, read our blog post,
 
 Yes, we've already started releasing open source versions of some of the plugins
 we use here, and we'll continue to do so.
-[Plugins](/docs/FAQ.md#what-is-a-plugin-in-backstage) are the building blocks of
+[Plugins](#what-is-a-plugin-in-backstage) are the building blocks of
 functionality in Backstage. We have over 120 plugins inside Spotify — many of
 those are specialized for our use, so will remain internal and proprietary to
 us. But we estimate that about a third of our existing plugins make good open
@@ -145,7 +145,7 @@ This makes it easier to create, find, and update documentation. We hope to
 release
 [the open source version](https://github.com/spotify/backstage/issues/687) in
 the future. (See also:
-"[Will Spotify's internal plugins be open sourced, too?](/docs/FAQ.md#will-spotifys-internal-plugins-be-open-sourced-too)"
+"[Will Spotify's internal plugins be open sourced, too?](#will-spotifys-internal-plugins-be-open-sourced-too)"
 above)
 
 ### Are you planning to have plugins baked into the repo? Or should they be developed in separate repos?

docs/features/software-catalog/installation.md

@@ -49,7 +49,7 @@ Where `backendUrl` is the `backend.baseUrl` from config, i.e.
 `const backendUrl = config.getString('backend.baseUrl')`.
 
 The catalog components depend on a number of other
-[Utility APIs](/docs/api/utility-apis.md) to function, including at least the
+[Utility APIs](../../api/utility-apis.md) to function, including at least the
 `ErrorApi` and `StorageApi`. You can find an example of how to install these in
 your app
 [here](https://github.com/spotify/backstage/blob/61c3a7e5b750dc7c059ef16b188594d31b2c04c2/packages/app/src/apis.ts#L80).

docs/features/software-templates/installation.md

@@ -143,8 +143,8 @@ const service = createServiceBuilder(module)
 At this point the scaffolder backend is installed in your backend package, but
 you will not have any templates available to use. These need to be added to the
 software catalog, as they are represented as entities of kind
-[Template](/docs/features/software-catalog/descriptor-format.md#kind-template).
-You can find out more about adding templates [here](./adding-templates.md).
+[Template](../software-catalog/descriptor-format.md#kind-template). You can find
+out more about adding templates [here](./adding-templates.md).
 
 To get up and running and try out some templates quickly, you can add some of
 our example templates through static configuration. Add the following to the

docs/verify-links.js

@@ -42,14 +42,25 @@ async function verifyUrl(basePath, url) {
   }
 
   // Only verify existence of local files for now, so skip anything with a schema
-  if (!url.match(/[a-z]+:/)) {
-    const path = url.startsWith('/')
-      ? resolvePath(projectRoot, `.${url}`)
-      : resolvePath(dirname(resolvePath(projectRoot, basePath)), url);
-    const exists = await fs.pathExists(path);
-    if (!exists) {
-      return { url, basePath, problem: 'missing' };
+  if (url.match(/[a-z]+:/)) {
+    return;
+  }
+
+  let path = '';
+
+  if (url.startsWith('/')) {
+    if (url.startsWith('/docs/') && basePath.match(/^(?:docs|microsite)\//)) {
+      return { url, basePath, problem: 'not-relative' };
     }
+
+    path = resolvePath(projectRoot, `.${url}`);
+  } else {
+    path = resolvePath(dirname(resolvePath(projectRoot, basePath)), url);
+  }
+
+  const exists = await fs.pathExists(path);
+  if (!exists) {
+    return { url, basePath, problem: 'missing' };
   }
 
   return;
@@ -93,6 +104,10 @@ async function main() {
     for (const { url, basePath, problem } of badUrls) {
       if (problem === 'missing') {
         console.error(`Unable to reach ${url}, linked from ${basePath}`);
+      } else if (problem === 'not-relative') {
+        console.error('Links to /docs/ must be relative');
+        console.error(`  From: ${basePath}`);
+        console.error(`  To: ${url}`);
       } else if (problem === 'absolute') {
         console.error(`Link to docs/ should be replaced by a relative URL`);
         console.error(`  From: ${basePath}`);