Add mavenLocal() repository warning

docs/topics/gradle/get-started-with-jvm-gradle-project.md

@@ -80,7 +80,7 @@ application {
 
 As you can see, there are a few Kotlin-specific artifacts added to the Gradle build file:
 
-1. In the `plugins` block, there is the `kotlin("jvm")` artifact – the plugin defines the version of Kotlin to be used in the project.
+1. In the `plugins{}` block, there is the `kotlin("jvm")` artifact – the plugin defines the version of Kotlin to be used in the project.
 
 2. In the `dependencies` section, there is `testImplementation(kotlin("test"))`. 
    Learn more about [setting dependencies on test libraries](gradle-configure-project.md#set-dependencies-on-test-libraries).

docs/topics/gradle/gradle-configure-project.md

@@ -11,7 +11,7 @@ and [configure the project's dependencies](#configure-dependencies) there.
 
 ## Apply the plugin
 
-To apply the Kotlin Gradle plugin, use the [`plugins` block](https://docs.gradle.org/current/userguide/plugins.html#sec:plugins_block)
+To apply the Kotlin Gradle plugin, use the [`plugins{}` block](https://docs.gradle.org/current/userguide/plugins.html#sec:plugins_block)
 from the Gradle plugins DSL:
 
 <tabs group="build-script">
@@ -187,7 +187,7 @@ tasks.withType(org.jetbrains.kotlin.gradle.tasks.KotlinJvmCompile.class).configu
 
 To avoid JVM target incompatibility, [configure a toolchain](#gradle-java-toolchains-support) or align JVM versions manually.
 
-#### What can go wrong if not checking targets compatibility {initial-collapse-state="collapsed"}
+#### What can go wrong if targets are incompatible {initial-collapse-state="collapsed"}
 
 There are two ways of manually setting JVM targets for Kotlin and Java source sets:
 * The implicit way via [setting up a Java toolchain](#gradle-java-toolchains-support).
@@ -601,7 +601,7 @@ plugins {
 ### Kotlin and Java sources for JavaScript
 
 This plugin only works for Kotlin files, so it is recommended that you keep Kotlin and Java files separate (if the
-project contains Java files). If you don't store them separately, specify the source folder in the `sourceSets` block:
+project contains Java files). If you don't store them separately, specify the source folder in the `sourceSets{}` block:
 
 <tabs group="build-script">
 <tab title="Kotlin" group-key="kotlin">
@@ -665,7 +665,7 @@ project.plugins.withType(KotlinBasePlugin.class) {
 ## Configure dependencies
 
 To add a dependency on a library, set the dependency of the required [type](#dependency-types) (for example, `implementation`) in the
-`dependencies` block of the source sets DSL.
+`dependencies{}` block of the source sets DSL.
 
 <tabs group="build-script">
 <tab title="Kotlin" group-key="kotlin">
@@ -1150,6 +1150,68 @@ dependencies {
 </tab>
 </tabs>
 
+## Declare repositories
+
+You can declare a publicly-available repository to use its open source dependencies. In the `repositories{}` block, set 
+the name of the repository:
+
+<tabs group="build-script">
+<tab title="Kotlin" group-key="kotlin">
+
+```kotlin
+repositories {
+    mavenCentral()
+}
+```
+</tab>
+<tab title="Groovy" group-key="groovy">
+
+```kotlin
+repositories {
+    mavenCentral()
+}
+```
+</tab>
+</tabs>
+
+Popular repositories are [Maven Central](https://central.sonatype.com/) and [Google's Maven repository](https://maven.google.com/web/index.html).
+
+> If you also work with Maven projects, we recommend avoiding adding `mavenLocal()` as a repository because you
+> may experience problems when switching between Gradle and Maven projects. If you must add the `mavenLocal()` repository,
+> add it as the last repository in your `repositories{}` block. For more information, see
+> [The case for mavenLocal()](https://docs.gradle.org/current/userguide/declaring_repositories.html#sec:case-for-maven-local).
+> 
+{type="warning"}
+
+If you need to declare the same repositories in more than one subproject, declare the repositories centrally in the
+`dependencyResolutionManagement{}` block in your `settings.gradle(.kts)` file:
+
+<tabs group="build-script">
+<tab title="Kotlin" group-key="kotlin">
+
+```kotlin
+dependencyResolutionManagement {
+    repositories {
+        mavenCentral()
+    }
+}
+```
+</tab>
+<tab title="Groovy" group-key="groovy">
+
+```kotlin
+dependencyResolutionManagement {
+    repositories {
+        mavenCentral()
+    }
+}
+```
+</tab>
+</tabs>
+
+Any declared repositories in subprojects override repositories declared centrally. For more information on how to control
+this behavior and what options are available, see [Gradle's documentation](https://docs.gradle.org/current/userguide/declaring_repositories.html#sub:centralized-repository-declaration).
+
 ## What's next?
 
 Learn more about:

docs/topics/maven.md

@@ -6,7 +6,7 @@ Maven is a build system that you can use to build and manage any Java-based proj
 
 The *kotlin-maven-plugin* compiles Kotlin sources and modules. Currently, only Maven v3 is supported.
 
-Define the version of Kotlin you want to use via the `kotlin.version` property:
+In your `pom.xml` file, define the version of Kotlin you want to use in the `kotlin.version` property:
 
 ```xml
 <properties>
@@ -23,6 +23,25 @@ To use JDK 17, in your `.mvn/jvm.config` file, add:
 --add-opens=java.base/java.io=ALL-UNNAMED
 ```
 
+## Declare repositories
+
+By default, the `mavenCentral` repository is available for all Maven projects. To access artifacts in other repositories,
+specify the ID and URL of each repository in the `<repositories>` element:
+
+```xml
+<repositories>
+    <repository>
+        <id>spring-repo</id>
+        <url>https://repo.spring.io/release</url>
+    </repository>
+</repositories>
+```
+
+> If you declare `mavenLocal()` as a repository in a Gradle project, you may experience problems when switching 
+> between Gradle and Maven projects. For more information, see [Declare repositories](gradle-configure-project.md#declare-repositories).
+>
+{type="note"}
+
 ## Set dependencies
 
 Kotlin has an extensive standard library that can be used in your applications.

docs/topics/whatsnew18.md

@@ -535,7 +535,7 @@ The shift of the default value from `warning` to `error` is a preparation step f
 **We encourage you to set this property to `error`** and [configure a toolchain](gradle-configure-project.md#gradle-java-toolchains-support)
 or align JVM versions manually.
 
-Learn more about [what can go wrong if you don't check the targets' compatibility](gradle-configure-project.md#what-can-go-wrong-if-not-checking-targets-compatibility).
+Learn more about [what can go wrong if you don't check the targets' compatibility](gradle-configure-project.md#what-can-go-wrong-if-targets-are-incompatible).
 
 ### Resolution of Kotlin Gradle plugins' transitive dependencies