docgen: more explanation in api index

packages/docgen/src/docgen/ApiDocPrinter.ts

@@ -88,6 +88,13 @@ export default class ApiDocPrinter {
 
     printer.header(1, 'Backstage Utility APIs');
 
+    printer.paragraph(
+      'The following is a list of all Utility APIs defined by `@backstage/core`.',
+      'They are available to use by plugins and components, and need to be provided by the app',
+      'They can be accessed using the `useApi` hook, also provided by `@backstage/core`.',
+      'For more information, see https://github.com/spotify/backstage/blob/master/docs/api/utility-apis.md.',
+    );
+
     for (const api of apiDocs) {
       printer.header(3, `${api.name.replace(/ApiRef$/, '')}`, api.id);
 

packages/docgen/src/docgen/MarkdownPrinter.ts

@@ -48,9 +48,10 @@ export default class MarkdownPrinter {
     this.line();
   }
 
-  paragraph(text: string) {
+  paragraph(...text: string[]) {
     this.line(
       text
+        .join('\n')
         .trim()
         .split('\n')
         .map(line => line.trim())

packages/docgen/src/generate.ts

@@ -87,7 +87,7 @@ export async function generate(targetPath: string) {
     [
       'site_name: api-references',
       'nav:',
-      `  - Utility API Index: 'README.md'`,
+      `  - API Index: 'README.md'`,
       ...apiTypes.map(({ name }) => `  - ${name}: '${name}.md'`),
       'plugins:',
       '  - techdocs-core',