Merge pull request #17549 from backstage/blam/fix-microsite-build

[microsite] Use Docusaurus@canary
2023-04-28 10:12:10 +02:00
parent 0884e5d09d 2a20913877
commit c8c649464b
42 changed files with 2803 additions and 2107 deletions
@@ -13,7 +13,8 @@ It’s the first open source infrastructure platform by Spotify that allows you

 ![img](assets/blog_1.png)

-<!--truncate-->
+<!-- prettier-ignore -->
+{/* truncate */}

 ## As simple as writing a plugin.

@@ -9,7 +9,8 @@ authorImageURL: https://pbs.twimg.com/profile_images/121166861/6919c047c0d0edaac

 Two days ago, we released the open source version of [Backstage](https://backstage.io/), our homegrown developer portal. And we learned a thing or two via the feedback we received. So, I wanted to take this opportunity to further explain what we’re trying to do with Backstage — and more importantly, what we want to give to the greater engineering community beyond Spotify.

-<!--truncate-->
+<!-- prettier-ignore -->
+{/* truncate */}

 ## What’s the big infrastructure problem?

@@ -9,7 +9,8 @@ authorImageURL: https://pbs.twimg.com/profile_images/1224058798958088192/JPxS8uz

 We’re proud to announce that our first internal plugin at Spotify has been open-sourced as part of Backstage. This plugin works with the newly open-sourced [lighthouse-audit-service](https://github.com/spotify/lighthouse-audit-service) to run and track Lighthouse audits for your websites.

-<!--truncate-->
+<!-- prettier-ignore -->
+{/* truncate */}

 ## What is Lighthouse?

@@ -11,7 +11,8 @@ We want users to be able to create their own version of Backstage quickly and ea

 In this blog post we’ll look at what a Backstage app is and how to create one using our [CLI](https://www.npmjs.com/package/@backstage/cli).

-<!--truncate-->
+<!-- prettier-ignore -->
+{/* truncate */}

 ## What is a Backstage app?

@@ -9,7 +9,8 @@ authorImageURL: https://avatars0.githubusercontent.com/bih

 Just a few weeks ago, we released our internal plugin for [Lighthouse website audits] as our first open source plugin, so the whole community could use it. Today, we’re excited to add a new plugin to that list — say hello to the [Tech Radar plugin]!

-<!--truncate-->
+<!-- prettier-ignore -->
+{/* truncate */}

 ## What is Tech Radar?

@@ -9,7 +9,8 @@ authorImageURL: https://avatars2.githubusercontent.com/u/46946747

 One of the great things about the open source community is once you put your work out there, you really never know where it might end up. That’s certainly the case here.

-<!--truncate-->
+<!-- prettier-ignore -->
+{/* truncate */}

 When Weaveworks decided to build an X-ray diagnostics app to help fight COVID-19, they pulled together a lot of different open source resources — from projects big and small, built by both familiar tech partners and some brand new ones, too.

@@ -12,7 +12,8 @@ We released the open source version of Backstage a little less than two months a

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

-<!--truncate-->
+<!-- prettier-ignore -->
+{/* truncate */}

 ## Progress so far

@@ -9,7 +9,8 @@ image: https://backstage.io/blog/assets/6/header.png

 ![img](assets/6/header.png)

-<!--truncate-->
+<!-- prettier-ignore -->
+{/* truncate */}

 ## You asked, we listened

@@ -9,7 +9,8 @@ authorImageURL: https://avatars1.githubusercontent.com/u/1236238?s=460&v=4

 Getting authentication right is important. It helps keep your platform safe, it’s one of the first things users will interact with, and there are many different authentication providers to support. To this end, we chose to use [Passport](http://www.passportjs.org/) to provide an easy-to-use, out-of-the-box experience that can be extended to your own, pre-existing authentication providers (known as strategies). The Auth APIs in Backstage serve two purposes: identify the user and provide a way for plugins to request access to third-party services on behalf of the user. We’ve already implemented Google and GitHub authentication to provide examples and to get you started.

-<!--truncate-->
+<!-- prettier-ignore -->
+{/* truncate */}

 ## What is Passport?

@@ -10,7 +10,8 @@ authorURL: https://twitter.com/stalund
  <source src="/blog/assets/2020-08-05/feature.mp4" type="video/mp4" />
 </video>

-<!--truncate-->
+<!-- prettier-ignore -->
+{/* truncate */}

 ## Balancing autonomy and standardization

@@ -10,7 +10,8 @@ Since we [open sourced Backstage](https://backstage.io/blog/2020/03/16/announcin
 <iframe width="780" height="440" src="https://www.youtube.com/embed/mOLCgdPw1iA" frameBorder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowFullScreen>
 </iframe>

-<!--truncate-->
+<!-- prettier-ignore -->
+{/* truncate */}

 Internally, we call it TechDocs. It’s the most used plugin at Spotify by far — accounting for about 20% of our Backstage traffic (even though it is just one of 130+ plugins). Its popularity is evidence of something simple: We made documentation so easy to create, find, and use — people actually use it.

@@ -8,7 +8,8 @@ authorURL: https://twitter.com/stalund

 ![cncf](assets/cncf-sandbox/cncf.png)

-<!--truncate-->
+<!-- prettier-ignore -->
+{/* truncate */}

 Backstage garnered quite a bit of interest from developers and organizations when it was first announced, and community interest continues to grow as plugins and new features are added with the open source community. We released the open source version of Backstage ‘early’. That was intentional. Because even though we’ve been using Backstage internally for years, we wanted the open source version to be developed with input and contributions from the community. And that’s exactly the product that’s going into the [CNCF Sandbox](https://www.cncf.io/sandbox-projects/) today.

@@ -8,7 +8,8 @@ authorURL: http://twitter.com/katherinemzhou

 We are excited to launch the Backstage Design System, which includes a [Figma UI kit](https://www.figma.com/community/file/850673348101741100), a rich set of [reusable code components](http://backstage.io/storybook) on Storybook, and [Guidelines](https://backstage.io/docs/dls/design) for designers and developers as they build plugins for Backstage.

-<!--truncate-->
+<!-- prettier-ignore -->
+{/* truncate */}

 ## Not just the way it looks

@@ -12,7 +12,8 @@ Now you may be thinking, “Yeah, sure, that sounds nice and all, but how does B

 ![plugins](https://backstage.io/img/cards-plugins.png)

-<!--truncate-->
+<!-- prettier-ignore -->
+{/* truncate */}

 Think of plugins as a mini version of an infrastructure tool or service — just the parts you need, made quick and easy. The advantage of using a Backstage plugin instead of a tool’s dedicated UI is that all your infrastructure is packaged into a “single pane of glass” instead of being spread out like independently built “islands”. Once you grow your infrastructure portfolio, the complexity really starts to add up. The Backstage plugin model allows you to add more tools without increasing the cognitive load for your users.

@@ -11,7 +11,8 @@ How did Spotify save millions on cloud costs within a matter of months?? We made

 Are we turning engineers into accountants? Nope, we’re just letting engineers do what they do best, in the place that feels natural to them: inside Backstage.

-<!--truncate-->
+<!-- prettier-ignore -->
+{/* truncate */}

 ## Why put a cost management tool in the hands of engineers?

@@ -10,7 +10,8 @@ authorURL: https://github.com/Rugvip

 ![Animation cycling between stability index scores](assets/2020-12-22/stability-index-hero.gif)

-<!--truncate-->
+<!-- prettier-ignore -->
+{/* truncate */}

 Backstage has a great and growing community of users and contributors. With so much valuable feedback, this inevitably means that sometimes we will go back and revise design decisions that introduce breaking changes. Furthermore, as we continue to ship new features and systems, we’ll continue this cycle of iterating, gathering feedback, and iterating again before reaching a stable API.

@@ -11,7 +11,8 @@ TLDR; We’re rethinking the Kubernetes developer experience with a new feature:

 And since Backstage uses the native Kubernetes API, the feature works with whichever cloud provider (AWS, Azure, GCP, etc.) or managed service (OpenShift, IBM Cloud, GKE, etc.) you already use.

-<!--truncate-->
+<!-- prettier-ignore -->
+{/* truncate */}

 ## The missing link between K8s and your service

@@ -8,7 +8,8 @@ authorURL: https://www.linkedin.com/in/austinlamon

 One of the greatest strengths of Backstage also presents a never-ending challenge: Backstage is highly customizable and allows you to easily build a unique developer portal suited to your organization’s needs. The downside of this flexibility is that it can be hard to know where to start. Backstage can do so many things — integrating every part of your tech infrastructure and developer experience — but if you set off building a developer portal without a plan, it’s easy to get overwhelmed by all the possibilities. To help you form your plan, this post will detail how Spotify came to design our internal portal and recommend potential models for you to use when designing and building your own.

-<!--truncate-->
+<!-- prettier-ignore -->
+{/* truncate */}

 ## Infrastructure as tech culture

@@ -13,7 +13,8 @@ In order to grow Backstage further, Spotify is increasing the support we provide

 And while Spotify remains committed to maturing the Backstage platform — both as original creator and active maintainer — we also want to make room for the community to take greater ownership. Backstage may have started inside Spotify, but it belongs to all of you. So, we hope you join us in what’s next.

-<!--truncate-->
+<!-- prettier-ignore -->
+{/* truncate */}

 ## What’s next: More support for adopters and contributors

@@ -13,7 +13,8 @@ So, you don’t just get an improved out-of-the-box experience for searching wha

 With one query, your teams can find exactly what they’re looking for: anything and everything.

-<!--truncate-->
+<!-- prettier-ignore -->
+{/* truncate */}

 ## Search and explore

@@ -9,7 +9,8 @@ authorImageURL: https://avatars.githubusercontent.com/u/3645856?v=4

 **TLDR**; At a high level, Backstage performs three main jobs: [Create, Manage, and Explore](https://backstage.io/blog/2021/05/20/adopting-backstage#three-jobs-create-manage-explore). Throughout the year, we’ve been focussed on improving the stability and scalability of these areas while enhancing the feature sets based upon requests from the community. Software Templates — which enable push-button deployments with all your standards and best practices built-in — is our first feature-complete release candidate to graduate to beta. Read on to learn how this release improves template customization and flexibility, as well as performance.

-<!--truncate-->
+<!-- prettier-ignore -->
+{/* truncate */}

 Let’s rewind a little bit, around a year in fact. Backstage had been open sourced, and we released our first version of Software Templates and our Scaffolder plugin.

@@ -9,7 +9,8 @@ authorImageURL: https://avatars.githubusercontent.com/u/3496491?v=4

 **TLDR:** Another beta has landed! We continue to focus on improving the stability and scalability of Backstage while enhancing its functionality. Thanks to focused efforts from the TechDocs core team and community, we're happy to say that TechDocs — [our docs-like-code solution](https://backstage.io/blog/2020/09/08/announcing-tech-docs) for all the software in your catalog — is now, after [Software Templates](https://backstage.io/blog/2021/07/26/software-templates-are-now-in-beta), the second core feature to graduate to beta.

-<!--truncate-->
+<!-- prettier-ignore -->
+{/* truncate */}

 In addition to new features and improvements, we made numerous compatibility updates ahead of this feature release. You'll find support for a variety of CI systems, cloud storage solutions, and source control systems — so that TechDocs works for most orgs, right out of box. But there's much more to explore in this beta, thanks to contributions from the community.

@@ -11,7 +11,8 @@ We’re excited to celebrate an important milestone for the Backstage community:

 Before digging into why we believe this is so important, we want to send a huge “thank you” to all the Backstage adopters and contributors who have helped grow the Backstage community. First, to the publicly listed adopters as your visible support for the project excites others to learn more about Backstage. Second, to those non-listed adopters, many of whom still engage in the community via issues, comments, or code contributions. Thank you!

-<!--truncate-->
+<!-- prettier-ignore -->
+{/* truncate */}

 ## Why we care about public adopters

@@ -15,7 +15,8 @@ In 2021 we’ve seen the project and community grow in every dimension, reaching

 Now let’s hear from the maintainers and look at the stats!

-<!--truncate-->
+<!-- prettier-ignore -->
+{/* truncate */}

 ## The community grew…and grew

@@ -11,7 +11,8 @@ _This blog post is co-authored by Emma Indal ([@emmaindal](https://github.com/em

 _TLDR;_ We’re excited to announce the arrival of homepage templates for Backstage. It can be intimidating to build up your own instance of Backstage, so we decided to make your life a bit easier by giving you an out-of-the-box homepage to hit the ground running. This template can be found in our [Backstage Storybook](https://backstage.io/storybook/?path=/story/plugins-home-templates--default-template), as well as future templates that we build.

-<!--truncate-->
+<!-- prettier-ignore -->
+{/* truncate */}

 ## Why homepage templates?

@@ -9,7 +9,8 @@ authorImageURL: https://avatars.githubusercontent.com/u/8433119?v=4

 _TLDR;_ The Spotify team recently announced [Backstage Upgrade Helper](https://backstage.github.io/upgrade-helper): a tool that helps adopters keep their Backstage application up-to-date. **Spoiler alert**: this is also a hidden and heartwarming tale about the beauty of open source innovation.

-<!--truncate-->
+<!-- prettier-ignore -->
+{/* truncate */}

 ## Upgrading Backstage was a common pain point

@@ -9,7 +9,8 @@ authorImageURL: https://avatars1.githubusercontent.com/u/1236238?s=460&v=4

 **TLDR:** Backstage has turned two. Of course, this is software, so we expect things to move fast. But when you have a passionate, worldwide community building together, we’ve now seen firsthand just how fast that can be. We’re marking our second year as a community by becoming a CNCF incubating project, reaching 100 public adopters, releasing version 1.0 of the core app, and other very nice birthday gifts. Rather than a toddler finding their feet, Backstage today is beginning to look awfully grown-up for a two-year-old.

-<!--truncate-->
+<!-- prettier-ignore -->
+{/* truncate */}

 ## Out of the Sandbox and into Incubation

@@ -10,7 +10,8 @@ authorImageURL: https://avatars.githubusercontent.com/u/6010860?v=4

 _TL;DR:_ If you’ve been waiting for Backstage to come out of beta, we’re excited to announce that Backstage 1.0 is here!

-<!--truncate-->
+<!-- prettier-ignore -->
+{/* truncate */}

 It’s been two years since Spotify [open sourced Backstage](https://backstage.io/blog/2020/03/16/announcing-backstage) so companies of all shapes and sizes — and in every industry all over the world — could build highly extensible and customized developer portals to best suit their organization’s needs and culture. Now hundreds of adopters are using Backstage as the single pane of glass for their core development, managing millions of components and technical documentation, and helping hundreds of thousands of developers be more productive and happy.

@@ -12,7 +12,8 @@ _This blog post is co-authored by Eric Peterson ([@iamEAP](https://github.com/ia

 _TL;DR:_ Introducing the TechDocs Addon Framework — a way for us all to contribute and share additional features, TechDocs Addons, on top of the base docs-like-code experience.

-<!--truncate-->
+<!-- prettier-ignore -->
+{/* truncate */}

 [TechDocs](https://backstage.io/docs/features/techdocs/) is a centralized platform for publishing, viewing, and discovering technical documentation across an entire organization. It's a solid foundation! But TechDocs doesn't solve higher order documentation needs on its own such as: How do you create and reinforce a culture of documentation? How do you build trust in the quality of technical documentation?

@@ -13,7 +13,8 @@ We first released the Backstage Search Platform over a year ago. Backstage Searc

 Backstage Search Platform makes it possible for you to search across your entire software ecosystem. With a Search platform that is customizable and extendable, you can identify your needs within your organization and set up search to solve these problems. Whether it is to search through the Software Catalog or technical documentation generated by the TechDocs plugin.

-<!--truncate-->
+<!-- prettier-ignore -->
+{/* truncate */}

 ## So what is Backstage Search 1.0?

@@ -11,7 +11,8 @@ authorURL: https://github.com/Rugvip

 As an [Incubating project](https://www.cncf.io/blog/2022/03/15/backstage-project-joins-the-cncf-incubator/) within the [Cloud Native Computing Foundation (CNCF)](https://www.cncf.io/), Backstage was fortunate enough to take advantage of a sponsored security audit. The [Open Source Technology Improvement Fund (OSTIF)](https://ostif.org/) sponsored the audit as part of its ongoing efforts to secure the open source software ecosystem, and the audit itself was performed by [X41 D-Sec](https://x41-dsec.de/). Our goal with the audit was to evaluate and improve Backstage’s security posture, focusing on the core Backstage framework and plugins.

-<!--truncate-->
+<!-- prettier-ignore -->
+{/* truncate */}

 ## Report Findings and Fixes

@@ -10,7 +10,8 @@ authorImageURL: https://avatars.githubusercontent.com/u/3496491?v=4

 ![The Plugin Analytics API](assets/22-09-08/analytics-api-fyi.png)

-<!--truncate-->
+<!-- prettier-ignore -->
+{/* truncate */}

 ## What is the plugin analytics API?

@@ -9,7 +9,8 @@ Backstage continues to grow in [popularity and maturity](https://roadie.io/blog/

 [![Introduction to Backstage: Developer Portals Made Easy (LFS142x): Enroll!](assets/22-11-15/Introduction-to-Backstage-Developer-Portals-Made-Easy-2-768x432.png)](https://www.edx.org/course/introduction-to-backstage-developer-portals-made-easy)

-<!--truncate-->
+<!-- prettier-ignore -->
+{/* truncate */}

 The course, [Introduction to Backstage: Developer Portals Made Easy (LFS142x)](https://www.edx.org/course/introduction-to-backstage-developer-portals-made-easy), starts discussing the benefits of adopting a Developer Portal. Then, it dives into what is Backstage, its main features (Catalog, Scaffolder, TechDocs), and how to map its capabilities to your organization. At last, it provides tips on how to connect with the community to ease up your adoption journey.

@@ -12,7 +12,8 @@ Our community is full of people from across the globe who bring incredible engag

 But before anticipating too much, let’s share some stats of this amazing 2022.

-<!--truncate-->
+<!-- prettier-ignore -->
+{/* truncate */}

 ## We grew … a lot!

@@ -8,7 +8,8 @@ At the heart of [Backstage](https://backstage.io/) is the [Backstage Software Ca

 ![catalog pipeline](assets/2023-01-31/catalog-pipeline.png)

-<!--truncate-->
+<!-- prettier-ignore -->
+{/* truncate */}

 A common use case is for an organization to want to surface ownership and metadata about repositories. Backstage provides a mechanism for discovering and transforming repository information into a standard data structure and persisting it into the Backstage [Catalog](https://backstage.io/docs/features/software-catalog/). This process is known as ingestion, where all data is transformed into a standard Backstage data structure known as an entity. Entities in the Catalog’s data store are accessible to the Backstage App via the REST API.

@@ -10,7 +10,8 @@ authorURL: https://github.com/leemills83

 Okay, everyone. Time to move on from all the 2022 reflections, Top 10 lists, and Wrapped(s), and turn our gaze in the other direction — towards 2023. As the Backstage team moves into the new year, we find ourselves asking those perennial questions: How can we continue to grow and enhance the Backstage community? How can we improve the experience for those adopting Backstage? How can we give the best support to Backstage contributors?

-<!--truncate-->
+<!-- prettier-ignore -->
+{/* truncate */}

 Well, we don’t have all the answers, but we do have some. So we wanted to share more on three ongoing initiatives aimed at moving the needle forward for these three distinct, yet interrelated, questions.

@@ -11,7 +11,8 @@ For the past year, the Backstage maintainer team has been spending time to give

 We’re happy to announce that the [v1.11](https://backstage.io/docs/releases/v1.11.0) release includes the public alpha of the [new Backstage backend system](https://backstage.io/docs/backend-system/)! The system has already been available to use for some time, as some of you have already found, but this alpha release marks the point where we are finally ready to encourage widespread adoption by plugin builders. We still don’t recommend that you use this new system in your production setups just yet, more on that later.

-<!--truncate-->
+<!-- prettier-ignore -->
+{/* truncate */}

 ## History of the Backstage backend system

@@ -9,7 +9,8 @@ authorImageURL: https://avatars.githubusercontent.com/u/3645856?v=4

 **TL;DR** Spotify released Backstage into open source three years ago today. Since then, the community has grown by leaps and bounds to stretch across the globe (and the Discord server!). Now that Backstage is a threenager, the growing pains are real. So, on this birthday, we want to cover our collective efforts to make it easier to adopt and contribute to Backstage.

-<!--truncate-->
+<!-- prettier-ignore -->
+{/* truncate */}

 ## They grow up so fast, don’t they?

@@ -68,6 +68,12 @@ module.exports = {
      },
    ],
  ],
+  markdown: {
+    preprocessor({ filePath, fileContent }) {
+      // Replace all HTML comments with emtpy strings as these are not supported by MDXv2.
+      return fileContent.replace(/<!--.*?-->/gs, '');
+    },
+  },
  webpack: {
    jsLoader: isServer => ({
      loader: require.resolve('swc-loader'),
@@ -17,21 +17,20 @@
    "docusaurus": "docusaurus"
  },
  "devDependencies": {
-    "@docusaurus/module-type-aliases": "2.4.0",
+    "@docusaurus/module-type-aliases": "0.0.0-5562",
    "@spotify/prettier-config": "^14.0.0",
    "@tsconfig/docusaurus": "^1.0.6",
    "@types/webpack-env": "^1.18.0",
    "js-yaml": "^4.1.0",
    "prettier": "^2.6.2",
-    "replace": "^1.2.2",
    "typescript": "^4.9.4",
    "yaml-loader": "^0.8.0"
  },
  "prettier": "@spotify/prettier-config",
  "dependencies": {
-    "@docusaurus/core": "2.4.0",
-    "@docusaurus/plugin-client-redirects": "^2.3.1",
-    "@docusaurus/preset-classic": "2.4.0",
+    "@docusaurus/core": "0.0.0-5562",
+    "@docusaurus/plugin-client-redirects": "0.0.0-5562",
+    "@docusaurus/preset-classic": "0.0.0-5562",
    "@swc/core": "^1.3.46",
    "clsx": "^1.1.1",
    "docusaurus-plugin-sass": "^0.2.3",
@@ -14,7 +14,6 @@
 * limitations under the License.
 */

-const replace = require('replace');
 const { existsSync, writeFileSync, mkdirSync } = require('fs');
 const path = require('path');

@@ -28,16 +27,7 @@ Run \`yarn build:api-docs\` to generate the API docs.

 async function main() {
  const referencesDir = '../docs/reference';
-  if (existsSync(referencesDir)) {
-    console.log('Removing HTML comments from docs/reference folder');
-    replace({
-      regex: '<!--(.*?)-->',
-      replacement: '',
-      paths: [referencesDir],
-      recursive: true,
-      silent: false,
-    });
-  } else {
+  if (!existsSync(referencesDir)) {
    mkdirSync(referencesDir);
    writeFileSync(path.join(referencesDir, 'index.md'), PLACEHOLDER);
  }