Merge pull request #1202 from bmuschko/bm/apply-plugin-multiproject

Add note on applying plugin in multi-project builds to user guide

src/docs/asciidoc/user-guide/02-getting-started.adoc

@@ -2,7 +2,7 @@
 
 The plugin can be applied with the `buildscript` syntax or the plugin DSL.
 Let's say you'd want to go with the plugin that provides the plain Docker operations for managing Docker images and containers.
-See the https://docs.gradle.org/current/userguide/plugins.html[Gradle user guide] for more information on applying plugins.
+See the {uri-gradle-docs}/userguide/plugins.html[Gradle user guide] for more information on applying plugins.
 
 ==== Applying the Plugin Using the buildscript Syntax
 
@@ -32,6 +32,9 @@ include::{samplesCodeDir}/remote-api-plugin/apply-plugin-dsl/groovy/build.gradle
 include::{samplesCodeDir}/remote-api-plugin/apply-plugin-dsl/kotlin/build.gradle.kts[]
 ----
 
+[IMPORTANT]
+Using the `plugins {}` block to apply the plugin requires special handling in a multi-project build. For more information, see the Gradle documentation section named {uri-gradle-docs}/userguide/plugins.html#sec:subprojects_plugins_dsl["Applying external plugins with same version to subprojects"].
+
 ==== Applying the Plugin From a Script Plugin
 
 Applying the plugin from a script plugin requires the use of the fully-qualified class name due to a https://github.com/gradle/gradle/issues/1262[bug in Gradle core]. Be aware that the plugin DSL cannot be used to apply a binary plugin from a script plugin.