fix: conflicts

docs/README.md

@@ -43,11 +43,7 @@ better yet, a pull request.
       - [Overview](features/techdocs/README.md)
       - [Getting Started](features/techdocs/getting-started.md)
       - [Concepts](features/techdocs/concepts.md)
-      - [Reading Documentation](features/techdocs/reading-documentation.md)
-      - [Writing Documentation](features/techdocs/writing-documentation.md)
-      - [Publishing Documentation](features/techdocs/publishing-documentation.md)
-      - [Contributing](features/techdocs/contributing.md)
-      - [Debugging](features/techdocs/debugging.md)
+      - [Creating and Publishing Documentation](features/techdocs/creating-and-publishing.md)
       - [FAQ](features/techdocs/FAQ.md)
   - Plugins
     - [Overview](plugins/index.md)

docs/features/software-catalog/index.md

@@ -24,3 +24,7 @@ can be organised around the entities in the catalog.
 TODO
 
 ![](service-catalog-home.png)
+
+## Links
+
+- [[Blog post] Backstage Service Catalog released in alpha](https://backstage.io/blog/2020/06/22/backstage-service-catalog-alpha)

docs/features/techdocs/README.md

@@ -26,12 +26,15 @@ Spotify’s developer experience offering with 2,400+ documentation sites and
 | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
 | [TechDocs V.0 ✅][v0]   | Read docs in Backstage - Enable anyone to get a reader experience working in Backstage. [See V.0 Use Cases.](./#techdocs-v0)          |
 | [TechDocs V.1 🚧][v1]   | TechDocs end to end (alpha) - Alpha of TechDocs that you can use end to end - and contribute to. [See V.1 Use Cases.](./#techdocs-v1) |
-| [TechDocs V.2 🔮⌛][v2] | Widget Architecture - TechDocs widget architecture available, so the community can create their own customized features.              |
+| [TechDocs V.2 🔮⌛][v2] | Platform stability and compatibility improvements. [See V.2 Use Cases.](./#techdocs-v2)                                               |
+| TechDocs V.3 🔮⌛       | Widget Architecture - TechDocs widget architecture available, so the community can create their own customized features.              |
 
 [v0]: https://github.com/spotify/backstage/milestone/15
 [v1]: https://github.com/spotify/backstage/milestone/16
 [v2]: https://github.com/spotify/backstage/milestone/17
 
+<!-- TODO: Add link to milestone for v3 -->
+
 ## Use Cases
 
 #### TechDocs V.0
@@ -56,6 +59,14 @@ Spotify’s developer experience offering with 2,400+ documentation sites and
 
 #### TechDocs V.2
 
+Platform stability and compatibility improvements
+
+- As a user I can define the metadata generated for my documentation.
+- As a user I will be able to browse metadata from within my documentation in
+  Backstage.
+
+#### TechDocs V.3
+
 more to come...
 
 ## Structure

docs/overview/what-is-backstage.md

@@ -3,34 +3,34 @@ id: what-is-backstage
 title: What is Backstage?
 ---
 
-# [Backstage](https://backstage.io)
-
-![headline](../assets/headline.png)
+![service-catalog](https://backstage.io/blog/assets/6/header.png)
 
 [Backstage](https://backstage.io/) is an open platform for building developer
-portals. It’s based on the developer portal we’ve been using internally at
-Spotify for over four years. Backstage can be as simple as a services catalog or
-as powerful as the UX layer for your entire tech infrastructure.
+portals. Powered by a centralized service catalog, Backstage restores order to
+your microservices and infrastructure. So your product teams can ship
+high-quality code quickly — without compromising autonomy.
+
+Backstage unifies all your infrastructure tooling, services, and documentation
+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,
+  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
+  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
+- Plus, a growing ecosystem of
+  [open source plugins](https://github.com/spotify/backstage/tree/master/plugins)
+  that further expand Backstage’s customizability and functionality
 
 For more information go to [backstage.io](https://backstage.io) or join our
 [Discord chatroom](https://discord.gg/EBHEGzX).
 
-### Features
-
-- Create and manage all of your organization’s software and microservices in one
-  place.
-- Services catalog keeps track of all software and its ownership.
-- Visualizations provide information about your backend services and tooling,
-  and help you monitor them.
-- A unified method for managing microservices offers both visibility and
-  control.
-- Preset templates allow engineers to quickly create microservices in a
-  standardized way
-  ([coming soon](https://github.com/spotify/backstage/milestone/11)).
-- Centralized, full-featured technical documentation with integrated tooling
-  that makes it easy for developers to set up, publish, and maintain alongside
-  their code ([coming soon](https://github.com/spotify/backstage/milestone/15)).
-
 ### Benefits
 
 - For _engineering managers_, it allows you to maintain standards and best

docs/verify-links.js

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+/*
+ * Copyright 2020 Spotify AB
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+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) {
+  url = url.replace(/#.*$/, '');
+  url = url.replace(
+    /https:\/\/github.com\/spotify\/backstage\/(tree|blob)\/master/,
+    '',
+  );
+  if (!url) {
+    return;
+  }
+
+  // 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 };
+    }
+  }
+
+  return;
+}
+
+async function verifyFile(filePath) {
+  const content = await fs.readFile(filePath, 'utf8');
+  const mdLinks = content.match(/\[.+?\]\(.+?\)/g) || [];
+  const badUrls = [];
+
+  for (const mdLink of mdLinks) {
+    const url = mdLink.match(/\[.+\]\((.+)\)/)[1].trim();
+    const badUrl = await verifyUrl(filePath, url);
+    if (badUrl) {
+      badUrls.push(badUrl);
+    }
+  }
+
+  return badUrls;
+}
+
+async function main() {
+  process.chdir(projectRoot);
+
+  const files = await recursive('.', ['node_modules', 'dist', 'bin']);
+  const mdFiles = files.filter(f => f.endsWith('.md'));
+  const badUrls = [];
+
+  for (const mdFile of mdFiles) {
+    const badFileUrls = await verifyFile(mdFile);
+    badUrls.push(...badFileUrls);
+  }
+
+  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}`);
+    }
+    process.exit(1);
+  }
+}
+
+main().catch(error => {
+  console.error(error.stack);
+  process.exit(1);
+});