Merge pull request #10839 from backstage/techdocs/improve-readme-index-messaging

.changeset/techdocs-swift-weeks-admire.md

@@ -1,14 +1,5 @@
 ---
-'@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:
-    mkdocs:
-      legacyCopyReadmeMdToIndexMd: true
-```
+Removed an undocumented, broken behavior where `README.md` files would be copied to `index.md` if it did not exist, leading to broken links in the TechDocs UI.

.changeset/techdocs-swift-weeks-admired.md

@@ -0,0 +1,14 @@
+---
+'@backstage/plugin-techdocs-backend': minor
+---
+
+Removed an undocumented, broken behavior where `README.md` files would be copied to `index.md` if it did not exist, leading to broken links in the TechDocs UI.
+
+**WARNING**: If you notice 404s in TechDocs after updating, check to make sure that all markdown files referenced in your `mkdocs.yml`s' `nav` sections exist. The following configuration may be used to temporarily revert to the broken behavior.
+
+```yaml
+techdocs:
+  generator:
+    mkdocs:
+      legacyCopyReadmeMdToIndexMd: true
+```

.changeset/techdocs-swift-weeks-admiring.md

@@ -0,0 +1,11 @@
+---
+'@techdocs/cli': minor
+---
+
+Removed an undocumented, broken behavior where `README.md` files would be copied to `index.md` if it did not exist, leading to broken links in the TechDocs UI.
+
+**WARNING**: If you notice 404s in TechDocs after updating, check to make sure that all markdown files referenced in your `mkdocs.yml`s' `nav` sections exist. The following flag may be passed to the `generate` command to temporarily revert to the broken behavior.
+
+```sh
+techdocs-cli generate --legacyCopyReadmeMdToIndexMd
+```