From 24f4424f1d3f87ab6dfc9a36d3372f6b117537d3 Mon Sep 17 00:00:00 2001 From: Goooler Date: Mon, 10 Aug 2026 17:01:49 +0800 Subject: [PATCH 1/2] Use MkDocs admonition syntax for notes, warnings, and tips --- docs/changes/README.md | 6 ++-- docs/configuration/README.md | 5 +-- docs/configuration/dependencies/README.md | 21 ++++++++----- docs/configuration/merging/README.md | 38 ++++++++++++++--------- docs/configuration/minimizing/README.md | 12 ++++--- docs/configuration/relocation/README.md | 27 ++++++++++------ docs/getting-started/README.md | 6 ++-- 7 files changed, 72 insertions(+), 43 deletions(-) diff --git a/docs/changes/README.md b/docs/changes/README.md index 7fa1d570e..ac7b2015a 100644 --- a/docs/changes/README.md +++ b/docs/changes/README.md @@ -656,8 +656,10 @@ See more details about the fixed `DuplicatesStrategy` behaviors at [Handling Dup ## [8.1.1](https://github.com/GradleUp/shadow/releases/tag/8.1.1) - 2023-03-20 -**NOTE:** As of this version, the GitHub repository has migrated to the `main` branch as the default branch for -releases. +!!! note + + As of this version, the GitHub repository has migrated to the `main` branch as the default branch for + releases. ### What's Changed diff --git a/docs/configuration/README.md b/docs/configuration/README.md index 06770b18e..a8577f557 100644 --- a/docs/configuration/README.md +++ b/docs/configuration/README.md @@ -86,8 +86,9 @@ Inspecting the `META-INF/MANIFEST.MF` entry in the JAR file will reveal the foll Class-Path: junit-3.8.2.jar ``` -When deploying a shadowed JAR as an execution JAR, it is important to note that any non-bundled runtime dependencies -**must** be deployed in the location specified in the `Class-Path` entry in the manifest. +!!! important + + When deploying a shadowed JAR as an execution JAR, any non-bundled runtime dependencies **must** be deployed in the location specified in the `Class-Path` entry in the manifest. ## Configuring the JAR Manifest diff --git a/docs/configuration/dependencies/README.md b/docs/configuration/dependencies/README.md index b7a87f6b3..14ae61bdd 100644 --- a/docs/configuration/dependencies/README.md +++ b/docs/configuration/dependencies/README.md @@ -25,11 +25,14 @@ The above code sample would configure the [`ShadowJar`][ShadowJar] task to merge `compileClasspath` configuration. This means any dependency declared in the `runtimeOnly` configuration would be **not** be included in the final JAR. -> Note the literal use of [`project.configurations`][Project.configurations] when setting the -> [`configurations`][ShadowJar.configurations] attribute of a [`ShadowJar`][ShadowJar] task. -> This is **required**. It may be tempting to specify `configurations = [configurations.compileClasspath]` but this will -> not have the intended effect, as `configurations.compile` will try to delegate to the -> [`configurations`][ShadowJar.configurations] property of the [`ShadowJar`][ShadowJar] task instead of the `project` +!!! warning "Required Configuration" + + Note the literal use of [`project.configurations`][Project.configurations] when setting the + [`configurations`][ShadowJar.configurations] attribute of a [`ShadowJar`][ShadowJar] task. + + This is **required**. It may be tempting to specify `configurations = [configurations.compileClasspath]` but this will + not have the intended effect, as `configurations.compile` will try to delegate to the + [`configurations`][ShadowJar.configurations] property of the [`ShadowJar`][ShadowJar] task instead of the `project`. ## Embedding Local Jar Files into Your Shadowed JAR @@ -262,9 +265,11 @@ Gradle's [`project.configurations`][Project.configurations] block. } ``` -> While not being able to filter entire transitive dependency graphs might seem like an oversight, it is necessary -> because it would not be possible to intelligently determine the build author's intended results when there is a -> common dependency between two 1st level dependencies when one is excluded and the other is not. +!!! note + + While not being able to filter entire transitive dependency graphs might seem like an oversight, it is necessary + because it would not be possible to intelligently determine the build author's intended results when there is a + common dependency between two 1st level dependencies when one is excluded and the other is not. ### Using Regex Patterns to Filter Dependencies diff --git a/docs/configuration/merging/README.md b/docs/configuration/merging/README.md index 6fb7b2fb3..b28ff3f59 100644 --- a/docs/configuration/merging/README.md +++ b/docs/configuration/merging/README.md @@ -6,13 +6,15 @@ Maven Shade implementation. A [`ResourceTransformer`][ResourceTransformer] is in being written to the final output JAR. This allows a [`ResourceTransformer`][ResourceTransformer] to determine if it should process a particular entry and apply any modifications before writing the stream to the output. -**Important**: [`ResourceTransformer`][ResourceTransformer] follows a guaranteed processing order: +!!! important "Guaranteed Processing Order" -1. **Project files first**: All files in projects are processed before any dependency files. -2. **Dependency files second**: Files from configurations (runtime dependencies) or added via [`ShadowJar.from`][ShadowJar.from] are processed after project files. + [`ResourceTransformer`][ResourceTransformer] follows a guaranteed processing order: -This ordering is crucial when merging configuration files where you want to preserve project-specific values while -merging in additional data from dependencies. + 1. **Project files first**: All files in projects are processed before any dependency files. + 2. **Dependency files second**: Files from configurations (runtime dependencies) or added via [`ShadowJar.from`][ShadowJar.from] are processed after project files. + + This ordering is crucial when merging configuration files where you want to preserve project-specific values while + merging in additional data from dependencies. ## Handling Duplicates Strategy @@ -55,10 +57,12 @@ Different strategies will lead to different results for `foo/bar` files in the J `Entry .* is a duplicate but no duplicate handling strategy has been set`. - `WARN`: **Warn** about duplicates in the build log, this behaves exactly as `INHERIT` otherwise. -**NOTE:** The `duplicatesStrategy` evaluation takes precedence over transforming and relocating. -Because `ShadowJar` is a subclass of Gradle's `AbstractCopyTask`, duplicate filtering configured via -`duplicatesStrategy` is performed at Gradle's `CopySpec` processing layer **before** entries are passed to Shadow's -internal [`ResourceTransformer`][ResourceTransformer] engine. +!!! note "Precedence of DuplicatesStrategy" + + The `duplicatesStrategy` evaluation takes precedence over transforming and relocating. + Because `ShadowJar` is a subclass of Gradle's `AbstractCopyTask`, duplicate filtering configured via + `duplicatesStrategy` is performed at Gradle's `CopySpec` processing layer **before** entries are passed to Shadow's + internal [`ResourceTransformer`][ResourceTransformer] engine. If you mix the usages of `duplicatesStrategy = DuplicatesStrategy.EXCLUDE` and [`ResourceTransformer`][ResourceTransformer] like below: @@ -110,7 +114,9 @@ Alternatively, you can follow these steps: [`filesMatching`][Jar.filesMatching], [`filesNotMatching`][Jar.filesNotMatching], or [`eachFile`][Jar.eachFile] functions to set their `duplicatesStrategy` to `INCLUDE` or `WARN`. -Note, however that functions inherited from [`CopySpec`][CopySpec], such as [`filesMatching`][Jar.filesMatching], [`filesNotMatching`][Jar.filesNotMatching], [`eachFile`][Jar.eachFile], or others, disable the output caching. +!!! warning "Build Cache Impact" + + Functions inherited from [`CopySpec`][CopySpec], such as [`filesMatching`][Jar.filesMatching], [`filesNotMatching`][Jar.filesNotMatching], [`eachFile`][Jar.eachFile], or others, disable the output caching. Optional steps: @@ -345,11 +351,13 @@ method [`transform`][ShadowJar.transform] to add the [`ServiceFileTransformer`][ } ``` -> Groovy Extension Module descriptor files (located at `META-INF/services/org.codehaus.groovy.runtime.ExtensionModule`) -> are ignored by the [`ServiceFileTransformer`][ServiceFileTransformer]. -> This is due to these files having a different syntax than standard service descriptor files. -> Use the [`mergeGroovyExtensionModules()`][mergeGroovyExtensionModules] method to merge -> these files if your dependencies contain them. +!!! note "Groovy Extension Modules" + + Groovy Extension Module descriptor files (located at `META-INF/services/org.codehaus.groovy.runtime.ExtensionModule`) + are ignored by the [`ServiceFileTransformer`][ServiceFileTransformer]. + This is due to these files having a different syntax than standard service descriptor files. + Use the [`mergeGroovyExtensionModules()`][mergeGroovyExtensionModules] method to merge + these files if your dependencies contain them. ### Configuring the Location of Service Descriptor Files diff --git a/docs/configuration/minimizing/README.md b/docs/configuration/minimizing/README.md index 7ed7beaea..1615fcbd9 100644 --- a/docs/configuration/minimizing/README.md +++ b/docs/configuration/minimizing/README.md @@ -44,8 +44,10 @@ a `dependency` is interpreted as a regular expression. } ``` -> Dependencies scoped as `api` will be automatically excluded from minimization and used as "entry points" on -> minimization. +!!! note + + Dependencies scoped as `api` will be automatically excluded from minimization and used as "entry points" on + minimization. Similar to [`ShadowJar.dependencies`][ShadowJar.dependencies], projects can also be excluded. @@ -69,8 +71,10 @@ Similar to [`ShadowJar.dependencies`][ShadowJar.dependencies], projects can also } ``` -> When excluding a `project`, all dependencies of the excluded `project` are automatically excluded from -> minimization as well. +!!! note + + When excluding a `project`, all dependencies of the excluded `project` are automatically excluded from + minimization as well. ## Minimizing with R8 diff --git a/docs/configuration/relocation/README.md b/docs/configuration/relocation/README.md index 8d4063611..cf06d9db4 100644 --- a/docs/configuration/relocation/README.md +++ b/docs/configuration/relocation/README.md @@ -4,7 +4,9 @@ Shadow is capable of scanning a project's classes and relocating specific depend This is often required when one of the dependencies is susceptible to breaking changes in versions or to classpath pollution in a downstream project. -> Google's Guava and the ASM library are typical cases where package relocation can come in handy. +!!! tip + + Google's Guava and the ASM library are typical cases where package relocation can come in handy. Shadow uses the ASM library to modify class byte code to replace the package name and any import statements for a class. @@ -31,12 +33,14 @@ For example, the class `junit.framework.TestCase` becomes `shadow.junit.TestCase In the resulting JAR, the class file is relocated from `junit/framework/TestCase.class` to `shadow/junit/TestCase.class`. -> Relocation operates at a package level. -> It is not necessary to specify any patterns for matching, it will operate simply on the prefix provided. +!!! warning "Scope of Relocation" + + Relocation operates at a package level. + It is not necessary to specify any patterns for matching, it will operate simply on the prefix provided. -> Relocation will be applied globally to all instances of the matched prefix. -> That is, it does **not** scope to _only_ the dependencies being shadowed. -> Be specific as possible when configuring relocation as to avoid unintended relocations. + Relocation will be applied globally to all instances of the matched prefix. + That is, it does **not** scope to _only_ the dependencies being shadowed. + Be specific as possible when configuring relocation as to avoid unintended relocations. ## Filtering Relocation @@ -205,10 +209,13 @@ To configure automatic dependency relocation, set `enableAutoRelocation = true` } ``` -> Configuring package auto relocation can add significant time to the shadow process as it will process all dependencies -> in the configurations declared to be shadowed. By default, this is the `runtime` or `runtimeClasspath` configurations. -> Be mindful that some Gradle plugins will automatically add dependencies to your class path. You may need to remove these -> dependencies if you do not intend to shadow them into your library. +!!! warning "Performance & Transitive Dependencies" + + Configuring package auto relocation can add significant time to the shadow process as it will process all dependencies + in the configurations declared to be shadowed. By default, this is the `runtime` or `runtimeClasspath` configurations. + + Be mindful that some Gradle plugins will automatically add dependencies to your class path. You may need to remove these + dependencies if you do not intend to shadow them into your library. ## Relocating Kotlin Standard Library diff --git a/docs/getting-started/README.md b/docs/getting-started/README.md index 10d4fc03f..7545a7f58 100644 --- a/docs/getting-started/README.md +++ b/docs/getting-started/README.md @@ -106,8 +106,10 @@ Alternatively, the plugin can be added to the buildscript classpath and applied:

-**NOTE:** The correct maven coordinates for each version of Shadow can be found by referencing the Gradle Plugin -documentation [here](https://plugins.gradle.org/plugin/com.gradleup.shadow). +!!! note + + The correct maven coordinates for each version of Shadow can be found by referencing the Gradle Plugin + documentation [here](https://plugins.gradle.org/plugin/com.gradleup.shadow). Shadow is a reactive plugin. This means that applying Shadow by itself will perform no configuration on your project. From c8b25bc59f7d681c84f096de66331c4581e13cf7 Mon Sep 17 00:00:00 2001 From: Zongle Wang Date: Mon, 10 Aug 2026 17:14:23 +0800 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- docs/configuration/merging/README.md | 2 +- docs/configuration/minimizing/README.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/configuration/merging/README.md b/docs/configuration/merging/README.md index b28ff3f59..fd68c5510 100644 --- a/docs/configuration/merging/README.md +++ b/docs/configuration/merging/README.md @@ -116,7 +116,7 @@ Alternatively, you can follow these steps: !!! warning "Build Cache Impact" - Functions inherited from [`CopySpec`][CopySpec], such as [`filesMatching`][Jar.filesMatching], [`filesNotMatching`][Jar.filesNotMatching], [`eachFile`][Jar.eachFile], or others, disable the output caching. + Functions inherited from [`CopySpec`][CopySpec], such as [`filesMatching`][Jar.filesMatching], [`filesNotMatching`][Jar.filesNotMatching], [`eachFile`][Jar.eachFile], or others, disable the output caching. Optional steps: diff --git a/docs/configuration/minimizing/README.md b/docs/configuration/minimizing/README.md index 1615fcbd9..6103d9ff5 100644 --- a/docs/configuration/minimizing/README.md +++ b/docs/configuration/minimizing/README.md @@ -73,7 +73,7 @@ Similar to [`ShadowJar.dependencies`][ShadowJar.dependencies], projects can also !!! note - When excluding a `project`, all dependencies of the excluded `project` are automatically excluded from + When excluding a `project`, all dependencies of the excluded `project` are automatically excluded from minimization as well. ## Minimizing with R8