feat: more docs to backstage.io
This commit is contained in:
Ivan Shmidt
+94
-92
@@ -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)
|
||||
|
||||
|
Before Width: | Height: | Size: 389 KiB After Width: | Height: | Size: 389 KiB |
@@ -1,4 +1,7 @@
|
||||
# Adding authentication providers
|
||||
---
|
||||
id: add-auth-provider
|
||||
title: Adding authentication providers
|
||||
---
|
||||
|
||||
## Passport
|
||||
|
||||
|
||||
@@ -0,0 +1,6 @@
|
||||
---
|
||||
id: auth-backend
|
||||
title: Auth backend
|
||||
---
|
||||
|
||||
## TODO
|
||||
|
||||
@@ -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
|
||||
|
||||
+4
-1
@@ -1,4 +1,7 @@
|
||||
# User Authentication and Authorization in Backstage
|
||||
---
|
||||
id: index
|
||||
title: User Authentication and Authorization in Backstage
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
|
||||
+4
-1
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
+4
-1
@@ -1,4 +1,7 @@
|
||||
# Static Configuration in Backstage
|
||||
---
|
||||
id: index
|
||||
title: Static Configuration in Backstage
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
|
||||
@@ -1,4 +1,7 @@
|
||||
# Reading Backstage Configuration
|
||||
---
|
||||
id: reading
|
||||
title: Reading Backstage Configuration
|
||||
---
|
||||
|
||||
## Config API
|
||||
|
||||
|
||||
@@ -1,4 +1,7 @@
|
||||
# Writing Backstage Configuration Files
|
||||
---
|
||||
id: writing
|
||||
title: Writing Backstage Configuration Files
|
||||
---
|
||||
|
||||
## File Format
|
||||
|
||||
|
||||
@@ -0,0 +1,4 @@
|
||||
---
|
||||
id: software-catalog-api
|
||||
title: API
|
||||
---
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -0,0 +1,4 @@
|
||||
---
|
||||
id: extending-the-model
|
||||
title: Extending the model
|
||||
---
|
||||
|
||||
@@ -0,0 +1,4 @@
|
||||
---
|
||||
id: external-integrations
|
||||
title: External integrations
|
||||
---
|
||||
|
||||
@@ -1,4 +1,7 @@
|
||||
# Backstage Service Catalog (alpha)
|
||||
---
|
||||
id: software-catalog-overview
|
||||
title: Backstage Service Catalog (alpha)
|
||||
---
|
||||
|
||||
## What is a Service Catalog?
|
||||
|
||||
|
||||
@@ -0,0 +1,4 @@
|
||||
---
|
||||
id: populating-catalog
|
||||
title: Populating the catalog
|
||||
---
|
||||
|
||||
@@ -0,0 +1,4 @@
|
||||
---
|
||||
id: system-model
|
||||
title: System Model
|
||||
---
|
||||
|
||||
@@ -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
|
||||
```
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -1,4 +1,8 @@
|
||||
# TechDocs Documentation
|
||||
---
|
||||
id: techdocs-overview
|
||||
title: TechDocs Documentation
|
||||
sidebar_label: Overview
|
||||
---
|
||||
|
||||
## What is it?
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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/<remote-folder>`.
|
||||
|
||||
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)
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -0,0 +1,4 @@
|
||||
---
|
||||
id: configure-app-with-plugins
|
||||
title: Configuring App with plugins
|
||||
---
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -0,0 +1,4 @@
|
||||
---
|
||||
id: deployment-k8s
|
||||
title: Kubernetes
|
||||
---
|
||||
|
||||
@@ -1,4 +1,7 @@
|
||||
# Deployment (Other)
|
||||
---
|
||||
id: deployment-other
|
||||
title: Other
|
||||
---
|
||||
|
||||
## Deploying Locally
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -0,0 +1,6 @@
|
||||
---
|
||||
id: installation
|
||||
title: Installation
|
||||
---
|
||||
|
||||
Coming soon!
|
||||
|
||||
@@ -0,0 +1,6 @@
|
||||
---
|
||||
id: backend-plugin
|
||||
title: Backend plugin
|
||||
---
|
||||
|
||||
## TODO
|
||||
|
||||
@@ -0,0 +1,6 @@
|
||||
---
|
||||
id: call-existing-api
|
||||
title: Call existing API
|
||||
---
|
||||
|
||||
## TODO
|
||||
|
||||
@@ -1,4 +1,7 @@
|
||||
# Create a Backstage Plugin
|
||||
---
|
||||
id: create-a-plugin
|
||||
title: Create a Backstage Plugin
|
||||
---
|
||||
|
||||
A Backstage Plugin adds functionality to Backstage.
|
||||
|
||||
|
||||
@@ -1,4 +1,7 @@
|
||||
# Existing plugins
|
||||
---
|
||||
id: existing-plugins
|
||||
title: Existing plugins
|
||||
---
|
||||
|
||||
## Open source plugins
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
|
||||
|
||||
## Creating a plugin
|
||||
|
||||
|
||||
@@ -1,4 +1,7 @@
|
||||
# Plugin Development in Backstage
|
||||
---
|
||||
id: plugin-development
|
||||
title: Plugin Development in Backstage
|
||||
---
|
||||
|
||||
Backstage plugins provide features to a Backstage App.
|
||||
|
||||
|
||||
@@ -0,0 +1,6 @@
|
||||
---
|
||||
id: proxying
|
||||
title: Proxying
|
||||
---
|
||||
|
||||
## TODO
|
||||
|
||||
@@ -0,0 +1,6 @@
|
||||
---
|
||||
id: publish-private
|
||||
title: Publish private
|
||||
---
|
||||
|
||||
## TODO
|
||||
|
||||
@@ -1,4 +1,7 @@
|
||||
# Publishing
|
||||
---
|
||||
id: publishing
|
||||
title: Publishing
|
||||
---
|
||||
|
||||
## NPM
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
+38
-34
@@ -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": {
|
||||
|
||||
@@ -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"
|
||||
]
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user