diff --git a/docs/README.md b/docs/README.md index cdbfbc55785b7..dc49ace9ada73 100644 --- a/docs/README.md +++ b/docs/README.md @@ -4,99 +4,101 @@ really 😆) you find broken links or missing content, please create an issue or, better yet, a pull request. +# Plugins + - Overview - [What is Backstage?](overview/what-is-backstage.md) - [Backstage architecture](overview/architecture-overview.md) - - [Architecture and terminology](overview/architecture-terminology.md) + - [Architect:ure and terminology](overview/architecture-terminology.md) - [Roadmap](overview/roadmap.md) - - Getting started - - [Running Backstage locally](getting-started/index.md) - - [Installation](getting-started/installation.md) - - [Local development](getting-started/development-environment.md) - - [Demo deployment](https://backstage-demo.roadie.io) - - Production deployments - - [Create an App](getting-started/create-an-app.md) - - App configuration - - [Configuring App with plugins](getting-started/configure-app-with-plugins.md) - - [Customize the look-and-feel of your App](getting-started/app-custom-theme.md) - - Deployment scenarios - - [Kubernetes](getting-started/deployment-k8s.md) - - [Other](getting-started/deployment-other.md) - - Features - - Software Catalog - - [Overview](features/software-catalog/index.md) - - [System model](features/software-catalog/system-model.md) - - [YAML File Format](features/software-catalog/descriptor-format.md) - - [Populating the catalog](features/software-catalog/populating.md) - - [Extending the model](features/software-catalog/extending-the-model.md) - - [External integrations](features/software-catalog/external-integrations.md) - - [API](features/software-catalog/api.md) - - Software creation templates - - [Overview](features/software-templates/index.md) - - [Adding templates](features/software-templates/adding-templates.md) - - Extending the Scaffolder: - - [Overview](features/software-templates/extending/index.md) - - [Create your own Templater](features/software-templates/extending/create-your-own-templater.md) - - [Create your own Publisher](features/software-templates/extending/create-your-own-publisher.md) - - [Create your own Preparer](features/software-templates/extending/create-your-own-preparer.md) - - Docs-like-code - - [Overview](features/techdocs/README.md) - - [Getting Started](features/techdocs/getting-started.md) - - [Concepts](features/techdocs/concepts.md) - - [Creating and Publishing Documentation](features/techdocs/creating-and-publishing.md) - - [FAQ](features/techdocs/FAQ.md) - - Plugins - - [Overview](plugins/index.md) - - [Existing plugins](plugins/existing-plugins.md) - - [Creating a new plugin](plugins/create-a-plugin.md) - - [Developing a plugin](plugins/plugin-development.md) - - [Structure of a plugin](plugins/structure-of-a-plugin.md) - - Backends and APIs - - [Proxying](plugins/proxying.md) - - [Backstage backend plugin](plugins/backend-plugin.md) - - [Call existing API](plugins/call-existing-api.md) - - Testing - - [Overview](plugins/testing.md) - - Publishing - - [Open source and NPM](plugins/publishing.md) - - [Private/internal (non-open source)](plugins/publish-private.md) - - Configuration - - [Overview](conf/index.md) - - [Reading Configuration](conf/reading.md) - - [Writing Configuration](conf/writing.md) - - [Defining Configuration](conf/defining.md) - - Authentication and identity - - [Overview](auth/index.md) - - [Add auth provider](auth/add-auth-provider.md) - - [Auth backend](auth/auth-backend.md) - - [OAuth](auth/oauth.md) - - [Glossary](auth/glossary.md) - - Designing for Backstage - - [Backstage Design Language System (DLS)](dls/design.md) - - [Storybook -- reusable UI components](http://storybook.backstage.io) - - [Contributing to Storybook](dls/contributing-to-storybook.md) - - [Figma resources](dls/figma.md) - - API references - - TypeScript API - - [Utility APIs](api/utility-apis.md) - - [Utility API References](reference/utility-apis/README.md) - - [createPlugin](reference/createPlugin.md) - - [createPlugin-feature-flags](reference/createPlugin-feature-flags.md) - - [createPlugin-router](reference/createPlugin-router.md) - - Backend APIs - - [Backend](api/backend.md) - - Tutorials - - [Overview](tutorials/index.md) - - Architecture Decision Records (ADRs) - - [Overview](architecture-decisions/index.md) - - [ADR001 - Architecture Decision Record (ADR) log](architecture-decisions/adr001-add-adr-log.md) - - [ADR002 - Default Software Catalog File Format](architecture-decisions/adr002-default-catalog-file-format.md) - - [ADR003 - Avoid Default Exports and Prefer Named Exports](architecture-decisions/adr003-avoid-default-exports.md) - - [ADR004 - Module Export Structure](architecture-decisions/adr004-module-export-structure.md) - - [ADR005 - Catalog Core Entities](architecture-decisions/adr005-catalog-core-entities.md) - - [ADR006 - Avoid React.FC and React.SFC](architecture-decisions/adr006-avoid-react-fc.md) - - [ADR007 - Use MSW for Mocking Network Requests](architecture-decisions/adr007-use-msw-to-mock-service-requests.md) - - [ADR008 - Default Catalog File Name](architecture-decisions/adr008-default-catalog-file-name.md) - - [Contribute](../CONTRIBUTING.md) - - [Support](overview/support.md) - - [FAQ](FAQ.md) +- Getting started + - [Running Backstage locally](getting-started/index.md) + - [Installation](getting-started/installation.md) + - [Local development](getting-started/development-environment.md) + - [Demo deployment](https://backstage-demo.roadie.io) + - Production deployments + - [Create an App](getting-started/create-an-app.md) + - App configuration + - [Configuring App with plugins](getting-started/configure-app-with-plugins.md) + - [Customize the look-and-feel of your App](getting-started/app-custom-theme.md) + - Deployment scenarios + - [Kubernetes](getting-started/deployment-k8s.md) + - [Other](getting-started/deployment-other.md) +- Features + - Software Catalog + - [Overview](features/software-catalog/index.md) + - [System model](features/software-catalog/system-model.md) + - [YAML File Format](features/software-catalog/descriptor-format.md) + - [Populating the catalog](features/software-catalog/populating.md) + - [Extending the model](features/software-catalog/extending-the-model.md) + - [External integrations](features/software-catalog/external-integrations.md) + - [API](features/software-catalog/api.md) + - Software creation templates + - [Overview](features/software-templates/index.md) + - [Adding templates](features/software-templates/adding-templates.md) + - Extending the Scaffolder: + - [Overview](features/software-templates/extending/index.md) + - [Create your own Templater](features/software-templates/extending/create-your-own-templater.md) + - [Create your own Publisher](features/software-templates/extending/create-your-own-publisher.md) + - [Create your own Preparer](features/software-templates/extending/create-your-own-preparer.md) + - Docs-like-code + - [Overview](features/techdocs/README.md) + - [Getting Started](features/techdocs/getting-started.md) + - [Concepts](features/techdocs/concepts.md) + - [Creating and Publishing Documentation](features/techdocs/creating-and-publishing.md) + - [FAQ](features/techdocs/FAQ.md) +- Plugins + - [Overview](plugins/index.md) + - [Existing plugins](plugins/existing-plugins.md) + - [Creating a new plugin](plugins/create-a-plugin.md) + - [Developing a plugin](plugins/plugin-development.md) + - [Structure of a plugin](plugins/structure-of-a-plugin.md) + - Backends and APIs + - [Proxying](plugins/proxying.md) + - [Backstage backend plugin](plugins/backend-plugin.md) + - [Call existing API](plugins/call-existing-api.md) + - Testing + - [Overview](plugins/testing.md) + - Publishing + - [Open source and NPM](plugins/publishing.md) + - [Private/internal (non-open source)](plugins/publish-private.md) +- Configuration + - [Overview](conf/index.md) + - [Reading Configuration](conf/reading.md) + - [Writing Configuration](conf/writing.md) + - [Defining Configuration](conf/defining.md) +- Authentication and identity + - [Overview](auth/index.md) + - [Add auth provider](auth/add-auth-provider.md) + - [Auth backend](auth/auth-backend.md) + - [OAuth](auth/oauth.md) + - [Glossary](auth/glossary.md) +- Designing for Backstage + - [Backstage Design Language System (DLS)](dls/design.md) + - [Storybook -- reusable UI components](http://storybook.backstage.io) + - [Contributing to Storybook](dls/contributing-to-storybook.md) + - [Figma resources](dls/figma.md) +- API references + - TypeScript API + - [Utility APIs](api/utility-apis.md) + - [Utility API References](reference/utility-apis/README.md) + - [createPlugin](reference/createPlugin.md) + - [createPlugin-feature-flags](reference/createPlugin-feature-flags.md) + - [createPlugin-router](reference/createPlugin-router.md) + - Backend APIs + - [Backend](api/backend.md) +- Tutorials + - [Overview](tutorials/index.md) +- Architecture Decision Records (ADRs) + - [Overview](architecture-decisions/index.md) + - [ADR001 - Architecture Decision Record (ADR) log](architecture-decisions/adr001-add-adr-log.md) + - [ADR002 - Default Software Catalog File Format](architecture-decisions/adr002-default-catalog-file-format.md) + - [ADR003 - Avoid Default Exports and Prefer Named Exports](architecture-decisions/adr003-avoid-default-exports.md) + - [ADR004 - Module Export Structure](architecture-decisions/adr004-module-export-structure.md) + - [ADR005 - Catalog Core Entities](architecture-decisions/adr005-catalog-core-entities.md) + - [ADR006 - Avoid React.FC and React.SFC](architecture-decisions/adr006-avoid-react-fc.md) + - [ADR007 - Use MSW for Mocking Network Requests](architecture-decisions/adr007-use-msw-to-mock-service-requests.md) + - [ADR008 - Default Catalog File Name](architecture-decisions/adr008-default-catalog-file-name.md) +- [Contribute](../CONTRIBUTING.md) +- [Support](overview/support.md) +- [FAQ](FAQ.md) diff --git a/docs/plugins/my-plugin_screenshot.png b/docs/assets/my-plugin_screenshot.png similarity index 100% rename from docs/plugins/my-plugin_screenshot.png rename to docs/assets/my-plugin_screenshot.png diff --git a/docs/auth/add-auth-provider.md b/docs/auth/add-auth-provider.md index 33f1d335a0cf9..a2830dcf4f2c3 100644 --- a/docs/auth/add-auth-provider.md +++ b/docs/auth/add-auth-provider.md @@ -1,4 +1,7 @@ -# Adding authentication providers +--- +id: add-auth-provider +title: Adding authentication providers +--- ## Passport diff --git a/docs/auth/auth-backend.md b/docs/auth/auth-backend.md index e69de29bb2d1d..579d2e2cda3b0 100644 --- a/docs/auth/auth-backend.md +++ b/docs/auth/auth-backend.md @@ -0,0 +1,6 @@ +--- +id: auth-backend +title: Auth backend +--- + +## TODO diff --git a/docs/auth/glossary.md b/docs/auth/glossary.md index 6408587273ffb..607326b3a51f6 100644 --- a/docs/auth/glossary.md +++ b/docs/auth/glossary.md @@ -1,4 +1,7 @@ -# Glossary +--- +id: glossary +title: Glossary +--- - **Popup** - A separate browser window opened on top of the previous one. - **OAuth** - More specifically OAuth 2.0, a standard protocol for diff --git a/docs/auth/index.md b/docs/auth/index.md index 6f9af17cba284..b885db0820f37 100644 --- a/docs/auth/index.md +++ b/docs/auth/index.md @@ -1,4 +1,7 @@ -# User Authentication and Authorization in Backstage +--- +id: index +title: User Authentication and Authorization in Backstage +--- ## Summary diff --git a/docs/auth/oauth.md b/docs/auth/oauth.md index d348dd2f93285..6e6dc4da802e9 100644 --- a/docs/auth/oauth.md +++ b/docs/auth/oauth.md @@ -1,4 +1,7 @@ -# OAuth and OpenID Connect +--- +id: oauth +title: OAuth and OpenID Connect +--- This section describes how Backstage allows plugins to request OAuth Access Tokens and OpenID Connect ID Tokens on behalf of the user, to be used for auth diff --git a/docs/conf/defining.md b/docs/conf/defining.md index 0b15108f43f0e..b28d6b836269c 100644 --- a/docs/conf/defining.md +++ b/docs/conf/defining.md @@ -1,4 +1,7 @@ -# Defining Configuration for your Plugin +--- +id: defining +title: Defining Configuration for your Plugin +--- There is currently no tooling support or helpers for defining plugin configuration. But it's on the roadmap. diff --git a/docs/conf/index.md b/docs/conf/index.md index af1635d627ba0..bc1d7e8e1f899 100644 --- a/docs/conf/index.md +++ b/docs/conf/index.md @@ -1,4 +1,7 @@ -# Static Configuration in Backstage +--- +id: index +title: Static Configuration in Backstage +--- ## Summary diff --git a/docs/conf/reading.md b/docs/conf/reading.md index 9979f0360e31c..efeb0e61cb041 100644 --- a/docs/conf/reading.md +++ b/docs/conf/reading.md @@ -1,4 +1,7 @@ -# Reading Backstage Configuration +--- +id: reading +title: Reading Backstage Configuration +--- ## Config API diff --git a/docs/conf/writing.md b/docs/conf/writing.md index 8ab397846d367..da2a10a86dd1a 100644 --- a/docs/conf/writing.md +++ b/docs/conf/writing.md @@ -1,4 +1,7 @@ -# Writing Backstage Configuration Files +--- +id: writing +title: Writing Backstage Configuration Files +--- ## File Format diff --git a/docs/features/software-catalog/api.md b/docs/features/software-catalog/api.md index e69de29bb2d1d..fc1ae6e9ba183 100644 --- a/docs/features/software-catalog/api.md +++ b/docs/features/software-catalog/api.md @@ -0,0 +1,4 @@ +--- +id: software-catalog-api +title: API +--- diff --git a/docs/features/software-catalog/descriptor-format.md b/docs/features/software-catalog/descriptor-format.md index 68cee2352c772..3f0503f2abd90 100644 --- a/docs/features/software-catalog/descriptor-format.md +++ b/docs/features/software-catalog/descriptor-format.md @@ -1,4 +1,8 @@ -# Descriptor Format of Catalog Entities +--- +id: descriptor-format +title: Descriptor Format of Catalog Entities +sidebar_label: YAML File Format +--- This section describes the default data shape and semantics of catalog entities. diff --git a/docs/features/software-catalog/extending-the-model.md b/docs/features/software-catalog/extending-the-model.md index e69de29bb2d1d..9162c45133717 100644 --- a/docs/features/software-catalog/extending-the-model.md +++ b/docs/features/software-catalog/extending-the-model.md @@ -0,0 +1,4 @@ +--- +id: extending-the-model +title: Extending the model +--- diff --git a/docs/features/software-catalog/external-integrations.md b/docs/features/software-catalog/external-integrations.md index e69de29bb2d1d..ef5e6a780634b 100644 --- a/docs/features/software-catalog/external-integrations.md +++ b/docs/features/software-catalog/external-integrations.md @@ -0,0 +1,4 @@ +--- +id: external-integrations +title: External integrations +--- diff --git a/docs/features/software-catalog/index.md b/docs/features/software-catalog/index.md index d4d9bf1e2d44a..d1c4d51d60671 100644 --- a/docs/features/software-catalog/index.md +++ b/docs/features/software-catalog/index.md @@ -1,4 +1,7 @@ -# Backstage Service Catalog (alpha) +--- +id: software-catalog-overview +title: Backstage Service Catalog (alpha) +--- ## What is a Service Catalog? diff --git a/docs/features/software-catalog/populating.md b/docs/features/software-catalog/populating.md index e69de29bb2d1d..278f7af075119 100644 --- a/docs/features/software-catalog/populating.md +++ b/docs/features/software-catalog/populating.md @@ -0,0 +1,4 @@ +--- +id: populating-catalog +title: Populating the catalog +--- diff --git a/docs/features/software-catalog/system-model.md b/docs/features/software-catalog/system-model.md index e69de29bb2d1d..2fcf4e3c6834f 100644 --- a/docs/features/software-catalog/system-model.md +++ b/docs/features/software-catalog/system-model.md @@ -0,0 +1,4 @@ +--- +id: system-model +title: System Model +--- diff --git a/docs/features/software-templates/adding-templates.md b/docs/features/software-templates/adding-templates.md index bf540d656a9ef..2ec4bdd6f30bd 100644 --- a/docs/features/software-templates/adding-templates.md +++ b/docs/features/software-templates/adding-templates.md @@ -1,4 +1,7 @@ -# Adding your own Templates +--- +id: adding-templates +title: Adding your own Templates +--- Templates are stored in the **Service Catalog** under a kind `Template`. The minimum that the a template skeleton needs is a `template.yaml` but it would be @@ -15,7 +18,8 @@ metadata: # title of the template title: React SSR Template # a description of the template - description: Next.js application skeleton for creating isomorphic web applications. + description: + Next.js application skeleton for creating isomorphic web applications. # some tags to display in the frontend tags: - Recommended @@ -39,7 +43,7 @@ spec: type: string description: Unique name of the component description: - title: Description + title: Description type: string description: Description of the component ``` diff --git a/docs/features/software-templates/extending/create-your-own-preparer.md b/docs/features/software-templates/extending/create-your-own-preparer.md index 4e45bef5350ac..739c516658a5a 100644 --- a/docs/features/software-templates/extending/create-your-own-preparer.md +++ b/docs/features/software-templates/extending/create-your-own-preparer.md @@ -1,4 +1,7 @@ -# Create your own Preparer +--- +id: extending-preparer +title: Create your own Preparer +--- Preparers are responsible for reading the location of the definition of a [Template Entity](../../software-catalog/descriptor-format.md#kind-template) and diff --git a/docs/features/software-templates/extending/create-your-own-publisher.md b/docs/features/software-templates/extending/create-your-own-publisher.md index 8baf604e01358..51869dc3ad753 100644 --- a/docs/features/software-templates/extending/create-your-own-publisher.md +++ b/docs/features/software-templates/extending/create-your-own-publisher.md @@ -1,4 +1,7 @@ -# Create your own Publisher +--- +id: extending-publisher +title: Create your own Publisher +--- Publishers are responsible for pushing and storing the templated skeleton after the values have been templated by the `Templater`. See diff --git a/docs/features/software-templates/extending/create-your-own-templater.md b/docs/features/software-templates/extending/create-your-own-templater.md index 947190c5e5a1d..ac05eed3b0c7c 100644 --- a/docs/features/software-templates/extending/create-your-own-templater.md +++ b/docs/features/software-templates/extending/create-your-own-templater.md @@ -1,4 +1,7 @@ -# Creating your own Templater +--- +id: extending-templater +title: Creating your own Templater +--- Templaters are responsible for taking the directory path for the skeleton returned by the preparers, and then executing the templating command on top of diff --git a/docs/features/software-templates/extending/index.md b/docs/features/software-templates/extending/index.md index a55128c57d944..bc9bc4d85af06 100644 --- a/docs/features/software-templates/extending/index.md +++ b/docs/features/software-templates/extending/index.md @@ -1,4 +1,8 @@ -## Extending the Scaffolder +--- +id: extending-index +title: Extending the Scaffolder +sidebar_label: Overview +--- Welcome. Take a seat. You're at the Scaffolder Documentation. diff --git a/docs/features/software-templates/index.md b/docs/features/software-templates/index.md index c7358518cdc0c..fe58b5064bf74 100644 --- a/docs/features/software-templates/index.md +++ b/docs/features/software-templates/index.md @@ -1,4 +1,7 @@ -# Software Templates +--- +id: software-templates-index +title: Software Templates +--- The Software Templates part of Backstage is a tool that can help you create Components inside Backstage. It by default has the ability to load skeletons of diff --git a/docs/features/techdocs/FAQ.md b/docs/features/techdocs/FAQ.md index f872e6371892c..1a52a35cfb8ba 100644 --- a/docs/features/techdocs/FAQ.md +++ b/docs/features/techdocs/FAQ.md @@ -1,8 +1,13 @@ -# TechDocs FAQ +--- +id: faqs +title: TechDocs FAQ +sidebar_label: FAQ +--- This page answers frequently asked questions about [TechDocs](README.md). -_Got a question that you think others might be interested in knowing the answer to? Edit this file +_Got a question that you think others might be interested in knowing the answer +to? Edit this file [here](https://github.com/spotify/backstage/edit/master/docs/features/techdocs/FAQ.md)._ ## Technology @@ -25,4 +30,3 @@ package is a MkDocs Plugin that works like a wrapper around multiple MkDocs plugins (e.g. [MkDocs Monorepo Plugin](https://github.com/spotify/mkdocs-monorepo-plugin)) as well as a selection of Python Markdown extensions that TechDocs supports. - diff --git a/docs/features/techdocs/README.md b/docs/features/techdocs/README.md index 8d0fb01ec3818..f71e3d6c0db9e 100644 --- a/docs/features/techdocs/README.md +++ b/docs/features/techdocs/README.md @@ -1,4 +1,8 @@ -# TechDocs Documentation +--- +id: techdocs-overview +title: TechDocs Documentation +sidebar_label: Overview +--- ## What is it? diff --git a/docs/features/techdocs/concepts.md b/docs/features/techdocs/concepts.md index f06ed8b4c0c5a..f77747078cd2a 100644 --- a/docs/features/techdocs/concepts.md +++ b/docs/features/techdocs/concepts.md @@ -1,6 +1,10 @@ -# Concepts +--- +id: concepts +title: Concepts +--- -This page describes concepts that are introduced with Spotify's docs-like-code solution in Backstage. +This page describes concepts that are introduced with Spotify's docs-like-code +solution in Backstage. ### TechDocs Core Plugin diff --git a/docs/features/techdocs/creating-and-publishing.md b/docs/features/techdocs/creating-and-publishing.md index b38fb77b0891a..342b846dcc7a0 100644 --- a/docs/features/techdocs/creating-and-publishing.md +++ b/docs/features/techdocs/creating-and-publishing.md @@ -1,22 +1,29 @@ -# Creating and publishing your docs +--- +id: creating-and-publishing +title: Creating and publishing your docs +sidebar_label: Creating and Publishing Documentation +--- This section will guide you through: - Creating a basic setup for your documentation - Writing and previewing your documentation in a local Backstage environment - Creating a build ready for publication -- Publishing your documentation and making your Backstage instance read your published docs. +- Publishing your documentation and making your Backstage instance read your + published docs. ## Prerequisities - [Docker](https://docs.docker.com/get-docker/) - Static file hosting -- A working Backstage instance with TechDocs installed - (see [TechDocs getting started](getting-started.md)) +- A working Backstage instance with TechDocs installed (see + [TechDocs getting started](getting-started.md)) ## Create a basic documentation setup -In your home directory (also known as `~`), create a directory that contains your documentation (for example, `hello-docs`). Inside this directory, create a file called `mkdocs.yml`. Below is a basic example of how it could look. +In your home directory (also known as `~`), create a directory that contains +your documentation (for example, `hello-docs`). Inside this directory, create a +file called `mkdocs.yml`. Below is a basic example of how it could look. The `~/hello-docs/mkdocs.yml` file should have the following content: @@ -65,15 +72,19 @@ You should now have a folder called `~/hello-docs/site/`. ## Deploy to a file server -In order to serve documentation to TechDocs, our Backstage plugin needs to download the HTML rendered from the previous step. This will likely exist on an external file server, or a storage solution such as Google Cloud Storage. +In order to serve documentation to TechDocs, our Backstage plugin needs to +download the HTML rendered from the previous step. This will likely exist on an +external file server, or a storage solution such as Google Cloud Storage. -When deploying documentation, it should be deployed on that file server/storage solution with the following convention: `{id}/{file}`. For example, if -you want to upload the `getting-started/index.html` file for the `backstage` +When deploying documentation, it should be deployed on that file server/storage +solution with the following convention: `{id}/{file}`. For example, if you want +to upload the `getting-started/index.html` file for the `backstage` documentation site, we would upload it to our file server as `backstage/getting-started/index.html`. To explain further what this would look like for multiple documentation sites, -take a look at this example file tree that would be represented on your file server: +take a look at this example file tree that would be represented on your file +server: ```md /backstage/index.html /backstage/getting-started/index.html @@ -87,17 +98,19 @@ In this file tree, we have two documentation sites available: `backstage` and on `http://example.com` as the server URL. When you configure the TechDocs plugin in Backstage to use `http://example.com` -as the file server/storage solution, it will translate the following URLs to -the file server: +as the file server/storage solution, it will translate the following URLs to the +file server: | Backstage URL | File Server URL | | --------------------------------------------------------- | ------------------------------------------------------- | | https://demo.backstage.io/docs/backstage/ | http://example.com/backstage/index.html | | https://demo.backstage.io/docs/mkdocs/plugin-development/ | http://example.com/mkdocs/plugin-development/index.html | -Then deploying new sites is easy: simply copy over the `site/` -folder produced in the [Create documentation](#build-production-ready-documentation) step above to the file server/storage solution under the ID of the documentation site. It will then become immediately available in Backstage under -the same ID as you can see in the table above. +Then deploying new sites is easy: simply copy over the `site/` folder produced +in the [Create documentation](#build-production-ready-documentation) step above +to the file server/storage solution under the ID of the documentation site. It +will then become immediately available in Backstage under the same ID as you can +see in the table above. So, if the URL to your file server is `http://example.com/`, your `~/hello-docs/site` folder containing the documentation should be accessible at diff --git a/docs/features/techdocs/getting-started.md b/docs/features/techdocs/getting-started.md index 90dcd423fa94c..094f9a83783d6 100644 --- a/docs/features/techdocs/getting-started.md +++ b/docs/features/techdocs/getting-started.md @@ -1,17 +1,20 @@ -# Getting Started +--- +id: getting-started +title: Getting Started +--- > TechDocs is not yet feature complete - currently you can't set up a complete > end-to-end working TechDocs plugin without customizing the plugin itself. -> What you can expect from TechDocs V.0 is a demonstration of how to integrate docs into -> Backstage. TechDocs can create docs using +> What you can expect from TechDocs V.0 is a demonstration of how to integrate +> docs into Backstage. TechDocs can create docs using > [mkdocs](https://www.mkdocs.org/), as well as read published docs. If you > publish generated docs and pass in a `storageUrl` in your `app-config.yaml`, > you can view them in Backstage by going to > `http://localhost:3000/docs/`. -TechDocs functions as a plugin to -Backstage, so you will need to use Backstage to use TechDocs. +TechDocs functions as a plugin to Backstage, so you will need to use Backstage +to use TechDocs. ## What is Backstage? @@ -38,17 +41,20 @@ To create a new Backstage application for TechDocs, run the following command: npx @backstage/cli create-app ``` -You will then be prompted to enter a name for your application. Once that's done, a new Backstage application will be created in a new folder. For -example, if you choose the name `hello-world`, a new `hello-world` folder is created containing your new Backstage application. +You will then be prompted to enter a name for your application. Once that's +done, a new Backstage application will be created in a new folder. For example, +if you choose the name `hello-world`, a new `hello-world` folder is created +containing your new Backstage application. ## Installing TechDocs -TechDocs is not provided with the Backstage application by default, so you will now need to set up TechDocs manually. It should take less -than a minute. +TechDocs is not provided with the Backstage application by default, so you will +now need to set up TechDocs manually. It should take less than a minute. ### Adding the package -The first step is to add the TechDocs plugin to your Backstage application. Navigate to your new Backstage application folder: +The first step is to add the TechDocs plugin to your Backstage application. +Navigate to your new Backstage application folder: ```bash cd hello-world/ @@ -61,7 +67,7 @@ cd packages/app yarn add @backstage/plugin-techdocs ``` -After a short while, the TechDocs plugin should be successfully installed. +After a short while, the TechDocs plugin should be successfully installed. Next, you need to set up some basic configuration. Enter the following command: @@ -78,7 +84,8 @@ export { plugin as TechDocs } from '@backstage/plugin-techdocs'; ### Setting the configuration TechDocs allows for configuration of the docs storage URL through your -`app-config` file. The URL provided here is for demo docs to use for testing purposes. +`app-config` file. The URL provided here is for demo docs to use for testing +purposes. To use the demo docs, add the following lines to `app-config.yaml`: @@ -99,5 +106,5 @@ Open your browser at [http://localhost:3000/docs/](http://localhost:3000/docs/). ## Additional reading - * [Creating and publishing your docs](creating-and-publishing.md) - * [Back to README](README.md) +- [Creating and publishing your docs](creating-and-publishing.md) +- [Back to README](README.md) diff --git a/docs/getting-started/app-custom-theme.md b/docs/getting-started/app-custom-theme.md index 8c8b150171779..e555c6b52df50 100644 --- a/docs/getting-started/app-custom-theme.md +++ b/docs/getting-started/app-custom-theme.md @@ -1,4 +1,7 @@ -# Custom App Themes +--- +id: app-custom-theme +title: Customize the look-and-feel of your App +--- Backstage ships with a default theme with a light and dark mode variant. The themes are provided as a part of the diff --git a/docs/getting-started/configure-app-with-plugins.md b/docs/getting-started/configure-app-with-plugins.md index e69de29bb2d1d..cab3a0d1d2e87 100644 --- a/docs/getting-started/configure-app-with-plugins.md +++ b/docs/getting-started/configure-app-with-plugins.md @@ -0,0 +1,4 @@ +--- +id: configure-app-with-plugins +title: Configuring App with plugins +--- diff --git a/docs/getting-started/create-an-app.md b/docs/getting-started/create-an-app.md index 32093ea811e58..fe22935002e46 100644 --- a/docs/getting-started/create-an-app.md +++ b/docs/getting-started/create-an-app.md @@ -1,4 +1,7 @@ -# Backstage App +--- +id: create-an-app +title: Create an App +--- To get set up quickly with your own Backstage project you can create a Backstage App. diff --git a/docs/getting-started/deployment-k8s.md b/docs/getting-started/deployment-k8s.md index e69de29bb2d1d..9d63d8c6eb8a5 100644 --- a/docs/getting-started/deployment-k8s.md +++ b/docs/getting-started/deployment-k8s.md @@ -0,0 +1,4 @@ +--- +id: deployment-k8s +title: Kubernetes +--- diff --git a/docs/getting-started/deployment-other.md b/docs/getting-started/deployment-other.md index 26c70acac48f6..3b7796f8fe709 100644 --- a/docs/getting-started/deployment-other.md +++ b/docs/getting-started/deployment-other.md @@ -1,4 +1,7 @@ -# Deployment (Other) +--- +id: deployment-other +title: Other +--- ## Deploying Locally diff --git a/docs/getting-started/development-environment.md b/docs/getting-started/development-environment.md index e10ee4b24a367..d8890972adac8 100644 --- a/docs/getting-started/development-environment.md +++ b/docs/getting-started/development-environment.md @@ -1,4 +1,9 @@ -# Development Environment +--- +id: development-environment +title: Development Environment +--- + +# This section describes how to get set up for doing development on the Backstage repository. diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md index 2770b7a154df3..bfd3c709130d1 100644 --- a/docs/getting-started/index.md +++ b/docs/getting-started/index.md @@ -1,6 +1,7 @@ -# Getting started with Backstage - -## Running Backstage Locally +--- +id: index +title: Running Backstage Locally +--- To get up and running with a local Backstage to evaluate it, let's clone it off of GitHub and run an initial build. First make sure that you have at least node diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md index e69de29bb2d1d..a4f91b6e95480 100644 --- a/docs/getting-started/installation.md +++ b/docs/getting-started/installation.md @@ -0,0 +1,6 @@ +--- +id: installation +title: Installation +--- + +Coming soon! diff --git a/docs/plugins/backend-plugin.md b/docs/plugins/backend-plugin.md index e69de29bb2d1d..986af66c20034 100644 --- a/docs/plugins/backend-plugin.md +++ b/docs/plugins/backend-plugin.md @@ -0,0 +1,6 @@ +--- +id: backend-plugin +title: Backend plugin +--- + +## TODO diff --git a/docs/plugins/call-existing-api.md b/docs/plugins/call-existing-api.md index e69de29bb2d1d..075d4bdeb68bc 100644 --- a/docs/plugins/call-existing-api.md +++ b/docs/plugins/call-existing-api.md @@ -0,0 +1,6 @@ +--- +id: call-existing-api +title: Call existing API +--- + +## TODO diff --git a/docs/plugins/create-a-plugin.md b/docs/plugins/create-a-plugin.md index fa91e38b06510..0ca83b076cbb3 100644 --- a/docs/plugins/create-a-plugin.md +++ b/docs/plugins/create-a-plugin.md @@ -1,4 +1,7 @@ -# Create a Backstage Plugin +--- +id: create-a-plugin +title: Create a Backstage Plugin +--- A Backstage Plugin adds functionality to Backstage. diff --git a/docs/plugins/existing-plugins.md b/docs/plugins/existing-plugins.md index bd6fd19691822..8598ae02c44f0 100644 --- a/docs/plugins/existing-plugins.md +++ b/docs/plugins/existing-plugins.md @@ -1,4 +1,7 @@ -# Existing plugins +--- +id: existing-plugins +title: Existing plugins +--- ## Open source plugins diff --git a/docs/plugins/index.md b/docs/plugins/index.md index 5021ac98966fd..514212b2de0ca 100644 --- a/docs/plugins/index.md +++ b/docs/plugins/index.md @@ -1,4 +1,7 @@ -# Plugins +--- +id: index +title: Intro +--- Backstage is a single-page application composed of a set of plugins. @@ -8,7 +11,7 @@ development tool as a plugin in Backstage. By following strong [design guidelines](../dls/design.md) we ensure the the overall user experience stays consistent between plugins. -![plugin](my-plugin_screenshot.png) +![plugin](assets/my-plugin_screenshot.png) ## Creating a plugin diff --git a/docs/plugins/plugin-development.md b/docs/plugins/plugin-development.md index 41918b5de2130..b5c3240de0033 100644 --- a/docs/plugins/plugin-development.md +++ b/docs/plugins/plugin-development.md @@ -1,4 +1,7 @@ -# Plugin Development in Backstage +--- +id: plugin-development +title: Plugin Development in Backstage +--- Backstage plugins provide features to a Backstage App. diff --git a/docs/plugins/proxying.md b/docs/plugins/proxying.md index e69de29bb2d1d..4cf5b4c025b3f 100644 --- a/docs/plugins/proxying.md +++ b/docs/plugins/proxying.md @@ -0,0 +1,6 @@ +--- +id: proxying +title: Proxying +--- + +## TODO diff --git a/docs/plugins/publish-private.md b/docs/plugins/publish-private.md index e69de29bb2d1d..6361f708546fc 100644 --- a/docs/plugins/publish-private.md +++ b/docs/plugins/publish-private.md @@ -0,0 +1,6 @@ +--- +id: publish-private +title: Publish private +--- + +## TODO diff --git a/docs/plugins/publishing.md b/docs/plugins/publishing.md index 76997c30d2149..1d16ebb047e5d 100644 --- a/docs/plugins/publishing.md +++ b/docs/plugins/publishing.md @@ -1,4 +1,7 @@ -# Publishing +--- +id: publishing +title: Publishing +--- ## NPM diff --git a/docs/plugins/structure-of-a-plugin.md b/docs/plugins/structure-of-a-plugin.md index ceacf578fee77..20e72c539d870 100644 --- a/docs/plugins/structure-of-a-plugin.md +++ b/docs/plugins/structure-of-a-plugin.md @@ -1,4 +1,7 @@ -# Structure of a Plugin +--- +id: structure-of-a-plugin +title: Structure of a Plugin +--- Nice, you have a new plugin! We'll soon see how we can develop it into doing great things. But first off, let's look at what we get out of the box. diff --git a/docs/plugins/testing.md b/docs/plugins/testing.md index 701db3eff4ce9..110bc975159eb 100644 --- a/docs/plugins/testing.md +++ b/docs/plugins/testing.md @@ -1,4 +1,7 @@ -# Testing with Jest +--- +id: testing +title: Testing with Jest +--- Backstage uses [Jest](https://facebook.github.io/jest/) for all our unit testing needs. diff --git a/microsite/i18n/en.json b/microsite/i18n/en.json index 31ab6bea94fb5..97eb32ac55a3a 100644 --- a/microsite/i18n/en.json +++ b/microsite/i18n/en.json @@ -81,7 +81,8 @@ "title": "features/software-catalog/api" }, "features/software-catalog/descriptor-format": { - "title": "features/software-catalog/descriptor-format" + "title": "Descriptor Format of Catalog Entities", + "sidebar_label": "YAML File Format" }, "features/software-catalog/extending-the-model": { "title": "features/software-catalog/extending-the-model" @@ -89,8 +90,8 @@ "features/software-catalog/external-integrations": { "title": "features/software-catalog/external-integrations" }, - "features/software-catalog/index": { - "title": "features/software-catalog/index" + "features/software-catalog/software-catalog-overview": { + "title": "Backstage Service Catalog (alpha)" }, "features/software-catalog/populating": { "title": "features/software-catalog/populating" @@ -99,22 +100,22 @@ "title": "features/software-catalog/system-model" }, "features/software-templates/adding-templates": { - "title": "features/software-templates/adding-templates" + "title": "Adding your own Templates" }, - "features/software-templates/extending/create-your-own-preparer": { - "title": "features/software-templates/extending/create-your-own-preparer" + "features/software-templates/extending/extending-preparer": { + "title": "Create your own Preparer" }, - "features/software-templates/extending/create-your-own-publisher": { - "title": "features/software-templates/extending/create-your-own-publisher" + "features/software-templates/extending/extending-publisher": { + "title": "Create your own Publisher" }, - "features/software-templates/extending/create-your-own-templater": { - "title": "features/software-templates/extending/create-your-own-templater" + "features/software-templates/extending/extending-templater": { + "title": "Creating your own Templater" }, - "features/software-templates/extending/index": { - "title": "features/software-templates/extending/index" + "features/software-templates/extending/extending-index": { + "title": "Extending the Scaffolder" }, - "features/software-templates/index": { - "title": "features/software-templates/index" + "features/software-templates/software-templates-index": { + "title": "Software Templates" }, "features/techdocs/concepts": { "title": "features/techdocs/concepts" @@ -128,32 +129,32 @@ "features/techdocs/getting-started": { "title": "features/techdocs/getting-started" }, - "features/techdocs/README": { - "title": "features/techdocs/README" + "features/techdocs/techdocs-overview": { + "title": "TechDocs Documentation" }, "getting-started/app-custom-theme": { - "title": "getting-started/app-custom-theme" + "title": "Customize the look-and-feel of your App" }, "getting-started/configure-app-with-plugins": { "title": "getting-started/configure-app-with-plugins" }, "getting-started/create-an-app": { - "title": "getting-started/create-an-app" + "title": "Create an App" }, "getting-started/deployment-k8s": { "title": "getting-started/deployment-k8s" }, "getting-started/deployment-other": { - "title": "getting-started/deployment-other" + "title": "Other" }, "getting-started/development-environment": { - "title": "getting-started/development-environment" + "title": "Development Environment" }, "getting-started/index": { - "title": "getting-started/index" + "title": "Running Backstage Locally" }, "getting-started/installation": { - "title": "getting-started/installation" + "title": "Installation" }, "journey": { "title": "journey" @@ -174,37 +175,37 @@ "title": "What is Backstage?" }, "plugins/backend-plugin": { - "title": "plugins/backend-plugin" + "title": "Backend plugin" }, "plugins/call-existing-api": { - "title": "plugins/call-existing-api" + "title": "Call existing API" }, "plugins/create-a-plugin": { - "title": "plugins/create-a-plugin" + "title": "Create a Backstage Plugin" }, "plugins/existing-plugins": { - "title": "plugins/existing-plugins" + "title": "Existing plugins" }, "plugins/index": { - "title": "plugins/index" + "title": "Intro" }, "plugins/plugin-development": { - "title": "plugins/plugin-development" + "title": "Plugin Development in Backstage" }, "plugins/proxying": { - "title": "plugins/proxying" + "title": "Proxying" }, "plugins/publish-private": { - "title": "plugins/publish-private" + "title": "Publish private" }, "plugins/publishing": { - "title": "plugins/publishing" + "title": "Publishing" }, "plugins/structure-of-a-plugin": { - "title": "plugins/structure-of-a-plugin" + "title": "Structure of a Plugin" }, "plugins/testing": { - "title": "plugins/testing" + "title": "Testing with Jest" }, "README": { "title": "README" @@ -273,7 +274,10 @@ "Newsletter": "Newsletter" }, "categories": { - "Overview": "Overview" + "Overview": "Overview", + "Getting Started": "Getting Started", + "Features": "Features", + "Plugins": "Plugins" } }, "pages-strings": { diff --git a/microsite/sidebars.json b/microsite/sidebars.json index 13a0a7792a6b2..a32cd9d0953a4 100644 --- a/microsite/sidebars.json +++ b/microsite/sidebars.json @@ -5,6 +5,111 @@ "overview/architecture-overview", "overview/architecture-terminology", "overview/roadmap" + ], + "Getting Started": [ + "getting-started/index", + "getting-started/installation", + "getting-started/development-environment", + "getting-started/create-an-app", + { + "type": "subcategory", + "label": "App configuration", + "ids": [ + "getting-started/configure-app-with-plugins", + "getting-started/app-custom-theme" + ] + }, + { + "type": "subcategory", + "label": "Deployment", + "ids": [ + "getting-started/deployment-k8s", + "getting-started/deployment-other" + ] + } + ], + "Features": [ + { + "type": "subcategory", + "label": "Software Catalog", + "ids": [ + "features/software-catalog/software-catalog-overview", + "features/software-catalog/system-model", + "features/software-catalog/descriptor-format", + "features/software-catalog/populating-catalog", + "features/software-catalog/extending-the-model", + "features/software-catalog/external-integrations", + "features/software-catalog/software-catalog-api" + ] + }, + { + "type": "subcategory", + "label": "Software creation templates", + "ids": [ + "features/software-templates/software-templates-index", + "features/software-templates/adding-templates", + { + "type": "subcategory", + "label": "Extending the Scaffolder", + "ids": [ + "features/software-templates/extending/extending-index", + "features/software-templates/extending/extending-templater", + "features/software-templates/extending/extending-publisher", + "features/software-templates/extending/extending-preparer" + ] + } + ] + }, + { + "type": "subcategory", + "label": "Docs-like-code", + "ids": [ + "features/techdocs/techdocs-overview", + "features/techdocs/techdocs-getting-started", + "features/techdocs/techdocs-concepts", + "features/techdocs/techdocs-creating-and-publishing", + "features/techdocs/techdocs-faqs" + ] + } + ], + "Plugins": [ + "plugins/index", + "plugins/existing-plugins", + "plugins/create-a-plugin", + "plugins/plugin-development", + "plugins/structure-of-a-plugin", + { + "type": "subcategory", + "label": "Backends and APIs", + "ids": [ + "plugins/proxying", + "plugins/backend-plugin", + "plugins/call-existing-api" + ] + }, + { + "type": "subcategory", + "label": "Testing", + "ids": ["plugins/testing"] + }, + { + "type": "subcategory", + "label": "Publishing", + "ids": ["plugins/publishing", "plugins/publish-private"] + } + ], + "Configuration": [ + "conf/index", + "conf/reading", + "conf/writing", + "conf/defining" + ], + "Authentication and identity": [ + "auth/index", + "auth/add-auth-provider", + "auth/auth-backend", + "auth/oauth", + "auth/glossary" ] } }