Resolve or clarify simpler todos in techdocs-addons

Signed-off-by: Eric Peterson <ericpeterson@spotify.com>

packages/techdocs-addons/api-report.md

@@ -21,7 +21,6 @@ export type TechDocsAddonAsyncMetadata<TValue> = AsyncState<TValue | undefined>;
 
 // @public
 export enum TechDocsAddonLocations {
-  COMPONENT = 'component',
   CONTENT = 'content',
   HEADER = 'header',
   PRIMARY_SIDEBAR = 'primary sidebar',

packages/techdocs-addons/src/types.ts

@@ -51,15 +51,30 @@ export enum TechDocsAddonLocations {
   CONTENT = 'content',
 
   /**
-   * A virtual location allowing an instance of the addon to be rendered for
-   * every HTML node with the same tag name as the addon name in the markdown
-   * content. If no reference is made, no instance will be rendered. Works like
-   * regular React components, just being accessible from markdown.
+   * todo(backstage/community): This is a proposed virtual location which would
+   * help implement a common addon pattern in which many instances of a given
+   * element in markdown would be dynamically replaced at render-time based on
+   * attributes provided on that element, for example:
    *
-   * todo(backstage/techdocs-core): Keep and implement or remove before
-   * releasing this package!
+   * ```md
+   * ## Component Metadata
+   * [CatalogEntityCard](default:component/some-component-name)
+   *
+   * ## System Metadata
+   * [CatalogEntityCard](default:system/some-system-name)
+   * ```
+   *
+   * Could correspond to a TechDocs addon named `CatalogEntityCard` with
+   * location `TechDocsAddonLocations.COMPONENT`, whose `component` would be
+   * the react component that would be rendered in place of all instances of
+   * the markdown illustrated above.
+   *
+   * The `@backstage/techdocs-addons` plugin would need to be updated to, in
+   * cases where such addons had been registered, find all instances of the
+   * rendered markdown (e.g. `<a href="{entityRef}">CatalogEntityCard</a>`) and
+   * replace them with react portals to the addon component.
    */
-  COMPONENT = 'component',
+  // COMPONENT = 'component',
 }
 
 /**

plugins/techdocs/src/reader/components/TechDocsReaderPage/hooks.ts

@@ -29,11 +29,6 @@ export const useShadowRoot = () => {
  * Convenience hook for use within TechDocs addons that provides access to
  * elements that match a given selector within the shadow root.
  *
- * todo(backstage/techdocs-core): Consider extending `selectors` from string[]
- * to some kind of typed object array, so users have more control over the
- * shape of the result. e.g. a flag to indicate querySelector vs.
- * querySelectorAll.
- *
  * @public
  */
 export const useShadowRootElements = <