Migrate to mdbook

.github/workflows/ci.yml

@@ -22,6 +22,14 @@ jobs:
       uses: actions/setup-node@v4
       with:
         node-version: 20
+    - name: Setup Rust
+      uses: actions-rust-lang/setup-rust-toolchain@v1
+    - name: Install mdbook
+      run: |
+        cargo install mdbook --no-default-features --features search --vers "^0.4" --locked
+        cargo install mdbook-variables --vers "^0.2" --locked
+        export PATH="$PATH:$HOME/.cargo/bin"
+        mdbook --version
 
     - name: Build and test
       run: |

.gitignore

@@ -18,6 +18,7 @@ node_modules
 
 # Production
 build
+book
 
 # Generated files
 .docusaurus

book.toml

@@ -0,0 +1,18 @@
+[book]
+authors = ["Eugene Yokota"]
+language = "en"
+multilingual = false
+src = "src/reference"
+title = "The sbt book"
+
+[output.html]
+theme = "theme"
+additional-css = ["src/reference/custom-2024.css"]
+cname = "www.scala-sbt.org"
+
+[preprocessor.variables]
+
+[preprocessor.variables.variables]
+sbt_version = "2.0.0-alpha7"
+sbt_runner_version = "1.9.8"
+scala3ExampleVersion = "3.3.1"

build.sbt

