TechDocs: Tell users when index.md is missing (better error message) (#3429)

* TechDocs: Logger already prints the name of plugin

* TechDocs: Display a custom error message if provided

* TechDocs: throw custom error message if index.md is not present

* Language improvements. Thanks @freben

Co-authored-by: Fredrik Adelöw <freben@gmail.com>

Co-authored-by: Fredrik Adelöw <freben@gmail.com>

plugins/techdocs-backend/src/techdocs/stages/publish/local.ts

@@ -53,9 +53,7 @@ export class LocalPublish implements PublisherBase {
     );
 
     if (!fs.existsSync(publishDir)) {
-      this.logger.info(
-        `[TechDocs]: Could not find ${publishDir}, creates the directory.`,
-      );
+      this.logger.info(`Could not find ${publishDir}, creating the directory.`);
       fs.mkdirSync(publishDir, { recursive: true });
     }
 
@@ -63,7 +61,7 @@ export class LocalPublish implements PublisherBase {
       fs.copy(directory, publishDir, err => {
         if (err) {
           this.logger.debug(
-            `[TechDocs]: Failed to copy docs from ${directory} to ${publishDir}`,
+            `Failed to copy docs from ${directory} to ${publishDir}`,
           );
           reject(err);
         }

plugins/techdocs/src/api.ts

@@ -95,7 +95,13 @@ export class TechDocsStorageApi implements TechDocsStorage {
     );
 
     if (request.status === 404) {
-      throw new Error('Page not found');
+      let errorMessage = 'Page not found. ';
+      // path is empty for the home page of an entity's docs site
+      if (!path) {
+        errorMessage +=
+          'This could be because there is no index.md file in the root of the docs directory of this repository.';
+      }
+      throw new Error(errorMessage);
     }
 
     return request.text();

plugins/techdocs/src/reader/components/Reader.tsx

@@ -153,7 +153,7 @@ export const Reader = ({ entityId, onReady }: Props) => {
   ]);
 
   if (error) {
-    return <TechDocsNotFound />;
+    return <TechDocsNotFound errorMessage={error.message} />;
   }
 
   return (

plugins/techdocs/src/reader/components/TechDocsNotFound.test.tsx

@@ -27,3 +27,17 @@ describe('<TechDocsNotFound />', () => {
     expect(rendered.getByTestId('go-back-link')).toBeDefined();
   });
 });
+
+describe('<TechDocsNotFound errorMessage="This is a custom error message" />', () => {
+  it('should render with status code, custom error message and go back link', () => {
+    const rendered = render(
+      wrapInTestApp(
+        <TechDocsNotFound errorMessage="This is a custom error message" />,
+      ),
+    );
+    rendered.getByText(/This is a custom error message/i);
+    rendered.getByText(/404/i);
+    rendered.getByText(/Looks like someone dropped the mic!/i);
+    expect(rendered.getByTestId('go-back-link')).toBeDefined();
+  });
+});

plugins/techdocs/src/reader/components/TechDocsNotFound.tsx

@@ -17,11 +17,15 @@
 import React from 'react';
 import { ErrorPage } from '@backstage/core';
 
-export const TechDocsNotFound = () => {
+type Props = {
+  errorMessage?: string;
+};
+
+export const TechDocsNotFound = ({ errorMessage }: Props) => {
   return (
     <ErrorPage
       status="404"
-      statusMessage="Documentation not found"
+      statusMessage={errorMessage || 'Documentation not found'}
       additionalInfo={window.location.pathname}
     />
   );