+
+);
```
## Consequences
diff --git a/docs/architecture-decisions/adr010-luxon-date-library.md b/docs/architecture-decisions/adr010-luxon-date-library.md
new file mode 100644
index 0000000000..43f18f0f69
--- /dev/null
+++ b/docs/architecture-decisions/adr010-luxon-date-library.md
@@ -0,0 +1,36 @@
+---
+id: adrs-adr010
+title: ADR010: Use the Luxon Date Library
+description: Architecture Decision Record (ADR) for Luxon Date Library
+---
+
+## Context
+
+Date formatting (e.g. `a day ago`) and calculations are common within Backstage.
+Some of these useful features are not supported by the standard JavaScript
+`Date` object. The popular [Moment.js](https://momentjs.com/) library has been
+commonly used to fill this gap but suffers from large bundle sizes and mutable
+state issues. On top of this, `momentjs` is
+[being sunset](https://momentjs.com/docs/#/-project-status/) and the project
+recommends using one of the more modern alternative libraries.
+
+See
+[[RFC] Standardized Date & Time Library](https://github.com/backstage/backstage/issues/3401).
+
+## Decision
+
+We will use [Luxon](https://moment.github.io/luxon/index.html) as the standard
+date library within Backstage.
+
+`Luxon` provides a similar feature set and API to `Moment.js`, but improves on
+its design through immutability and the usage of modern JavaScript APIs (e.g.
+`Intl`). This results in smaller bundle sizes while providing a full feature set
+and avoids the need for using additional libraries for common date & time tasks.
+
+## Consequences
+
+- All core packages and plugins within Backstage should use `Luxon` for any date
+ manipulation or formatting that cannot be easily accomplished with the native
+ JavaScript `Date` object.
+- Using a single date library avoids having to learn multiple library APIs
+- Having a single date library will reduce bundle sizes
diff --git a/docs/architecture-decisions/adr011-plugin-package-structure.md b/docs/architecture-decisions/adr011-plugin-package-structure.md
new file mode 100644
index 0000000000..9133e5b7c2
--- /dev/null
+++ b/docs/architecture-decisions/adr011-plugin-package-structure.md
@@ -0,0 +1,74 @@
+---
+id: adrs-adr011
+title: ADR011: Plugin Package Structure
+description: Architecture Decision Record (ADR) for Plugin Package Structure
+---
+
+## Context
+
+A core feature of Backstage is the extensibility via plugins. The Backstage
+repository is open for contributions of plugins. Even most of the core features
+are implemented as plugins. A plugin consists of one or multiple packages in the
+`plugins/` directory. Up till now, we have a simple conventions for naming
+plugin packages: Plugins are named `x`, with the option of having a related
+backend plugin called `x-backend` (where `x` is the plugin name, like `catalog`
+or `techdocs`). There is a need for sharing code between the frontend and
+backend of a plugin, between backend plugins, or components and hooks between
+different frontend plugins
+([some examples](https://github.com/backstage/backstage/issues/3655#issuecomment-758166746)).
+This results in emerging plugin packages with shared code, like
+`packages/catalog-client` or `packages/techdocs-common`.
+
+> There is a common phrase in software development:
+> [Naming things is hard](https://martinfowler.com/bliki/TwoHardThings.html)
+
+To keep the contributed plugins consistent, this Architecture Decision Record
+provides rules for naming plugin packages.
+
+## Decision
+
+We will place all plugin related code in the `plugins/` directory. The
+`packages/` directory is reserved for core package of Backstage.
+
+We follow this structure for plugin packages (where `x` is the plugin name, for
+example `catalog` or `techdocs`):
+
+- `x`: Contains the main frontend code of the plugin.
+- `x-backend`: Contains the main backend code of the plugin.
+- `x-react`: Contains shared widgets, hooks and similar that both the plugin
+ itself (`x`) and third-party frontend plugins can depend on.
+- `x-node`: Contains utilities for backends that both the plugin backend itself
+ (`x-backend`) and third-party backend plugins can depend on.
+- `x-common`: An isomorphic package with platform agnostic models, clients, and
+ utilities that all packages above or any third-party plugin package can depend
+ on.
+
+We prefix the package names with `@backstage/plugin-`.
+
+This structure is based on a
+[suggestion in issue #3655](https://github.com/backstage/backstage/issues/3655#issuecomment-758166746).
+
+## Consequences
+
+We will actively migrate existing packages that are part of a plugin to the
+`plugins/` folder. This affects packages like:
+
+- `packages/techdocs-common` which should be moved to `plugins/techdocs-node`
+ and named `@backstage/plugin-techdocs-node`.
+- `packages/catalog-client` which will be part of a future
+ `plugins/catalog-common` and named `@backstage/plugin-catalog-common`.
+- While the new location of `packages/catalog-model` should be
+ `plugins/catalog-common` we might want to do an exception here, as it's a very
+ central package.
+
+The limited set of rules might not be sufficient in the future. If additional
+packages are required, we will revisit this decision and extend the pattern.
+
+If possible, we will add tools, such as lint rules, to help enforce the package
+names and dependencies between them or CLI commands to generate these packages.
+
+The distinction between core packages and plugins helps us to setup
+[CODEOWNERS](https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/about-code-owners)
+in the repository. We can set the code owners for the `packages/` folder to the
+core team and create additional rules (like `plugins/x*`) for plugin
+maintainers.
diff --git a/docs/architecture-decisions/index.md b/docs/architecture-decisions/index.md
index 3211f37550..f852170b1e 100644
--- a/docs/architecture-decisions/index.md
+++ b/docs/architecture-decisions/index.md
@@ -18,8 +18,9 @@ Records should be stored under the `architecture-decisions` directory.
### Creating an ADR
-- Copy `0000-template.md` to `docs/architecture-decisions/0000-my-decision.md`
- (my-decision should be descriptive. Do not assign an ADR number.)
+- Copy `docs/architecture-decisions/adr000-template.md` to
+ `docs/architecture-decisions/adr000-my-decision.md` (my-decision should be
+ descriptive. Do not assign an ADR number.)
- Fill in the ADR following the guidelines in the template
- Submit a pull request
- Address and integrate feedback from the community
diff --git a/docs/architecture.drawio b/docs/architecture.drawio
new file mode 100644
index 0000000000..dbe2a5f6fa
--- /dev/null
+++ b/docs/architecture.drawio
@@ -0,0 +1 @@
+{text}
+ {children}
+ 
+
+At a base-level, we want to support the following:
+
+- We aim to enable the capability to search across the entire Backstage
+ ecosystem including, but not limited to, entities in the software catalog.
+ Searchable content won't be required to relate directly to the software
+ catalog, but by convention, we may encourage loose relationships using
+ well-known field names or attributes.
+- We aim to enable the capability to deploy Backstage using any search engine,
+ by providing an integration and translation layer between the core search
+ plugin and search engine specific logic that can be extended for different
+ search engines. We may also introduce the ability to replace the backend API
+ endpoint with a custom endpoint for simpler customization.
+
+More advanced use-cases we hope to support with this architecture include:
+
+- It should be possible for any plugin to expose new content to search. (e.g.
+ entity metadata, documentation from TechDocs)
+- It should be possible for any plugin to append relevant metadata to existing
+ content in search. (e.g. location (path) for TechDocs page)
+- It should be possible to refine search queries (e.g. ranking, scoring, etc.)
+- It should be possible to customize the search UI
+- It should be possible to add search functionality to any Backstage plugin or
+ deployment
+
+Architecture non-goals:
+
+- At this time, we do not intend to directly support event-driven or incremental
+ index management. Instead, we'll be focused on scheduled, bulk index
+ management.
diff --git a/docs/features/software-catalog/configuration.md b/docs/features/software-catalog/configuration.md
index d10fb29e30..d5ad240dde 100644
--- a/docs/features/software-catalog/configuration.md
+++ b/docs/features/software-catalog/configuration.md
@@ -60,7 +60,7 @@ data from. Each entry is a structure with up to four elements:
and raw. If it is not supplied, anonymous access will be used.
- `apiBaseUrl` (optional): If you want to communicate using the APIv3 method
with this provider, specify the base URL for its endpoint here, with no
- trailing slash. Specifically when the target is github, you can leave it out
+ trailing slash. Specifically when the target is GitHub, you can leave it out
to be inferred automatically. For a GitHub Enterprise installation, it is
commonly at `https://api.
> Note: See below for our recommended deployment architecture which takes care
-> of stability, scalability and speed.
+> of stability, scalability and speed. Also look at the
+> [HOW TO migrate guide](how-to-guides.md#how-to-migrate-from-techdocs-basic-to-recommended-deployment-approach).
When you open a TechDocs site in Backstage, the
[TechDocs Reader](./concepts.md#techdocs-reader) makes a request to
-`techdocs-backend` with the entity ID and the path of the current page you are
-looking at. In response, it receives the static files (HTML, CSS, JSON, etc.) to
-render on the page in TechDocs/Backstage.
+`techdocs-backend` plugin with the entity ID and the path of the current page
+you are looking at. In response, it receives the static files (HTML, CSS, JSON,
+etc.) to render on the page in TechDocs/Backstage.
The static files consist of HTML, CSS and Images generated by MkDocs. We remove
-all the Javascript before adding them to Backstage for security reasons. And
-there are some additional techdocs metadata JSON files that TechDocs needs to
-render a site.
+all the JavaScript before adding them to Backstage for security reasons. And
+there is an additional `techdocs_metadata.json` file that TechDocs needs to
+render a site. It's important that you use either
+[techdocs-cli](https://github.com/backstage/techdocs-cli) or
+[techdocs-container](https://github.com/backstage/techdocs-container) to
+generate the docs for the expected output.
The TechDocs Reader then applies a list of "Transformers" (see
[Concepts](./concepts.md)) which modify the generated static HTML files for a
number of use cases e.g. Remove certain headers, filter out some HTML tags, etc.
Currently, we use the Backstage server's (or techdocs-backend's) local file
-system to store the generated files. Publishing to an external storage system
-(AWS S3, GCS, etc.) is also possible, but has not been implemented yet.
-
-A word about `UrlReader` vs Git preparer - Right now, we have two ways to fetch
-files from its source repository for docs site generation. 1. By using Git
-and 2. By directly using Source control (GitHub, Azure, etc.) APIs. This work is
-heavily in progress. Please reach out to us on Discord in the #docs-like-code
-channel to talk about it.
+system to store the generated files. However, it's ideal to use an external
+storage system (e.g. AWS S3, GCS or Azure Blob Storage). Read more in
+[using cloud storage](using-cloud-storage.md).
## Recommended deployment
@@ -49,22 +48,16 @@ The key difference in the recommended deployment approach is where the docs are
built.
We assume each entity lives in a repository somewhere (GitHub, GitLab, etc.). We
-recommend using a CI/CD pipeline with the repository that has a dedicated
-step/job to build docs for TechDocs. The generated static files are then stored
-in a cloud storage solution of your choice.
-[Track progress here](https://github.com/backstage/backstage/issues/3096).
+recommend [using a CI/CD pipeline](configuring-ci-cd.md) with the repository
+that has a dedicated step/job to generate docs for TechDocs. The generated
+static files are then [stored in a cloud storage](using-cloud-storage.md)
+solution of your choice.
Similar to how it is done in the Basic setup, the TechDocs Reader requests
`techdocs-backend` plugin for the docs site. `techdocs-backend` then requests
your configured storage solution for the necessary files and returns them to
TechDocs Reader.
-We will provide instructions, scripts and/or templates (e.g. GitHub actions) to
-build docs in your CI/CD system.
-[Track progress here.](https://github.com/backstage/backstage/issues/3400) You
-will be able to use `techdocs-cli` to build docs and publish the generated docs
-site files to your cloud storage system.
-
Note about caching: We have noticed internally that some storage providers can
be quite slow, which is why we are recommending a cache that sits between the
TechDocs Reader and the Storage.
@@ -97,7 +90,7 @@ permissions to publish the generated docs site files.
**Q: Why do you have separate "basic" and "recommended" deployment approaches?**
A: The basic or out-of-the-box setup is what you get when you create a new app
-or do a git clone of the Backstage repository. We want the first experience to
+or do a `git clone` of the Backstage repository. We want the first experience to
_just work magically_ so that you can have your first experience with TechDocs
which is smooth. However, if you decide to deploy Backstage/TechDocs for
production use, the basic setup would work but there are going to be downsides
@@ -109,19 +102,35 @@ and we welcome such "Alternative" ideas from the community.
**Q: Why don't you recommend techdocs-backend local filesystem to serve static
files?**
-A: It would make scaling a Backstage instance harder. Think about the case where
-we have distributed Backstage deployments. Using a separate file storage system
-for TechDocs makes it easier to do some operations like delete a docs site and
-wipe its contents.
+A: It makes scaling a Backstage instance harder. Think about the case where we
+have distributed Backstage deployments (e.g. multiple Kubernetes pods of your
+Backstage app). Using a separate/central file storage system for TechDocs is
+necessary to make sure sites are persistent when the servers/pods are restarted
+and avoid duplicating sites per instance. By having an external storage, we are
+making it easier to do some operations like delete a docs site or wipe its
+contents.
**Q: Why aren't docs built on the fly i.e. when users visits a page, generate
docs site in real-time?**
-A: Generating the content from Markdown on the fly is not optimal (although that
-is how the basic out-of-the-box setup is implemented). Storage solutions act as
-a cache for the generated static content. TechDocs is also currently built on
-MkDocs which does not allow us to build docs per-page, so we would have to build
-all docs for a entity on every request.
+A: Generating the content from Markdown on the fly is not optimal. Storage
+solutions act as a cache for the generated static content. TechDocs is also
+currently built on MkDocs which does not allow us to generate docs per-page, so
+we would have to build all docs for a entity on every request.
+
+**Q. Can you use the techdocs plugin without the techdocs-backend plugin?**
+
+A: `techdocs` and `techdocs-backend` plugins are designed to be used together,
+like any other Backstage plugin with a frontend and its backend (catalog,
+scaffolder, etc.). If you set your Backstage instance to generate docs on the
+server, `techdocs-backend` will be responsible for managing the whole build
+process, making sure it's scalable. It is responsible for securely communicating
+with the cloud storage provider, for both fetching static generated sites and
+publishing the updates. There are other planned features like an authentication
+layer for users to determine whether they have the permission to view a
+particular docs site. There are a handful of features which are extremely hard
+to develop without a tightly integrated backend in place. Hence, support for
+`techdocs` without `techdocs-backend` is limited and challenging to develop.
# Future work
@@ -132,22 +141,5 @@ We currently depend on MkDocs to parse doc sites written in Markdown. And we
store the generated static assets and re-use it later to render in Backstage. A
better (futuristic) approach will be to directly parse whatever type of source
files you have in your docs repository and directly render in Backstage in
-real-time.
-
-# Features status
-
-Status of all the features mentioned above.
-
-**In place ✅**
-
-- Basic setup with techdocs-backend file server as storage.
-
-**Work in progress 🚧**
-
-- Basic setup with cloud storage solution.
-
-**Not implemented yet ❌**
-
-- `techdocs-cli` is able to generate docs in CI/CD environment.
-- `techdocs-cli` is able to publish docs site to any storage.
-- `techdocs-backend` integration with Backstage access control management.
+real-time. You can read more in this
+[RFC - Simplifying TechDocs Frontend Architecture](https://github.com/backstage/backstage/issues/3998).
diff --git a/docs/features/techdocs/concepts.md b/docs/features/techdocs/concepts.md
index 1675c64288..408f092ebd 100644
--- a/docs/features/techdocs/concepts.md
+++ b/docs/features/techdocs/concepts.md
@@ -1,22 +1,52 @@
---
id: concepts
title: Concepts
-description: Documentation on concepts that are introduced with
-Spotify's docs-like-code solution in Backstage
+# prettier-ignore
+description: Documentation on 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
+## Generating TechDocs Steps
-The TechDocs Core Plugin is an [MkDocs](https://www.mkdocs.org/) plugin created
-as a wrapper around multiple MkDocs plugins and Python Markdown extensions to
-standardize the configuration of MkDocs used for TechDocs.
+### TechDocs Preparer
-[TechDocs Core](https://github.com/backstage/mkdocs-techdocs-core)
+Preparing is the first step of generating documentation for an entity. It
+fetches the source markdown files from the source code hosting provider (GitHub,
+GitLab, etc.) and passes the files to the generator for next steps.
-### TechDocs container
+There are two kinds of preparers available -
+
+1. Common Git Preparer - Uses `git clone` on any repository url.
+2. Url Reader - Uses source code hosting provider's API to download files.
+ (Faster and recommended)
+
+### TechDocs Generator
+
+Generating is the second step after preparing the markdown source files. This
+step either runs the TechDocs container (defined below) or runs `mkdocs` CLI to
+generate static HTML files and its assets.
+
+### TechDocs Publisher
+
+Publishing is the third and final step after preparing and generating docs.
+TechDocs Publisher uploads the generated files to a storage.
+
+The `techdocs-backend` plugin currently comes with two publishers - Google Cloud
+Storage and Local Filesystem. You can configure them in your Backstage app.
+[See here](./configuration.md).
+
+A TechDocs publisher is responsible for two things (two-way communication
+between `techdocs-backend` and the storage)
+
+1. Publish generated static files to a storage (Configured by
+ `techdocs.builder`)
+2. Read files from the storage when users visit a TechDocs site
+
+[TechDocs Backend](https://github.com/backstage/backstage/tree/master/plugins/techdocs-backend)
+
+## TechDocs Container
The TechDocs container is a Docker container available at
[DockerHub](https://hub.docker.com/r/spotify/techdocs). It builds static HTML
@@ -25,16 +55,15 @@ MkDocs.
[TechDocs Container](https://github.com/backstage/techdocs-container)
-### TechDocs publisher
+## TechDocs Core Plugin
-The `techdocs-backend` plugin currently comes with one publisher -
-`LocalPublish`.
+The TechDocs Core Plugin is an [MkDocs](https://www.mkdocs.org/) plugin created
+as a wrapper around multiple MkDocs plugins and Python Markdown extensions to
+standardize the configuration of MkDocs used for TechDocs.
-[TechDocs Backend](https://github.com/backstage/backstage/tree/master/plugins/techdocs-backend)
+[TechDocs Core](https://github.com/backstage/mkdocs-techdocs-core)
-More standalone publishers will come in the near future...
-
-### TechDocs CLI
+## TechDocs CLI
The TechDocs CLI was created to make it easy to write, generate and preview
documentation for publishing. Currently it mostly acts as a wrapper around the
@@ -43,7 +72,7 @@ container.
[TechDocs CLI](https://github.com/backstage/techdocs-cli)
-### TechDocs Reader
+## TechDocs Reader
Documentation generated by TechDocs is generated as static HTML sites. The
TechDocs Reader was therefore created to be able to integrate pre-generated HTML
@@ -55,7 +84,7 @@ TechDocs widgets for a customized full-featured TechDocs experience.
[TechDocs Reader](https://github.com/backstage/backstage/blob/master/plugins/techdocs/src/reader/README.md)
-### Transformers
+## Transformers
Transformers are different pieces of functionality used inside the TechDocs
Reader. The reason why transformers were introduced was to provide a way to
diff --git a/docs/features/techdocs/configuration.md b/docs/features/techdocs/configuration.md
new file mode 100644
index 0000000000..20e436d8a4
--- /dev/null
+++ b/docs/features/techdocs/configuration.md
@@ -0,0 +1,106 @@
+---
+id: configuration
+title: TechDocs Configuration Options
+# prettier-ignore
+description: Reference documentation for configuring TechDocs using app-config.yaml
+---
+
+Using the `app-config.yaml` in the Backstage app, you can configure TechDocs
+using several options. This page serves as a reference to all the available
+configuration options for TechDocs.
+
+```yaml
+# File: app-config.yaml
+
+techdocs:
+ # generators.techdocs can have two values: 'docker' or 'local'. This is to determine how to run the generator - whether to
+ # spin up the techdocs-container docker image or to run mkdocs locally (assuming all the dependencies are taken care of).
+ # You want to change this to 'local' if you are running Backstage using your own custom Docker setup and want to avoid running
+ # into Docker in Docker situation. Read more here
+ # https://backstage.io/docs/features/techdocs/getting-started#disable-docker-in-docker-situation-optional
+
+ generators:
+ techdocs: 'docker'
+
+ # techdocs.builder can be either 'local' or 'external.
+ # If builder is set to 'local' and you open a TechDocs page, techdocs-backend will try to generate the docs, publish to storage
+ # and show the generated docs afterwords. This is the "Basic" setup of the TechDocs Architecture.
+ # If builder is set to 'external', techdocs-backend will only fetch the docs and will NOT try to generate and publish. In this case of 'external',
+ # we assume that docs are being built by an external process (e.g. in the CI/CD pipeline of the repository). This is the "Recommended" setup of
+ # the architecture. Read more here https://backstage.io/docs/features/techdocs/architecture
+
+ builder: 'local'
+
+ # techdocs.publisher is used to configure the Storage option, whether you want to use the local filesystem to store generated docs
+ # or you want to use External storage providers like Google Cloud Storage, AWS S3, etc.
+
+ publisher:
+ # techdocs.publisher.type can be - 'local' or 'googleGcs' or 'awsS3' or 'azureBlobStorage'.
+ # When set to 'local', techdocs-backend will create a 'static' directory at its root to store generated documentation files.
+ # When set to 'googleGcs', techdocs-backend will use a Google Cloud Storage Bucket to store generated documentation files.
+ # When set to 'awsS3', techdocs-backend will use an Amazon Web Service (AWS) S3 bucket to store generated documentation files.
+
+ type: 'local'
+
+ # Required when techdocs.publisher.type is set to 'googleGcs'. Skip otherwise.
+
+ googleGcs:
+ # (Required) Cloud Storage Bucket Name
+ bucketName: 'techdocs-storage'
+
+ # (Optional) An API key is required to write to a storage bucket.
+ # If missing, GOOGLE_APPLICATION_CREDENTIALS environment variable will be used.
+ # https://cloud.google.com/docs/authentication/production
+ credentials:
+ $file: '/path/to/google_application_credentials.json'
+
+ # Required when techdocs.publisher.type is set to 'awsS3'. Skip otherwise.
+
+ awsS3:
+ # (Required) AWS S3 Bucket Name
+ bucketName: 'techdocs-storage'
+
+ # (Optional) An API key is required to write to a storage bucket.
+ # If not set, environment variables or aws config file will be used to authenticate.
+ # https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/loading-node-credentials-environment.html
+ # https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/loading-node-credentials-shared.html
+ credentials:
+ accessKeyId:
+ $env: TECHDOCS_AWSS3_ACCESS_KEY_ID_CREDENTIAL
+ secretAccessKey:
+ $env: TECHDOCS_AWSS3_SECRET_ACCESS_KEY_CREDENTIAL
+
+ # (Optional) AWS Region of the bucket.
+ # If not set, AWS_REGION environment variable or aws config file will be used.
+ # https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/setting-region.html
+ region:
+ $env: AWS_REGION
+
+ # Required when techdocs.publisher.type is set to 'azureBlobStorage'. Skip otherwise.
+
+ azureBlobStorage:
+ # (Required) Azure Blob Storage Container Name
+ containerName: 'techdocs-storage'
+
+ # (Required) An account name is required to write to a storage blob container.
+ # https://docs.microsoft.com/en-us/rest/api/storageservices/authorize-with-shared-key
+ credentials:
+ accountName:
+ $env: TECHDOCS_AZURE_BLOB_STORAGE_ACCOUNT_NAME
+ # (Optional) An account key is required to write to a storage container.
+ # If missing,AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET environment variable will be used.
+ # https://docs.microsoft.com/en-us/azure/storage/common/storage-auth?toc=/azure/storage/blobs/toc.json
+ accountKey:
+ $env: TECHDOCS_AZURE_BLOB_STORAGE_ACCOUNT_KEY
+
+ # (Optional and Legacy) TechDocs makes API calls to techdocs-backend using this URL. e.g. get docs of an entity, get metadata, etc.
+ # You don't have to specify this anymore.
+
+ requestUrl: http://localhost:7000/api/techdocs
+
+ # (Optional and Legacy) Just another route in techdocs-backend where TechDocs requests the static files from. This URL uses an HTTP middleware
+ # to serve files from either a local directory or an External storage provider.
+ # You don't have to specify this anymore.
+
+ storageUrl: http://localhost:7000/api/techdocs/static/docs
+```
diff --git a/docs/features/techdocs/configuring-ci-cd.md b/docs/features/techdocs/configuring-ci-cd.md
new file mode 100644
index 0000000000..a9844ef528
--- /dev/null
+++ b/docs/features/techdocs/configuring-ci-cd.md
@@ -0,0 +1,169 @@
+---
+id: configuring-ci-cd
+title: Configuring CI/CD to generate and publish TechDocs sites
+# prettier-ignore
+description: Configuring CI/CD to generate and publish TechDocs sites to cloud storage
+---
+
+In the [Recommended deployment setup](./architecture.md#recommended-deployment),
+TechDocs reads the static generated documentation files from a cloud storage
+bucket (GCS, AWS S3, etc.). The documentation site is generated on the CI/CD
+workflow associated with the repository containing the documentation files. This
+document explains the steps needed to generate docs on CI and publish to a cloud
+storage using [`techdocs-cli`](https://github.com/backstage/techdocs-cli).
+
+The steps here target all kinds of CI providers (GitHub Actions, CircleCI,
+Jenkins, etc.). Specific tools for individual providers will also be made
+available here for simplicity (e.g. a GitHub Actions runner, CircleCI orb,
+etc.).
+
+A summary of the instructions below looks like this -
+
+```sh
+# This is an example script
+
+# Prepare
+REPOSITORY_URL='https://github.com/org/repo'
+git clone $REPOSITORY_URL
+cd repo
+
+# Install @techdocs/cli, mkdocs and mkdocs plugins
+npm install -g @techdocs/cli
+pip install mkdocs-techdocs-core==0.*
+
+# Generate
+techdocs-cli generate --no-docker
+
+# Publish
+techdocs-cli publish --publisher-type awsS3 --storage-name 
+
+