diff --git a/assemblies/assembly-configuring-techdocs.adoc b/assemblies/assembly-configuring-techdocs.adoc index 7a6f12040b..8afb63a65e 100644 --- a/assemblies/assembly-configuring-techdocs.adoc +++ b/assemblies/assembly-configuring-techdocs.adoc @@ -1,7 +1,7 @@ :_mod-docs-content-type: ASSEMBLY :context: configuring-techdocs [id="{context}"] -= Configuring TechDocs += TechDocs configuration The TechDocs plugin is preinstalled and enabled on a {product-short} instance by default. You can disable or enable the TechDocs plugin, and change other parameters, by configuring the {product} Helm chart or the {product} Operator ConfigMap. diff --git a/assemblies/assembly-techdocs-addons-installing.adoc b/assemblies/assembly-techdocs-addons-installing.adoc new file mode 100644 index 0000000000..6e20fd3b08 --- /dev/null +++ b/assemblies/assembly-techdocs-addons-installing.adoc @@ -0,0 +1,16 @@ +:_mod-docs-content-type: ASSEMBLY +:context: techdocs-addon-installing +[id="techdocs-addon-installing"] += Installing and configuring a TechDocs add-on + +TechDocs add-ons are supported by {company-name} are imported by the `backstage-plugin-techdocs-module-addons-contrib` plugin package. The `` add-on is preinstalled in the TechDocs plugin and enabled by default. You can install external TechDocs add-ons by adding them to `backstage-plugin-techdocs-module-addons-contrib` package with either the {product} Operator or Helm chart. Additionally, you can import compatible third-party add-ons, including add-ons that you create yourself, with a third-party dynamic plugin. + +include::modules/techdocs/proc-techdocs-addon-install-operator.adoc[] + +include::modules/techdocs/proc-techdocs-addon-install-helm.adoc[] + +include::modules/techdocs/proc-techdocs-addon-install-third-party.adoc[] + +.Additional resources +* link:https://docs.redhat.com/en/documentation/red_hat_developer_hub/1.4/html/installing_and_viewing_plugins_in_red_hat_developer_hub/rhdh-installing-rhdh-plugins_title-plugins-rhdh-about[Installing dynamic plugins in Red Hat Developer Hub] +* link:https://docs.redhat.com/en/documentation/red_hat_developer_hub/1.4/html/installing_and_viewing_plugins_in_red_hat_developer_hub/assembly-third-party-plugins[Third-party plugins in Red Hat Developer Hub] diff --git a/assemblies/assembly-techdocs-addons-removing.adoc b/assemblies/assembly-techdocs-addons-removing.adoc new file mode 100644 index 0000000000..ce6c9c9af3 --- /dev/null +++ b/assemblies/assembly-techdocs-addons-removing.adoc @@ -0,0 +1,12 @@ +:_mod-docs-content-type: ASSEMBLY +:context: techdocs-addon-removing +[id="techdocs-addon-removing"] += Removing a TechDocs add-on + +Administrators can remove installed TechDocs add-ons from your {product} instance by using either the Operator or Helm chart, depending on the method used to install the add-on. If you used the Operator to install the add-on, remove it from the ConfigMap. If you used the Helm chart to install the add-on, remove it from the Helm chart. + +If you want to disable a plugin instead of removing it from your {product} instance, you can disable the plugin that you are using to import the TechDocs add-on. Since the `disabled` status is controlled at the plugin level, disabling the plugin disables all of the TechDocs add-ons in the specified plugin package. + +include::modules/techdocs/proc-techdocs-addon-remove-operator.adoc[] + +include::modules/techdocs/proc-techdocs-addon-remove-helm.adoc[] diff --git a/assemblies/assembly-techdocs-addons-using.adoc b/assemblies/assembly-techdocs-addons-using.adoc new file mode 100644 index 0000000000..8fb4713e60 --- /dev/null +++ b/assemblies/assembly-techdocs-addons-using.adoc @@ -0,0 +1,12 @@ +:_mod-docs-content-type: ASSEMBLY +:context: techdocs-addon-using +[id="techdocs-addon-using"] += Using TechDocs add-ons + +After an administrator installs a TechDocs add-on in your {product} instance, you can use it to extend the functionality of the TechDocs plugin and enhance your documentation experience. + +include::modules/techdocs/proc-techdocs-addon-use-report-issue.adoc[] + +include::modules/techdocs/proc-techdocs-addon-use-text-size.adoc[] + +include::modules/techdocs/proc-techdocs-addon-use-light-box.adoc[] diff --git a/assemblies/assembly-techdocs-addons.adoc b/assemblies/assembly-techdocs-addons.adoc new file mode 100644 index 0000000000..7903a09071 --- /dev/null +++ b/assemblies/assembly-techdocs-addons.adoc @@ -0,0 +1,34 @@ +:_mod-docs-content-type: ASSEMBLY +:context: techdocs-addon +[id="techdocs-addon"] += TechDocs add-ons + +TechDocs add-ons are dynamic plugins that extend the functionality of the built-in TechDocs plugin. For example, you can use add-ons to report documentation issues, change text size, or view images in overlay in either the TechDocs Reader page or an Entity page. + +The following table describes the TechDocs add-ons that are available for {product} {product-version}: + +.TechDocs Add-ons available in {product} +|=== +| TechDocs Add-on | Package/Plugin | Description | Type + +| `` +| `backstage-plugin-techdocs-module-addons-contrib` +| Select a portion of text on a TechDocs page and open an issue against the repository that contains the documentation. The issue template is automatically populated with the selected text. +| Preinstalled + +| `` +| `backstage-plugin-techdocs-module-addons-contrib` +| Customize text size on documentation pages by increasing or decreasing the font size with a slider or buttons. The default value for font size is 100% and this setting is kept in the browser's local storage whenever it is changed. +| External + +| `` +| `backstage-plugin-techdocs-module-addons-contrib` +| Open images in a light-box on documentation pages, to navigate to multiple images on a single page. The image size of the light-box image is the same as the image size on the document page. Clicking the zoom icon increases the image size to fit the screen. +| External + +//future release | `` +//future release | `backstage-plugin-techdocs-module-addons-contrib` +//future release | Expand or collapse the subtitles in the TechDocs navigation menu and keep your preferred state between documentation sites. +|=== + +You can use a dynamic plugin to import a TechDocs add-on. TechDocs add-ons are enabled at the plugin level, therefore, enabling a plugin enables all of the TechDocs add-ons in the specified plugin package. The preinstalled and external add-ons supported by {company} are imported by the `backstage-plugin-techdocs-module-addons-contrib` plugin package. Since the `disabled` status is set at the plugin level, the `disabled` status of the plugin package applies to all of the TechDocs add-ons imported by that package. diff --git a/modules/techdocs/con-techdocs-about.adoc b/modules/techdocs/con-techdocs-about.adoc index 9b3a854104..d8249c3fcd 100644 --- a/modules/techdocs/con-techdocs-about.adoc +++ b/modules/techdocs/con-techdocs-about.adoc @@ -18,4 +18,4 @@ Built-in navigation and search:: Locate the information that you need within a document quickly and easily. Add-ons:: -Customize your TechDocs experience with add-ons to address higher-order documentation needs. +Make your documentation more functional and interactive with supported TechDocs add-ons. Some add-ons are preinstalled and enabled by default. To extend the default functionality, you can dynamically load external and third-party add-ons into your {product} instance. If you want to further customize your TechDocs experience, you can create add-ons that meet specific documentation needs for your organization. diff --git a/modules/techdocs/proc-techdocs-addon-create.adoc b/modules/techdocs/proc-techdocs-addon-create.adoc new file mode 100644 index 0000000000..0c452e9932 --- /dev/null +++ b/modules/techdocs/proc-techdocs-addon-create.adoc @@ -0,0 +1,149 @@ +// Module included in the following assemblies: +// +// [WIP] file created but not currently part of any assembly or title + +:_mod-docs-content-type: PROCEDURE +[id="proc-techdocs-addon-create_{context}"] +== Creating a TechDocs add-on + +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. + +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. + +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: +[source,json,subs="+attributes,+quotes"] +---- +__/ + dev/ + index.ts + src/ + components/ + __/ + __.test.tsx + __.tsx + index.ts + __/ + __.test.tsx + __.tsx + index.ts + index.ts + plugin.test.ts + plugin.ts + routes.ts + setupTests.ts + .eslintrc.js + package.json + README.md +---- + +.Prerequisites +* The `yarn` package manager is installed. +* Docker v3.2.0 or later or Podman v3.2.0 or later is installed and running. + +.Procedure +. In the terminal, navigate to the root folder of the repository where you want to create your new plugin. +. To create a new front-end plugin, run the following command: ++ +[source,terminal,subs="+attributes,+quotes"] +---- +yarn new +---- +.Example output ++ +[source,terminal,subs="+quotes"] +---- +? What do you want to create? plugin - A new frontend plugin +? Enter the ID of the plugin [required] +---- ++ +. In the terminal prompt, type a name for the new plugin. For example: ++ +[source,terminal,subs="+attributes,+quotes"] +---- +? Enter the ID of the plugin [required] __ +---- ++ +.Example output ++ +[source,terminal,subs="+attributes,+quotes"] +---- +Successfully created plugin +---- ++ +.Result +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. ++ +. In the terminal, navigate to your new plugin directory. For example: ++ +[source,terminal,subs="+attributes,+quotes"] +---- +cd plugins/__ +---- +. Add the`@backstage/plugin-techdocs-react` package to get frontend utilities for TechDocs add-ons. For example: ++ +[source,terminal,subs="+attributes,+quotes"] +---- +yarn add @backstage/plugin-techdocs-react +---- +. 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. +. In the `plugins.ts` file, add the following code: ++ +[source,java,subs="+attributes,+quotes"] +---- +import { createPlugin } from '@backstage/core-plugin-api'; +import { createTechDocsAddonExtension } from '@backstage/plugin-techdocs-react'; + +export const __ = createPlugin({ + id: '__', + }); + + /* + * + * @public + */ +export const __ = __.provide( + createTechDocsAddonExtension<__>({ + name: '__', + location: TechDocsAddonLocations.Content, + component: __, + }), +); +---- ++ +where + +__ :: Specifies the new plugin that you use to import the TechDocs add-on to your {product} instance. +__ :: Specifies the custom TechDocs add-on that you want to create. +__ (Optional) :: Specifies the `props` for your new TechDocs add-on, as specified in your `__.tsx` file, if applicable. +__ :: 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. +. In the `index.ts` file, export the custom TechDocs add-on that you want to create by adding the following code: ++ +[source,java,subs="+attributes,+quotes"] +---- +export { __, __ } from './plugin'; +---- +. Create a new `__.tsx` file and add the code for your new TechDocs add-on component. ++ +//// +[source,java,subs="+attributes,+quotes"] +---- +can add example code for this file, if helpful +can also mention a template that the user can configure, if there is one +---- +//// +. Create a new `index.tsx` file and use it to export your new TechDocs add-on component by adding the following code: ++ +[source,java,subs="+attributes,+quotes"] +---- +export { __, type __} from './__' +---- ++ +where + +__ (Optional) :: Specifies the `props` for your new TechDocs add-on, as specified in your `__.tsx` file, if applicable. +. In the `plugins.ts` file, import your new TechDocs add-on component. +. 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] + +.Verification +. Restart the RHDH application and verify that the plugin is successfully activated and configured. +. Verify the application logs for confirmation and ensure the plugin is functioning as expected. diff --git a/modules/techdocs/proc-techdocs-addon-install-helm.adoc b/modules/techdocs/proc-techdocs-addon-install-helm.adoc new file mode 100644 index 0000000000..68ccbb27c3 --- /dev/null +++ b/modules/techdocs/proc-techdocs-addon-install-helm.adoc @@ -0,0 +1,61 @@ +// Module included in the following assemblies: +// +// * assemblies/assembly-techdocs-addons-installing.adoc + +:_mod-docs-content-type: PROCEDURE +[id="proc-techdocs-addon-install-helm_{context}"] +== Installing and configuring an external TechDocs add-on using the Helm chart + +You can use a dynamic plugin to import TechDocs add-ons into your TechDocs plugin. If you use the {product} Helm chart to install the dynamic plugin, you can add TechDocs add-ons to the plugin package in your Helm chart. + +Preinstalled add-ons, such as `ReportIssue`, are included in the default `backstage-plugin-techdocs-module-addons-contrib` package configuration. External add-ons that are supported by {company-name} are installed by manually adding them to the `techdocsAddons` section of the configuration file. + +.Prerequisites +* The TechDocs plugin is installed and enabled. + +.Procedure +. In your Helm chart, add the `global.dynamic` parameters required to install a dynamic plugin, as shown in link:https://docs.redhat.com/en/documentation/red_hat_developer_hub/1.4/html/installing_and_viewing_plugins_in_red_hat_developer_hub/rhdh-installing-rhdh-plugins_title-plugins-rhdh-about#con-install-dynamic-plugin-helm_rhdh-installing-rhdh-plugins[Installing dynamic plugins using the Helm chart ] ++ +[NOTE] +==== +The default configuration includes the `dynamic-plugins.default.yaml` file, which contains all of the dynamic plugins, including TechDocs add-ons, that are preinstalled in {product}, whether they are enabled or disabled by default. +==== +. In your Helm chart, add the default `backstage-plugin-techdocs-module-addons-contrib` package configuration. For example: ++ +[source,yaml,subs="+quotes,+attributes"] +---- +global: + dynamic: + plugins: + - package: ./dynamic-plugins/dist/backstage-plugin-techdocs-module-addons-contrib + disabled: false + pluginConfig: + dynamicPlugins: + frontend: + backstage.plugin-techdocs-module-addons-contrib: + techdocsAddons: + - importName: ReportIssue +---- +. In the `techdocsAddons` section of the Helm chart, add `importName: __` for each external TechDocs add-on that you want to add from the specified plugin package. For example: ++ +[source,yaml,subs="+quotes,+attributes"] +---- +global: + dynamic: + plugins: + - package: ./dynamic-plugins/dist/backstage-plugin-techdocs-module-addons-contrib + disabled: false + pluginConfig: + dynamicPlugins: + frontend: + backstage.plugin-techdocs-module-addons-contrib: + techdocsAddons: + - importName: ReportIssue + - importName: __ +---- ++ +where: + +__:: Specifies the external TechDocs add-on that you want to install, for example, `TextSize` or `LightBox`. + +//.Next steps \ No newline at end of file diff --git a/modules/techdocs/proc-techdocs-addon-install-operator.adoc b/modules/techdocs/proc-techdocs-addon-install-operator.adoc new file mode 100644 index 0000000000..ce175771b3 --- /dev/null +++ b/modules/techdocs/proc-techdocs-addon-install-operator.adoc @@ -0,0 +1,91 @@ +// Module included in the following assemblies: +// +// * assemblies/assembly-techdocs-addons-installing.adoc + +:_mod-docs-content-type: PROCEDURE +[id="proc-techdocs-addon-install-operator_{context}"] +== Installing and configuring an external TechDocs add-on using the Operator + +You can use a dynamic plugin to import TechDocs add-ons into your TechDocs plugin. If you use the {product} Operator to install the dynamic plugin, you can add TechDocs add-ons to the plugin package in your ConfigMap. + +Preinstalled add-ons, such as `ReportIssue`, are included in the default `backstage-plugin-techdocs-module-addons-contrib` package configuration. External add-ons that are supported by {company-name} are installed by manually adding them to the `techdocsAddons` section of the configuration file. + +.Procedure + +. From the Developer perspective in the {ocp-short} web console, click *ConfigMaps* > *Create ConfigMap*. +. From the *Create ConfigMap* page, select the *YAML view* option in the *Configure via* field. +. In the newly created ConfigMap, add the default `backstage-plugin-techdocs-module-addons-contrib` package configuration. For example: ++ +[source,yaml,subs="+quotes,+attributes"] +---- +kind: ConfigMap +apiVersion: v1 +metadata: + name: dynamic-plugins-rhdh +data: + dynamic-plugins.yaml: | + includes: + - dynamic-plugins.default.yaml + plugins: + - package: ./dynamic-plugins/dist/backstage-plugin-techdocs-module-addons-contrib + disabled: false + pluginConfig: + dynamicPlugins: + frontend: + backstage.plugin-techdocs-module-addons-contrib: + techdocsAddons: + - importName: ReportIssue +---- +. In the `techdocsAddons` section of the ConfigMap, add `importName: __` for each external TechDocs add-on that you want to add from the specified plugin package. For example: ++ +[source,yaml,subs="+quotes,+attributes"] +---- +kind: ConfigMap +apiVersion: v1 +metadata: + name: dynamic-plugins-rhdh +data: + dynamic-plugins.yaml: | + includes: + - dynamic-plugins.default.yaml + plugins: + - package: ./dynamic-plugins/dist/backstage-plugin-techdocs-module-addons-contrib + disabled: false + pluginConfig: + dynamicPlugins: + frontend: + backstage.plugin-techdocs-module-addons-contrib: + techdocsAddons: + - importName: ReportIssue + - importName: __ +---- ++ +where: + +__:: Specifies the external TechDocs add-on that you want to install, for example, `TextSize` or `LightBox`. +. Click *Create*. +. In the web console navigation menu, click *Topology*. +. Click on the overflow menu for the {product} instance that you want to use and select *Edit Backstage* to load the YAML view of the {product} instance. +. In your `{product-custom-resource-type}` CR, add the `dynamicPluginsConfigMapName: __` key-value pair. For example: ++ +[source,yaml] +---- +apiVersion: rhdh.redhat.com/v1alpha3 +kind: Backstage +metadata: + name: my-rhdh +spec: + application: +# ... + dynamicPluginsConfigMapName: __ +# ... +---- ++ +where: + +__:: Specifies the name of your dynamic plugins ConfigMap for your {product} instance, for example, `dynamic-plugins-rhdh`. +. Click *Save*. +. In the web console navigation menu, click *Topology* and wait for the {product} pod to start. +. Click the *Open URL* icon to start using the {product} platform with the new configuration changes. + +//.Next steps diff --git a/modules/techdocs/proc-techdocs-addon-install-third-party.adoc b/modules/techdocs/proc-techdocs-addon-install-third-party.adoc new file mode 100644 index 0000000000..650b136917 --- /dev/null +++ b/modules/techdocs/proc-techdocs-addon-install-third-party.adoc @@ -0,0 +1,86 @@ +// Module included in the following assemblies: +// +// * assemblies/assembly-techdocs-addons-installing.adoc + +:_mod-docs-content-type: PROCEDURE +[id="proc-techdocs-addon-install-third-party_{context}"] +== Installing and configuring a third-party TechDocs add-on + +You can install compatible third-party TechDocs add-on on your {product} instance as a front-end dynamic plugin. + +.Prerequisites +* The third-party TechDocs add-on has a valid `package.json` file in its root directory, containing all required metadata and dependencies. +* The third-party plugin is packaged as a dynamic plugin in an OCI image. For alternative package types, see link:https://redhat-developer.github.io/red-hat-developers-documentation-rhdh/release-1.5/plugins-rhdh-install/#assembly-install-third-party-plugins-rhdh[Installing third-party plugins in Red Hat Developer Hub]. +* You have installed the `yarn` package manager. +* The third-party plugin is packaged as a dynamic plugin in an OCI image.* You have installed and configured Node.js and NPM. + +.Procedure +. Install the third-party plugin that you want to use to import your third-party add-on by entering the following command: ++ +[source,terminal,subs="+quotes,+attributes"] +---- +yarn install +---- +. Obtain the source code for the third-party TechDocs add-on that you want to use. +. Export the TechDocs add-on as a dynamic plugin using the following command: ++ +[source,terminal,subs="+quotes,+attributes"] +---- +npx @janus-idp/cli@latest package export-dynamic-plugin +---- ++ +[NOTE] +==== +The `@latest` tag pulls the latest version of the @janus-idp/cli package, which is compatible with the most recent features and fixes. Use a version that is compatible with your {product} version. +==== +. To package the third-party TechDocs add-on as a dynamic plugin, navigate to the root directory where the plugin is stored (not the dist-dynamic directory) and run the `npx` command with the `--tag` option to specify the image name and tag. For example: ++ +[source,terminal,subs="+quotes,+attributes"] +---- +npx @janus-idp/cli@latest package package-dynamic-plugins --tag quay.io/__/__:latest +---- ++ +[NOTE] +==== +The output of the package-dynamic-plugins command provides the file path to the plugin for use in the `dynamic-plugin-config.yaml` file. +==== ++ +. To publish the third-party TechDocs add-on to a Quay repository, push the image to a registry using one of the following commands, depending on your virtualization tool: +* To use `podman`, enter the following command: ++ +[source,terminal,subs="+quotes,+attributes"] +---- +podman push quay.io/__/__:latest +---- +* To use `docker`, enter the following command: ++ +[source,terminal,subs="+quotes,+attributes"] +---- +docker push quay.io/__/__:latest +---- +. Open your `dynamic-plugins.yaml` file to view or modify the configuration for the third-party TechDocs add-on. For example: ++ +[source,yaml,subs="+quotes,+attributes"] +---- +plugins: + - package: oci://quay.io/__/__:latest!__ + disabled: false + pluginConfig: + dynamicPlugins: + frontend: + __ + techdocsAddons: + - importName: __ + config: + props: + __: __ +---- ++ +where + +__ :: Specifies your Quay user name or organization name. +__ :: Specifies the name of the image for the third-party add-on that you want to use, for example, `mermaid`. +__ :: Specifies the , for example, `backstage-plugin-techdocs-addon-mermaid`. +__ :: Specifies the name of the third-party add-on that you want to use, for example, `Mermaid`. +__ :: Specifies the name of the custom property that can be passed to the third-party add-on, for example, `themeVariables`. Properties are specific to each add-on. You can list multiple properties for an add-on. +__ :: Specifies the value of a property key for the third-party add-on, for example, `lineColor: #000000`. diff --git a/modules/techdocs/proc-techdocs-addon-remove-helm.adoc b/modules/techdocs/proc-techdocs-addon-remove-helm.adoc new file mode 100644 index 0000000000..3c0a6dc112 --- /dev/null +++ b/modules/techdocs/proc-techdocs-addon-remove-helm.adoc @@ -0,0 +1,56 @@ +// Module included in the following assemblies: +// +// * assemblies/assembly-techdocs-addons-removing.adoc + +:_mod-docs-content-type: PROCEDURE +[id="proc-techdocs-addon-remove-helm_{context}"] +== Removing an external TechDocs add-on from your Helm chart + +If you no longer want to use the functionality of a TechDocs add-on that is imported from a particular plugin that you installed on your {product} instance with the Helm chart, you can temporarily disable it or permanently remove it from your Helm chart. The `disabled` status is controlled at the plugin level, therefore, disabling the plugin disables all of the TechDocs add-ons in the disabled plugin package. + +.Procedure +* In the `plugins` section of the Helm chart, do one of the following actions based on whether you want to disable or remove a TechDocs add-on: +** To temporarily disable all of the TechDocs add-ons in a particular plugin package, change the value of the `disabled` field to `true`. For example: ++ +[source,yaml,subs="+quotes,+attributes"] +---- +global: + dynamic: + plugins: + - package: ./dynamic-plugins/dist/backstage-plugin-techdocs-module-addons-contrib + disabled: true + pluginConfig: + dynamicPlugins: + frontend: + backstage.plugin-techdocs-module-addons-contrib: + techdocsAddons: + - importName: ReportIssue + - importName: __ +---- ++ +where: + +__:: Specifies the external TechDocs add-on that you want to remove, for example, `TextSize`. +** To remove one or more TechDocs add-ons from your {product} instance, delete `importName: __` for each external TechDocs add-on that you want to remove from the `techdocsAddons` section of your Helm chart. For example: ++ +[source,yaml,subs="+quotes,+attributes"] +---- +global: + dynamic: + plugins: + - package: ./dynamic-plugins/dist/backstage-plugin-techdocs-module-addons-contrib + disabled: false + pluginConfig: + dynamicPlugins: + frontend: + backstage.plugin-techdocs-module-addons-contrib: + techdocsAddons: + - importName: ReportIssue + - importName: __ +---- ++ +where: + +__:: Specifies the external TechDocs add-on that you want to remove, for example, `TextSize`. + +//.Next steps \ No newline at end of file diff --git a/modules/techdocs/proc-techdocs-addon-remove-operator.adoc b/modules/techdocs/proc-techdocs-addon-remove-operator.adoc new file mode 100644 index 0000000000..5ed5685463 --- /dev/null +++ b/modules/techdocs/proc-techdocs-addon-remove-operator.adoc @@ -0,0 +1,75 @@ +// Module included in the following assemblies: +// +// * assemblies/assembly-techdocs-addons-removing.adoc + +:_mod-docs-content-type: PROCEDURE +[id="proc-techdocs-addon-remove-operator_{context}"] +== Removing an external TechDocs add-on from your ConfigMap + +If you no longer want to use the functionality of a TechDocs add-on that is imported from a particular plugin that you installed on your {product} instance with the Operator, you can temporarily disable it or permanently remove it from your ConfigMap. The `disabled` status is controlled at the plugin level, therefore, disabling the plugin disables all of the TechDocs add-ons in the disabled plugin package. + +.Procedure + +. From the Developer perspective in the {ocp-short} web console, click *ConfigMaps*. +. From the *ConfigMaps* page, click the ConfigMap that contains the TechDocs add-on that you want to remove. +. Select the *YAML view* option in the *Configure via* field. +. In the `plugins` section of the ConfigMap, do one of the following actions based on whether you want to disable or remove a TechDocs add-on: +** To temporarily disable all of the TechDocs add-ons in a particular plugin package, change the value of the `disabled` field to `true`. For example: ++ +[source,yaml,subs="+quotes,+attributes"] +---- +kind: ConfigMap +apiVersion: v1 +metadata: + name: dynamic-plugins-rhdh +data: + dynamic-plugins.yaml: | + includes: + - dynamic-plugins.default.yaml + plugins: + - package: ./dynamic-plugins/dist/backstage-plugin-techdocs-module-addons-contrib + disabled: true + pluginConfig: + dynamicPlugins: + frontend: + backstage.plugin-techdocs-module-addons-contrib: + techdocsAddons: + - importName: ReportIssue + - importName: __ +---- ++ +where: + +__:: Specifies the external TechDocs add-on that you want to remove, for example, `TextSize`. +** To remove one or more TechDocs add-ons from your {product} instance, delete `importName: __` for each external TechDocs add-on that you want to remove from the `techdocsAddons` section of your ConfigMap. For example: ++ +[source,yaml,subs="+quotes,+attributes"] +---- +kind: ConfigMap +apiVersion: v1 +metadata: + name: dynamic-plugins-rhdh +data: + dynamic-plugins.yaml: | + includes: + - dynamic-plugins.default.yaml + plugins: + - package: ./dynamic-plugins/dist/backstage-plugin-techdocs-module-addons-contrib + disabled: false + pluginConfig: + dynamicPlugins: + frontend: + backstage.plugin-techdocs-module-addons-contrib: + techdocsAddons: + - importName: ReportIssue + - importName: __ +---- ++ +where: + +__:: Specifies the external TechDocs add-on that you want to remove, for example, `TextSize`. +. Click *Save*. +. In the web console navigation menu, click *Topology* and wait for the {product} pod to start. +. Click the *Open URL* icon to start using the {product} platform with the new configuration changes. + +//.Next steps diff --git a/modules/techdocs/proc-techdocs-addon-use-light-box.adoc b/modules/techdocs/proc-techdocs-addon-use-light-box.adoc new file mode 100644 index 0000000000..6d5f547d03 --- /dev/null +++ b/modules/techdocs/proc-techdocs-addon-use-light-box.adoc @@ -0,0 +1,18 @@ +// Module included in the following assemblies: +// +// * assemblies/assembly-techdocs-addons-using.adoc + +:_mod-docs-content-type: PROCEDURE +[id="proc-techdocs-addon-use-light-box_{context}"] +== Using the LightBox TechDocs add-on + +If your TechDocs documentation contains an image, you can use the `LightBox` add-on to view an enlarged version of the image in a lightbox, or overlay window. You can also zoom to change the size the lightbox image. If a single documentation page contains multiple images, you can navigate between images in the lightbox. + +.Prerequisites +* The `LightBox` add-on is installed and enabled in your TechDocs plugin. + +.Procedure +. In your TechDocs documentation, click on the image that you want to view in a lightbox. +. In the lightbox, you can do any of the following actions: +* Click the image or scroll to zoom in or zoom out. +* Click the arrow to navigate between images. diff --git a/modules/techdocs/proc-techdocs-addon-use-report-issue.adoc b/modules/techdocs/proc-techdocs-addon-use-report-issue.adoc new file mode 100644 index 0000000000..0d4ccb6d0f --- /dev/null +++ b/modules/techdocs/proc-techdocs-addon-use-report-issue.adoc @@ -0,0 +1,28 @@ +// Module included in the following assemblies: +// +// * assemblies/assembly-techdocs-addons-using.adoc + +:_mod-docs-content-type: PROCEDURE +[id="proc-techdocs-addon-use-report-issue_{context}"] +== Using the ReportIssue TechDocs add-on + +If you find an error in your organization's TechDocs documentation, you can use the `ReportIssue` add-on to open a new GitHub or GitLab issue directly from the documentation. `ReportIssue` automatically imports the text that you highlight in the document into a new issue template in your repository. + +.Prerequisites +* The `ReportIssue` add-on is installed and enabled in your TechDocs plugin. +* You have permissions to create issues in the repository where documentation issues are reported. + +.Procedure +. In your TechDocs documentation, highlight the text that you want to report an issue for. +. Click the text in the `ReportIssue` box, for example, *Open new GitHub issue*. +. From the new issue page in your repository, use the template to create the issue that you want to report. ++ +[NOTE] +==== +The default issue title is *Documentation feedback: __*, where __ is the text that you highlighted in your TechDocs documentation. + +In the issue description, __ is the default value for the *The highlighted text* field. +==== + +.Verification +* The issue that you created is listed on the issues page in your repository. diff --git a/modules/techdocs/proc-techdocs-addon-use-text-size.adoc b/modules/techdocs/proc-techdocs-addon-use-text-size.adoc new file mode 100644 index 0000000000..dda295bf52 --- /dev/null +++ b/modules/techdocs/proc-techdocs-addon-use-text-size.adoc @@ -0,0 +1,23 @@ +// Module included in the following assemblies: +// +// * assemblies/assembly-techdocs-addons-using.adoc + +:_mod-docs-content-type: PROCEDURE +[id="proc-techdocs-addon-use-text-size_{context}"] +== Using the TextSize TechDocs add-on + +You can use the `TextSize` add-on to change the size of the text on either the TechDocs Reader page or an Entity page. + +.Prerequisites +* The `TextSize` add-on is installed and enabled in your TechDocs plugin. + +.Procedure +. In your TechDocs header, click the *Settings* icon. +. Use the sliding scale to adjust the size of your documentation text. ++ +[NOTE] +==== +* The default text size is 100% +* The minimize text size is 90% +* The maximum text size is 150% +==== diff --git a/titles/customizing/master.adoc b/titles/customizing/master.adoc index 6b5ea1f5a5..3b54976696 100644 --- a/titles/customizing/master.adoc +++ b/titles/customizing/master.adoc @@ -25,13 +25,8 @@ include::modules/customizing-the-learning-paths/proc-customize-rhdh-learning-pat include::assemblies/assembly-configuring-the-global-header.adoc[leveloffset=+1] - include::assemblies/assembly-configuring-a-floating-action-button.adoc[leveloffset=+1] - -include::assemblies/assembly-configuring-techdocs.adoc[leveloffset=+1] - - include::modules/customizing-the-tech-radar-page/proc-customize-rhdh-tech-radar-page.adoc[leveloffset=+1] diff --git a/titles/techdocs/master.adoc b/titles/techdocs/master.adoc index 649b8bb685..cf9a0a8a03 100644 --- a/titles/techdocs/master.adoc +++ b/titles/techdocs/master.adoc @@ -11,3 +11,12 @@ include::modules/techdocs/con-techdocs-about.adoc[leveloffset=+1] include::assemblies/assembly-configuring-techdocs.adoc[leveloffset=+1] // techdocs add-ons +include::assemblies/assembly-techdocs-addons.adoc[leveloffset=+1] + +include::assemblies/assembly-techdocs-addons-installing.adoc[leveloffset=+2] + +include::assemblies/assembly-techdocs-addons-removing.adoc[leveloffset=+2] + +include::assemblies/assembly-techdocs-addons-using.adoc[leveloffset=+2] + +include::modules/techdocs/proc-techdocs-addon-create.adoc[leveloffset=+1]