feat: more docs to backstage.io

teknokeras · Aug 12, 2020 · 0867d3d · 0867d3d
1 parent 4ef9628
commit 0867d3d
Show file tree

Hide file tree

Showing 50 changed files with 487 additions and 193 deletions.
diff --git 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 → docs/assets/my-plugin_screenshot.png b/docs/plugins/my-plugin_screenshot.png → docs/assets/my-plugin_screenshot.png
diff --git 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
@@ -0,0 +1,6 @@
+---
+id: auth-backend
+title: Auth backend
+---
+
+## TODO
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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