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

Signed-off-by: Phil Kuang <pkuang@factset.com>

.changeset/swift-weeks-admire.md

@@ -0,0 +1,13 @@
+---
+'@techdocs/cli': minor
+'@backstage/plugin-techdocs-backend': minor
+'@backstage/plugin-techdocs-node': minor
+---
+
+BREAKING: The default Techdocs behavior will no longer attempt to copy `docs/README.md` or `README.md` to `docs/index.md` (if not found). To retain this behavior in your instance, you can set the following config in your `app-config.yaml`:
+
+```yaml
+techdocs:
+  generator:
+    legacyCopyReadmeMdToIndexMd: true
+```

docs/features/techdocs/cli.md

@@ -132,6 +132,8 @@ Options:
                                   in techdocs_metadata.json.
   --omitTechdocsCoreMkdocsPlugin  An option to disable automatic addition of techdocs-core plugin to the mkdocs.yaml files.
                                   Defaults to false, which means that the techdocs-core plugin is always added to the mkdocs file.
+  --legacyCopyReadmeMdToIndexMd   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. (default: false)
   -v --verbose                    Enable verbose output. (default: false)
   -h, --help                      display help for command
 ```

docs/features/techdocs/configuration.md

@@ -42,6 +42,13 @@ techdocs:
       # Defaults to false, which means that the techdocs-core plugin is always added to the mkdocs file.
       omitTechdocsCorePlugin: false
 
+    # (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: false
+
   # techdocs.builder can be either 'local' or 'external.
   # Using the default build strategy, if builder is set to 'local' and you open a TechDocs page,
   # techdocs-backend will try to generate the docs, publish to storage and show the generated docs afterwords.

packages/techdocs-cli/src/commands/generate/generate.ts

@@ -42,6 +42,7 @@ export default async function generate(cmd: Command) {
   const omitTechdocsCorePlugin = cmd.omitTechdocsCoreMkdocsPlugin;
   const dockerImage = cmd.dockerImage;
   const pullImage = cmd.pull;
+  const legacyCopyReadmeMdToIndexMd = cmd.legacyCopyReadmeMdToIndexMd;
 
   logger.info(`Using source dir ${sourceDir}`);
   logger.info(`Will output generated files in ${outputDir}`);
@@ -56,6 +57,7 @@ export default async function generate(cmd: Command) {
         runIn: cmd.docker ? 'docker' : 'local',
         dockerImage,
         pullImage,
+        legacyCopyReadmeMdToIndexMd,
         mkdocs: {
           omitTechdocsCorePlugin,
         },

packages/techdocs-cli/src/commands/index.ts

@@ -59,6 +59,11 @@ export function registerCommands(program: CommanderStatic) {
       "Don't patch MkDocs file automatically with techdocs-core plugin.",
       false,
     )
+    .option(
+      '--legacyCopyReadmeMdToIndexMd',
+      '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.',
+      false,
+    )
     .alias('build')
     .action(lazy(() => import('./generate/generate').then(m => m.default)));
 

plugins/techdocs-backend/config.d.ts

@@ -44,6 +44,15 @@ export interface Config {
        * Pull the latest docker image
        */
       pullImage?: boolean;
+
+      /**
+       * (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,
+          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.legacyCopyReadmeMdToIndexMd',
+    ),
   };
 }

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

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