Merge pull request #1933 from spotify/rugvip/noabs

docs: avoid absolute links to docs + verify with script
2020-08-13 11:04:27 +02:00
parent a252b1a82f 2da62ba511
commit f24efbda66
7 changed files with 34 additions and 19 deletions
@@ -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
@@ -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);
  }
@@ -21,7 +21,7 @@ A Backstage app is a modern monorepo web project that is built using Backstage p

 More specifically, a Backstage app includes the core packages and APIs that provide base functionality to the app. The actual UX is provided by plugins. As an example, when you first load the `/` page of the app, the content is provided by the `welcome` plugin.

-Plugins are the essential building blocks of Backstage and extend the platform by providing additional features and functionality. Read more about [Backstage plugins](https://github.com/spotify/backstage/tree/master/docs/getting-started) on GitHub.
+Plugins are the essential building blocks of Backstage and extend the platform by providing additional features and functionality. Read more about [Backstage plugins](/docs/getting-started) on GitHub.

 ## A personalized platform

@@ -50,7 +50,7 @@ yarn start

 And you are good to go! 👍

-Read the full documentation on how to [create an app](https://github.com/spotify/backstage/blob/master/docs/getting-started/create-an-app.md) on GitHub.
+Read the full documentation on how to [create an app](/docs/getting-started/create-an-app.md) on GitHub.

 ## What do I get? (Let's get technical...)

@@ -27,7 +27,7 @@ Quote from [Platform Nuts & Bolts: Extendable Data Models](https://www.kislayver

 Entities, or what we refer to as “components” in Backstage, represent all software, including services, websites, libraries, data pipelines, and so forth. The focus of Phase 2 will be on adding an entity model in Backstage that makes it easy for engineers to create and manage the software components they own.

-With the ability to create a plethora of components in Backstage, how does one keep track of all the software in the ecosystem? Therein lies the highlight feature of Phase 2: the [Service Catalog](https://github.com/spotify/backstage/milestone/4). The service catalog — or software catalog — is a centralized system that keeps track of ownership and metadata about all software in your ecosystem. The catalog is built around the concept of [metadata yaml files](https://github.com/spotify/backstage/blob/master/docs/architecture-decisions/adr002-default-catalog-file-format.md) stored together with the code, which are then harvested and visualized in Backstage.
+With the ability to create a plethora of components in Backstage, how does one keep track of all the software in the ecosystem? Therein lies the highlight feature of Phase 2: the [Service Catalog](https://github.com/spotify/backstage/milestone/4). The service catalog — or software catalog — is a centralized system that keeps track of ownership and metadata about all software in your ecosystem. The catalog is built around the concept of [metadata yaml files](/docs/architecture-decisions/adr002-default-catalog-file-format.md) stored together with the code, which are then harvested and visualized in Backstage.

 ![img](assets/20-05-20/Service_Catalog_MVP.png)

@@ -24,7 +24,7 @@ With these insights we decided to re-focus our efforts towards the most requeste

 ## What is the service catalog?

-The Backstage Service Catalog — actually, a software catalog, since it includes more than just services — is a centralized system that keeps track of ownership and metadata for all the software in your ecosystem (services, websites, libraries, data pipelines, etc). The catalog is built around the concept of [metadata yaml files](https://github.com/spotify/backstage/blob/master/docs/architecture-decisions/adr002-default-catalog-file-format.md#format) stored together with the code, which are then harvested and visualized in Backstage.
+The Backstage Service Catalog — actually, a software catalog, since it includes more than just services — is a centralized system that keeps track of ownership and metadata for all the software in your ecosystem (services, websites, libraries, data pipelines, etc). The catalog is built around the concept of [metadata yaml files](/docs/architecture-decisions/adr002-default-catalog-file-format.md#format) stored together with the code, which are then harvested and visualized in Backstage.

 This was our pitch for the virtues of a service catalog when we first [announced](https://backstage.io/blog/2020/05/22/phase-2-service-catalog) it as part of Phase 2:

@@ -39,7 +39,7 @@ Getting started is really straightforward, and can be broadly broken down into f
 4. Add the provider to the backend.
 5. Add a frontend Auth Utility API.

-For full details, take a look at our [“Adding authentication providers” documentation](https://github.com/spotify/backstage/blob/master/docs/auth/add-auth-provider.md) and at the [excellent documentation](http://www.passportjs.org/docs/) provided by Passport.
+For full details, take a look at our [“Adding authentication providers” documentation](/docs/auth/add-auth-provider.md) and at the [excellent documentation](http://www.passportjs.org/docs/) provided by Passport.

 ## Interested in contributing to the next steps for authentication?

@@ -35,11 +35,11 @@ Since the templates can be customized to integrate with your existing infrastruc

 ### Golden Paths pave the way

-You can customize Backstage Software Templates to fit your organization’s standards. Using Go instead of Java? CircleCI instead of Jenkins? Serverless instead of Kubernetes? GCP instead of AWS? [Make your own recipes for any software component](https://github.com/spotify/backstage/blob/master/docs/features/software-templates/adding-templates.md) and your best practices will be baked right in.
+You can customize Backstage Software Templates to fit your organization’s standards. Using Go instead of Java? CircleCI instead of Jenkins? Serverless instead of Kubernetes? GCP instead of AWS? [Make your own recipes for any software component](/docs/features/software-templates/adding-templates.md) and your best practices will be baked right in.

 ## Getting started

-The sample Software Templates are available under `/create`. If you're setting up Backstage for the first time, follow [Getting Started with Backstage](https://github.com/spotify/backstage/blob/master/docs/getting-started/index.md) and go to `http://localhost:3000/create`. If you’ve already been running Backstage locally, run the command `yarn lerna run mock-data` to load the new sample templates into the Service Catalog first.
+The sample Software Templates are available under `/create`. If you're setting up Backstage for the first time, follow [Getting Started with Backstage](/docs/getting-started/index.md) and go to `http://localhost:3000/create`. If you’ve already been running Backstage locally, run the command `yarn lerna run mock-data` to load the new sample templates into the Service Catalog first.

 ![available-templates](assets/2020-08-05/templates.png)

@@ -69,7 +69,7 @@ New components, of course, get added automatically to the Backstage Service Cata

 ## Define your standards

-Backstage ships with four example templates, but since these are likely not the (only) ones you want to promote inside your company, the next step is to add [your own templates](https://github.com/spotify/backstage/blob/master/docs/features/software-templates/adding-templates.md). Using Backstage’s Software Templates feature, it’s easy to help your engineers get started building software with your organization’s best practices built-in.
+Backstage ships with four example templates, but since these are likely not the (only) ones you want to promote inside your company, the next step is to add [your own templates](/docs/features/software-templates/adding-templates.md). Using Backstage’s Software Templates feature, it’s easy to help your engineers get started building software with your organization’s best practices built-in.

 We have learned that one of the keys to getting these standards adopted is to keep an open process. Templates are code. By making it clear to your engineers that you are open to pull requests, and that teams with different needs can add their own templates, you are on the path of striking a good balance between autonomy and standardization.