diff --git a/docs/features/techdocs/getting-started.md b/docs/features/techdocs/getting-started.md index eaa6c2de72..71852302e2 100644 --- a/docs/features/techdocs/getting-started.md +++ b/docs/features/techdocs/getting-started.md @@ -194,6 +194,33 @@ async function main() { 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. +### New Backend System + +To install TechDocs when using the New Backend system you will need to do the following. + +Navigate to `packages/backend` of your Backstage app, and install the `@backstage/plugin-techdocs-backend` package. + +```bash +# 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-search-backend-module-catalog/alpha')); +/* highlight-add-end */ + +backend.start(); +``` + +> Note: The above is a very simplified example, you may have more content then this in your version. + ## Setting the configuration **See [TechDocs Configuration Options](configuration.md) for complete diff --git a/docs/features/techdocs/how-to-guides.md b/docs/features/techdocs/how-to-guides.md index afc257f20b..a370ba5d97 100644 --- a/docs/features/techdocs/how-to-guides.md +++ b/docs/features/techdocs/how-to-guides.md @@ -721,6 +721,53 @@ and publish the documentation for them. If the value of the `company.com/techdoc annotation is anything other than `'local'`, the user is responsible for publishing documentation to the appropriate location in the TechDocs external storage. +### Hybrid build strategy using the New Backend System + +To setup a hybrid build strategy using the New Backend System you'll follow the same steps as above but for Step 4 you will need to do the following: + +```ts title="packages/backend/src/index.ts" +const backend = createBackend(); + +import { createBackendModule } from '@backstage/backend-plugin-api'; +import { + DocsBuildStrategy, + techdocsBuildsExtensionPoint, +} from '@backstage/plugin-techdocs-node'; + +const techdocsCustomerBuildStrategy = createBackendModule({ + pluginId: 'techdocs', + moduleId: 'customBuildStrategy', + register(env) { + env.registerInit({ + deps: { + techdocs: techdocsBuildsExtensionPoint, + }, + async init({ techdocs }) { + const docsBuildStrategy: DocsBuildStrategy = { + shouldBuild: async params => + params.entity.metadata?.annotations?.[ + 'demo.backstage.io/techdocs-builder' + ] === 'local', + }; + + techdocs.setBuildStrategy(docsBuildStrategy); + }, + }); + }, +}); + +// Other plugins... + +/* highlight-add-start */ +backend.add(import('@backstage/plugin-search-backend-module-catalog/alpha')); +backend.add(); +/* highlight-add-end */ + +backend.start(techdocsCustomerBuildStrategy()); +``` + +> Note: You may need to add the `@backstage/plugin-techdocs-node` package to your backend `package.json` if it's not been imported already. + ## How to use other mkdocs plugins? The default plugin [mkdocs-techdocs-core](https://github.com/backstage/mkdocs-techdocs-core) provides a set of plugins that can be viewed as the minimum required plugins to enable TechDocs. Your organization might have needs beyond the core set though, here is the recommended way to enable other plugins.