@backstage/plugin-techdocs 0.0.0-nightly-202201323044 → 0.0.0-nightly-20220203021748

package/CHANGELOG.md

@@ -1,23 +1,178 @@
 # @backstage/plugin-techdocs
 
-## 0.0.0-nightly-202201323044
+## 0.0.0-nightly-20220203021748
+
+### Patch Changes
+
+- 742434a6ba: Fixed a bug where links to files within a TechDocs site that use the `download` attribute would result in a 404 in cases where the TechDocs backend and Backstage frontend application are on the same host.
+- 359c31e31d: Added support for documentation using the raw `<source>` tag to point to relative resources like audio or video files.
+- 18317a08db: Fixed a bug where copy-to-clipboard buttons were appended to unintended elements.
+- Updated dependencies
+  - @backstage/core-components@0.0.0-nightly-20220203021748
+  - @backstage/plugin-catalog-react@0.0.0-nightly-20220203021748
+  - @backstage/integration-react@0.0.0-nightly-20220203021748
+  - @backstage/plugin-catalog@0.0.0-nightly-20220203021748
+  - @backstage/plugin-search@0.0.0-nightly-20220203021748
+
+## 0.13.2-next.1
+
+### Patch Changes
+
+- 742434a6ba: Fixed a bug where links to files within a TechDocs site that use the `download` attribute would result in a 404 in cases where the TechDocs backend and Backstage frontend application are on the same host.
+- Updated dependencies
+  - @backstage/core-components@0.8.7-next.1
+  - @backstage/plugin-catalog-react@0.6.13-next.1
+  - @backstage/plugin-catalog@0.7.11-next.1
+
+## 0.13.2-next.0
+
+### Patch Changes
+
+- 359c31e31d: Added support for documentation using the raw `<source>` tag to point to relative resources like audio or video files.
+- Updated dependencies
+  - @backstage/core-components@0.8.7-next.0
+  - @backstage/integration-react@0.1.20-next.0
+  - @backstage/plugin-catalog@0.7.11-next.0
+  - @backstage/plugin-catalog-react@0.6.13-next.0
+  - @backstage/plugin-search@0.6.1-next.0
+
+## 0.13.1
+
+### Patch Changes
+
+- bdc53553eb: chore(deps): bump `react-text-truncate` from 0.16.0 to 0.17.0
+- a64f99f734: Code snippets now include a "copy to clipboard" button.
+- Updated dependencies
+  - @backstage/core-components@0.8.6
+  - @backstage/plugin-search@0.6.0
+  - @backstage/plugin-catalog@0.7.10
+
+## 0.13.0
+
+### Minor Changes
+
+- aecfe4f403: Make `TechDocsClient` and `TechDocsStorageClient` use the `FetchApi`. You now
+  need to pass in an instance of that API when constructing the client, if you
+  create a custom instance in your app.
+
+  If you are replacing the factory:
+
+  ```diff
+  +import { fetchApiRef } from '@backstage/core-plugin-api';
+
+   createApiFactory({
+     api: techdocsStorageApiRef,
+     deps: {
+       configApi: configApiRef,
+       discoveryApi: discoveryApiRef,
+       identityApi: identityApiRef,
+  +    fetchApi: fetchApiRef,
+     },
+     factory: ({
+       configApi,
+       discoveryApi,
+       identityApi,
+  +    fetchApi,
+     }) =>
+       new TechDocsStorageClient({
+         configApi,
+         discoveryApi,
+         identityApi,
+  +      fetchApi,
+       }),
+   }),
+   createApiFactory({
+     api: techdocsApiRef,
+     deps: {
+       configApi: configApiRef,
+       discoveryApi: discoveryApiRef,
+  -    identityApi: identityApiRef,
+  +    fetchApi: fetchApiRef,
+     },
+     factory: ({
+       configApi,
+       discoveryApi,
+  -    identityApi,
+  +    fetchApi,
+     }) =>
+       new TechDocsClient({
+         configApi,
+         discoveryApi,
+  -      identityApi,
+  +      fetchApi,
+       }),
+   }),
+  ```
+
+  If instantiating directly:
+
+  ```diff
+  +import { fetchApiRef } from '@backstage/core-plugin-api';
+
+  +const fetchApi = useApi(fetchApiRef);
+   const storageClient = new TechDocsStorageClient({
+     configApi,
+     discoveryApi,
+     identityApi,
+  +  fetchApi,
+   });
+   const techdocsClient = new TechDocsClient({
+     configApi,
+     discoveryApi,
+  -  identityApi,
+  +  fetchApi,
+   }),
+  ```
+
+### Patch Changes
+
+- 51fbedc445: Migrated usage of deprecated `IdentityApi` methods.
+- 29710c91c2: use lighter color for block quotes and horizontal rulers
+- Updated dependencies
+  - @backstage/core-components@0.8.5
+  - @backstage/integration@0.7.2
+  - @backstage/plugin-search@0.5.6
+  - @backstage/core-plugin-api@0.6.0
+  - @backstage/plugin-catalog@0.7.9
+  - @backstage/plugin-catalog-react@0.6.12
+  - @backstage/config@0.1.13
+  - @backstage/catalog-model@0.9.10
+  - @backstage/integration-react@0.1.19
+
+## 0.12.15-next.0
+
+### Patch Changes
+
+- 51fbedc445: Migrated usage of deprecated `IdentityApi` methods.
+- 29710c91c2: use lighter color for block quotes and horizontal rulers
+- Updated dependencies
+  - @backstage/core-components@0.8.5-next.0
+  - @backstage/core-plugin-api@0.6.0-next.0
+  - @backstage/plugin-catalog@0.7.9-next.0
+  - @backstage/config@0.1.13-next.0
+  - @backstage/plugin-catalog-react@0.6.12-next.0
+  - @backstage/plugin-search@0.5.6-next.0
+  - @backstage/catalog-model@0.9.10-next.0
+  - @backstage/integration-react@0.1.19-next.0
+  - @backstage/integration@0.7.2-next.0
+
+## 0.12.14
 
 ### Patch Changes
 
 - 5333451def: Cleaned up API exports
 - 1628ca3f49: Fix an issue where the TechDocs sidebar is hidden when the Backstage sidebar is pinned at smaller screen sizes
 - Updated dependencies
