From 94db137153e9f27cc47b10fb37a83cfd8bf27cbe Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Wed, 12 Aug 2020 18:41:06 +0200 Subject: [PATCH 1/2] docs/verify-links: avoid absolute links within docs --- docs/verify-links.js | 23 +++++++++++++++++++---- 1 file changed, 19 insertions(+), 4 deletions(-) diff --git a/docs/verify-links.js b/docs/verify-links.js index 8c865309f9..0a3b08e425 100755 --- a/docs/verify-links.js +++ b/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); } From 2da62ba5118eaf9266ab934a898175b76ea27885 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Wed, 12 Aug 2020 18:45:51 +0200 Subject: [PATCH 2/2] docs: use relative links to docs/ --- docs/overview/what-is-backstage.md | 14 +++++++------- .../2020-04-30-how-to-quickly-set-up-backstage.md | 4 ++-- .../blog/2020-05-22-phase-2-service-catalog.md | 2 +- .../2020-06-22-backstage-service-catalog-alpha.md | 2 +- ...e-authentication-in-backstage-using-passport.md | 2 +- ...8-05-announcing-backstage-software-templates.md | 6 +++--- 6 files changed, 15 insertions(+), 15 deletions(-) diff --git a/docs/overview/what-is-backstage.md b/docs/overview/what-is-backstage.md index 86b5417d5f..c8d659db9a 100644 --- a/docs/overview/what-is-backstage.md +++ b/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 diff --git a/microsite/blog/2020-04-30-how-to-quickly-set-up-backstage.md b/microsite/blog/2020-04-30-how-to-quickly-set-up-backstage.md index 7b1fbb2d11..65ee02f6a0 100644 --- a/microsite/blog/2020-04-30-how-to-quickly-set-up-backstage.md +++ b/microsite/blog/2020-04-30-how-to-quickly-set-up-backstage.md @@ -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...) diff --git a/microsite/blog/2020-05-22-phase-2-service-catalog.md b/microsite/blog/2020-05-22-phase-2-service-catalog.md index 631931bb82..682965d2dd 100644 --- a/microsite/blog/2020-05-22-phase-2-service-catalog.md +++ b/microsite/blog/2020-05-22-phase-2-service-catalog.md @@ -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) diff --git a/microsite/blog/2020-06-22-backstage-service-catalog-alpha.md b/microsite/blog/2020-06-22-backstage-service-catalog-alpha.md index a352faf0cb..0928b8769b 100644 --- a/microsite/blog/2020-06-22-backstage-service-catalog-alpha.md +++ b/microsite/blog/2020-06-22-backstage-service-catalog-alpha.md @@ -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: diff --git a/microsite/blog/2020-07-01-how-to-enable-authentication-in-backstage-using-passport.md b/microsite/blog/2020-07-01-how-to-enable-authentication-in-backstage-using-passport.md index 5111f5c726..ccdd8b34c6 100644 --- a/microsite/blog/2020-07-01-how-to-enable-authentication-in-backstage-using-passport.md +++ b/microsite/blog/2020-07-01-how-to-enable-authentication-in-backstage-using-passport.md @@ -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? diff --git a/microsite/blog/2020-08-05-announcing-backstage-software-templates.md b/microsite/blog/2020-08-05-announcing-backstage-software-templates.md index 79b5ec45fd..6143442782 100644 --- a/microsite/blog/2020-08-05-announcing-backstage-software-templates.md +++ b/microsite/blog/2020-08-05-announcing-backstage-software-templates.md @@ -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.