Add file path escaping to Scaladoc

As Jekyll (and in extension GitHub pages) makes starting a file/folder
name with a couple characters illegal, those character are now being
replaced with a "$charname" format.

Some tests concerning links were adjusted to accomodate the changes.

Author: jchyb

scaladoc/src/dotty/tools/scaladoc/renderers/Locations.scala

@@ -47,8 +47,9 @@ trait Locations(using ctx: DocContext):
               case "<empty>" :: tail => "_empty_" :: tail
               case other => other
             if ctx.args.apiSubdirectory then "api" :: fqn else fqn
-        cache.put(dri, path)
-        path
+        val escapedPath = escapePath(path)
+        cache.put(dri, escapedPath)
+        escapedPath
       case cached => cached
 
   private def unknownPage(dri: DRI): String =

scaladoc/src/dotty/tools/scaladoc/util/escape.scala

@@ -9,3 +9,19 @@ object Escape:
       .replace("/", "$div")
       .replace("\\", "$bslash")
     if escaped != filename then escaped + "$" else escaped
+
+  def escapePath(path: Seq[String]) = path.escapeIllegalJekyllChars
+
+  /**  
+   *  Jekyll (also used by GitHub Pages) by default makes a couple characters 
+   *  illegal to use in file name beginnings. Those can be disabled manually,
+   *  however as suggested by #14612 and like supported in Scala 2 scaladoc
+   *  it's better to have those characters escaped here by default.
+   */
+  extension (path: Seq[String]) private def escapeIllegalJekyllChars: Seq[String] =
+    path.map(
+      _.replaceAll("^~", "\\$tilde")
+        .replaceAll("^\\_", "\\$underline")
+        .replaceAll("^\\.", "\\$dot")
+        .replaceAll("^\\#", "\\$hash")
+    )

scaladoc/test/dotty/tools/scaladoc/ReportingTest.scala

@@ -80,7 +80,7 @@ class ReportingTest:
     )){ diag =>
       assertNoWarning(diag)
       val Seq(msg) = diag.errorMsgs.map(_.toLowerCase)
-      Seq("conflict","api", "static", "page", "_docs/tests/adoc.html")
+      Seq("conflict","api", "static", "page", "$underlinedocs/tests/adoc.html")
       .foreach( word =>
           Assert.assertTrue(s"Error message: $msg should contains $word", msg.contains(word))
         )

scaladoc/test/dotty/tools/scaladoc/renderers/LocationTests.scala

@@ -44,8 +44,8 @@ class LocationTests:
       locations.escapedAbsolutePathWithAnchor(new DRI(location, anchor))
 
     assertEquals(
-      "scala/%23::.html#abcde",
-      pathWithAnchor("scala.#::", "abcde")
+      "scala/$hash%23::.html#abcde",
+      pathWithAnchor("scala.##::", "abcde")
     )
 
     assertEquals(

scaladoc/test/dotty/tools/scaladoc/site/NavigationTest.scala

@@ -44,5 +44,5 @@ class NavigationTest extends BaseHtmlTest:
       )),
     ))
 
-    testNavMenu("_docs/Adoc.html", topLevelNav)
+    testNavMenu("$underlinedocs/Adoc.html", topLevelNav)
   }

scaladoc/test/dotty/tools/scaladoc/site/SiteGeneratationTest.scala

@@ -32,13 +32,13 @@ class SiteGeneratationTest extends BaseHtmlTest:
       }
 
   def testDocPages()(using ProjectContext) =
-    checkFile("_docs/Adoc.html")(title = "Adoc", header = "Header in Adoc", parents = Seq(projectName))
-    checkFile("_docs/dir/index.html")(title = "A directory", header = "A directory", parents = Seq(projectName))
-    checkFile("_docs/dir/nested.html")(
+    checkFile("$underlinedocs/Adoc.html")(title = "Adoc", header = "Header in Adoc", parents = Seq(projectName))
+    checkFile("$underlinedocs/dir/index.html")(title = "A directory", header = "A directory", parents = Seq(projectName))
+    checkFile("$underlinedocs/dir/nested.html")(
       title = "Nested in a directory", header = "Nested in a directory", parents = Seq(projectName, "A directory"))
 
   def testDocIndexPage()(using ProjectContext) =
-    checkFile("_docs/index.html")(title = projectName, header = s"$projectName in header")
+    checkFile("$underlinedocs/index.html")(title = projectName, header = s"$projectName in header")
 
   def testApiPages(
     mainTitle: String = "API",
@@ -66,13 +66,13 @@ class SiteGeneratationTest extends BaseHtmlTest:
     testDocIndexPage()
     testApiPages()
 
-    withHtmlFile("_docs/Adoc.html"){ content  =>
+    withHtmlFile("$underlinedocs/Adoc.html"){ content  =>
         content.assertAttr("p a","href", "../tests/site/SomeClass.html")
     }
 
     withHtmlFile("tests/site/SomeClass.html"){ content  =>
       content.assertAttr(".breadcrumbs a","href",
-        "../../_docs/index.html", "../../index.html", "../site.html", "SomeClass.html"
+        "../../$underlinedocs/index.html", "../../index.html", "../site.html", "SomeClass.html"
       )
     }
   }
@@ -98,7 +98,7 @@ class SiteGeneratationTest extends BaseHtmlTest:
   @Test
   def staticLinking() = withGeneratedSite(testDocPath.resolve("static-links")){
 
-    withHtmlFile("_docs/Adoc.html"){ content  =>
+    withHtmlFile("$underlinedocs/Adoc.html"){ content  =>
         content.assertAttr("p a","href",
         "dir/html.html",
         "dir/name...with..dots..html",