Reorganize doc navigations (#1340)

* Remove "Shadowing Gradle Plugins"

* Update "Default Java/Kotlin/Groovy Tasks"

* Update Gradle Plugins nav

* Update docs/getting-started/README.md

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

* Merge introductions

* Move introduction/README.md out

* Compat image for GMF

* Note "I"

* Add myself into "Maintainers"

---------

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

Author: Goooler

docs/README.md

@@ -1,16 +1,59 @@
 <div style="text-align: center;">
-  <img src="images/logo.svg" alt="Shadow Gradle Plugin" style="max-width: 300px; height: auto;">
+  <img src="images/logo.svg" alt="Shadow Gradle Plugin" width="300"/>
   <h1><strong>Shadow Gradle Plugin</strong></h1>
-  <p><em>The library author's dependency toolkit</em></p>
 </div>
 
----
+# Introduction
 
-Previously this plugin was developed by [@johnrengelman](https://github.com/johnrengelman) and published under the ID [
-`com.github.johnrengelman.shadow`](https://plugins.gradle.org/plugin/com.github.johnrengelman.shadow)
-before maintenance was transferred to the [GradleUp organization](https://github.com/GradleUp) to ensure future
-development, see [#908](https://github.com/GradleUp/shadow/issues/908).
+Shadow is a Gradle plugin for combining a project's dependency classes and resources into a single
+output Jar.
+The combined Jar is often referred to a _fat-jar_ or _uber-jar_.
+Shadow utilizes [`JarInputStream`](https://docs.oracle.com/javase/8/docs/api/java/util/jar/JarInputStream.html) and [`JarOutputStream`](https://docs.oracle.com/javase/8/docs/api/java/util/jar/JarOutputStream.html) to efficiently process dependent libraries
+into the output jar without incurring the I/O overhead of expanding the jars to disk.
 
-If you are still using the old plugin ID in your build script, we recommend to switch to the new plugin ID [
-`com.gradleup.shadow`](https://plugins.gradle.org/plugin/com.gradleup.shadow)
-and update to the latest version to receive all the latest bug fixes and improvements.
+!!! warning "Plugin ID Change"
+
+    Previously this plugin was developed by [@johnrengelman](https://github.com/johnrengelman) and published under the ID [
+    `com.github.johnrengelman.shadow`](https://plugins.gradle.org/plugin/com.github.johnrengelman.shadow)
+    before maintenance was transferred to the [GradleUp organization](https://github.com/GradleUp) to ensure future
+    development, see [#908](https://github.com/GradleUp/shadow/issues/908).
+    
+    If you are still using the old plugin ID in your build script, we recommend to switch to the new plugin ID [
+    `com.gradleup.shadow`](https://plugins.gradle.org/plugin/com.gradleup.shadow)
+    and update to the latest version to receive all the latest bug fixes and improvements.
+
+## Benefits of Shadow
+
+Shadowing a project output has 2 major use cases:
+
+1. Creating an _executable_ JAR distribution
+2. Bundling and relocating common dependencies in libraries to avoid classpath conflicts
+
+### Executable Distributions
+
+Executable distribution is the main use case for deploying an _application_ that can be executed/run in the runtime
+environment.
+In the case of Shadow, this is a single _uber_ or _fat_ JAR.
+The JAR file contains all the application code and dependent libraries to execute (not including the standard JVM
+libraries).
+The shadow JAR does **not** include the JRE itself.
+It must be available on the target system.
+
+Executable JARs contain a JAR MANIFEST that specifies the application Main Class.
+This allows the application to be started with a single command:
+
+```shell
+java -jar application-shadow.jar
+```
+
+### Library Bundling
+
+Dependency bundling and relocation is the main use case for _library_ authors.
+The goal of a bundled library is to create a pre-packaged dependency for other libraries or applications to utilize.
+Often in these scenarios, a library may contain a dependency that a downstream library or application also uses.
+In _some_ cases, different versions of this common dependency can cause an issue in either the upstream library or
+the downstream application.
+These issues often manifest themselves as binary incompatibilities in either the library or application code.
+
+By utilizing Shadow's ability to _relocate_ the package names for dependencies, a library author can ensure that the
+library's dependencies will not conflict with the same dependency being declared by the downstream application.

docs/about/README.md

@@ -1,13 +1,13 @@
 # About This Project
 
-I started this project in December 2012. We were working on converting from a monolithic application into the
+I (John Engelman) started this project in December 2012. We were working on converting from a monolithic application into the
 new hot jazz of "microservices" using Dropwizard.
 I had also just started learning about Gradle and I knew that the incremental build system it provided would benefit
 our development team greatly.
 Unfortunately, the closest thing that Gradle had to Maven's Shade plugin was its ability to create application TARs and
 ZIPs.
 
-So, Charlie Knudsen and I (John Engelman) set out to port the existing Shade code into a Gradle plugin.
+So, Charlie Knudsen and I set out to port the existing Shade code into a Gradle plugin.
 This port is what existed up until the `0.9` milestone releases for Shadow.
 It functioned, but it wasn't idiomatic Gradle by any means.
 
@@ -19,6 +19,7 @@ so Shadow was published there.
 ## Maintainers
 
 * [John Engelman](https://github.com/johnrengelman)
+* [Goooler](https://github.com/Goooler)
 
 ## Contributors
 

docs/getting-started/README.md

@@ -116,13 +116,16 @@ Instead, Shadow _reacts_
 This means, that for most users, the `java` or `groovy` plugins must be _explicitly_ applied
 to have the desired effect.
 
-## Default Java/Groovy Tasks
+## Default Java/Kotlin/Groovy Tasks
 
-In the presence of the `java` or `groovy` plugins, Shadow will automatically configure the
-following behavior:
+In the presence of the `java`, `org.jetbrains.kotlin.jvm` or `groovy` plugins
+(that apply [JavaPlugin](https://docs.gradle.org/current/userguide/java_plugin.html) in their build logic),
+Shadow will automatically configure the following behavior:
 
 * Adds a `shadowJar` task to the project.
 * Adds a `shadow` configuration to the project.
+* Adds a `shadow` variant to the project.
+* Adds a `shadow` component to the project.
 * Configures the `shadowJar` task to include all sources from the project's `main` sourceSet.
 * Configures the `shadowJar` task to bundle all dependencies from the `runtimeClasspath` configuration.
 * Configures the _classifier_ attribute of the `shadowJar` task to be `'all'` .
@@ -137,10 +140,3 @@ following behavior:
     * `META-INF/versions/**/module-info.class`
     * `module-info.class`
 * Creates and registers the `shadow` component in the project (used for integrating with `maven-publish`).
-
-## Shadowing Gradle Plugins
-
-Shadow ships with a companion task that can be used to automatically discover dependency packages and configure 
-them for relocation. This is useful in projects if you want to relocate all dependencies.
-
-For more details see the section [Using Shadow to Package Gradle Plugins](../plugins/README.md)

docs/plugins/README.md docs/gradle-plugins/README.md

@@ -40,7 +40,7 @@ Shadow works well for Kotlin JVM projects like Java projects. Here is an example
     ```
 
 You can mix the Kotlin JVM plugin with `java-gradle-plugin`, `application`, and other Java plugins,
-easily organize your build logic for [Packaging Gradle Plugins](../plugins/README.md), [Publishing Libraries](../publishing/README.md),
+easily organize your build logic for [Packaging Gradle Plugins](../gradle-plugins/README.md), [Publishing Libraries](../publishing/README.md),
 [Running Applications](../application-plugin/README.md), and so on.
 
 ## For Kotlin Multiplatform Plugin

docs/introduction/README.md

@@ -57,8 +57,7 @@ markdown_extensions:
   - md_in_html
 
 nav:
-  - 'Home': README.md
-  - 'Introduction': introduction/README.md
+  - 'Introduction': README.md
   - 'Getting Started': getting-started/README.md
   - 'Configuration':
       - 'Overview': configuration/README.md
@@ -74,7 +73,7 @@ nav:
   - 'Groovy and Scala Plugins': groovy-and-scala-plugins/README.md
   - 'Publishing': publishing/README.md
   - 'Multi-Project': multi-project/README.md
-  - 'Plugins': plugins/README.md
+  - 'Gradle Plugins': gradle-plugins/README.md
   - 'Changes': changes/README.md
   - 'API': api/index.html
   - 'About': about/README.md