Adding some documentation on how to use the TechDocs extensions

Signed-off-by: Joshua Jung <joshua.p.jung@gmail.com>
2024-08-30 11:35:08 -05:00
parent ffe31a8ae0
commit 8976bc0e94
2 changed files with 55 additions and 0 deletions
@@ -0,0 +1,54 @@
+---
+id: extensions
+title: Using TechDocs Extensions
+sidebar_label: Using TechDocs Extensions
+description: How to use the built-in TechDocs extension points
+---
+
+# TechDocs Backend Extensions
+
+The TechDocs backend plugin provides the following extension points:
+
+- `techdocsBuildsExtensionPoint`
+- `techdocsGeneratorExtensionPoint`
+- `techdocsPreparerExtensionPoint`
+- `techdocsPublisherExtensionPoint`
+
+## Build Extensions
+
+### Set Log Transport
+
+By default, the TechDocs build phase does not log out much information while building out TechDocs. However, the
+`techdocsBuildsExtensionPoint` can be used to setup a custom Winston transport for TechDocs build logs.
+
+Here is an example of logging to console:
+
+```typescript jsx title="packages/backend/src/extensions/techDocsExtension.ts"
+import { techdocsBuildsExtensionPoint } from '@backstage/plugin-techdocs-backend';
+import { createBackendModule } from '@backstage/backend-plugin-api';
+import { transports } from 'winston';
+
+export const techDocsExtension = createBackendModule({
+  pluginId: 'techdocs',
+  moduleId: 'extension',
+  register(env) {
+    env.registerInit({
+      deps: {
+        build: techdocsBuildsExtensionPoint,
+      },
+      async init({ build }) {
+        // You can obviously use any custom transport here...
+        build.setBuildLogTransport(new transports.Console());
+      },
+    });
+  },
+});
+```
+
+And then of course register this extension with the backend:
+
+```typescript jsx title="packages/backend/src/index.ts"
+import {techDocsExtension} from "./extensions/techDocsExtension";
+...
+backend.add(techDocsExtension());
+```