Use MkDocs admonition syntax for notes, warnings, and tips

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
 

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
 

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
 

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
 

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
 

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

docs/getting-started/README.md

@@ -106,8 +106,10 @@ Alternatively, the plugin can be added to the buildscript classpath and applied:
     </p>
     </details>
 
-**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.