Add Table of Contents to static sites

Author: pikinier20

docs/_layouts/doc-page.html

@@ -15,7 +15,7 @@ <h1>{{ page.title }}</h1>
   </header>
   {{ content }}
   <div class="content-contributors hidden">
-    <h5>Contributors to this page:</h5>
+    <span><b>Contributors to this page</b></span>
     <div id="documentation-contributors" class="contributors-container"></div>
   </div>
 </main>

scaladoc-testcases/docs/_docs/docs/f5.html

@@ -0,0 +1,3 @@
+<h1>Header 1</h1>
+<h2>Header 2</h2>
+<h3>Header 3</h3>

scaladoc-testcases/docs/sidebar.yml

@@ -4,3 +4,4 @@ subsection:
   - page: docs/f2.md
   - page: docs/f3.md
   - page: docs/f4.md
+  - page: docs/f5.html

scaladoc/resources/dotty_res/styles/scalastyle.css

@@ -10,6 +10,7 @@
 
   /* Layout Settings (changes on small screens) */
   --side-width: 300px;
+  --toc-width: 300px;
   --content-padding: 24px 42px;
   --footer-height: 42px;
 }
@@ -43,6 +44,7 @@ body, button, input {
 #main-content {
   min-height: calc(100vh - var(--footer-height) - 24px);
   margin-left: var(--side-width);
+  margin-right: var(--toc-width);
   padding: var(--content-padding);
   padding-bottom: calc(24px + var(--footer-height));
 
@@ -905,6 +907,36 @@ footer .socials {
   height: 8px;
 }
 
+#toc {
+  position: fixed;
+  right: 0px;
+  top: 0px;
+  width: var(--toc-width);
+  height: 100%;
+
+  padding-top: 15vh;
+  padding-right: 10px;
+
+  display: flex;
+  flex-direction: column;
+}
+
+#toc .toc-title {
+  font-weight: bold;
+  padding-left: 16px;
+}
+
+#toc ul {
+  list-style-type: none;
+  padding-left: 16px;
+}
+
+#toc a {
+  display: block;
+  padding-top: 0.5em;
+  padding-bottom: 0.5em;
+}
+
 /* Signature coloring */
 
 :root {
@@ -941,6 +973,12 @@ footer .socials {
   }
 }
 /* Landscape phones, portait tablets */
+@media(max-width: 1200px) {
+  :root {
+    --toc-width: 0px;
+  }
+}
+
 @media(max-width: 768px) {
   :root {
     --content-padding: 12px 12px;
@@ -1086,6 +1124,7 @@ footer .socials {
   flex-direction: column;
 
   transition: color 0.5s, background-color 0.5s;
+  z-index: 3;
 }
 
 .arrows.previous, .arrows.next {

scaladoc/src/dotty/tools/scaladoc/api.scala

@@ -1,6 +1,7 @@
 package dotty.tools.scaladoc
 
 import dotty.tools.scaladoc.tasty.comments.Comment
+import util.HTML.AppliedTag
 
 enum Visibility(val name: String):
   case Unrestricted extends Visibility("")
@@ -258,3 +259,18 @@ case class SnippetCompilerData(
   imports: List[String],
   position: SnippetCompilerData.Position
 )
+
+case class PageContent(content: AppliedTag, toc: Seq[TocEntry])
+
+case class TocEntry(level: Int, content: String, anchor: String)
+
+object TocEntry:
+  val tagLevels: Map[String, Int] = Map(
+    ("h1" -> 1),
+    ("h2" -> 2),
+    ("h3" -> 3),
+    ("h4" -> 4),
+    ("h5" -> 5),
+    ("h6" -> 6)
+  )
+  def apply(tag: String, content: String, anchor: String): TocEntry = TocEntry(tagLevels(tag), content, anchor)

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

@@ -22,7 +22,7 @@ class HtmlRenderer(rootPackage: Member, members: Map[DRI, Member])(using ctx: Do
     html(
       mkHead(page),
       body(
-        if !page.hasFrame then renderContent(page)
+        if !page.hasFrame then renderContent(page).content
         else mkFrame(page.link, parents, renderContent(page))
       )
     )
@@ -148,7 +148,23 @@ class HtmlRenderer(rootPackage: Member, members: Map[DRI, Member])(using ctx: Do
       )
     }
 
-  private def mkFrame(link: Link, parents: Vector[Link], content: => AppliedTag): AppliedTag =
+  private def renderTableOfContents(toc: Seq[TocEntry]): Option[AppliedTag] =
+    def renderTocRec(level: Int, rest: Seq[TocEntry]): Seq[AppliedTag] =
+      rest match {
+        case Nil => Nil
+        case head :: tail if head.level == level =>
+          val (nested, rest) = tail.span(_.level > level)
+          val nestedList = if nested.nonEmpty then Seq(ul(renderTocRec(level + 1, nested))) else Nil
+          li(a(href := head.anchor)(head.content), nestedList) +: renderTocRec(level, rest)
+        case rest @ (head :: tail) if head.level > level =>
+          val (prefix, suffix) = rest.span(_.level > level)
+          li(ul(renderTocRec(level + 1, prefix))) +: renderTocRec(level, suffix)
+      }
+
+    renderTocRec(1, toc).headOption.map(toc => ul(cls := "toc-list")(toc))
+
+
+  private def mkFrame(link: Link, parents: Vector[Link], content: => PageContent): AppliedTag =
     val projectLogo =
       args.projectLogo.map { path =>
         val fileName = Paths.get(path).getFileName()
@@ -202,7 +218,7 @@ class HtmlRenderer(rootPackage: Member, members: Map[DRI, Member])(using ctx: Do
         div(id := "scaladoc-searchBar"),
         main(id := "main-content")(
           parentsHtml,
-          div(id := "content")(content),
+          div(id := "content")(content.content),
         ),
         footer(
           div(id := "generated-by")(
@@ -239,5 +255,11 @@ class HtmlRenderer(rootPackage: Member, members: Map[DRI, Member])(using ctx: Do
             )
           )
         )
-      )
+      ),
+      renderTableOfContents(content.toc).fold(Nil) { toc =>
+        div(id := "toc")(
+          span(cls := "toc-title")("In this article"),
+          toc
+        )
+      }
     )

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

@@ -22,7 +22,7 @@ class MarkdownRenderer(rootPackage: Member, members: Map[DRI, Member])(using ctx
     super.render()
 
   override def pageContent(page: Page, parents: Vector[Link]): AppliedTag =
-    renderContent(page)
+    renderContent(page).content
 
   private def renderResources(): Seq[String] =
     allResources(Nil).flatMap(renderResource)

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

@@ -387,7 +387,7 @@ class MemberRenderer(signatureRenderer: SignatureRenderer)(using DocContext) ext
     div(cls := "filterLowerContainer")()
   )
 
-  def fullMember(m: Member): AppliedTag =
+  def fullMember(m: Member): PageContent =
     val intro = m.kind match
       case Kind.RootPackage =>Seq(h1(summon[DocContext].args.name))
       case _ =>
@@ -401,11 +401,13 @@ class MemberRenderer(signatureRenderer: SignatureRenderer)(using DocContext) ext
             memberSignature(m)
           )
         )
