Overhaul docsite landing page

docs/modules/ROOT/nav.adoc

@@ -3,6 +3,8 @@
 // but we intentionally skim over them and do not go into depth: the focus is
 // on end user goals and how to achieve them.
 
+.xref:index.adoc[]
+
 .xref:javalib/intro.adoc[]
 * xref:javalib/installation-ide.adoc[]
 * xref:javalib/builtin-commands.adoc[]

docs/modules/ROOT/pages/comparisons/gradle.adoc

@@ -3,6 +3,30 @@
 
 include::partial$gtag-config.adoc[]
 
+Compared to Gradle,
+
+
+* **Mill follows Gradle's conciseness and extensibility**: Rather than pages and pages of verbose XML, every
+line 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.
+Like Gradle, end users can easily customize their build to fit their exact needs without
+needing to go through the process of writing plugins.
+
+* **Mill can be xref:comparisons/gradle.adoc#_performance[2-3x faster than Gradle]**:
+Although both Mill and Gradle automatically cache and parallelize your build, Mill
+does so with much less fixed overhead. This means less time waiting for your build
+tool, and more time for the things that really matter to your project.
+
+* **Mill enforces best practices by default**.
+xref:depth/evaluation-model.adoc#_caching_at_each_layer_of_the_evaluation_model[All parts of a Mill build are cached and incremental by default].
+All Mill tasks write their output to xref:fundamentals/out-dir.adoc[a standard place].
+All task inter-dependencies are automatically captured without manual annotation. Where Gradle requires
+considerable effort and expertise to understand your build and set it up in the right way, Mill's
+xref:comparisons/gradle.adoc#_ide_experience[good IDE experience] makes understanding
+your build easier, and its xref:comparisons/gradle.adoc#_extensibility[extensibility model]
+makes configuring your build foolproof, so the easiest thing to do in Mill is usually the
+right thing to do.
+
 This page compares using Mill to Gradle, using the https://github.com/mockito/mockito[Mockito Testing Library]
 codebase as the example. Mockito is a medium sized codebase, 100,000 lines of Java split over 22
 subprojects. By porting it to Mill, this case study should give you

docs/modules/ROOT/pages/comparisons/maven.adoc

@@ -3,6 +3,29 @@
 
 include::partial$gtag-config.adoc[]
 
+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, so small Mill
+projects require minimal effort to get started, and larger Mill projects have a consistent
+structure building on these defaults.
+
+* **Mill automatically caches and parallelizes your build, offering 3-10x speedups**:
+Not just the built-in tasks that Mill ships with, but also any custom tasks or modules.
+This maximizes the snappiness of your command-line build workflows to keep you productive,
+which especially matters in larger codebases where builds tend to get slow:
+xref:comparisons/maven.adoc#_performance[a Maven "clean install" workflow
+  taking over a minute might take just a few seconds in Mill].
+
+* **Mill makes customizing the build tool much easier than Maven**. Projects usually
+grow beyond just compiling a single language: needing custom
+code generation, linting workflows, tool integrations, output artifacts, or support for
+additional languages. Mill's xref:comparisons/maven.adoc#_extensibility_ide_experience[extensibility and IDE experience]
+makes doing this yourself easy and safe, with type-checked code and
+xref:depth/sandboxing.adoc[sandboxed tasks]
+
+
 This page compares using Mill to Maven, using the https://github.com/netty/netty[Netty Network Server]
 codebase as the example. Netty is a large, old codebase. 500,000 lines of Java, written by
 over 100 contributors across 15 years, split over 47 subprojects, with over 10,000 lines of

docs/modules/ROOT/pages/comparisons/sbt.adoc

@@ -3,6 +3,29 @@
 
 include::partial$gtag-config.adoc[]
 
+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 meet your exact needs 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.
+
 This page compares using Mill to SBT, using the https://github.com/gatling/gatling[Gatling Load Testing Framework]
 codebase as the example. Gatling is a medium sized codebase, 40,000 lines of Scala split over 21
 subprojects. By porting it to Mill, this case study should give you an idea of how Mill compares

docs/modules/ROOT/pages/index.adoc

