Migrate to mdbook

.github/workflows/ci.yml

@@ -22,35 +22,19 @@ 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: |
         sbt -v scalafmtSbtCheck scalafmtCheckAll scripted makeSite
 
-    - name: Pandoc English
-      if: ${{ github.event_name == 'push' && github.repository == 'sbt/website' && github.ref == 'refs/heads/1.x' }}
-      uses: eed3si9n/pandoc@master
-      with:
-        args: '--pdf-engine=xelatex --toc -s -o target/pamflet/sbt-reference.pdf target/pamflet/Combined+Pages+Pdf.md'
-
-    - name: Pandoc Japanese
-      if: ${{ github.event_name == 'push' && github.repository == 'sbt/website' && github.ref == 'refs/heads/1.x' }}
-      uses: eed3si9n/pandoc@master
-      with:
-        args: '--pdf-engine=xelatex -V CJKmainfont="Noto Sans JP" --toc -s -o target/pamflet/ja/sbt-reference.pdf target/pamflet/ja/Combined+Pages+Pdf.md'
-
-    - name: Pandoc Chinese
-      if: ${{ github.event_name == 'push' && github.repository == 'sbt/website' && github.ref == 'refs/heads/1.x' }}
-      uses: eed3si9n/pandoc@master
-      with:
-        args: '--pdf-engine=xelatex -V CJKmainfont="Noto Sans SC" --toc -s -o target/pamflet/zh-cn/sbt-reference.pdf target/pamflet/zh-cn/Combined+Pages+Pdf.md'
-
-    - name: Pandoc Spanish
-      if: ${{ github.event_name == 'push' && github.repository == 'sbt/website' && github.ref == 'refs/heads/1.x' }}
-      uses: eed3si9n/pandoc@master
-      with:
-        args: '--pdf-engine=xelatex --toc -s -o target/pamflet/es/sbt-reference.pdf target/pamflet/es/Combined+Pages+Pdf.md'
-
     # https://docs.github.com/en/free-pro-team@latest/actions/reference/encrypted-secrets
     - name: Deploy to GH Pages
       if: ${{ github.event_name == 'push' && github.repository == 'sbt/website' && (github.ref == 'refs/heads/develop' || github.ref == 'refs/heads/1.x' || github.ref == 'refs/heads/1.x-beta') }}

.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 book of sbt"
+
+[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,17 @@
+The book of sbt
+===============
+
+![sbt logo](files/sbt-logo.svg)
+
+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;
+}