Overhaul introductory section of docsite

docs/modules/ROOT/nav.adoc

@@ -3,15 +3,15 @@
 // but we intentionally skim over them and do not go into depth: the focus is
 // on end user goals and how to achieve them.
 .Scala Quick Start
-* xref:Intro_to_Mill_for_Scala.adoc[]
+* xref:Scala_Intro_to_Mill.adoc[]
 * xref:Scala_Installation_IDE_Support.adoc[]
-* xref:Builtin_Commands.adoc[]
+* xref:Scala_Builtin_Commands.adoc[]
 * xref:Scala_Build_Examples.adoc[]
 * xref:Scala_Module_Config.adoc[]
-* xref:Web_Build_Examples.adoc[]
+* xref:Scala_Web_Build_Examples.adoc[]
 
 .Java Quick Start
-* xref:Intro_to_Mill_for_Java.adoc[]
+* xref:Java_Intro_to_Mill.adoc[]
 * xref:Java_Installation_IDE_Support.adoc[]
 * xref:Java_Builtin_Commands.adoc[]
 * xref:Java_Build_Examples.adoc[]

docs/modules/ROOT/pages/Extending_Mill.adoc

@@ -84,8 +84,8 @@ def idea(ev: Evaluator) = T.command {
 ----
 
 Many built-in tools are implemented as custom evaluator commands:
-xref:Builtin_Commands.adoc#_inspect[inspect],
-xref:Builtin_Commands.adoc#_resolve[resolve],
-xref:Builtin_Commands.adoc#_show[show].
+xref:Scala_Builtin_Commands.adoc#_inspect[inspect],
+xref:Scala_Builtin_Commands.adoc#_resolve[resolve],
+xref:Scala_Builtin_Commands.adoc#_show[show].
 If you want a way to run Mill commands and programmatically manipulate the
 tasks and outputs, you do so with your own evaluator command.

docs/modules/ROOT/pages/Java_Intro_to_Mill.adoc

@@ -0,0 +1,86 @@
+
+// Author Notes:
+//
+// This is the first page a user is expected to land on when learning about
+// Mill. It is designed to be a quick, broad overview to get someone started:
+// what is Mill, why should they care, and what some simple Mill builds look
+// like and how to use them. We intentionally touch shallowly on a lot of
+// topics without giving them a proper discussion, since the other pages have
+// plenty of space to go in-depth.
+//
+// By the end of this page, a prospective Mill user should be familiar with
+// what Mill is, hopefully have downloaded an example to try out, and be
+// interested in learning more about the Mill build tool
+
+= Introduction to Mill for Java
+
+:page-aliases: index.adoc, Intro_to_Mill.adoc, Intro_to_Mill_for_Java.adoc
+
+:language: Java
+
+include::partial$Intro_to_Mill_Header.adoc[]
+
+Mill is used to build some real-world Java projects, such as the
+https://github.com/swaldman/c3p0[C3P0 JDBC Connection Pool], and
+can be used for applications built on top of common Java frameworks like
+xref:Java_Web_Build_Examples.adoc#_spring_boot_todomvc_app[Spring Boot] or
+xref:Java_Web_Build_Examples.adoc#_micronaut_todomvc_app[Micronaut].
+
+Mill borrows ideas from other tools like https://maven.apache.org/[Maven],
+https://gradle.org/[Gradle], https://bazel.build/[Bazel], but tries to learn from the
+strengths of each tool and improve on their weaknesses. Although Maven and Gradle
+are mature widely-used tools, they have fundamental limitations in their design
+(https://blog.ltgt.net/maven-is-broken-by-design/[Maven Design],
+https://www.bruceeckel.com/2021/01/02/the-problem-with-gradle/[Gradle Design]) that make
+them difficult to improve upon incrementally.
+
+Compared to Maven:
+
+* **Mill follows Maven's innovation of good built-in defaults**: Mill's built-in
+  ``JavaModule``s follow Maven's "convention over configuration" style. This provides an
+  excellent default template that can be used to structure your project without any custom
+  configuration.
+
+* **Mill makes customizing the build tool much easier than Maven**. As projects grow, build
+  grow beyond just compiling a single language: you need custom
+  code generation, custom linting workflows, custom output artifacts, or support for
+  additional programming languages. Mill makes doing this yourself easy, so you are not beholden
+  to third-party plugins that may not exist, be well maintained, or interact well with each other.
+
+* **Mill automatically caches and parallelizes your build**: This applies not just to the
+  built-in ``JavaModule``s and tasks that Mill ships with, but also any custom logic the
+  developer may configure in their Mill build. This maximizes performance and snappiness of
+  your command-line build workflows, and especially matters in larger codebases where builds
+  tend to get slow.
+
+Compared to Gradle:
+
+* **Mill follows Gradle's conciseness**: Rather than pages and pages of verbose XML, every
+  line of configuration in a Mill build is meaningful. e.g. adding a dependency is 1 line in
+  Mill, like it is in Gradle, and unlike the 5 line `<dependency>` declaration you find in Maven
+
+* **Mill helps keep your build understandable**: Unlike Gradle config statements that can
+  work in mysterious ways, Mill build configuration is done via vanilla methods, objects,
+  inheritance, and overrides. This means that impact of a Mill config statement is localized,
+  without "_spooky action at a distance_", and the exact meaning of any config statement is
+  a single "_jump-to-definition_" away in your IDE.
+
+Mill build files are written in Scala, but you do not need to have prior experience
+in Scala to read or write them.
+
+
+include::partial$Intro_to_Mill_BlogVideo.adoc[]
+
+== Simple Java Module
+
+include::example/basicjava/1-simple.adoc[]
+
+== Custom Build Logic
+
+include::example/basicjava/2-custom-build-logic.adoc[]
+
+== Multi-Module Project
+
+include::example/basicjava/3-multi-module.adoc[]
+
+include::partial$Intro_to_Mill_Footer.adoc[]

docs/modules/ROOT/pages/Out_Dir.adoc

@@ -90,7 +90,7 @@ feel free to poke around the various
 `foo.dest/` folders to see what files are being created, or the `foo.json` files to see what is being returned by a
 particular task.
 You can also simply delete folders within `out/` if you want to force portions of your project to be
-rebuilt, e.g. by deleting the `+out/main/+` or `+out/main/compile.*+` folders, but we strongly encourage you to use the xref:Builtin_Commands.adoc#_clean[`clean` command] instead.
+rebuilt, e.g. by deleting the `+out/main/+` or `+out/main/compile.*+` folders, but we strongly encourage you to use the xref:Scala_Builtin_Commands.adoc#_clean[`clean` command] instead.
 
 [WARNING]
 --

docs/modules/ROOT/pages/Builtin_Commands.adoc → docs/modules/ROOT/pages/Scala_Builtin_Commands.adoc

@@ -1,5 +1,7 @@
 = Built-in Commands
 
+:page-aliases: Scala_Builtin_Commands.adoc
+
 Mill comes with a number of useful commands out of the box. These are listed
 in the Scaladoc:
 

docs/modules/ROOT/pages/Scala_Intro_to_Mill.adoc

@@ -0,0 +1,79 @@
+// Author Notes:
+//
+// This is the first page a user is expected to land on when learning about
+// Mill. It is designed to be a quick, broad overview to get someone started:
+// what is Mill, why should they care, and what some simple Mill builds look
+// like and how to use them. We intentionally touch shallowly on a lot of
+// topics without giving them a proper discussion, since the other pages have
+// plenty of space to go in-depth.
+//
+// By the end of this page, a prospective Mill user should be familiar with
+// what Mill is, hopefully have downloaded an example to try out, and be
+// interested in learning more about the Mill build tool
+
+= Introduction to Mill for Scala
+
+:page-aliases: index.adoc, Intro_to_Mill.adoc, Intro_to_Mill_for_Scala.adoc
+
+:language: Scala
+
+include::partial$Intro_to_Mill_Header.adoc[]
+
+Mill is used to build many mainstream Scala projects, such as the
+https://github.com/coursier/coursier[Coursier dependency resolver],
+https://github.com/VirtusLab/scala-cli[Scala-CLI], and the
+https://github.com/com-lihaoyi/Ammonite[Ammonite REPL]
+
+Mill borrows ideas from other tools like https://maven.apache.org/[Maven],
+https://gradle.org/[Gradle], https://bazel.build/[Bazel], or https://www.scala-sbt.org/[SBT].
+It tries to learn from the strengths of each tool, while improving on their weaknesses.
+
+Compared to SBT:
+
+* **Mill makes customizing the build yourself much easier**: most of what build tools
+  do work with files and call subprocesses, and Mill makes doing that yourself easy.
+  This means you can always make your Mill build do exactly what you want, and are not
+  beholden to third-party plugins that may not exist, be well maintained, or interact well
+  with each other.
+
+* **Mill is much more performant**: SBT has enough overhead that even a dozen
+  subprojects is enough to slow it down, while Mill can handle hundreds of modules without issue.
+  Custom tasks in SBT re-execute every time, whereas in Mill they are cached automatically.
+  Mill's watch-for-changes-and-re-run implementation has much lower latency than SBT's. The
+  list of ways Mill improves upon SBT's performance is long, and at the command line you
+  can really feel it
+
+* **Mill builds are much easier to understand**: Your Mill build is made of bog-standard
+  ``object``s and ``def``s, rather than SBT's
+  https://eed3si9n.com/4th-dimension-with-sbt-013/[four-dimensional task matrix]. Your IDE's
+  "*jump-to-definition*" in Mill actually brings you to the implementation of a task, rather
+  than an SBT `taskKey` declaration. Customizing things is as simple as writing or overriding
+  `def`s. The net effect is that despite both tools' build files being written in Scala,
+  Mill's build files are much easier to understand and maintain.
+
+For a more detailed dive into the problems with SBT or how Mill improves upon them, check
+out the following blog posts:
+
+- https://www.lihaoyi.com/post/SowhatswrongwithSBT.html[So, what's wrong with SBT?]
+- https://www.lihaoyi.com/post/MillBetterScalaBuilds.html[Mill: Better Scala Builds]
+
+include::partial$Intro_to_Mill_BlogVideo.adoc[]
+
+If you are using Mill, you will find the following book by the Author useful in
+using Mill and its supporting libraries to the fullest:
+
+* https://handsonscala.com/[Hands-on Scala Programming]
+
+== Simple Scala Module
+
+include::example/basic/1-simple.adoc[]
+
+== Custom Build Logic
+
+include::example/basic/2-custom-build-logic.adoc[]
+
+== Multi-Module Project
+
+include::example/basic/3-multi-module.adoc[]
+
+include::partial$Intro_to_Mill_Footer.adoc[]

docs/modules/ROOT/pages/Web_Build_Examples.adoc → docs/modules/ROOT/pages/Scala_Web_Build_Examples.adoc

@@ -1,5 +1,7 @@
 = Scala Web Build Examples
 
+:page-aliases: Web_Build_Examples.adoc
+
 This page contains examples of using Mill as a build tool for web-applications.
 It covers setting up a basic backend server, Todo-MVC app, topics like cache
 busting, as well as usage of Scala.js both as standalone modules as well as

docs/modules/ROOT/pages/The_Mill_Evaluation_Model.adoc

@@ -38,8 +38,8 @@ of. In general, we have found that having "two places" to put code - outside of
 
 The hard boundary between these two phases is what lets users easily query
 and visualize their module hierarchy and task graph without running them: using
-xref:Builtin_Commands.adoc#inspect[inspect], xref:Builtin_Commands.adoc#plan[plan],
-xref:Builtin_Commands.adoc#_visualize[visualize], etc.. This helps keep your
+xref:Scala_Builtin_Commands.adoc#inspect[inspect], xref:Scala_Builtin_Commands.adoc#plan[plan],
+xref:Scala_Builtin_Commands.adoc#_visualize[visualize], etc.. This helps keep your
 Mill build discoverable even as the `build.sc` codebase grows.
 
 == Caching at Each Layer of the Evaluation Model

docs/modules/ROOT/partials/Intro_to_Mill_BlogVideo.adoc

@@ -0,0 +1,14 @@
+
+If you're interested in the fundamental ideas behind Mill, rather than the user-facing
+benefits discussed above, the following presentation
+and companion blog post is a good introduction into what the Mill build tool is
+all about:
+
+- https://www.youtube.com/watch?v=UsXgCeU-ovI&list=PLLMLOC3WM2r6ZFhFfVH74W-sl8LfWtOEc&index=15[Video: A Deep Dive into the Mill Build Tool]
+- https://www.lihaoyi.com/post/SoWhatsSoSpecialAboutTheMillScalaBuildTool.html[Blog Post: What's So Special About The Mill Scala Build Tool?]
+
+The rest of this page contains a quick introduction to getting start with using
+Mill to build a simple {language} program. The other pages of this doc-site go into
+more depth, with more examples of how to use Mill and more details of how the
+Mill build tool works.
+