diff --git a/README.md b/README.md
index 4f4e523f7e..21b99bfcd4 100644
--- a/README.md
+++ b/README.md
@@ -1,184 +1,223 @@
# Dokka
[](https://kotlinlang.org/docs/components-stability.html)
-[](https://confluence.jetbrains.com/display/ALL/JetBrains+on+GitHub)
-[/statusIcon)](https://teamcity.jetbrains.com/viewType.html?buildTypeId=Kotlin_Dokka_DokkaAntMavenGradle&branch_KotlinTools_Dokka=%3Cdefault%3E&tab=buildTypeStatusDiv)
+[](https://github.com/JetBrains#jetbrains-on-github)
-Dokka is a documentation engine for Kotlin, performing the same function as javadoc for Java.
-Just like Kotlin itself, Dokka fully supports mixed-language Java/Kotlin projects. It understands
-standard Javadoc comments in Java files and [KDoc comments](https://kotlinlang.org/docs/reference/kotlin-doc.html) in Kotlin files,
-and can generate documentation in multiple formats including standard Javadoc, HTML and Markdown.
+Dokka is an API documentation engine for Kotlin.
-:mega: Dokka team now leads the product to the first Stable release.
-And we’d really appreciate it if you could [take our brief survey](https://surveys.jetbrains.com/s3/dokka-survey) about your dev. experience with the tool. It helps us to understand priorities right and deliver the most valuable things.
+Just like Kotlin itself, Dokka supports mixed-language projects. It understands Kotlin's
+[KDoc comments](https://kotlinlang.org/docs/kotlin-doc.html#kdoc-syntax) and Java's
+[Javadoc comments](https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html).
-## Using Dokka
+Dokka can generate documentation in multiple formats, including its own modern [HTML format](#html),
+multiple flavors of [Markdown](#markdown), and Java's [Javadoc HTML](#javadoc).
-**Full documentation is available at [https://kotlin.github.io/dokka/1.7.20/](https://kotlin.github.io/dokka/1.7.20/)**
+Some libraries that use Dokka for their API reference documentation:
-### Using the Gradle plugin
-_Note: If you are upgrading from 0.10.x to a current release of Dokka, please have a look at our
-[migration guide](runners/gradle-plugin/MIGRATION.md)_
+* [kotlinx.coroutines](https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/)
+* [Bitmovin](https://cdn.bitmovin.com/player/android/3/docs/index.html)
+* [Hexagon](https://hexagonkt.com/api/index.html)
+* [Ktor](https://api.ktor.io/)
+* [OkHttp](https://square.github.io/okhttp/4.x/okhttp/okhttp3/) (Markdown)
+
+You can run Dokka using [Gradle](https://kotlinlang.org/docs/dokka-gradle.html),
+[Maven](https://kotlinlang.org/docs/dokka-maven.html) or from the [command line](https://kotlinlang.org/docs/dokka-cli.html).
+It is also [highly pluggable](https://kotlinlang.org/docs/dokka-plugins.html).
+
+## Documentation
+
+Comprehensive documentation for Dokka is available on [kotlinlang.org](https://kotlinlang.org/docs/dokka-introduction.html)
+
+## Get started with Dokka
+
+### Gradle
+
+
+Kotlin DSL
+
+Apply the Gradle plugin for Dokka in the root build script of your project:
-The preferred way is to use `plugins` block.
-
-build.gradle.kts:
```kotlin
plugins {
id("org.jetbrains.dokka") version "1.7.20"
}
+```
+
+When documenting [multi-project](https://docs.gradle.org/current/userguide/multi_project_builds.html) builds, you need
+to apply the Gradle plugin for Dokka within subprojects as well:
-repositories {
- mavenCentral()
+```kotlin
+subprojects {
+ apply(plugin = "org.jetbrains.dokka")
}
```
-The plugin adds `dokkaHtml`, `dokkaJavadoc`, `dokkaGfm` and `dokkaJekyll` tasks to the project.
-
-#### Applying plugins
-Dokka plugin creates Gradle configuration for each output format in the form of `dokka${format}Plugin`:
+
-```kotlin
-dependencies {
- dokkaHtmlPlugin("org.jetbrains.dokka:kotlin-as-java-plugin:1.7.20")
+
+Groovy DSL
+
+Apply Gradle plugin for Dokka in the root project:
+
+```groovy
+plugins {
+ id 'org.jetbrains.dokka' version '1.7.20'
}
-```
+```
-You can also create a custom Dokka task and add plugins directly inside:
+When documenting [multi-project](https://docs.gradle.org/current/userguide/multi_project_builds.html) builds, you need
+to apply the Gradle plugin for Dokka within subprojects as well:
-```kotlin
-val customDokkaTask by creating(DokkaTask::class) {
- dependencies {
- plugins("org.jetbrains.dokka:kotlin-as-java-plugin:1.7.20")
- }
+```groovy
+subprojects {
+ apply plugin: 'org.jetbrains.dokka'
}
```
-Please note that `dokkaJavadoc` task will properly document only single `jvm` source set
+
-To generate the documentation, use the appropriate `dokka${format}` Gradle task:
+To generate documentation, run the following Gradle tasks:
-```bash
-./gradlew dokkaHtml
-```
+* `dokkaHtml` for single-project builds
+* `dokkaHtmlMultiModule` for multi-project builds
-Please see the [Dokka Gradle example project](https://github.com/Kotlin/dokka/tree/master/examples/gradle/dokka-gradle-example) for an example.
+By default, the output directory is set to `/build/dokka/html` and `/build/dokka/htmlMultiModule` respectively.
-We encourage users to create their own plugins and share them with the community on [official plugins list](docs/src/doc/docs/community/plugins-list.md).
+To learn more about the Gradle plugin for Dokka, see [documentation for Gradle](https://kotlinlang.org/docs/dokka-gradle.html).
-#### Android
+### Maven
-Make sure you apply Dokka after `com.android.library` and `kotlin-android`.
+Add the Dokka Maven plugin to the `plugins` section of your POM file:
-```kotlin
-buildscript {
- dependencies {
- classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:${kotlin_version}")
- classpath("org.jetbrains.dokka:dokka-gradle-plugin:${dokka_version}")
- }
-}
-repositories {
- mavenCentral()
-}
-apply(plugin= "com.android.library")
-apply(plugin= "kotlin-android")
-apply(plugin= "org.jetbrains.dokka")
+```xml
+
+
+
+ org.jetbrains.dokka
+ dokka-maven-plugin
+ 1.7.20
+
+
+ pre-site
+
+ dokka
+
+
+
+
+
+
```
-```kotlin
-dokkaHtml.configure {
- dokkaSourceSets {
- named("main") {
- noAndroidSdkLink.set(false)
- }
- }
-}
-```
+To generate documentation, run the `dokka:dokka` goal.
+
+By default, the output directory is set to `target/dokka`.
+
+To learn more about using Dokka with Maven, see [documentation for Maven](https://kotlinlang.org/docs/dokka-maven.html).
+
+### CLI
-#### Multi-module projects
-For documenting Gradle multi-module projects, you can use `dokka${format}Multimodule` tasks.
+It is possible to run Dokka from the command line without having to use any of the build tools, but it's more
+difficult to set up and for that reason it is not covered in this section.
+
+Please consult [documentation for the command line runner](https://kotlinlang.org/docs/dokka-cli.html)
+to learn how to use it.
+
+### Android
+
+In addition to applying and configuring Dokka, you can apply Dokka's
+[Android documentation plugin](plugins/android-documentation), which aims to improve documentation experience on the
+Android platform:
+
+
+Gradle Kotlin DSL
```kotlin
-tasks.dokkaHtmlMultiModule.configure {
- outputDirectory.set(buildDir.resolve("dokkaCustomMultiModuleOutput"))
+dependencies {
+ dokkaPlugin("org.jetbrains.dokka:android-documentation-plugin:1.7.20")
}
```
-`DokkaMultiModule` depends on all Dokka tasks in the subprojects, runs them, and creates a toplevel page
-with links to all generated (sub)documentations
-
-### Using the Maven plugin
-
-The Maven plugin does not support multi-platform projects.
+
-Documentation is by default generated in `target/dokka`.
+
+Gradle Groovy DSL
-The following goals are provided by the plugin:
+```groovy
+dependencies {
+ dokkaPlugin 'org.jetbrains.dokka:android-documentation-plugin:1.7.20'
+}
+```
- * `dokka:dokka` - generate HTML documentation in Dokka format (showing declarations in Kotlin syntax)
- * `dokka:javadoc` - generate HTML documentation in Javadoc format (showing declarations in Java syntax)
- * `dokka:javadocJar` - generate a .jar file with Javadoc format documentation
+
-#### Applying plugins
-You can add plugins inside the `dokkaPlugins` block:
+
+Maven
```xml
org.jetbrains.dokka
dokka-maven-plugin
- ${dokka.version}
-
-
- pre-site
-
- dokka
-
-
-
+ ...
org.jetbrains.dokka
- kotlin-as-java-plugin
- ${dokka.version}
+ android-documentation-plugin
+ 1.7.20
```
-Please see the [Dokka Maven example project](https://github.com/Kotlin/dokka/tree/master/examples/maven) for an example.
+
-### Using the Command Line
+## Output formats
-To run Dokka from the command line, download the [Dokka CLI runner](https://mvnrepository.com/artifact/org.jetbrains.dokka/dokka-cli).
-To generate documentation, run the following command:
-```
-java -jar dokka-cli.jar
-```
+### HTML
-You can also use a JSON file with dokka configuration:
- ```
- java -jar
- ```
+HTML is Dokka's default and recommended output format. You can see an example of the output by browsing documentation
+for [kotlinx.coroutines](https://kotlinlang.org/api/kotlinx.coroutines/).
-### Output formats
- Dokka documents Java classes as seen in Kotlin by default, with javadoc format being the only exception.
+HTML format is configurable and, among other things, allows you to modify stylesheets, add custom image assets, change
+footer message and revamp the structure of the generated HTML pages through templates.
- * `html` - HTML format used by default
- * `javadoc` - looks like JDK's Javadoc, Kotlin classes are translated to Java
- * `gfm` - GitHub flavored markdown
- * `jekyll` - Jekyll compatible markdown
+For more details and examples, see [documentation for HTML format](https://kotlinlang.org/docs/dokka-html.html).
-If you want to generate the documentation as seen from Java perspective, you can add the `kotlin-as-java` plugin
-to the Dokka plugins classpath, eg. in Gradle:
+### Markdown
-```kotlin
-dependencies{
- implementation("...")
- dokkaGfmPlugin("org.jetbrains.dokka:kotlin-as-java-plugin:${dokka-version}")
-}
-```
+Dokka is able to generate documentation in GitHub Flavored and Jekyll compatible Markdown. However, both of these
+formats are still in Alpha, so you might encounter bugs and migration issues.
+
+For more details and examples, see [documentation for Markdown formats](https://kotlinlang.org/docs/dokka-markdown.html).
+
+### Javadoc
+
+Dokka's Javadoc output format is a lookalike of Java's
+[Javadoc HTML format](https://docs.oracle.com/en/java/javase/19/docs/api/index.html). This format is still in Alpha,
+so you might encounter bugs and migration issues.
+
+Javadoc format tries to visually mimic HTML pages generated by the Javadoc tool, but it's not a direct implementation
+or an exact copy. In addition, all Kotlin signatures are translated to Java signatures.
+
+For more details and examples, see [documentation for Javadoc format](https://kotlinlang.org/docs/dokka-javadoc.html).
+
+## Dokka plugins
+
+Dokka was built from the ground up to be easily extensible and highly customizable, which allows the community to
+implement plugins for missing or very specific features that are not provided out of the box.
+
+Learn more about Dokka plugins and their configuration in [Dokka plugins](https://kotlinlang.org/docs/dokka-plugins.html).
+
+If you want to learn how to develop Dokka plugins, see
+[Developer guides](https://kotlin.github.io/dokka/1.7.20/developer_guide/introduction/).
+
+## Community
+
+Dokka has a dedicated `#dokka` channel in [Kotlin Community Slack](https://surveys.jetbrains.com/s3/kotlin-slack-sign-up)
+where you can chat about Dokka, its plugins and how to develop them, as well as get in touch with maintainers.
+
+## Building and Contributing
-#### FAQ
-If you encounter any problems, please see the [FAQ](https://github.com/Kotlin/dokka/wiki/faq).
+See [Contributing Guidelines](CONTRIBUTING.md)