|
| 1 | +// Module included in the following assemblies: |
| 2 | +// |
| 3 | +// [WIP] file created but not currently part of any assembly or title |
| 4 | + |
| 5 | +:_mod-docs-content-type: PROCEDURE |
| 6 | +[id="proc-techdocs-addon-create_{context}"] |
| 7 | +== Creating a TechDocs add-on |
| 8 | + |
| 9 | +If your organization has documentation needs that are not met by the functions of existing TechDocs add-ons, developers can create a new add-on for your TechDocs plugin. |
| 10 | + |
| 11 | +A TechDocs add-on is a React component that is imported from a front-end plugin. If you do not have an existing plugin that you can use to export your TechDocs add-on, you can create a new plugin by using `backstage-cli` to generate a default front-end plugin structure that you can customize. |
| 12 | + |
| 13 | +The folder structure of a new plugin that can be used to import TechDocs add-ons into the TechDocs plugin looks similar to the following example: |
| 14 | +[source,json,subs="+attributes,+quotes"] |
| 15 | +---- |
| 16 | +_<new_plugin_for_techdocs_add-on>_/ |
| 17 | + dev/ |
| 18 | + index.ts |
| 19 | + src/ |
| 20 | + components/ |
| 21 | + _<new_techdocs_add-on_component>_/ |
| 22 | + _<new_techdocs_add-on_component>_.test.tsx |
| 23 | + _<new_techdocs_add-on_component>_.tsx |
| 24 | + index.ts |
| 25 | + _<new_techdocs_add-on_fetch-component>_/ |
| 26 | + _<new_techdocs_add-on_fetch-component>_.test.tsx |
| 27 | + _<new_techdocs_add-on_fetch-component>_.tsx |
| 28 | + index.ts |
| 29 | + index.ts |
| 30 | + plugin.test.ts |
| 31 | + plugin.ts |
| 32 | + routes.ts |
| 33 | + setupTests.ts |
| 34 | + .eslintrc.js |
| 35 | + package.json |
| 36 | + README.md |
| 37 | +---- |
| 38 | + |
| 39 | +.Prerequisites |
| 40 | +* The `yarn` package manager is installed. |
| 41 | +* Docker v3.2.0 or later or Podman v3.2.0 or later is installed and running. |
| 42 | +
|
| 43 | +.Procedure |
| 44 | +. In the terminal, navigate to the root folder of the repository where you want to create your new plugin. |
| 45 | +. To create a new front-end plugin, run the following command: |
| 46 | ++ |
| 47 | +[source,terminal,subs="+attributes,+quotes"] |
| 48 | +---- |
| 49 | +yarn new |
| 50 | +---- |
| 51 | +.Example output |
| 52 | ++ |
| 53 | +[source,terminal,subs="+quotes"] |
| 54 | +---- |
| 55 | +? What do you want to create? plugin - A new frontend plugin |
| 56 | +? Enter the ID of the plugin [required] |
| 57 | +---- |
| 58 | ++ |
| 59 | +. In the terminal prompt, type a name for the new plugin. For example: |
| 60 | ++ |
| 61 | +[source,terminal,subs="+attributes,+quotes"] |
| 62 | +---- |
| 63 | +? Enter the ID of the plugin [required] _<new_plugin_for_techdocs_add-on>_ |
| 64 | +---- |
| 65 | ++ |
| 66 | +.Example output |
| 67 | ++ |
| 68 | +[source,terminal,subs="+attributes,+quotes"] |
| 69 | +---- |
| 70 | +Successfully created plugin |
| 71 | +---- |
| 72 | ++ |
| 73 | +.Result |
| 74 | +In the `plugins` directory, a sub-directory with the same name that you gave to your plugin is automatically generated. The directory contains all of the files that you need to configure to create your new plugin. |
| 75 | ++ |
| 76 | +. In the terminal, navigate to your new plugin directory. For example: |
| 77 | ++ |
| 78 | +[source,terminal,subs="+attributes,+quotes"] |
| 79 | +---- |
| 80 | +cd plugins/_<new_techdocs_add-on_directory>_ |
| 81 | +---- |
| 82 | +. Add the`@backstage/plugin-techdocs-react` package to get frontend utilities for TechDocs add-ons. For example: |
| 83 | ++ |
| 84 | +[source,terminal,subs="+attributes,+quotes"] |
| 85 | +---- |
| 86 | +yarn add @backstage/plugin-techdocs-react |
| 87 | +---- |
| 88 | +. In the directory containing the components of your custom TechDocs add-on, delete any default files or file components that are not required for your add-on, such as the `routes.ts` file or components of the `index.tsx` and `plugins.ts` files. |
| 89 | +. In the `plugins.ts` file, add the following code: |
| 90 | ++ |
| 91 | +[source,java,subs="+attributes,+quotes"] |
| 92 | +---- |
| 93 | +import { createPlugin } from '@backstage/core-plugin-api'; |
| 94 | +import { createTechDocsAddonExtension } from '@backstage/plugin-techdocs-react'; |
| 95 | + |
| 96 | +export const _<new_plugin_for_techdocs_add-on>_ = createPlugin({ |
| 97 | + id: '_<new_techdocs_add-on>_', |
| 98 | + }); |
| 99 | + |
| 100 | + /* |
| 101 | + * |
| 102 | + * @public |
| 103 | + */ |
| 104 | +export const _<new_techdocs_add-on>_ = _<new_plugin_for_techdocs_add-on>_.provide( |
| 105 | + createTechDocsAddonExtension<_<new_techdocs_addon_props>_>({ |
| 106 | + name: '_<new_techdocs_add-on>_', |
| 107 | + location: TechDocsAddonLocations.Content, |
| 108 | + component: _<new_techdocs_add-on_component>_, |
| 109 | + }), |
| 110 | +); |
| 111 | +---- |
| 112 | ++ |
| 113 | +where |
| 114 | +
|
| 115 | +_<new_plugin_for_techdocs_add-on>_ :: Specifies the new plugin that you use to import the TechDocs add-on to your {product} instance. |
| 116 | +_<new_techdocs_add-on>_ :: Specifies the custom TechDocs add-on that you want to create. |
| 117 | +_<new_techdocs_addon_props>_ (Optional) :: Specifies the `props` for your new TechDocs add-on, as specified in your `_<new_techdocs_add-on>_.tsx` file, if applicable. |
| 118 | +_<new_techdocs_add-on_component>_ :: Specifies the React component for the custom TechDocs add-on that you want to create. You will create this component in a `.tsx` file in a later step. |
| 119 | +. In the `index.ts` file, export the custom TechDocs add-on that you want to create by adding the following code: |
| 120 | ++ |
| 121 | +[source,java,subs="+attributes,+quotes"] |
| 122 | +---- |
| 123 | +export { _<new_plugin_for_techdocs_add-on>_, _<new_techdocs_add-on>_ } from './plugin'; |
| 124 | +---- |
| 125 | +. Create a new `_<new_techdocs_add-on>_.tsx` file and add the code for your new TechDocs add-on component. |
| 126 | ++ |
| 127 | +//// |
| 128 | +[source,java,subs="+attributes,+quotes"] |
| 129 | +---- |
| 130 | +can add example code for this file, if helpful |
| 131 | +can also mention a template that the user can configure, if there is one |
| 132 | +---- |
| 133 | +//// |
| 134 | +. Create a new `index.tsx` file and use it to export your new TechDocs add-on component by adding the following code: |
| 135 | ++ |
| 136 | +[source,java,subs="+attributes,+quotes"] |
| 137 | +---- |
| 138 | +export { _<new_techdocs_add-on>_, type _<new_techdocs_addon_props>_} from './_<new_techdocs_add-on_directory>_' |
| 139 | +---- |
| 140 | ++ |
| 141 | +where |
| 142 | +
|
| 143 | +_<new_techdocs_addon_props>_ (Optional) :: Specifies the `props` for your new TechDocs add-on, as specified in your `_<new_techdocs_add-on>_.tsx` file, if applicable. |
| 144 | +. In the `plugins.ts` file, import your new TechDocs add-on component. |
| 145 | +. Install and configure your new TechDocs add-on by following the steps in link:{techdocs-book-url}#techdocs-addon-installing[Installing and configuring a TechDocs add-on] |
| 146 | +
|
| 147 | +.Verification |
| 148 | +. Restart the RHDH application and verify that the plugin is successfully activated and configured. |
| 149 | +. Verify the application logs for confirmation and ensure the plugin is functioning as expected. |
0 commit comments