-  - @backstage/config@0.0.0-nightly-202201323044
-  - @backstage/integration@0.0.0-nightly-202201323044
-  - @backstage/core-components@0.0.0-nightly-202201323044
-  - @backstage/core-plugin-api@0.0.0-nightly-202201323044
-  - @backstage/plugin-catalog-react@0.0.0-nightly-202201323044
-  - @backstage/errors@0.0.0-nightly-202201323044
-  - @backstage/catalog-model@0.0.0-nightly-202201323044
-  - @backstage/integration-react@0.0.0-nightly-202201323044
-  - @backstage/theme@0.0.0-nightly-202201323044
-  - @backstage/plugin-catalog@0.0.0-nightly-202201323044
-  - @backstage/plugin-search@0.0.0-nightly-202201323044
+  - @backstage/config@0.1.12
+  - @backstage/integration@0.7.1
+  - @backstage/core-components@0.8.4
+  - @backstage/core-plugin-api@0.5.0
+  - @backstage/plugin-catalog-react@0.6.11
+  - @backstage/errors@0.2.0
+  - @backstage/catalog-model@0.9.9
+  - @backstage/integration-react@0.1.18
+  - @backstage/plugin-catalog@0.7.8
+  - @backstage/plugin-search@0.5.5
 
 ## 0.12.13
 

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 /// <reference types="react" />
 import * as _backstage_core_plugin_api from '@backstage/core-plugin-api';
-import { DiscoveryApi, IdentityApi } from '@backstage/core-plugin-api';
+import { DiscoveryApi, FetchApi, IdentityApi } from '@backstage/core-plugin-api';
 import * as _backstage_catalog_model from '@backstage/catalog-model';
 import { Entity, LocationSpec, EntityName } from '@backstage/catalog-model';
 import { Config } from '@backstage/config';