@@ -0,0 +1,97 @@
+= Mill: A Blazing Fast JVM Build Tool
+
+```graphviz
+digraph G {
+  rankdir=LR
+  node [shape=box width=0 height=0 style=filled fillcolor=white]
+  bgcolor=transparent
+  newrank=true;
+  subgraph cluster_0 {
+    style=dashed
+    node [shape=box width=0 height=0 style=filled fillcolor=white]
+    label = "foo";
+
+    "foo.sources" -> "foo.compile" -> "foo.classPath" -> "foo.assembly"
+    "foo.resources" -> "foo.assembly"
+    "foo.classPath"
+  }
+  subgraph cluster_1 {
+    style=dashed
+    node [shape=box width=0 height=0 style=filled fillcolor=white]
+    label = "bar";
+
+    "foo.classPath" -> "bar.compile" [constraint=false]
+    "foo.classPath" -> "bar.classPath"
+    "bar.sources" -> "bar.compile" -> "bar.classPath" -> "bar.assembly"
+    "bar.resources" -> "bar.assembly"
+  }
+}
+```
+
+Mill is a fast, scalable, multi-language build tool that supports Java, Scala,
+and Kotlin. Although the Java compiler is fast and the Java language is easy,
+JVM build tools have a reputation for being sluggish and confusing. Mill lets
+your build system take full advantage of the JVM's performance and usability:
+
+* Mill can build the same Java codebase xref:comparisons/maven.adoc[5-10x faster than Maven],
+or xref:comparisons/gradle.adoc[2-4x faster than Gradle]
+
+* Mill's typed config language and immutable xref:depth/design-principles.adoc[task graph]
+helps keep builds clean and understandable
+
+* Mill scales well from small single-module projects
+to xref:depth/large-builds.adoc[large monorepos] with hundreds of modules
+
+Mill achieves this via the following:
+
+* *Performance*: Mill's xref:fundamentals/tasks.adoc[build graph] automatically
+xref:depth/evaluation-model.adoc#_caching_at_each_layer_of_the_evaluation_model[caches]
+and xref:javalib/intro.adoc#_parallel_task_execution[parallelizes] build
+tasks, keeping your workflows fast and responsive. Mill adds minimal overhead over
+the logic necessary to build your project, while providing tools to let you identify
+and resolve bottlenecks in your build
+
+* *Maintainability*: Mill goes beyond YAML and Bash, with config and custom logic written in
+xref:javalib/intro.adoc#_custom_build_logic[concise type-checked code],
+and an immutable xref:depth/design-principles.adoc[module tree and task graph]. This
+catches config issues early, and helps IDEs
+(xref:javalib/installation-ide.adoc#_intellij[IntelliJ] or
+xref:javalib/installation-ide.adoc#_vscode[VSCode])
+understand your Mill build better than any other build system
+
+* *Flexibility*: Mill's tasks and modules allow anything from adding
+xref:fundamentals/tasks.adoc#primitive-tasks[simple build steps], up to
+entire xref:extending/new-language.adoc[language toolchains].
+You can xref:extending/import-ivy-plugins.adoc[import any JVM library] in your build,
+use Mill's rich ecosystem of xref:extending/thirdparty-plugins.adoc[Third-Party Mill Plugins],
+or xref:extending/writing-plugins.adoc[write plugins] yourself and
+xref:extending/writing-plugins.adoc#_publishing[publish them] to Maven Central for others to use.
+
+To begin using Mill, check out the introductory documentation for each language:
+
+* xref:javalib/intro.adoc[]
+* xref:scalalib/intro.adoc[]
+* xref:kotlinlib/intro.adoc[]
+
+
+Mill is used to build many real-world projects, such as the
+https://github.com/swaldman/c3p0[C3P0 JDBC Connection Pool],
+https://github.com/coursier/coursier[Coursier JVM dependency resolver],
+https://github.com/com-lihaoyi/Ammonite[Ammonite REPL], and the
+https://github.com/SpinalHDL/SpinalHDL[SpinalHDL] and
+https://github.com/chipsalliance/chisel[Chisel] hardware design frameworks.
+Mill can be used for applications built on top of common JVM frameworks like
+xref:javalib/web-examples.adoc#_spring_boot_todomvc_app[Spring Boot] or
+xref:javalib/web-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. For comparisons with existing
+build tools, check out these pages:
+
+* xref:comparisons/maven.adoc[Mill vs Maven]
+* xref:comparisons/gradle.adoc[Mill vs Gradle]
+* xref:comparisons/gradle.adoc[Mill vs SBT]
+
+If you're interested in the fundamental ideas behind Mill, rather than the user-facing
+benefits discussed above, check out the page on xref:depth/design-principles.adoc[Mill Design Principles].

docs/modules/ROOT/pages/javalib/intro.adoc

@@ -13,27 +13,15 @@
 // interested in learning more about the Mill build tool
 
 = Building Java Projects with Mill
-:page-aliases: index.adoc, Intro_to_Mill.adoc, Intro_to_Mill_for_Java.adoc, Java_Intro_to_Mill.adoc
+:page-aliases: Intro_to_Mill.adoc, Intro_to_Mill_for_Java.adoc, Java_Intro_to_Mill.adoc
 
 include::partial$gtag-config.adoc[]
 
 
 :language: Java
 :language-small: 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:javalib/web-examples.adoc#_spring_boot_todomvc_app[Spring Boot] or
-xref:javalib/web-examples.adoc#_micronaut_todomvc_app[Micronaut].
-
-include::partial$Intro_Maven_Gradle_Comparison.adoc[]
-
-include::partial$Intro_to_Mill_BlogVideo.adoc[]
-
-
+include::partial$Intro_Header.adoc[]
 
 == Simple Java Module
 

docs/modules/ROOT/pages/kotlinlib/intro.adoc

@@ -19,26 +19,15 @@ include::partial$gtag-config.adoc[]
 
 :language: Kotlin
 :language-small: kotlin
-:language-ext: kt
+
+include::partial$Intro_Header.adoc[]
 
 NOTE: *Kotlin support in Mill is experimental*! A lot of stuff works, which is
 documented under this section, but a lot of stuff doesn't. In particular,
 support for Android, KotlinJS and Kotlin-Multi-Platform is still in its infancy.
 The API is not yet stable and may evolve. Try it out but please be aware of its
 limitations!
 
-
-include::partial$Intro_to_Mill_Header.adoc[]
-
-
-include::partial$Intro_Maven_Gradle_Comparison.adoc[]
-
-Mill's Kotlin support originated as the third-party plugin
-https://github.com/lefou/mill-kotlin[lefou/mill-kotlin], which was later included with
-the main Mill codebase under its https://github.com/lefou/mill-kotlin/blob/main/LICENSE[Apache 2.0 License].
-
-include::partial$Intro_to_Mill_BlogVideo.adoc[]
-
 == Simple Kotlin Module
 
 include::partial$example/kotlinlib/basic/1-simple.adoc[]
@@ -56,3 +45,10 @@ include::partial$Intro_to_Mill_Footer.adoc[]
 == Maven-Compatible Modules
 
 include::partial$example/kotlinlib/basic/4-compat-modules.adoc[]
+
+== History
+
+Mill's Kotlin support originated as the third-party plugin
+https://github.com/lefou/mill-kotlin[lefou/mill-kotlin], which was later included with
+the main Mill codebase under its
+https://github.com/lefou/mill-kotlin/blob/main/LICENSE[Apache 2.0 License].

docs/modules/ROOT/pages/scalalib/intro.adoc

@@ -18,56 +18,8 @@ include::partial$gtag-config.adoc[]
 
 :language: Scala
 :language-small: scala
-:language-ext: 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], the
-https://github.com/com-lihaoyi/Ammonite[Ammonite REPL], and the
-https://github.com/SpinalHDL/SpinalHDL[SpinalHDL] and
-https://github.com/chipsalliance/chisel[Chisel] hardware design frameworks.
-
-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 meet your exact needs 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]
+include::partial$Intro_Header.adoc[]
 
 == Simple Scala Module
 

docs/modules/ROOT/partials/Intro_Header.adoc

@@ -0,0 +1,4 @@
+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.