From 2776f735d7cf79b1fe69a8c00b25d68be8464096 Mon Sep 17 00:00:00 2001
From: Patrik Oldsberg <poldsberg@gmail.com>
Date: Thu, 16 Jul 2020 15:35:48 +0200
Subject: [PATCH] docgen: more explanation in api index

---
 packages/docgen/src/docgen/ApiDocPrinter.ts   | 7 +++++++
 packages/docgen/src/docgen/MarkdownPrinter.ts | 3 ++-
 packages/docgen/src/generate.ts               | 2 +-
 3 files changed, 10 insertions(+), 2 deletions(-)

diff --git a/packages/docgen/src/docgen/ApiDocPrinter.ts b/packages/docgen/src/docgen/ApiDocPrinter.ts
index 93c6f8677e..221d50985e 100644
--- a/packages/docgen/src/docgen/ApiDocPrinter.ts
+++ b/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);
 
diff --git a/packages/docgen/src/docgen/MarkdownPrinter.ts b/packages/docgen/src/docgen/MarkdownPrinter.ts
index 36e7c8b1d6..fb64863da9 100644
--- a/packages/docgen/src/docgen/MarkdownPrinter.ts
+++ b/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())
diff --git a/packages/docgen/src/generate.ts b/packages/docgen/src/generate.ts
index 59ac45b3ad..91ea3a02f6 100644
--- a/packages/docgen/src/generate.ts
+++ b/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',