Initial package to encapsulate the TechDocs addon framework.

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

plugins/techdocs-addons/.eslintrc.js

@@ -0,0 +1 @@
+module.exports = require('@backstage/cli/config/eslint-factory')(__dirname);

plugins/techdocs-addons/README.md

@@ -0,0 +1,5 @@
+# @backstage/plugin-techdocs-addons
+
+Package encapsulating the TechDocs Addons framework.
+
+todo(backstage/techdocs-core): Fill in with real documentation!

plugins/techdocs-addons/api-report.md

@@ -0,0 +1,24 @@
+## API Report File for "@backstage/plugin-techdocs-addons"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+import { ComponentType } from 'react';
+
+// @public
+export enum TechDocsAddonLocations {
+  COMPONENT = 'component',
+  CONTENT = 'content',
+  HEADER = 'header',
+  PRIMARY_SIDEBAR = 'primary sidebar',
+  SECONDARY_SIDEBAR = 'secondary sidebar',
+  SUBHEADER = 'subheader',
+}
+
+// @public
+export type TechDocsAddonOptions<TAddonProps = {}> = {
+  name: string;
+  location: TechDocsAddonLocations;
+  component: ComponentType<TAddonProps>;
+};
+```

plugins/techdocs-addons/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@backstage/plugin-techdocs-addons",
+  "version": "0.0.0",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public",
+    "main": "dist/index.esm.js",
+    "types": "dist/index.d.ts"
+  },
+  "backstage": {
+    "role": "frontend-plugin"
+  },
+  "scripts": {
+    "start": "backstage-cli package start",
+    "build": "backstage-cli package build",
+    "lint": "backstage-cli package lint",
+    "test": "backstage-cli package test",
+    "clean": "backstage-cli package clean",
+    "prepack": "backstage-cli package prepack",
+    "postpack": "backstage-cli package postpack"
+  },
+  "dependencies": {},
+  "peerDependencies": {
+    "@types/react": "^16.13.1 || ^17.0.0",
+    "react": "^16.13.1 || ^17.0.0"
+  },
+  "devDependencies": {},
+  "files": [
+    "dist"
+  ]
+}

plugins/techdocs-addons/src/index.ts

@@ -0,0 +1,23 @@
+/*
+ * Copyright 2022 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * Package encapsulating the TechDocs Addon framework.
+ *
+ * @packageDocumentation
+ */
+
+export type { TechDocsAddonLocations, TechDocsAddonOptions } from './types';

plugins/techdocs-addons/src/types.ts

@@ -0,0 +1,69 @@
+/*
+ * Copyright 2022 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { ComponentType } from 'react';
+
+/**
+ * Locations for which TechDocs addons may be declared and rendered.
+ * @public
+ */
+export enum TechDocsAddonLocations {
+  /**
+   * These addons fill up the header from the right, on the same line as the
+   * title.
+   */
+  HEADER = 'header',
+
+  /**
+   * These addons appear below the header and above all content; tooling addons
+   * can be inserted for convenience.
+   */
+  SUBHEADER = 'subheader',
+
+  /**
+   * These addons appear left of the content and above the navigation.
+   */
+  PRIMARY_SIDEBAR = 'primary sidebar',
+
+  /**
+   * These addons appear right of the content and above the table of contents.
+   */
+  SECONDARY_SIDEBAR = 'secondary sidebar',
+
+  /**
+   * A virtual location which allows mutation of all content within the shadow
+   * root by transforming DOM nodes. These addons should return null on render.
+   */
+  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.
+   */
+  COMPONENT = 'component',
+}
+
+/**
+ * Options for creating a TechDocs addon.
+ * @public
+ */
+export type TechDocsAddonOptions<TAddonProps = {}> = {
+  name: string;
+  location: TechDocsAddonLocations;
+  component: ComponentType<TAddonProps>;
+};

scripts/api-extractor.ts

@@ -257,6 +257,8 @@ const NO_WARNING_PACKAGES = [
   'plugins/scaffolder-common',
   'plugins/search-backend-node',
   'plugins/search-common',
+  'plugins/techdocs',
+  'plugins/techdocs-addons',
   'plugins/techdocs-backend',
   'plugins/techdocs-node',
   'plugins/tech-insights',
@@ -264,7 +266,6 @@ const NO_WARNING_PACKAGES = [
   'plugins/tech-insights-backend-module-jsonfc',
   'plugins/tech-insights-common',
   'plugins/tech-insights-node',
-  'plugins/techdocs',
   'plugins/todo',
   'plugins/todo-backend',
 ];