diff --git a/.changeset/swift-weeks-admire.md b/.changeset/swift-weeks-admire.md new file mode 100644 index 0000000000..c546cb6834 --- /dev/null +++ b/.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 +``` diff --git a/docs/features/techdocs/cli.md b/docs/features/techdocs/cli.md index 6efb83549e..f5ca9e7f39 100644 --- a/docs/features/techdocs/cli.md +++ b/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 /README.md or README.md + in case a default /index.md is not provided. (default: false) -v --verbose Enable verbose output. (default: false) -h, --help display help for command ``` diff --git a/docs/features/techdocs/configuration.md b/docs/features/techdocs/configuration.md index a3f4723173..4d068f5af3 100644 --- a/docs/features/techdocs/configuration.md +++ b/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 /README.md + # or README.md in case a default /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. diff --git a/packages/techdocs-cli/src/commands/generate/generate.ts b/packages/techdocs-cli/src/commands/generate/generate.ts index 98529698ca..d192e7a2f9 100644 --- a/packages/techdocs-cli/src/commands/generate/generate.ts +++ b/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, }, diff --git a/packages/techdocs-cli/src/commands/index.ts b/packages/techdocs-cli/src/commands/index.ts index 6ad62c5668..555758a3f4 100644 --- a/packages/techdocs-cli/src/commands/index.ts +++ b/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 /README.md or README.md in case a default /index.md is not provided.', + false, + ) .alias('build') .action(lazy(() => import('./generate/generate').then(m => m.default))); diff --git a/plugins/techdocs-backend/config.d.ts b/plugins/techdocs-backend/config.d.ts index d4782ff406..4801381b0c 100644 --- a/plugins/techdocs-backend/config.d.ts +++ b/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 /README.md + * or README.md in case a default /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; }; /** diff --git a/plugins/techdocs-node/src/stages/generate/techdocs.test.ts b/plugins/techdocs-node/src/stages/generate/techdocs.test.ts index ece8337001..5957b6f99e 100644 --- a/plugins/techdocs-node/src/stages/generate/techdocs.test.ts +++ b/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, + }); + }); }); diff --git a/plugins/techdocs-node/src/stages/generate/techdocs.ts b/plugins/techdocs-node/src/stages/generate/techdocs.ts index fd05c3bf8b..faa8faa60f 100644 --- a/plugins/techdocs-node/src/stages/generate/techdocs.ts +++ b/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', + ), }; } diff --git a/plugins/techdocs-node/src/stages/generate/types.ts b/plugins/techdocs-node/src/stages/generate/types.ts index f46dbdc56a..bdbdb1095d 100644 --- a/plugins/techdocs-node/src/stages/generate/types.ts +++ b/plugins/techdocs-node/src/stages/generate/types.ts @@ -40,6 +40,7 @@ export type GeneratorConfig = { dockerImage?: string; pullImage?: boolean; omitTechdocsCoreMkdocsPlugin?: boolean; + legacyCopyReadmeMdToIndexMd?: boolean; }; /**