Add redirections from old URLs to avoid breakages (#15118)

* Add redirections from old URLs to avoid breakages

The Scala 3 reference documentation that used to be published to https://docs.scala-lang.org was using some different URLs than the URLs used by the documentation produced by Scaladoc. You can see here some examples of breakages:
scala/docs.scala-lang@763d518

We add redirects from previously supported URLs to avoid such breakages in case there are links in the web that point to the old URLs.

Author: julienrf

docs/_docs/reference/other-new-features/other-new-types.md renamed to docs/_docs/reference/other-new-features/other-new-features.md

@@ -69,7 +69,7 @@ subsection:
           - page: reference/metaprogramming/reflection.md
           - page: reference/metaprogramming/tasty-inspect.md
       - title: Other New Features
-        index: reference/other-new-features/other-new-types.md
+        index: reference/other-new-features/other-new-features.md
         subsection:
           - page: reference/other-new-features/trait-parameters.md
           - page: reference/other-new-features/transparent-traits.md

docs/sidebar.yml

@@ -1381,21 +1381,33 @@ object Build {
         generateDocumentation(Testcases)
       }.value,
 
+      // Generate the Scala 3 reference documentation (published at https://docs.scala-lang.org/scala3/reference)
       generateReferenceDocumentation := Def.inputTaskDyn {
         val shouldRegenerateExpectedLinks = (Space ~> literal("--no-regenerate-expected-links")).?.parsed.isEmpty
 
         generateStaticAssetsTask.value
 
+        // Move all the source files to a temporary directory and apply some changes specific to the reference documentation
         val temp = IO.createTemporaryDirectory
         IO.copyDirectory(file("docs"), temp / "docs")
         IO.delete(temp / "docs" / "_blog")
 
+        // Overwrite the main layout and the sidebar
         IO.copyDirectory(
           file("project") / "resources" / "referenceReplacements",
           temp / "docs",
           overwrite = true
         )
 
+        // Add redirections from previously supported URLs, for some pages
+        for (name <- Seq("changed-features", "contextual", "dropped-features", "metaprogramming", "other-new-features")) {
+          val path = temp / "docs" / "_docs" / "reference" / name / s"${name}.md"
+          val contentLines = IO.read(path).linesIterator.to[collection.mutable.ArrayBuffer]
+          contentLines.insert(1, s"redirectFrom: /${name}.html") // Add redirection
+          val newContent = contentLines.mkString("\n")
+          IO.write(path, newContent)
+        }
+
         val languageReferenceConfig = Def.task {
           Scala3.value
             .add(OutputDir("scaladoc/output/reference"))

project/Build.scala

@@ -49,7 +49,7 @@ subsection:
       - page: reference/metaprogramming/reflection.md
       - page: reference/metaprogramming/tasty-inspect.md
   - title: Other New Features
-    index: reference/other-new-features/other-new-types.md
+    index: reference/other-new-features/other-new-features.md
     subsection:
       - page: reference/other-new-features/trait-parameters.md
       - page: reference/other-new-features/transparent-traits.md