@@ -11,53 +11,23 @@ ThisBuild / scalafmtOnCompile := true
 lazy val root = (project in file("."))
   .enablePlugins(
     (if (isDevelopBranch) Seq(DocusaurusSitePlugin) else Seq()) ++
-      Seq(LowTechSnippetPamfletPlugin, ScriptedPlugin): _*
+      Seq(MdBookSitePlugin, ScriptedPlugin, SitePreviewPlugin): _*
   )
   .settings(
     name := "website",
     siteEmail := "eed3si9n" + "@gmail.com",
     // Reference
-    Pamflet / sourceDirectory := baseDirectory.value / "src" / "reference",
-    Pamflet / siteSubdirName := s"""$targetSbtBinaryVersion/docs""",
+    MdBook / siteSubdirName := s"""$targetSbtBinaryVersion/docs/en""",
     tutorialSubDirName := s"""$targetSbtBinaryVersion/tutorial""",
     landingSubDirName := "",
     // Redirects
     redirectSettings,
-    SiteHelpers.addMappingsToSiteDir(Redirect / mappings, Pamflet / siteSubdirName),
+    // SiteHelpers.addMappingsToSiteDir(Redirect / mappings, Pamflet / siteSubdirName),
     SiteHelpers.addMappingsToSiteDir(RedirectLanding / mappings, landingSubDirName),
-    redirectTutorialSettings,
-    SiteHelpers.addMappingsToSiteDir(RedirectTutorial / mappings, tutorialSubDirName),
+    // redirectTutorialSettings,
+    // SiteHelpers.addMappingsToSiteDir(RedirectTutorial / mappings, tutorialSubDirName),
     // GitHub Pages. See project/Docs.scala
     customGhPagesSettings,
-    Pamflet / mappings := {
-      val xs = (Pamflet / mappings).value
-      Pdf.cleanupCombinedPages(xs) ++ xs
-    },
-    if (scala.sys.BooleanProp.keyExists("sbt.website.generate_pdf"))
-      Def settings (
-        // NOTE - PDF settings must be done externally like this because pdf generation generically looks
-        // through `mappings in Config` for Combined+Pages.md to generate PDF from, and therefore we
-        // can't create a circular dependency by adding it back into the original mappings.
-        Pdf.settings,
-        Pdf.settingsFor(Pamflet, "sbt-reference"),
-        SiteHelpers.addMappingsToSiteDir(
-          Pamflet / Pdf.generatePdf / mappings,
-          Pamflet / siteSubdirName,
-        )
-      )
-    else if (scala.sys.BooleanProp.keyExists("sbt.website.detect_pdf"))
-      Def.settings(
-        // assume PDF files were created in another Docker container
-        Pamflet / Pdf.detectPdf := ((Pamflet / target).value ** "*.pdf").get,
-        Pamflet / Pdf.detectPdf / mappings := {
-          (Pamflet / Pdf.detectPdf).value pair Path.relativeTo((Pamflet / target).value)
-        },
-        SiteHelpers.addMappingsToSiteDir(
-          Pamflet / Pdf.detectPdf / mappings,
-          Pamflet / siteSubdirName,
-        )
-      )
-    else Nil,
     fileEncoding := {
       sys.props("file.encoding") match {
         case "UTF-8" => "UTF-8"
@@ -71,5 +41,3 @@ lazy val root = (project in file("."))
     scriptedBufferLog := false,
     isGenerateSiteMap := true
   )
-
-//

docusaurus.config.js

@@ -72,14 +72,6 @@ const config = {
       'classic',
       /** @type {import('@docusaurus/preset-classic').Options} */
       ({
-        docs: {
-          routeBasePath: '2.x/docs/',
-          sidebarPath: './sidebars.js',
-          // Please change this to your repo.
-          // Remove this to remove the "edit this page" links.
-          editUrl:
-            'https://github.com/sbt/website/tree/develop',
-        },
         theme: {
           customCss: './src/css/custom.css',
         },
@@ -115,8 +107,7 @@ const config = {
             position: 'left',
           },
           {
-            type: 'docSidebar',
-            sidebarId: 'tutorialSidebar',
+            href: 'https://www.scala-sbt.org/2.x/docs/en/',
             label: 'Doc Beta',
             position: 'right',
           },

project/Docs.scala

@@ -34,7 +34,8 @@ object Docs {
   // - src/reference/template.properties
   lazy val targetSbtBinaryVersion = {
     if (isBetaBranch) "1.x-beta"
-    else "1.x"
+    else if (is1xBranch) "1.x"
+    else "2.x"
   }
 
   // to avoid duplicates, tell Google to only index /1.x/**

project/MdBookSitePlugin.scala

@@ -0,0 +1,41 @@
+import sbt.*
+import Keys.*
+import com.typesafe.sbt.site.SitePlugin.autoImport.siteSubdirName
+import com.typesafe.sbt.site.SitePlugin
+import com.typesafe.sbt.site.util.SiteHelpers
+import scala.annotation.nowarn
+
+object MdBookSitePlugin extends AutoPlugin {
+  override def requires = SitePlugin
+  override def trigger = noTrigger
+  override def projectSettings = mdbookSettings(Compile)
+
+  object autoImport {
+    val MdBook = config("mdbook")
+    val mdbookBuild = taskKey[File]("")
+    val mdbookDirectory = settingKey[File]("Directory where docs are located")
+  }
+  import autoImport.*
+
+  @nowarn
+  def mdbookSettings(config: Configuration): Seq[Setting[_]] =
+    inConfig(if (config == Compile) MdBook else config)(
+      List(
+        siteSubdirName := "",
+        mdbookDirectory := baseDirectory.value,
+        config / mdbookBuild := {
+          import scala.sys.process.*
+          val dir = mdbookDirectory.value
+          Process(List("mdbook", "build"), cwd = dir).!
+          val out = dir / "book"
+          out
+        },
+      )
+    ) ++
+      SiteHelpers.watchSettings(ThisScope.in(config, mdbookBuild.key)) ++
+      SiteHelpers.addMappingsToSiteDir(
+        (config / mdbookBuild)
+          .map(SiteHelpers.selectSubpaths(_, AllPassFilter)),
+        (if (config == Compile) MdBook else config) / siteSubdirName
+      )
+}

project/plugins.sbt

@@ -1,5 +1,4 @@
-addSbtPlugin("com.github.sbt" % "sbt-site-paradox" % "1.5.0")
+ThisBuild / libraryDependencySchemes += "org.scala-lang.modules" %% "scala-xml" % VersionScheme.Always
+addSbtPlugin("com.github.sbt" % "sbt-site" % "1.5.0")
 addSbtPlugin("com.github.sbt" % "sbt-ghpages" % "0.7.0")
-libraryDependencies += "org.foundweekends" %% "pamflet-library" % "0.11.0"
 addSbtPlugin("org.scalameta" % "sbt-scalafmt" % "2.4.2")
-addSbtPlugin("com.lightbend.paradox" % "sbt-paradox" % "0.6.9")

src/reference/README.md

@@ -0,0 +1,15 @@
+The sbt book
+============
+
+sbt is a simple build tool for Scala and Java.
+sbt downloads your library dependencies via Coursier,
+incrementally compiles and tests your projects,
+integrates with IDEs like IntelliJ and VS Code,
+makes JAR packages, and publishes them to [Maven Central](https://central.sonatype.com/),
+JVM community's package registry.
+
+```scala
+scalaVersion := "{{scala3ExampleVersion}}"
+```
+
+You just need one line of `build.sbt` to get started with Scala.

src/reference/SUMMARY.md

@@ -0,0 +1,14 @@
+# Summary
+
+[Introduction](README.md)
+
+# Quick Start
+
+- [Installing sbt runner](Setup.md)
+- [sbt by example](sbt-by-example.md)
+
+----
+
+# Appendix
+
+- [Setup notes](setup-notes.md)

src/reference/Setup.md

@@ -0,0 +1,56 @@
+Installing sbt runner
+=====================
+
+To build an sbt project, you'll need to take these steps:
+
+- Install JDK (We recommend Eclipse Adoptium Temurin JDK 8, 11, or 17, or Zulu JDK 8 for macOS with ARM chips).
+- Install sbt runner.
+
+sbt runner is a script that invokes a declared version of sbt, downloading it beforehand if necessary. This allows build authors to precisely control
+the sbt version, instead of relying on users' machine environment.
+
+### Prerequisites
+
+sbt runs on all major operating systems; however, it requires JDK 8 or higher to run.
+
+```bash
+java -version
+# openjdk version "1.8.0_352"
+```
+
+### Install sbt with **cs setup**
+
+Follow [Install](https://www.scala-lang.org/download/) page, and install Scala using Coursier.
+
+```bash
+cs setup
+```
+
+This should install the latest stable version of `sbt`.
+
+### Installing from SDKMAN
+
+To install both JDK and sbt, consider using [SDKMAN](https://sdkman.io/).
+
+```bash
+sdk install java $(sdk list java | grep -o "\b8\.[0-9]*\.[0-9]*\-tem" | head -1)
+sdk install sbt
+```
+
+### Universal packages
+
+- [sbt-{{sbt_runner_version}}.zip][ZIP]
+- [sbt-{{sbt_runner_version}}.tgz][TGZ]
+- [sbt-{{sbt_runner_version}}.msi][MSI]
+
+Verify the sbt runner
+---------------------
+
+```bash
+sbt --script-version
+# {{sbt_runner_version}}
+```
+
+  [MSI]: https://github.com/sbt/sbt/releases/download/v{{sbt_runner_version}}/sbt-{{sbt_runner_version}}.msi
+  [ZIP]: https://github.com/sbt/sbt/releases/download/v{{sbt_runner_version}}/sbt-{{sbt_runner_version}}.zip
+  [TGZ]: https://github.com/sbt/sbt/releases/download/v{{sbt_runner_version}}/sbt-{{sbt_runner_version}}.tgz

src/reference/custom-2024.css

@@ -0,0 +1,7 @@
+html {
+  font-family: "Helvetica Neue", "Roboto", "Arial", sans-serif;
+}
+
+pre {
+  border: solid 1px lightgray;
+}

src/reference/00-Getting-Started/02-sbt-by-example.md → src/reference/sbt-by-example.md

@@ -1,37 +1,32 @@
----
-out: sbt-by-example.html
----
 
   [Basic-Def]: Basic-Def.html
-  [Setup]: Setup.html
+  [Setup]: Setup.md
   [Running]: Running.html
   [Essential-sbt]: https://www.scalawilliam.com/essential-sbt/
 
 sbt by example
 --------------
 
-This page assumes you've [installed sbt 1][Setup].
+This page assumes you've [installed sbt runner][Setup].
 
 Let's start with examples rather than explaining how sbt works or why.
 
 ### Create a minimum sbt build
 
-```
-\$ mkdir foo-build
-\$ cd foo-build
-\$ touch build.sbt
+```bash
+mkdir foo-build
+cd foo-build
+touch build.sbt
+mkdir project
+echo "sbt.version={{sbt_version}}" > project/build.properties
 ```
 
 ### Start sbt shell
 
-```
-\$ sbt
-[info] Updated file /tmp/foo-build/project/build.properties: set sbt.version to 1.9.3
-[info] welcome to sbt 1.9.3 (Eclipse Adoptium Java 17.0.8)
-[info] Loading project definition from /tmp/foo-build/project
-[info] loading settings for project foo-build from build.sbt ...
-[info] Set current project to foo-build (in build file:/tmp/foo-build/)
-[info] sbt server started at local:///Users/eed3si9n/.sbt/1.0/server/abc4fb6c89985a00fd95/sock
+```bash
+$ sbt
+[info] welcome to sbt {{sbt_version}} (Azul Systems, Inc. Java 1.8.0_352)
+....
 [info] started sbt server
 sbt:foo-build>
 ```
@@ -48,8 +43,8 @@ sbt:foo-build> exit
 
 As a convention, we will use the `sbt:...>` or `>` prompt to mean that we're in the sbt interactive shell.
 
-```
-\$ sbt
+```bash
+$ sbt
 sbt:foo-build> compile
 ```
 
@@ -453,10 +448,10 @@ sbt:Hello> dist
 Here's how you can run the packaged app:
 
 ```
-\$ /tmp/someother
-\$ cd /tmp/someother
-\$ unzip -o -d /tmp/someother /tmp/foo-build/target/universal/hello-0.1.0-SNAPSHOT.zip
-\$ ./hello-0.1.0-SNAPSHOT/bin/hello
+$ /tmp/someother
+$ cd /tmp/someother
+$ unzip -o -d /tmp/someother /tmp/foo-build/target/universal/hello-0.1.0-SNAPSHOT.zip
+$ ./hello-0.1.0-SNAPSHOT/bin/hello
 Hello! The current temperature in New York is 22.7 C.
 ```
 
@@ -473,7 +468,7 @@ sbt:Hello> Docker/publishLocal
 Here's how to run the Dockerized app:
 
 ```
-\$ docker run hello:0.1.0-SNAPSHOT
+$ docker run hello:0.1.0-SNAPSHOT
 Hello! The current temperature in New York is 22.7 C.
 ```
 
@@ -528,7 +523,7 @@ sbt:Hello> inspect tree dist
 You can also run sbt in batch mode, passing sbt commands directly from the terminal.
 
 ```
-\$ sbt clean "testOnly HelloSuite"
+$ sbt clean "testOnly HelloSuite"
 ```
 
 **Note**: Running in batch mode requires JVM spinup and JIT each time,
@@ -541,7 +536,7 @@ or a continuous test like `~testQuick`.
 You can use the sbt `new` command to quickly setup a simple "Hello world" build.
 
 ```
-\$ sbt new scala/scala-seed.g8
+$ sbt new scala/scala-seed.g8
 ....
 A minimal Scala project.