docs: migrate feature docs to new frontend system as primary content
Rewrite documentation for TechDocs, Software Templates, Software Catalog, Search, and Kubernetes features to use the new frontend system as the primary installation and configuration instructions. Old frontend system instructions are moved to separate `--old` suffixed files for pages with substantial legacy content, or updated inline for pages with minimal old-system content. Files migrated: - techdocs/getting-started.md - techdocs/how-to-guides.md - software-templates/writing-custom-step-layouts.md - software-templates/writing-custom-field-extensions.md - software-templates/index.md - software-catalog/catalog-customization.md - search/getting-started.md - search/how-to-guides.md - kubernetes/installation.md Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com> Made-with: Cursor
This commit is contained in:
Patrik Oldsberg
@@ -0,0 +1,242 @@
|
||||
---
|
||||
id: getting-started--old
|
||||
title: Getting Started (Old Frontend System)
|
||||
description: Getting Started Documentation
|
||||
---
|
||||
|
||||
::::info
|
||||
This documentation is for Backstage apps that still use the old frontend
|
||||
system. If your app uses the new frontend system, read the
|
||||
[current guide](./getting-started.md) instead.
|
||||
::::
|
||||
|
||||
TechDocs functions as a plugin in Backstage and ships with it installed out of the box, so you will need to use Backstage to use TechDocs.
|
||||
|
||||
If you haven't setup Backstage already, start [here](../../getting-started/index.md).
|
||||
|
||||
## Adding TechDocs frontend plugin
|
||||
|
||||
The first step is to add the TechDocs plugin to your Backstage application.
|
||||
Navigate to your new Backstage application directory. And then to your
|
||||
`packages/app` directory, and install the `@backstage/plugin-techdocs` package.
|
||||
|
||||
```bash title="From your Backstage root directory"
|
||||
yarn --cwd packages/app add @backstage/plugin-techdocs
|
||||
```
|
||||
|
||||
Once the package has been installed, you need to import the plugin in your app.
|
||||
|
||||
In `packages/app/src/App.tsx`, import `TechDocsPage` and add the following to
|
||||
`FlatRoutes`:
|
||||
|
||||
```tsx title="packages/app/src/App.tsx"
|
||||
import {
|
||||
DefaultTechDocsHome,
|
||||
TechDocsIndexPage,
|
||||
TechDocsReaderPage,
|
||||
} from '@backstage/plugin-techdocs';
|
||||
|
||||
const AppRoutes = () => {
|
||||
<FlatRoutes>
|
||||
{/* ... other plugin routes */}
|
||||
<Route path="/docs" element={<TechDocsIndexPage />}>
|
||||
<DefaultTechDocsHome />
|
||||
</Route>
|
||||
<Route
|
||||
path="/docs/:namespace/:kind/:name/*"
|
||||
element={<TechDocsReaderPage />}
|
||||
/>
|
||||
</FlatRoutes>;
|
||||
};
|
||||
```
|
||||
|
||||
It would be nice to decorate your pages with something else... Having a link that redirects you to a new issue page when you highlight text in your documentation would be really cool, right? Let's learn how to do this using the TechDocs Addon Framework!
|
||||
|
||||
With the [TechDocs Addon framework](https://backstage.io/docs/features/techdocs/addons#installing-and-using-addons), you can render React components in documentation pages and these Addons can be provided by any Backstage plugin. The framework is exported by the [@backstage/plugin-techdocs-react](https://www.npmjs.com/package/@backstage/plugin-techdocs-react) package and there is a `<ReportIssue />` Addon in the [@backstage/plugin-techdocs-module-addons-contrib](https://www.npmjs.com/package/@backstage/plugin-techdocs-module-addons-contrib) package for you to use once you have these two dependencies installed:
|
||||
|
||||
```tsx
|
||||
import {
|
||||
DefaultTechDocsHome,
|
||||
TechDocsIndexPage,
|
||||
TechDocsReaderPage,
|
||||
} from '@backstage/plugin-techdocs';
|
||||
/* highlight-add-start */
|
||||
import { TechDocsAddons } from '@backstage/plugin-techdocs-react';
|
||||
import { ReportIssue } from '@backstage/plugin-techdocs-module-addons-contrib';
|
||||
/* highlight-add-end */
|
||||
|
||||
const AppRoutes = () => {
|
||||
<FlatRoutes>
|
||||
{/* ... other plugin routes */}
|
||||
<Route path="/docs" element={<TechDocsIndexPage />}>
|
||||
<DefaultTechDocsHome />
|
||||
</Route>
|
||||
<Route
|
||||
path="/docs/:namespace/:kind/:name/*"
|
||||
element={<TechDocsReaderPage />}
|
||||
>
|
||||
{/* highlight-add-start */}
|
||||
<TechDocsAddons>
|
||||
<ReportIssue />
|
||||
</TechDocsAddons>
|
||||
{/* highlight-add-end */}
|
||||
</Route>
|
||||
</FlatRoutes>;
|
||||
};
|
||||
```
|
||||
|
||||
I know, you're curious to see how it looks, aren't you? See the image below:
|
||||
|
||||
<!-- todo: Needs zoomable plugin -->
|
||||
|
||||
|
||||
|
||||
By clicking the open new issue button, you will be redirected to the new issue page according to the source code provider you are using:
|
||||
|
||||
<!-- todo: Needs zoomable plugin -->
|
||||
|
||||
|
||||
|
||||
That's it! Now, we need the TechDocs Backend plugin for the frontend to work.
|
||||
|
||||
## Adding TechDocs Backend plugin
|
||||
|
||||
First we need to install the `@backstage/plugin-techdocs-backend` package.
|
||||
|
||||
```bash title="From your Backstage root directory"
|
||||
yarn --cwd packages/backend add @backstage/plugin-techdocs-backend
|
||||
```
|
||||
|
||||
Then in your backend `index.ts` you will add the following line.
|
||||
|
||||
```ts title="packages/backend/src/index.ts"
|
||||
const backend = createBackend();
|
||||
|
||||
// Other plugins...
|
||||
|
||||
/* highlight-add-start */
|
||||
backend.add(import('@backstage/plugin-techdocs-backend'));
|
||||
/* highlight-add-end */
|
||||
|
||||
backend.start();
|
||||
```
|
||||
|
||||
That's it! TechDocs frontend and backend have now been added to your Backstage
|
||||
app. Now let us tweak some configurations to suit your needs.
|
||||
|
||||
## Setting the configuration
|
||||
|
||||
**See [TechDocs Configuration Options](configuration.md) for complete
|
||||
configuration reference.**
|
||||
|
||||
### Should TechDocs Backend generate docs?
|
||||
|
||||
```yaml
|
||||
techdocs:
|
||||
builder: 'local'
|
||||
```
|
||||
|
||||
Note that we recommend generating docs on CI/CD instead. Read more in the
|
||||
"Basic" and "Recommended" sections of the
|
||||
[TechDocs Architecture](architecture.md). But if you want to get started quickly
|
||||
set `techdocs.builder` to `'local'` so that TechDocs Backend is responsible for
|
||||
generating documentation sites. If set to `'external'`, Backstage will assume
|
||||
that the sites are being generated on each entity's CI/CD pipeline, and are
|
||||
being stored in a storage somewhere.
|
||||
|
||||
When `techdocs.builder` is set to `'external'`, TechDocs becomes more or less a
|
||||
read-only experience where it serves static files from a storage containing all
|
||||
the generated documentation.
|
||||
|
||||
### Choosing storage (publisher)
|
||||
|
||||
TechDocs needs to know where to store generated documentation sites and where to
|
||||
fetch the sites from. This is managed by a
|
||||
[Publisher](./concepts.md#techdocs-publisher). Examples: Google Cloud Storage,
|
||||
Amazon S3, or local filesystem of Backstage server.
|
||||
|
||||
It is okay to use the local filesystem in a "basic" setup when you are trying
|
||||
out Backstage for the first time. At a later time, review
|
||||
[Using Cloud Storage](./using-cloud-storage.md).
|
||||
|
||||
```yaml
|
||||
techdocs:
|
||||
builder: 'local'
|
||||
publisher:
|
||||
type: 'local'
|
||||
```
|
||||
|
||||
### Disabling Docker in Docker situation (Optional)
|
||||
|
||||
You can skip this if your `techdocs.builder` is set to `'external'`.
|
||||
|
||||
The TechDocs Backend plugin runs a docker container with mkdocs installed to
|
||||
generate the frontend of the docs from source files (Markdown). If you are
|
||||
deploying Backstage using Docker, this will mean that your Backstage Docker
|
||||
container will try to run another Docker container for TechDocs Backend.
|
||||
|
||||
To avoid this problem, we have a configuration available. You can set a value in
|
||||
your `app-config.yaml` that tells the techdocs generator if it should run the
|
||||
`local` mkdocs or run it from `docker`. This defaults to running as `docker` if
|
||||
no config is provided.
|
||||
|
||||
```yaml
|
||||
techdocs:
|
||||
builder: 'local'
|
||||
publisher:
|
||||
type: 'local'
|
||||
generator:
|
||||
runIn: local
|
||||
```
|
||||
|
||||
Setting `generator.runIn` to `local` means you will have to make sure your
|
||||
environment is compatible with techdocs.
|
||||
|
||||
You will have to install the `mkdocs` and `mkdocs-techdocs-core` package from
|
||||
pip, optionally also `graphviz` and `plantuml` from your OS package manager (e.g.
|
||||
apt).
|
||||
|
||||
You can do so by including the following lines right above `USER node` of your
|
||||
`Dockerfile`:
|
||||
|
||||
```Dockerfile
|
||||
RUN apt-get update && \
|
||||
apt-get install -y python3 python3-pip python3-venv && \
|
||||
rm -rf /var/lib/apt/lists/*
|
||||
|
||||
ENV VIRTUAL_ENV=/opt/venv
|
||||
RUN python3 -m venv $VIRTUAL_ENV
|
||||
ENV PATH="$VIRTUAL_ENV/bin:$PATH"
|
||||
|
||||
RUN pip3 install mkdocs-techdocs-core
|
||||
```
|
||||
|
||||
Please be aware that the version requirement could change, you need to check our
|
||||
[`Dockerfile`](https://github.com/backstage/techdocs-container/blob/main/Dockerfile)
|
||||
and make sure to match with it.
|
||||
|
||||
On a Debian-based Docker container, Python packages must be either installed using
|
||||
the OS package manager or within a virtual environment (see the
|
||||
[related PEP](https://peps.python.org/pep-0668/)). Alternative is to use e.g.
|
||||
[pipx](https://pypa.github.io/pipx/) for installing Python packages in an isolated
|
||||
environment.
|
||||
|
||||
The above Dockerfile snippet installs the latest `mkdocs-techdoc-core` package.
|
||||
Version numbers can be found in the corresponding
|
||||
[changelog](https://github.com/backstage/mkdocs-techdocs-core#changelog). In
|
||||
case you want to pin the version, use the example below:
|
||||
|
||||
```Dockerfile
|
||||
RUN pip3 install mkdocs-techdocs-core==1.2.3
|
||||
```
|
||||
|
||||
Note: We recommend Python version 3.11 or higher.
|
||||
|
||||
> Caveat: Please install the `mkdocs-techdocs-core` package after all other
|
||||
> Python packages. The order is important to make sure we get correct version of
|
||||
> some of the dependencies.
|
||||
|
||||
## Additional reading
|
||||
|
||||
- [Creating and publishing your docs](creating-and-publishing.md)
|
||||
- [Back to README](README.md)
|
||||
@@ -4,6 +4,13 @@ title: Getting Started
|
||||
description: Getting Started Documentation
|
||||
---
|
||||
|
||||
::::info
|
||||
This documentation is written for the new frontend system, which is the default
|
||||
in new Backstage apps. If your Backstage app still uses the old frontend system,
|
||||
read the [old frontend system version of this guide](./getting-started--old.md)
|
||||
instead.
|
||||
::::
|
||||
|
||||
TechDocs functions as a plugin in Backstage and ships with it installed out of the box, so you will need to use Backstage to use TechDocs.
|
||||
|
||||
If you haven't setup Backstage already, start [here](../../getting-started/index.md).
|
||||
@@ -11,88 +18,37 @@ If you haven't setup Backstage already, start [here](../../getting-started/index
|
||||
## Adding TechDocs frontend plugin
|
||||
|
||||
The first step is to add the TechDocs plugin to your Backstage application.
|
||||
Navigate to your new Backstage application directory. And then to your
|
||||
`packages/app` directory, and install the `@backstage/plugin-techdocs` package.
|
||||
|
||||
```bash title="From your Backstage root directory"
|
||||
yarn --cwd packages/app add @backstage/plugin-techdocs
|
||||
```
|
||||
|
||||
Once the package has been installed, you need to import the plugin in your app.
|
||||
Once installed, the plugin is automatically available in your app through the default feature discovery. For more details and alternative installation methods, see [installing plugins](../../frontend-system/building-apps/05-installing-plugins.md).
|
||||
|
||||
In `packages/app/src/App.tsx`, import `TechDocsPage` and add the following to
|
||||
`FlatRoutes`:
|
||||
The plugin provides a docs index page at `/docs` and a reader page for individual documentation sites, along with a "Docs" navigation item in the sidebar and a documentation tab on entity pages.
|
||||
|
||||
```tsx title="packages/app/src/App.tsx"
|
||||
import {
|
||||
DefaultTechDocsHome,
|
||||
TechDocsIndexPage,
|
||||
TechDocsReaderPage,
|
||||
} from '@backstage/plugin-techdocs';
|
||||
## Using TechDocs Addons
|
||||
|
||||
const AppRoutes = () => {
|
||||
<FlatRoutes>
|
||||
{/* ... other plugin routes */}
|
||||
<Route path="/docs" element={<TechDocsIndexPage />}>
|
||||
<DefaultTechDocsHome />
|
||||
</Route>
|
||||
<Route
|
||||
path="/docs/:namespace/:kind/:name/*"
|
||||
element={<TechDocsReaderPage />}
|
||||
/>
|
||||
</FlatRoutes>;
|
||||
};
|
||||
The TechDocs Addon framework lets you render React components in documentation pages. Addons are provided as separate plugin packages that are automatically discovered when installed.
|
||||
|
||||
For example, to add the Report Issue addon:
|
||||
|
||||
```bash title="From your Backstage root directory"
|
||||
yarn --cwd packages/app add @backstage/plugin-techdocs-module-addons-contrib
|
||||
```
|
||||
|
||||
It would be nice to decorate your pages with something else... Having a link that redirects you to a new issue page when you highlight text in your documentation would be really cool, right? Let's learn how to do this using the TechDocs Addon Framework!
|
||||
|
||||
With the [TechDocs Addon framework](https://backstage.io/docs/features/techdocs/addons#installing-and-using-addons), you can render React components in documentation pages and these Addons can be provided by any Backstage plugin. The framework is exported by the [@backstage/plugin-techdocs-react](https://www.npmjs.com/package/@backstage/plugin-techdocs-react) package and there is a `<ReportIssue />` Addon in the [@backstage/plugin-techdocs-module-addons-contrib](https://www.npmjs.com/package/@backstage/plugin-techdocs-module-addons-contrib) package for you to use once you have these two dependencies installed:
|
||||
|
||||
```tsx
|
||||
import {
|
||||
DefaultTechDocsHome,
|
||||
TechDocsIndexPage,
|
||||
TechDocsReaderPage,
|
||||
} from '@backstage/plugin-techdocs';
|
||||
/* highlight-add-start */
|
||||
import { TechDocsAddons } from '@backstage/plugin-techdocs-react';
|
||||
import { ReportIssue } from '@backstage/plugin-techdocs-module-addons-contrib';
|
||||
/* highlight-add-end */
|
||||
|
||||
const AppRoutes = () => {
|
||||
<FlatRoutes>
|
||||
{/* ... other plugin routes */}
|
||||
<Route path="/docs" element={<TechDocsIndexPage />}>
|
||||
<DefaultTechDocsHome />
|
||||
</Route>
|
||||
<Route
|
||||
path="/docs/:namespace/:kind/:name/*"
|
||||
element={<TechDocsReaderPage />}
|
||||
>
|
||||
{/* highlight-add-start */}
|
||||
<TechDocsAddons>
|
||||
<ReportIssue />
|
||||
</TechDocsAddons>
|
||||
{/* highlight-add-end */}
|
||||
</Route>
|
||||
</FlatRoutes>;
|
||||
};
|
||||
```
|
||||
|
||||
I know, you're curious to see how it looks, aren't you? See the image below:
|
||||
Once installed, the addon is automatically active. You can see it in action when you highlight text in your documentation:
|
||||
|
||||
<!-- todo: Needs zoomable plugin -->
|
||||
|
||||
|
||||
|
||||
By clicking the open new issue button, you will be redirected to the new issue page according to the source code provider you are using:
|
||||
By clicking the open new issue button, you are redirected to the new issue page according to the source code provider you are using:
|
||||
|
||||
<!-- todo: Needs zoomable plugin -->
|
||||
|
||||
|
||||
|
||||
That's it! Now, we need the TechDocs Backend plugin for the frontend to work.
|
||||
|
||||
## Adding TechDocs Backend plugin
|
||||
|
||||
First we need to install the `@backstage/plugin-techdocs-backend` package.
|
||||
@@ -115,13 +71,11 @@ backend.add(import('@backstage/plugin-techdocs-backend'));
|
||||
backend.start();
|
||||
```
|
||||
|
||||
That's it! TechDocs frontend and backend have now been added to your Backstage
|
||||
app. Now let us tweak some configurations to suit your needs.
|
||||
That's it! TechDocs frontend and backend have now been added to your Backstage app. Now let us tweak some configurations to suit your needs.
|
||||
|
||||
## Setting the configuration
|
||||
|
||||
**See [TechDocs Configuration Options](configuration.md) for complete
|
||||
configuration reference.**
|
||||
**See [TechDocs Configuration Options](configuration.md) for complete configuration reference.**
|
||||
|
||||
### Should TechDocs Backend generate docs?
|
||||
|
||||
@@ -130,28 +84,15 @@ techdocs:
|
||||
builder: 'local'
|
||||
```
|
||||
|
||||
Note that we recommend generating docs on CI/CD instead. Read more in the
|
||||
"Basic" and "Recommended" sections of the
|
||||
[TechDocs Architecture](architecture.md). But if you want to get started quickly
|
||||
set `techdocs.builder` to `'local'` so that TechDocs Backend is responsible for
|
||||
generating documentation sites. If set to `'external'`, Backstage will assume
|
||||
that the sites are being generated on each entity's CI/CD pipeline, and are
|
||||
being stored in a storage somewhere.
|
||||
Note that we recommend generating docs on CI/CD instead. Read more in the "Basic" and "Recommended" sections of the [TechDocs Architecture](architecture.md). But if you want to get started quickly set `techdocs.builder` to `'local'` so that TechDocs Backend is responsible for generating documentation sites. If set to `'external'`, Backstage will assume that the sites are being generated on each entity's CI/CD pipeline, and are being stored in a storage somewhere.
|
||||
|
||||
When `techdocs.builder` is set to `'external'`, TechDocs becomes more or less a
|
||||
read-only experience where it serves static files from a storage containing all
|
||||
the generated documentation.
|
||||
When `techdocs.builder` is set to `'external'`, TechDocs becomes more or less a read-only experience where it serves static files from a storage containing all the generated documentation.
|
||||
|
||||
### Choosing storage (publisher)
|
||||
|
||||
TechDocs needs to know where to store generated documentation sites and where to
|
||||
fetch the sites from. This is managed by a
|
||||
[Publisher](./concepts.md#techdocs-publisher). Examples: Google Cloud Storage,
|
||||
Amazon S3, or local filesystem of Backstage server.
|
||||
TechDocs needs to know where to store generated documentation sites and where to fetch the sites from. This is managed by a [Publisher](./concepts.md#techdocs-publisher). Examples: Google Cloud Storage, Amazon S3, or local filesystem of Backstage server.
|
||||
|
||||
It is okay to use the local filesystem in a "basic" setup when you are trying
|
||||
out Backstage for the first time. At a later time, review
|
||||
[Using Cloud Storage](./using-cloud-storage.md).
|
||||
It is okay to use the local filesystem in a "basic" setup when you are trying out Backstage for the first time. At a later time, review [Using Cloud Storage](./using-cloud-storage.md).
|
||||
|
||||
```yaml
|
||||
techdocs:
|
||||
@@ -164,15 +105,9 @@ techdocs:
|
||||
|
||||
You can skip this if your `techdocs.builder` is set to `'external'`.
|
||||
|
||||
The TechDocs Backend plugin runs a docker container with mkdocs installed to
|
||||
generate the frontend of the docs from source files (Markdown). If you are
|
||||
deploying Backstage using Docker, this will mean that your Backstage Docker
|
||||
container will try to run another Docker container for TechDocs Backend.
|
||||
The TechDocs Backend plugin runs a docker container with mkdocs installed to generate the frontend of the docs from source files (Markdown). If you are deploying Backstage using Docker, this will mean that your Backstage Docker container will try to run another Docker container for TechDocs Backend.
|
||||
|
||||
To avoid this problem, we have a configuration available. You can set a value in
|
||||
your `app-config.yaml` that tells the techdocs generator if it should run the
|
||||
`local` mkdocs or run it from `docker`. This defaults to running as `docker` if
|
||||
no config is provided.
|
||||
To avoid this problem, we have a configuration available. You can set a value in your `app-config.yaml` that tells the techdocs generator if it should run the `local` mkdocs or run it from `docker`. This defaults to running as `docker` if no config is provided.
|
||||
|
||||
```yaml
|
||||
techdocs:
|
||||
@@ -183,15 +118,11 @@ techdocs:
|
||||
runIn: local
|
||||
```
|
||||
|
||||
Setting `generator.runIn` to `local` means you will have to make sure your
|
||||
environment is compatible with techdocs.
|
||||
Setting `generator.runIn` to `local` means you will have to make sure your environment is compatible with techdocs.
|
||||
|
||||
You will have to install the `mkdocs` and `mkdocs-techdocs-core` package from
|
||||
pip, optionally also `graphviz` and `plantuml` from your OS package manager (e.g.
|
||||
apt).
|
||||
You will have to install the `mkdocs` and `mkdocs-techdocs-core` package from pip, optionally also `graphviz` and `plantuml` from your OS package manager (e.g. apt).
|
||||
|
||||
You can do so by including the following lines right above `USER node` of your
|
||||
`Dockerfile`:
|
||||
You can do so by including the following lines right above `USER node` of your `Dockerfile`:
|
||||
|
||||
```Dockerfile
|
||||
RUN apt-get update && \
|
||||
@@ -205,20 +136,11 @@ ENV PATH="$VIRTUAL_ENV/bin:$PATH"
|
||||
RUN pip3 install mkdocs-techdocs-core
|
||||
```
|
||||
|
||||
Please be aware that the version requirement could change, you need to check our
|
||||
[`Dockerfile`](https://github.com/backstage/techdocs-container/blob/main/Dockerfile)
|
||||
and make sure to match with it.
|
||||
Please be aware that the version requirement could change, you need to check our [`Dockerfile`](https://github.com/backstage/techdocs-container/blob/main/Dockerfile) and make sure to match with it.
|
||||
|
||||
On a Debian-based Docker container, Python packages must be either installed using
|
||||
the OS package manager or within a virtual environment (see the
|
||||
[related PEP](https://peps.python.org/pep-0668/)). Alternative is to use e.g.
|
||||
[pipx](https://pypa.github.io/pipx/) for installing Python packages in an isolated
|
||||
environment.
|
||||
On a Debian-based Docker container, Python packages must be either installed using the OS package manager or within a virtual environment (see the [related PEP](https://peps.python.org/pep-0668/)). Alternative is to use e.g. [pipx](https://pypa.github.io/pipx/) for installing Python packages in an isolated environment.
|
||||
|
||||
The above Dockerfile snippet installs the latest `mkdocs-techdoc-core` package.
|
||||
Version numbers can be found in the corresponding
|
||||
[changelog](https://github.com/backstage/mkdocs-techdocs-core#changelog). In
|
||||
case you want to pin the version, use the example below:
|
||||
The above Dockerfile snippet installs the latest `mkdocs-techdoc-core` package. Version numbers can be found in the corresponding [changelog](https://github.com/backstage/mkdocs-techdocs-core#changelog). In case you want to pin the version, use the example below:
|
||||
|
||||
```Dockerfile
|
||||
RUN pip3 install mkdocs-techdocs-core==1.2.3
|
||||
@@ -226,9 +148,7 @@ RUN pip3 install mkdocs-techdocs-core==1.2.3
|
||||
|
||||
Note: We recommend Python version 3.11 or higher.
|
||||
|
||||
> Caveat: Please install the `mkdocs-techdocs-core` package after all other
|
||||
> Python packages. The order is important to make sure we get correct version of
|
||||
> some of the dependencies.
|
||||
> Caveat: Please install the `mkdocs-techdocs-core` package after all other Python packages. The order is important to make sure we get correct version of some of the dependencies.
|
||||
|
||||
## Additional reading
|
||||
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -5,6 +5,13 @@ sidebar_label: How-To guides
|
||||
description: TechDocs How-To guides related to TechDocs
|
||||
---
|
||||
|
||||
::::info
|
||||
This documentation is written for the new frontend system, which is the default
|
||||
in new Backstage apps. If your Backstage app still uses the old frontend system,
|
||||
read the [old frontend system version of this guide](./how-to-guides--old.md)
|
||||
instead.
|
||||
::::
|
||||
|
||||
## How to migrate from TechDocs Basic to Recommended deployment approach?
|
||||
|
||||
The main difference between TechDocs Basic and Recommended deployment approach
|
||||
@@ -108,241 +115,37 @@ much data git clone has to transfer.
|
||||
## How to customize the TechDocs home page?
|
||||
|
||||
TechDocs uses a composability pattern similar to the Search and Catalog plugins
|
||||
in Backstage. While a default table experience, similar to the one provided by
|
||||
the Catalog plugin, is made available for ease-of-use, it's possible for you to
|
||||
provide a completely custom experience, tailored to the needs of your
|
||||
organization. For example, TechDocs comes with an alternative grid based layout
|
||||
(`<EntityListDocsGrid>`) and panel layout (`TechDocsCustomHome`).
|
||||
in Backstage. The default TechDocs home page provides a table experience
|
||||
similar to the one provided by the Catalog plugin. TechDocs also comes with
|
||||
an alternative grid based layout and panel layout.
|
||||
|
||||
This is done in your `app` package. By default, you might see something like
|
||||
this in your `App.tsx`:
|
||||
|
||||
```tsx
|
||||
const AppRoutes = () => {
|
||||
<FlatRoutes>
|
||||
<Route path="/docs" element={<TechDocsIndexPage />}>
|
||||
<DefaultTechDocsHome />
|
||||
</Route>
|
||||
</FlatRoutes>;
|
||||
};
|
||||
```
|
||||
|
||||
### Using TechDocsCustomHome
|
||||
|
||||
You can easily customize the TechDocs home page using TechDocs panel layout
|
||||
(`<TechDocsCustomHome />`).
|
||||
|
||||
Modify your `App.tsx` as follows:
|
||||
|
||||
```tsx
|
||||
import { Fragment, PropsWithChildren } from 'react';
|
||||
import { TechDocsCustomHome } from '@backstage/plugin-techdocs';
|
||||
//...
|
||||
|
||||
const options = { emptyRowsWhenPaging: false };
|
||||
const linkDestination = (entity: Entity): string | undefined => {
|
||||
return entity.metadata.annotations?.['external-docs'];
|
||||
};
|
||||
const techDocsTabsConfig = [
|
||||
{
|
||||
label: 'Recommended Documentation',
|
||||
panels: [
|
||||
{
|
||||
title: 'Golden Path',
|
||||
description: 'Documentation about standards to follow',
|
||||
panelType: 'DocsCardGrid',
|
||||
panelProps: { CustomHeader: () => <ContentHeader title='Golden Path'/> },
|
||||
filterPredicate: entity =>
|
||||
entity?.metadata?.tags?.includes('golden-path') ?? false,
|
||||
},
|
||||
{
|
||||
title: 'Recommended',
|
||||
description: 'Useful documentation',
|
||||
panelType: 'InfoCardGrid',
|
||||
panelProps: {
|
||||
CustomHeader: () => <ContentHeader title='Recommended' />
|
||||
linkDestination: linkDestination,
|
||||
},
|
||||
filterPredicate: entity =>
|
||||
entity?.metadata?.tags?.includes('recommended') ?? false,
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
label: 'Browse All',
|
||||
panels: [
|
||||
{
|
||||
description: 'Browse all docs',
|
||||
filterPredicate: filterEntity,
|
||||
panelType: 'TechDocsIndexPage',
|
||||
title: 'All',
|
||||
panelProps: { PageWrapper: Fragment, CustomHeader: Fragment, options: options },
|
||||
},
|
||||
],
|
||||
},
|
||||
];
|
||||
const docsFilter = {
|
||||
kind: ['Location', 'Resource', 'Component'],
|
||||
'metadata.annotations.featured-docs': CATALOG_FILTER_EXISTS,
|
||||
}
|
||||
const customPageWrapper = ({ children }: PropsWithChildren<{}>) =>
|
||||
(<PageWithHeader title="Docs" themeId="documentation">{children}</PageWithHeader>)
|
||||
const AppRoutes = () => {
|
||||
<FlatRoutes>
|
||||
<Route
|
||||
path="/docs"
|
||||
element={
|
||||
<TechDocsCustomHome
|
||||
tabsConfig={techDocsTabsConfig}
|
||||
filter={docsFilter}
|
||||
CustomPageWrapper={customPageWrapper}
|
||||
/>
|
||||
}
|
||||
/>
|
||||
</FlatRoutes>;
|
||||
};
|
||||
```
|
||||
|
||||
### Building a Custom home page
|
||||
|
||||
But you can replace `<DefaultTechDocsHome />` with any React component, which
|
||||
will be rendered in its place. Most likely, you would want to create and
|
||||
maintain such a component in a new directory at
|
||||
`packages/app/src/components/techdocs`, and import and use it in `App.tsx`:
|
||||
|
||||
For example, you can define the following Custom home page component:
|
||||
|
||||
```tsx
|
||||
import { ReactNode } from 'react';
|
||||
|
||||
import { Content } from '@backstage/core-components';
|
||||
import {
|
||||
CatalogFilterLayout,
|
||||
EntityOwnerPicker,
|
||||
EntityTagPicker,
|
||||
UserListPicker,
|
||||
EntityListProvider,
|
||||
} from '@backstage/plugin-catalog-react';
|
||||
import {
|
||||
TechDocsPageWrapper,
|
||||
TechDocsPicker,
|
||||
} from '@backstage/plugin-techdocs';
|
||||
import { Entity } from '@backstage/catalog-model';
|
||||
|
||||
import { EntityListDocsGrid } from '@backstage/plugin-techdocs';
|
||||
|
||||
export type CustomTechDocsHomeProps = {
|
||||
groups?: Array<{
|
||||
title: ReactNode;
|
||||
filterPredicate: ((entity: Entity) => boolean) | string;
|
||||
}>;
|
||||
};
|
||||
|
||||
export const CustomTechDocsHome = ({ groups }: CustomTechDocsHomeProps) => {
|
||||
return (
|
||||
<TechDocsPageWrapper>
|
||||
<Content>
|
||||
<EntityListProvider>
|
||||
<CatalogFilterLayout>
|
||||
<CatalogFilterLayout.Filters>
|
||||
<TechDocsPicker />
|
||||
<UserListPicker initialFilter="all" />
|
||||
<EntityOwnerPicker />
|
||||
<EntityTagPicker />
|
||||
</CatalogFilterLayout.Filters>
|
||||
<CatalogFilterLayout.Content>
|
||||
<EntityListDocsGrid groups={groups} />
|
||||
</CatalogFilterLayout.Content>
|
||||
</CatalogFilterLayout>
|
||||
</EntityListProvider>
|
||||
</Content>
|
||||
</TechDocsPageWrapper>
|
||||
);
|
||||
};
|
||||
```
|
||||
|
||||
Then you can add the following to your `App.tsx`:
|
||||
|
||||
```tsx
|
||||
import { CustomTechDocsHome } from './components/techdocs/CustomTechDocsHome';
|
||||
// ...
|
||||
const AppRoutes = () => {
|
||||
<FlatRoutes>
|
||||
<Route path="/docs" element={<TechDocsIndexPage />}>
|
||||
<CustomTechDocsHome
|
||||
groups={[
|
||||
{
|
||||
title: 'Recommended Documentation',
|
||||
filterPredicate: entity =>
|
||||
entity?.metadata?.tags?.includes('recommended') ?? false,
|
||||
},
|
||||
{
|
||||
title: 'My Docs',
|
||||
filterPredicate: 'ownedByUser',
|
||||
},
|
||||
]}
|
||||
/>
|
||||
</Route>
|
||||
</FlatRoutes>;
|
||||
};
|
||||
```
|
||||
Customization of the TechDocs home page in the new frontend system is done by
|
||||
overriding the default page extension. For details on how to override
|
||||
extensions, see the [extension overrides](../../frontend-system/architecture/25-extension-overrides.md) documentation.
|
||||
|
||||
## How to customize the TechDocs reader page?
|
||||
|
||||
Similar to how it is possible to customize the TechDocs Home, it is also
|
||||
possible to customize the TechDocs Reader Page. It is done in your `app`
|
||||
package. By default, you might see something like this in your `App.tsx`:
|
||||
The TechDocs reader page can be configured through `app-config.yaml`. For
|
||||
example, you can disable the in-context search or the header:
|
||||
|
||||
```tsx
|
||||
const AppRoutes = () => {
|
||||
<Route path="/docs/:namespace/:kind/:name/*" element={<TechDocsReaderPage />}>
|
||||
{techDocsPage}
|
||||
</Route>;
|
||||
};
|
||||
```yaml title="app-config.yaml"
|
||||
app:
|
||||
extensions:
|
||||
- page:techdocs/reader:
|
||||
config:
|
||||
withoutSearch: true
|
||||
```
|
||||
|
||||
The `techDocsPage` is a default techdocs reader page which lives in
|
||||
`packages/app/src/components/techdocs`. It includes the following without you
|
||||
having to set anything up.
|
||||
|
||||
```tsx
|
||||
<Page themeId="documentation">
|
||||
<TechDocsReaderPageHeader />
|
||||
<TechDocsReaderPageSubheader />
|
||||
<TechDocsReaderPageContent />
|
||||
</Page>
|
||||
```yaml title="app-config.yaml"
|
||||
app:
|
||||
extensions:
|
||||
- page:techdocs/reader:
|
||||
config:
|
||||
withoutHeader: true
|
||||
```
|
||||
|
||||
If you would like to compose your own `techDocsPage`, you can do so by replacing
|
||||
the children of TechDocsPage with something else. Maybe you are _just_
|
||||
interested in replacing the Header:
|
||||
|
||||
```tsx
|
||||
<Page themeId="documentation">
|
||||
<Header type="documentation" title="Custom Header" />
|
||||
<TechDocsReaderPageContent />
|
||||
</Page>
|
||||
```
|
||||
|
||||
Or maybe you want to disable the in-context search
|
||||
|
||||
```tsx
|
||||
<Page themeId="documentation">
|
||||
<Header type="documentation" title="Custom Header" />
|
||||
<TechDocsReaderPageContent withSearch={false} />
|
||||
</Page>
|
||||
```
|
||||
|
||||
Or maybe you want to replace the entire TechDocs Page.
|
||||
|
||||
```tsx
|
||||
<Page themeId="documentation">
|
||||
<Header type="documentation" title="Custom Header" />
|
||||
<Content data-testid="techdocs-content">
|
||||
<p>my own content</p>
|
||||
</Content>
|
||||
</Page>
|
||||
```
|
||||
For more advanced customization of the reader page, you can override the page
|
||||
extension. See the [extension overrides](../../frontend-system/architecture/25-extension-overrides.md) documentation for details.
|
||||
|
||||
## How to migrate from TechDocs Alpha to Beta
|
||||
|
||||
@@ -446,32 +249,9 @@ export class TechDocsCustomApiClient implements TechDocsApi {
|
||||
}
|
||||
```
|
||||
|
||||
2. Override the API refs `techdocsStorageApiRef` and `techdocsApiRef` with your
|
||||
new implemented APIs in the `App.tsx` using `ApiFactories`.
|
||||
[Read more about App APIs](https://backstage.io/docs/api/utility-apis#app-apis).
|
||||
|
||||
```typescript
|
||||
const app = createApp({
|
||||
apis: [
|
||||
// TechDocsStorageApi
|
||||
createApiFactory({
|
||||
api: techdocsStorageApiRef,
|
||||
deps: { discoveryApi: discoveryApiRef, configApi: configApiRef },
|
||||
factory({ discoveryApi, configApi }) {
|
||||
return new TechDocsCustomStorageApi({ discoveryApi, configApi });
|
||||
},
|
||||
}),
|
||||
// TechDocsApi
|
||||
createApiFactory({
|
||||
api: techdocsApiRef,
|
||||
deps: { discoveryApi: discoveryApiRef },
|
||||
factory({ discoveryApi }) {
|
||||
return new TechDocsCustomApiClient({ discoveryApi });
|
||||
},
|
||||
}),
|
||||
],
|
||||
});
|
||||
```
|
||||
2. Override the default API extensions by creating custom API extensions using
|
||||
`createApiExtension` from `@backstage/frontend-plugin-api`, and install them
|
||||
in your app. See the [Utility APIs](../../frontend-system/utility-apis/01-index.md) documentation for details on how to create and install custom API extensions.
|
||||
|
||||
## How to add the documentation setup to your software templates
|
||||
|
||||
|
||||
Reference in New Issue
Block a user