Merge pull request #10377 from kuangp/fix/techdocs-readme

fix(README): do not copy docs/README.md as docs/index.md

plugins/techdocs-backend/config.d.ts

@@ -44,6 +44,20 @@ export interface Config {
        * Pull the latest docker image
        */
       pullImage?: boolean;
+
+      /**
+       * Override behavior specific to mkdocs.
+       */
+      mkdocs?: {
+        /**
+         * (Optional and not recommended) Configures the techdocs generator to
+         * attempt to ensure an index.md exists falling back to using <docs-dir>/README.md
+         * or README.md in case a default <docs-dir>/index.md is not provided.
+         * Note that https://www.mkdocs.org/user-guide/configuration/#edit_uri behavior
+         * will be broken in these scenarios.
+         */
+        legacyCopyReadmeMdToIndexMd?: boolean;
+      };
     };
 
     /**

plugins/techdocs-node/src/stages/generate/techdocs.test.ts

@@ -137,4 +137,24 @@ describe('readGeneratorConfig', () => {
       );
     });
   });
+
+  it('should read legacyCopyReadmeMdToIndexMd config', () => {
+    const config = new ConfigReader({
+      techdocs: {
+        generator: {
+          runIn: 'docker',
+          dockerImage: 'my-org/techdocs',
+          pullImage: false,
+          mkdocs: { legacyCopyReadmeMdToIndexMd: true },
+        },
+      },
+    });
+
+    expect(readGeneratorConfig(config, logger)).toEqual({
+      runIn: 'docker',
+      dockerImage: 'my-org/techdocs',
+      pullImage: false,
+      legacyCopyReadmeMdToIndexMd: true,
+    });
+  });
 });

plugins/techdocs-node/src/stages/generate/techdocs.ts

@@ -111,7 +111,10 @@ export class TechdocsGenerator implements GeneratorBase {
         parsedLocationAnnotation,
         this.scmIntegrations,
       );
-      await patchIndexPreBuild({ inputDir, logger: childLogger, docsDir });
+
+      if (this.options.legacyCopyReadmeMdToIndexMd) {
+        await patchIndexPreBuild({ inputDir, logger: childLogger, docsDir });
+      }
     }
 
     if (!this.options.omitTechdocsCoreMkdocsPlugin) {
@@ -218,5 +221,8 @@ export function readGeneratorConfig(
     omitTechdocsCoreMkdocsPlugin: config.getOptionalBoolean(
       'techdocs.generator.mkdocs.omitTechdocsCorePlugin',
     ),
+    legacyCopyReadmeMdToIndexMd: config.getOptionalBoolean(
+      'techdocs.generator.mkdocs.legacyCopyReadmeMdToIndexMd',
+    ),
   };
 }

plugins/techdocs-node/src/stages/generate/types.ts

@@ -40,6 +40,7 @@ export type GeneratorConfig = {
   dockerImage?: string;
   pullImage?: boolean;
   omitTechdocsCoreMkdocsPlugin?: boolean;
+  legacyCopyReadmeMdToIndexMd?: boolean;
 };
 
 /**