@@ -19,10 +19,33 @@ declare type TechDocsEntityMetadata = Entity & {
     locationMetadata?: LocationSpec;
 };
 
+/**
+ * Utility API reference for the {@link TechDocsStorageApi}.
+ *
+ * @public
+ */
 declare const techdocsStorageApiRef: _backstage_core_plugin_api.ApiRef<TechDocsStorageApi>;
+/**
+ * Utility API reference for the {@link TechDocsApi}.
+ *
+ * @public
+ */
 declare const techdocsApiRef: _backstage_core_plugin_api.ApiRef<TechDocsApi>;
+/**
+ * The outcome of a docs sync operation.
+ *
+ * @public
+ */
 declare type SyncResult = 'cached' | 'updated';
+/**
+ * API which talks to TechDocs storage to fetch files to render.
+ *
+ * @public
+ */
 interface TechDocsStorageApi {
+    /**
+     * Set to techdocs.requestUrl as the URL for techdocs-backend API.
+     */
     getApiOrigin(): Promise<string>;
     getStorageUrl(): Promise<string>;
     getBuilder(): Promise<string>;
@@ -30,7 +53,15 @@ interface TechDocsStorageApi {
     syncEntityDocs(entityId: EntityName, logHandler?: (line: string) => void): Promise<SyncResult>;
     getBaseUrl(oldBaseUrl: string, entityId: EntityName, path: string): Promise<string>;
 }
+/**
+ * API to talk to techdocs-backend.
+ *
+ * @public
+ */
 interface TechDocsApi {
+    /**
+     * Set to techdocs.requestUrl as the URL for techdocs-backend API.
+     */
     getApiOrigin(): Promise<string>;
     getTechDocsMetadata(entityId: EntityName): Promise<TechDocsMetadata>;
     getEntityMetadata(entityId: EntityName): Promise<TechDocsEntityMetadata>;
@@ -38,15 +69,17 @@ interface TechDocsApi {
 
 /**
  * API to talk to `techdocs-backend`.
+ *
+ * @public
  */
 declare class TechDocsClient implements TechDocsApi {
     configApi: Config;
     discoveryApi: DiscoveryApi;
-    identityApi: IdentityApi;
-    constructor({ configApi, discoveryApi, identityApi, }: {
+    private fetchApi;
+    constructor(options: {
         configApi: Config;
         discoveryApi: DiscoveryApi;
-        identityApi: IdentityApi;
+        fetchApi: FetchApi;
     });
     getApiOrigin(): Promise<string>;
     /**
@@ -71,15 +104,19 @@ declare class TechDocsClient implements TechDocsApi {
 }
 /**
  * API which talks to TechDocs storage to fetch files to render.
+ *
+ * @public
  */
 declare class TechDocsStorageClient implements TechDocsStorageApi {
     configApi: Config;
     discoveryApi: DiscoveryApi;
     identityApi: IdentityApi;
-    constructor({ configApi, discoveryApi, identityApi, }: {
+    private fetchApi;
+    constructor(options: {
         configApi: Config;
         discoveryApi: DiscoveryApi;
         identityApi: IdentityApi;
+        fetchApi: FetchApi;
     });
     getApiOrigin(): Promise<string>;
     getStorageUrl(): Promise<string>;

package/dist/index.esm.js

@@ -1,4 +1,4 @@
-import { createApiRef, createRouteRef, useRouteRef, useApi, configApiRef, createPlugin, createApiFactory, discoveryApiRef, identityApiRef, createRoutableExtension, createComponentExtension } from '@backstage/core-plugin-api';
+import { createApiRef, createRouteRef, useRouteRef, useApi, configApiRef, createPlugin, createApiFactory, discoveryApiRef, identityApiRef, fetchApiRef, createRoutableExtension, createComponentExtension } from '@backstage/core-plugin-api';
 import { ResponseError, NotFoundError } from '@backstage/errors';
 import { EventSourcePolyfill } from 'event-source-polyfill';
 import React, { useEffect, useState, useReducer, useRef, useMemo, createContext, useContext, useCallback } from 'react';
@@ -37,14 +37,10 @@ const techdocsApiRef = createApiRef({
 });
 
 class TechDocsClient {
-  constructor({
-    configApi,
-    discoveryApi,
-    identityApi
-  }) {
-    this.configApi = configApi;
-    this.discoveryApi = discoveryApi;
-    this.identityApi = identityApi;
+  constructor(options) {
+    this.configApi = options.configApi;
+    this.discoveryApi = options.discoveryApi;
+    this.fetchApi = options.fetchApi;
   }
   async getApiOrigin() {
     var _a;
@@ -54,10 +50,7 @@ class TechDocsClient {
     const { kind, namespace, name } = entityId;
     const apiOrigin = await this.getApiOrigin();
     const requestUrl = `${apiOrigin}/metadata/techdocs/${namespace}/${kind}/${name}`;
-    const token = await this.identityApi.getIdToken();
-    const request = await fetch(`${requestUrl}`, {
-      headers: token ? { Authorization: `Bearer ${token}` } : {}
-    });
+    const request = await this.fetchApi.fetch(`${requestUrl}`);
     if (!request.ok) {
       throw await ResponseError.fromResponse(request);
     }
@@ -67,10 +60,7 @@ class TechDocsClient {
     const { kind, namespace, name } = entityId;
     const apiOrigin = await this.getApiOrigin();
     const requestUrl = `${apiOrigin}/metadata/entity/${namespace}/${kind}/${name}`;
-    const token = await this.identityApi.getIdToken();
-    const request = await fetch(`${requestUrl}`, {
-      headers: token ? { Authorization: `Bearer ${token}` } : {}
-    });
+    const request = await this.fetchApi.fetch(`${requestUrl}`);
     if (!request.ok) {
       throw await ResponseError.fromResponse(request);
     }
@@ -78,14 +68,11 @@ class TechDocsClient {
   }
 }
 class TechDocsStorageClient {
-  constructor({
-    configApi,
-    discoveryApi,
-    identityApi
-  }) {
-    this.configApi = configApi;
-    this.discoveryApi = discoveryApi;
-    this.identityApi = identityApi;
+  constructor(options) {
+    this.configApi = options.configApi;
+    this.discoveryApi = options.discoveryApi;
+    this.identityApi = options.identityApi;
+    this.fetchApi = options.fetchApi;
   }
   async getApiOrigin() {
     var _a;
@@ -102,10 +89,7 @@ class TechDocsStorageClient {
     const { kind, namespace, name } = entityId;
     const storageUrl = await this.getStorageUrl();
     const url = `${storageUrl}/${namespace}/${kind}/${name}/${path}`;
-    const token = await this.identityApi.getIdToken();
-    const request = await fetch(`${url.endsWith("/") ? url : `${url}/`}index.html`, {
-      headers: token ? { Authorization: `Bearer ${token}` } : {}
-    });
+    const request = await this.fetchApi.fetch(`${url.endsWith("/") ? url : `${url}/`}index.html`);
     let errorMessage = "";
     switch (request.status) {
       case 404:
@@ -125,7 +109,7 @@ class TechDocsStorageClient {
     const { kind, namespace, name } = entityId;
     const apiOrigin = await this.getApiOrigin();
     const url = `${apiOrigin}/sync/${namespace}/${kind}/${name}`;
-    const token = await this.identityApi.getIdToken();
+    const { token } = await this.identityApi.getCredentials();
     return new Promise((resolve, reject) => {
       const source = new EventSourcePolyfill(url, {
         withCredentials: true,
@@ -495,12 +479,14 @@ const techdocsPlugin = createPlugin({
       deps: {
         configApi: configApiRef,
         discoveryApi: discoveryApiRef,
-        identityApi: identityApiRef
+        identityApi: identityApiRef,
+        fetchApi: fetchApiRef
       },
-      factory: ({ configApi, discoveryApi, identityApi }) => new TechDocsStorageClient({
+      factory: ({ configApi, discoveryApi, identityApi, fetchApi }) => new TechDocsStorageClient({
         configApi,
         discoveryApi,
-        identityApi
+        identityApi,
+        fetchApi
       })
     }),
     createApiFactory({
@@ -508,12 +494,12 @@ const techdocsPlugin = createPlugin({
       deps: {
         configApi: configApiRef,
         discoveryApi: discoveryApiRef,
-        identityApi: identityApiRef
+        fetchApi: fetchApiRef
       },
-      factory: ({ configApi, discoveryApi, identityApi }) => new TechDocsClient({
+      factory: ({ configApi, discoveryApi, fetchApi }) => new TechDocsClient({
         configApi,
         discoveryApi,
-        identityApi
+        fetchApi
       })
     })
   ],
@@ -598,6 +584,7 @@ const addBaseUrl = ({
     await Promise.all([
       updateDom(dom.querySelectorAll("img"), "src"),
       updateDom(dom.querySelectorAll("script"), "src"),
+      updateDom(dom.querySelectorAll("source"), "src"),
       updateDom(dom.querySelectorAll("link"), "href"),
       updateDom(dom.querySelectorAll("a[download]"), "href")
     ]);
@@ -686,7 +673,7 @@ const addLinkClickListener = ({
         const href = target.getAttribute("href");
         if (!href)
           return;
-        if (href.startsWith(baseUrl)) {
+        if (href.startsWith(baseUrl) && !elem.hasAttribute("download")) {
           e.preventDefault();
           onClick(e, href);
         }
@@ -696,6 +683,22 @@ const addLinkClickListener = ({
   };
 };
 
+const copyToClipboard = () => {
+  return (dom) => {
+    Array.from(dom.querySelectorAll("pre > code")).forEach((codeElem) => {
+      var _a;
+      const button = document.createElement("button");
+      const toBeCopied = codeElem.textContent || "";
+      button.className = "md-clipboard md-icon";
+      button.title = "Copy to clipboard";
+      button.innerHTML = '<svg viewBox="0 0 24 24"><path d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg>';
+      button.addEventListener("click", () => navigator.clipboard.writeText(toBeCopied));
+      (_a = codeElem == null ? void 0 : codeElem.parentElement) == null ? void 0 : _a.prepend(button);
+    });
+    return dom;
+  };
+};
+
 const removeMkdocsHeader = () => {
   return (dom) => {
     var _a;
@@ -1330,6 +1333,8 @@ const useTechDocsReaderDom = (entityRef) => {
 
             --md-code-fg-color: ${theme.palette.text.primary};
             --md-code-bg-color: ${theme.palette.background.paper};
+            --md-accent-fg-color: ${theme.palette.primary.main};
+            --md-default-fg-color--lightest: ${theme.palette.textVerySubtle};
           }
           .md-main__inner { margin-top: 0; }
           .md-sidebar {  position: fixed; bottom: 100px; width: 20rem; }
@@ -1342,6 +1347,13 @@ const useTechDocsReaderDom = (entityRef) => {
           .md-typeset h1, .md-typeset h2, .md-typeset h3 { font-weight: bold; }
           .md-nav { font-size: 1rem; }
           .md-grid { max-width: 90vw; margin: 0 }
+          .md-typeset blockquote {
+            color: ${theme.palette.textSubtle};
+            border-left: 0.2rem solid ${theme.palette.textVerySubtle};
+          }
+          .md-typeset hr {
+            border-bottom: 0.05rem dotted ${theme.palette.textVerySubtle};
+          }
           .md-typeset table:not([class]) {
             font-size: 1rem;
             border: 1px solid ${theme.palette.text.primary};
@@ -1452,11 +1464,14 @@ const useTechDocsReaderDom = (entityRef) => {
     theme.palette.primary.main,
     theme.palette.success.main,
     theme.palette.text.primary,
+    theme.palette.textSubtle,
+    theme.palette.textVerySubtle,
     theme.typography.fontFamily,
     isPinned
   ]);
   const postRender = useCallback(async (transformedElement) => transform(transformedElement, [
     scrollIntoAnchor(),
+    copyToClipboard(),
     addLinkClickListener({
       baseUrl: window.location.origin,
       onClick: (event, url) => {