-
-    div(
-      intro,
-      memberInfo(m, withBrief = false),
-      classLikeParts(m),
-      buildDocumentableFilter, // TODO Need to make it work in JS :(
-      buildMembers(m)
+    PageContent(
+      div(
+        intro,
+        memberInfo(m, withBrief = false),
+        classLikeParts(m),
+        buildDocumentableFilter, // TODO Need to make it work in JS :(
+        buildMembers(m)
+      ),
+      Seq.empty // For now, we don't support table of contents in members
     )

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

@@ -115,7 +115,7 @@ abstract class Renderer(rootPackage: Member, val members: Map[DRI, Member], prot
 
     all
 
-  def renderContent(page: Page) = page.content match
+  def renderContent(page: Page): PageContent = page.content match
     case m: Member =>
       val signatureRenderer = new SignatureRenderer:
         def currentDri: DRI = page.link.dri
@@ -126,7 +126,7 @@ abstract class Renderer(rootPackage: Member, val members: Map[DRI, Member], prot
 
       MemberRenderer(signatureRenderer).fullMember(m)
     case t: ResolvedTemplate => siteContent(page.link.dri, t)
-    case a: String =>  raw(a)
+    case a: String =>  PageContent(raw(a), Seq.empty)
 
 
 

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

@@ -8,10 +8,12 @@ import java.net.URL
 import dotty.tools.scaladoc.site._
 import scala.util.Try
 import org.jsoup.Jsoup
+import org.jsoup.nodes.Element
 import java.nio.file.Paths
 import java.nio.file.Path
 import java.nio.file.Files
 import java.io.File
+import scala.util.chaining._
 
 case class ResolvedTemplate(template: LoadedTemplate, ctx: StaticSiteContext):
   val resolved = template.resolveToHtml(ctx)
@@ -26,7 +28,7 @@ trait SiteRenderer(using DocContext) extends Locations:
 
   private val HashRegex = "([^#]+)(#.+)".r
 
-  def siteContent(pageDri: DRI, content: ResolvedTemplate): AppliedTag =
+  def siteContent(pageDri: DRI, content: ResolvedTemplate): PageContent =
     import content.ctx
     def tryAsDri(str: String): Option[String] =
       val (path, prefix) = str match
@@ -67,10 +69,27 @@ trait SiteRenderer(using DocContext) extends Locations:
         processLocalLink(str)
 
     val document = Jsoup.parse(content.resolved.code)
+
+    val toc = document.select("h1, h2, h3, h4, h5, h6").asScala.toSeq
+      .map { elem =>
+        val content = elem.text()
+
+        if elem.select("a[href]").isEmpty then {
+          val normalizedText = content.trim.toLowerCase.split("\\s+").mkString("-")
+          val anchor = Element("a")
+            .attr("href", s"#$normalizedText")
+            .id(normalizedText)
+            .addClass("anchor")
+          elem.insertChildren(0, JList(anchor))
+        }
+
+        TocEntry(elem.tag().getName, content, s"#${elem.selectFirst("a[href]").id()}")
+      }
+
     document.select("a").forEach(element =>
       element.attr("href", processLocalLinkWithGuard(element.attr("href")))
     )
     document.select("img").forEach { element =>
       element.attr("src", processLocalLink(element.attr("src")))
     } // foreach does not work here. Why?
-    raw(document.outerHtml())
+    PageContent(raw(document.outerHtml()), toc)