Reformats the docs to improve readability

.github/workflows/deploy.yml

@@ -23,7 +23,7 @@ jobs:
       - name: Build Site
         run: |
           # Don't cache it to track updates.
-          pip install mkdocs-material
+          pip install mkdocs-material mdx_truly_sane_lists
           mkdocs build
       - uses: actions/upload-pages-artifact@v5
         with:

.github/workflows/links.yml

@@ -31,7 +31,7 @@ jobs:
       - name: Mkdocs build validation
         run: |
           # Don't cache it to track updates.
-          pip install mkdocs-material
+          pip install mkdocs-material mdx_truly_sane_lists
           mkdocs build --strict
       - uses: umbrelladocs/action-linkspector@v1
         with:

CONTRIBUTING.md

@@ -60,7 +60,7 @@ Shadow uses [Android Lint](https://developer.android.com/studio/write/lint) to c
 Shadow's user guide is built using [MkDocs Material](https://squidfunk.github.io/mkdocs-material/). You can build and
 preview the documentation website locally:
 
-- **Install MkDocs dependencies**: `pip install mkdocs mkdocs-material`
+- **Install MkDocs dependencies**: `pip install mkdocs-material mdx_truly_sane_lists`
 - **Preview documentation locally**: `mkdocs serve` (then navigate to `http://127.0.0.1:8000/`)
 - **Build the static site**: `mkdocs build`
 

README.md

@@ -10,13 +10,13 @@ with R8/ProGuard. The Gradle counterpart to Maven Shade Plugin.
 
 > [!NOTE]\
 > Previously this plugin was developed by [@johnrengelman](https://github.com/johnrengelman) and published under the
-> ID [`com.github.johnrengelman.shadow`][johnrengelman's]
-> 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).
+> ID [`com.github.johnrengelman.shadow`][johnrengelman's] 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`][gradleup's]
-> and update to the latest version to receive all the latest bug fixes and improvements.
+> 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`][gradleup's] and update to the latest version to receive all the latest bug fixes and
+> improvements.
 
 ## Documentation
 

docs/README.md

@@ -4,18 +4,18 @@
 
 # Introduction
 
-A Gradle plugin for creating fat/uber JARs, transforming files, relocating packages, and optimizing applications
-with R8/ProGuard. The Gradle counterpart to Maven Shade Plugin.
+A Gradle plugin for creating fat/uber JARs, transforming files, relocating packages, and optimizing applications with
+R8/ProGuard. The Gradle counterpart to Maven Shade Plugin.
 
 !!! warning "Plugin ID Change"
 
     Previously this plugin was developed by [@johnrengelman][johnrengelman] and published under the ID
     [`com.github.johnrengelman.shadow`][johnrengelman's] before maintenance was transferred to the
     [GradleUp organization][GradleUp] to ensure future development, see [#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`][gradleup's] and update to the latest version to receive all the latest bug fixes
-    and improvements.
+    [`com.gradleup.shadow`][gradleup's] and update to the latest version to receive all the latest bug fixes and
+    improvements.
 
 | Shadow Version | Min Gradle Version | Min Java Version | Plugin ID                                            |
 |----------------|--------------------|------------------|------------------------------------------------------|
@@ -37,34 +37,29 @@ Shadowing a project output has 2 major use cases:
 ### 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.
+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:
+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.
+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.
 
 
-
 [johnrengelman's]: https://plugins.gradle.org/plugin/com.github.johnrengelman.shadow
 [gradleup's]: https://plugins.gradle.org/plugin/com.gradleup.shadow
 [johnrengelman]: https://github.com/johnrengelman

docs/about/README.md

@@ -1,25 +1,21 @@
 # About This Project
 
 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 Shade Plugin was its ability to create application TARs and
-ZIPs.
+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 Shade Plugin was its ability to create application TARs and ZIPs.
 
-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.
+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.
 
 Starting with 0.9, Shadow was rewritten from the ground up as standard Gradle plugin and leveraged as much of Gradle's
-classes and concepts as possible.
-At the same time as the 0.9 release, Gradle was announcing the [Gradle Plugin Portal][gradle-plugin-portal] and
-so Shadow was published there.
+classes and concepts as possible. At the same time as the 0.9 release, Gradle was announcing
+the [Gradle Plugin Portal][gradle-plugin-portal] and so Shadow was published there.
 
 ## Maintainers
 
-* [John Engelman][john-engelman]
-* [Zongle Wang][zongle-wang]
+- [John Engelman][john-engelman]
+- [Zongle Wang][zongle-wang]
 
 ## Contributors
 
@@ -28,7 +24,6 @@ so Shadow was published there.
 </a>
 
 
-
 [gradle-plugin-portal]: https://plugins.gradle.org
 [john-engelman]: https://github.com/johnrengelman
 [zongle-wang]: https://github.com/Goooler

docs/android-plugins/README.md

@@ -4,5 +4,4 @@ Now you can bundle and publish multiple Android libraries as one with
 [Android Fused Library Plugin][android-fused-library-plugin], which is officially supported by Android.
 
 
-
 [android-fused-library-plugin]: https://developer.android.com/build/publish-library/fused-library

docs/application-plugin/README.md

@@ -3,9 +3,9 @@
 Shadow reacts to the presence of Gradle's [`application`][application] plugin and will automatically configure
 additional tasks for running the shadowed JAR and creating distributions containing the shadowed JAR.
 
-Just like the normal [`Jar`][Jar] task, when the [`application`][application] plugin is applied,
-the [`ShadowJar`][ShadowJar] manifest will be configured to contain the `Main-Class` attribute with the value specified
-in the project's `application.mainClass` attribute.
+Just like the normal [`Jar`][Jar] task, when the [`application`][application] plugin is applied, the
+[`ShadowJar`][ShadowJar] manifest will be configured to contain the `Main-Class` attribute with the value specified in
+the project's `application.mainClass` attribute.
 
 === "Kotlin"
 
@@ -35,10 +35,9 @@ in the project's `application.mainClass` attribute.
 
 ## Running the Shadow JAR
 
-When applied along with the `application` plugin, the `runShadow` task will be created for starting
-the application from the shadowed JAR.
-The `runShadow` task is a [`JavaExec`][JavaExec] task that is configured to execute `java -jar myproject-all.jar`.
-It can be configured the same as any other [`JavaExec`][JavaExec] task.
+When applied along with the `application` plugin, the `runShadow` task will be created for starting the application from
+the shadowed JAR. The `runShadow` task is a [`JavaExec`][JavaExec] task that is configured to execute
+`java -jar myproject-all.jar`. It can be configured the same as any other [`JavaExec`][JavaExec] task.
 
 === "Kotlin"
 
@@ -81,9 +80,8 @@ It can be configured the same as any other [`JavaExec`][JavaExec] task.
 ## Distributing the Shadow JAR
 
 The Shadow plugin will also configure distribution tasks when in the presence of the [`application`][application]
-plugin. The plugin will create `shadowDistZip` and `shadowDistTar` which creates Zip and Tar distributions
-respectively. Each distribution will contain the shadowed JAR file along with the necessary start scripts to launch
-the application.
+plugin. The plugin will create `shadowDistZip` and `shadowDistTar` which creates Zip and Tar distributions respectively.
+Each distribution will contain the shadowed JAR file along with the necessary start scripts to launch the application.
 
 Additionally, the plugin will create the `installShadowDist` and `startShadowScripts` tasks which stages the necessary
 files for a distribution to `build/install/<project name>-shadow/`.
@@ -169,7 +167,6 @@ You can also add more files into the distribution like:
 View [The Distribution Plugin][distribution-plugin] for more information about configuring distributions.
 
 
-
 [Jar]: https://docs.gradle.org/current/dsl/org.gradle.api.tasks.bundling.Jar.html
 [JavaExec]: https://docs.gradle.org/current/dsl/org.gradle.api.tasks.JavaExec.html
 [ShadowJar]: ../api/shadow/com.github.jengelman.gradle.plugins.shadow.tasks/-shadow-jar/index.html