Gradle/DevKit approach or Plugin/Theme topic content reorganization (#862)

code_samples/README.md

@@ -55,7 +55,7 @@ In the following table, you may find all available samples provided in the separ
 | [Run Configuration](./run_configuration)                               | Run configuration implementation with factory, options and UI.                                                                                                                |
 | [Settings](./settings)                                                 | Custom settings panel, adds a settings panel to the **Settings/Preferences** panel under **Tools**.                                                                           |
 | [Simple Language Plugin](./simple_language_plugin)                     | Custom language support, defines a new *Simple language* with syntax highlighting, annotations, code completion, and other features.                                          |
-| [Theme Basics](./theme_basics)                                         | Sample *UI Theme* plugin with basic interface modifications.                                                                                                                  |
+| [Theme Basics](./theme_basics)                                         | Sample *theme* plugin with basic interface modifications.                                                                                                                     |
 | [Tool Window](./tool_window)                                           | Custom Tool Window example plugin.                                                                                                                                            |
 | [Tree Structure Provider](./tree_structure_provider)                   | Tree Structure Provider showing only plain text files.                                                                                                                        |
 

code_samples/theme_basics/README.md

@@ -1,12 +1,12 @@
 # Theme Basics [![JetBrains IntelliJ Platform SDK Docs](https://jb.gg/badges/docs.svg)][docs]
-*Reference: [Creating Custom UI Themes in IntelliJ SDK Docs][docs:themes]*
+*Reference: [Creating Custom Themes in IntelliJ SDK Docs][docs:themes]*
 
 ## Quickstart
 
-Custom UI Themes are available beginning in version 2019.1.
+Custom themes are available beginning in version 2019.1.
 
-Creating a custom UI Theme is a process of choosing a base IDE Theme (Light or Darcula) then changing aspects of the base Theme definition.
-Custom UI Themes can:
+Creating a custom theme is a process of choosing a base IDE Theme (Light or Darcula) then changing aspects of the base Theme definition.
+Custom themes can:
 - substitute icons,
 - change the colors of icons and UI controls,
 - alter the borders and insets of UI controls,

code_samples/theme_basics/resources/META-INF/plugin.xml

@@ -20,7 +20,7 @@
 
   <description>
     <![CDATA[
-      IntelliJ Platform SDK code sample to illustrate creating <em>UI Themes</em>.
+      IntelliJ Platform SDK code sample to illustrate creating <em>themes</em>.
     ]]>
   </description>
   <change-notes>

ijs.tree

@@ -22,28 +22,25 @@
     <toc-element id="content_updates.md" accepts-web-file-names="recently_updated.html"/>
   </toc-element>
   <toc-element toc-title="Part I — Plugins">
-    <toc-element id="basics.md">
+    <toc-element id="plugins_quick_start.md" accepts-web-file-names="basics.html">
       <toc-element id="plugin_alternatives.md" toc-title="Plugin Alternatives"/>
       <toc-element id="plugin_required_experience.md"/>
-      <toc-element id="types_of_plugins.md"/>
+      <toc-element id="plugin_types.md" accepts-web-file-names="types-of-plugins.html"/>
     </toc-element>
-    <toc-element id="getting_started.md">
-      <toc-element id="github_template.md" toc-title="Using GitHub Template"/>
-      <toc-element id="gradle_build_system.md" accepts-web-file-names="build_system.html"
-                   toc-title="Using Gradle">
-        <toc-element id="gradle_prerequisites.md"/>
-        <toc-element id="gradle_guide.md"/>
-        <toc-element id="deployment.md"/>
+    <toc-element id="developing_plugins.md"
+                 accepts-web-file-names="getting-started.html,gradle-build-system.html,build_system.html">
+      <toc-element id="creating_plugin_project.md" accepts-web-file-names="gradle-prerequisites.html">
+        <toc-element id="plugin_github_template.md" toc-title="Plugin GitHub Template"
+                     accepts-web-file-names="github-template.html"/>
+        <toc-element id="migrating_plugin_devkit_to_gradle.md"/>
       </toc-element>
-      <toc-element id="using_dev_kit.md">
-        <toc-element id="setting_up_environment.md"/>
-        <toc-element id="creating_plugin_project.md" accepts-web-file-names="creating_an_action.html"/>
-        <toc-element id="running_and_debugging_a_plugin.md"/>
-        <toc-element id="deploying_plugin.md"/>
-      </toc-element>
-      <toc-element id="publishing_plugin.md"/>
+      <toc-element id="configuring_plugin_project.md" accepts-web-file-names="gradle-guide.html">
+        <toc-element id="using_kotlin.md" accepts-web-file-names="kotlin.html"/>
       </toc-element>
       <toc-element id="ide_development_instance.md" accepts-web-file-names="settings_caches_logs.html"/>
+      <toc-element id="plugin_signing.md"/>
+      <toc-element id="publishing_plugin.md" accepts-web-file-names="deployment.html"/>
+    </toc-element>
     <toc-element id="plugin_structure.md">
       <toc-element id="plugin_content.md"/>
       <toc-element id="bundling_plugin_openapi_sources.md" toc-title="Plugin API Sources"/>
@@ -60,8 +57,6 @@
     </toc-element>
     <toc-element id="dynamic_plugins.md"/>
     <toc-element id="intellij_artifacts.md"/>
-    <toc-element id="kotlin.md"/>
-    <toc-element id="plugin_signing.md"/>
     <toc-element id="faq.md"/>
   </toc-element>
   <toc-element toc-title="Part II — Base Platform">
@@ -90,14 +85,9 @@
       <toc-element id="misc_swing_components.md"/>
       <toc-element id="work_with_icons_and_images.md" toc-title="Icons and Images"/>
       <toc-element id="color_scheme_management.md"/>
-    </toc-element>
-    <toc-element id="jcef.md" toc-title="JCEF"/>
-    <toc-element id="themes_intro.md">
-      <toc-element id="themes.md"/>
-      <toc-element id="themes_customize.md" toc-title="Customizing UI Theme"/>
-      <toc-element id="themes_extras.md" toc-title="Adding Schemes and Images"/>
       <toc-element id="themes_metadata.md"/>
     </toc-element>
+    <toc-element id="jcef.md" toc-title="JCEF"/>
     <toc-element id="basic_action_system.md" accepts-web-file-names="action_system.html">
       <toc-element id="action_system.md">
         <toc-element id="working_with_custom_actions.md"/>
@@ -346,6 +336,19 @@
     <toc-element toc-title="Build Your Own IDE"/>
     <toc-element toc-title="Licensing"/>
   </toc-element>
+  <toc-element toc-title="Part X — Themes">
+    <toc-element id="themes_getting_started.md" accepts-web-file-names="themes-intro.html"/>
+    <toc-element id="developing_themes.md" accepts-web-file-names="using-dev-kit.html">
+      <toc-element id="setting_up_theme_environment.md" accepts-web-file-names="setting-up-environment.html"/>
+      <toc-element id="creating_theme_project.md" accepts-web-file-names="creating_an_action.html"/>
+      <toc-element id="running_and_debugging_a_theme.md" accepts-web-file-names="running-and-debugging-a-plugin.html"/>
+      <toc-element id="deploying_theme.md" accepts-web-file-names="deploying-plugin.html"/>
+    </toc-element>
+    <toc-element id="theme_structure.md" accepts-web-file-names="themes.html">
+      <toc-element id="themes_customize.md" toc-title="Customizing a Theme"/>
+      <toc-element id="themes_extras.md" toc-title="Adding Schemes and Images"/>
+    </toc-element>
+  </toc-element>
   <toc-element toc-title="Appendix I — Resources">
     <toc-element id="glossary.md"/>
     <toc-element id="explore_api.md" toc-title="Explore the API"/>

topics/appendix/api_notable/api_notable_list_2019.md

@@ -13,7 +13,7 @@ Support for transitive optional plugin dependencies
 : [Optional <path>plugin.xml</path> configuration files](plugin_configuration_file.md#additional-plugin-configuration-files) can now specify [`<depends>`](plugin_configuration_file.md#idea-plugin__depends). [Issue](https://youtrack.jetbrains.com/issue/IDEA-209769)
 
 Theme/Keymap plugins do not require restart
-: (Un)Installing or enabling/disabling [Theme](themes_intro.md) or [Keymap](https://plugins.jetbrains.com/search?tags=Keymap) plugins doesn't require an IDE restart anymore.
+: (Un)Installing or enabling/disabling [Theme](themes_getting_started.md) or [Keymap](https://plugins.jetbrains.com/search?tags=Keymap) plugins doesn't require an IDE restart anymore.
 
 Run task once (per project)
 : Use `com.intellij.ide.util.RunOnceUtil` to run a task exactly once for application or per project.

topics/appendix/tools/gradle_intellij_plugin/tools_gradle_intellij_plugin.md

@@ -478,7 +478,7 @@ Default value
 ### buildPlugin
 {id="tasks-buildplugin"}
 
-Assembles a plugin and prepares ZIP archive for [deployment](deployment.md).
+Assembles a plugin and prepares ZIP archive for [deployment](publishing_plugin.md).
 
 #### archiveBaseName
 {id="buildplugin-task-archivebasename"}
@@ -817,7 +817,7 @@ Default value
 #### sinceBuild
 {id="patchpluginxml-task-sincebuild"}
 
-The lower bound of the version range to be patched used in the `since-build` attribute of the [`<idea-version>`](plugin_configuration_file.md#idea-plugin__idea-version) tag.
+The lower bound of the [version range](build_number_ranges.md) to be patched used in the `since-build` attribute of the [`<idea-version>`](plugin_configuration_file.md#idea-plugin__idea-version) tag.
 
 {style="narrow"}
 Type
@@ -830,7 +830,7 @@ Default value
 #### untilBuild
 {id="patchpluginxml-task-untilbuild"}
 
-The upper bound of the version range to be patched used in the `until-build` attribute of the [`<idea-version>`](plugin_configuration_file.md#idea-plugin__idea-version) tag.
+The upper bound of the [version range](build_number_ranges.md) to be patched used in the `until-build` attribute of the [`<idea-version>`](plugin_configuration_file.md#idea-plugin__idea-version) tag.
 
 {style="narrow"}
 Type
@@ -973,11 +973,11 @@ See [`prepareSandbox` Task](#tasks-preparesandbox).
 Publishes plugin to the remote [JetBrains Marketplace](https://plugins.jetbrains.com) repository.
 
 The following attributes are a part of the Publishing DSL `publishPlugin { ... }` in which allows Gradle to upload plugin to [JetBrains Marketplace](https://plugins.jetbrains.com).
-Note that you need to [upload the plugin](publishing_plugin.md) to the repository at least once manually (to specify options like the license, repository URL etc.) before uploads through Gradle can be used.
+Note that you need to [upload the plugin](publishing_plugin.md#uploading-a-plugin-to-jetbrains-marketplace) to the repository at least once manually (to specify options like the license, repository URL etc.) before uploads through Gradle can be used.
 
 See the instruction on [how to generate authentication token](https://plugins.jetbrains.com/docs/marketplace/plugin-upload.html).
 
-See [](deployment.md) tutorial for step-by-step instructions.
+See [](publishing_plugin.md#publishing-plugin-with-gradle) tutorial for step-by-step instructions.
 
 
 #### token
@@ -1732,4 +1732,4 @@ Validates the plugin project configuration:
 
 - The dependency on the Kotlin Standard Library (stdlib) is automatically added when using the Gradle Kotlin plugin and may conflict with the version provided with the IntelliJ Platform.
 
-> Read more about controlling this behavior on [](kotlin.md#kotlin-standard-library).
+> Read more about controlling this behavior on [](using_kotlin.md#kotlin-standard-library).

topics/appendix/tools/ide_tooling/internal_actions/internal_ui_laf_defaults.md

@@ -38,4 +38,4 @@ The <control>Choose Color</control> window is displayed.
 Color changes can be specified as RGB, HSB, hexadecimal, or using the graphical color picker.
 Pressing the <control>Choose</control> button changes the UI Control color immediately.
 
-UI Control colors can be reset using the <control>Choose Color</control> window, or by resetting the [UI Theme](https://www.jetbrains.com/help/idea/settings-appearance.html).
+UI Control colors can be reset using the <control>Choose Color</control> window, or by resetting the [theme](https://www.jetbrains.com/help/idea/settings-appearance.html).

topics/appendix/verifying_plugin_compatibility.md

@@ -9,7 +9,7 @@ For API annotated with `ApiStatus.@Internal`, see [](api_internal.md) for more d
 
 Compatibility with newer IDEs can easily be verified for plugins hosted on the [JetBrains Marketplace](https://plugins.jetbrains.com) using the built-in [Plugin Verifier](https://blog.jetbrains.com/platform/2018/07/plugins-repository-now-integrates-with-the-plugin-verification-tool/).
 
-Integration in [Gradle build](gradle_build_system.md) is available using the [`runPluginVerifier`](tools_gradle_intellij_plugin.md#tasks-runpluginverifier) task, please see [Gradle IntelliJ Plugin - Plugin Verifier](tools_gradle_intellij_plugin.md#tasks-runpluginverifier) for details.
+Integration in [Gradle build](configuring_plugin_project.md) is available using the [`runPluginVerifier`](tools_gradle_intellij_plugin.md#tasks-runpluginverifier) task, please see [Gradle IntelliJ Plugin - Plugin Verifier](tools_gradle_intellij_plugin.md#tasks-runpluginverifier) for details.
 
 You can easily integrate it within your CI by running this task as another quality check step.
 Check the IntelliJ Platform Plugin Template [GitHub workflow configuration file](https://github.com/JetBrains/intellij-platform-plugin-template/blob/main/.github/workflows/build.yml) as sample.

topics/basics/getting_started.md

@@ -1,40 +0,0 @@
-[//]: # (title: Creating A Plugin)
-
-<!-- Copyright 2000-2022 JetBrains s.r.o. and other contributors. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file. -->
-
-This documentation section will help you get started with developing plugins for the IntelliJ Platform.
-You can use either [IntelliJ IDEA Community Edition](https://www.jetbrains.com/idea/download/) or [IntelliJ IDEA Ultimate](https://www.jetbrains.com/idea/download/) as your IDE (it is highly recommended to use the latest available version).
-Both include the complete set of plugin development tools.
-To become more familiar with IntelliJ IDEA, please refer to the [IntelliJ IDEA Web Help](https://www.jetbrains.com/idea/help/).
-
-> In some cases, implementing an actual IntelliJ Platform plugin might not be necessary, as [alternative solutions](plugin_alternatives.md) exist.
->
-{type="tip"}
-
-There are three supported workflows available for building plugins.
-The recommended workflow for new projects is to [use GitHub Template](#using-github-template) or to [use Gradle](#using-gradle) to create everything from scratch.
-The old [Plugin DevKit](#using-devkit) workflow still supports existing projects.
-
-## Using GitHub Template
-
-* [Developing plugins using GitHub Template](github_template.md)
-
-## Using Gradle
-
-* [Developing plugins using Gradle](gradle_build_system.md)
-    * [Getting Started with Gradle](gradle_prerequisites.md)
-    * [Configuring Gradle Projects](gradle_guide.md)
-    * [Publishing Plugins with Gradle](deployment.md)
-
-## Using DevKit
-
-* [Developing plugins using DevKit](using_dev_kit.md)
-    * [Setting Up a Development Environment](setting_up_environment.md)
-    * [Creating a Plugin Project](creating_plugin_project.md)
-    * [Running and Debugging a Plugin](running_and_debugging_a_plugin.md)
-    * [Deploying a Plugin](deploying_plugin.md)
-    * [Publishing a Plugin](publishing_plugin.md)
-
-> A dedicated [SBT plugin](https://github.com/JetBrains/sbt-idea-plugin) is available for plugins implemented in Scala.
->
-{type="tip"}

topics/basics/getting_started/build_number_ranges.md

@@ -1,8 +1,9 @@
 [//]: # (title: Build Number Ranges)
-<!-- Copyright 2000-2022 JetBrains s.r.o. and other contributors. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file. -->
+
+<!-- Copyright 2000-2022 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. -->
 
 Use this reference of build number ranges to specify the correct `since-build` and `until-build` values in your plugin descriptor.
-Setting the actual values in <path>[plugin.xml](plugin_configuration_file.md)</path> is managed by [`patchPluginXml`](tools_gradle_intellij_plugin.md#tasks-patchpluginxml) Gradle task, see [](gradle_guide.md#patching-the-plugin-configuration-file).
+Setting the actual values in <path>[plugin.xml](plugin_configuration_file.md)</path> is managed by [`patchPluginXml`](tools_gradle_intellij_plugin.md#tasks-patchpluginxml) Gradle task, see [](configuring_plugin_project.md#patching-the-plugin-configuration-file).
 
 Please note the following regarding values:
 

topics/basics/getting_started/creating_plugin_project.md

@@ -1,42 +0,0 @@
-[//]: # (title: Creating a Plugin Project)
-
-<!-- Copyright 2000-2022 JetBrains s.r.o. and other contributors. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file. -->
-
-> For new projects, it is highly recommended to use [Gradle-based setup](getting_started.md).
->
-{type="note"}
-
-This section explains how you can create a new plugin project from scratch using the <menupath>New Project</menupath> wizard.
-Optionally, you can import an existing project or import a project from external models.
-You can also add a new plugin module to the current IntelliJ Platform project.
-For more information, refer to the [IntelliJ IDEA Web Help](https://www.jetbrains.com/idea/help/new-project-wizard.html).
-
-### Creating an IntelliJ Platform Plugin Project
-
-> Make sure to [](setting_up_environment.md) before proceeding.
->
-{type="note"}
-
-* On the main menu, choose <menupath>File | New | Project</menupath>.
-  The <control>New Project</control> wizard starts.
-  ![New Project Wizard](new_project_wizard.png)
-* Select <control>IntelliJ Platform Plugin</control> project type.
-* Click <control>Next</control> button.
-* Set the desired project name.
-* Click <control>Finish</control> to generate project structure files.
-* Go to <menupath>File | Project Structure</menupath> to customize project settings if required.
-
-### Creating an IntelliJ Platform Plugin Module
-
-* Select <menupath>File | New | Module</menupath> and choose the <control>IntelliJ Platform Plugin</control> module type.
-  ![IntelliJ Platform Plugin Module](intellij_platform_plugin_module.png)
-  <br/>
-  <br/>
-* Enter your desired plugin name.
-* Go to <menupath>File | Project Structure</menupath> and select the newly created *IntelliJ Platform SDK* as the default SDK for the plugin module:
-  ![Set Plugin Module SDK](set_plugin_module_sdk.png)
-
-### Adding Code to the Project
-
-Before running the new project, add some code to provide simple functionality.
-See the [](working_with_custom_actions.md) tutorial for step-by-step instructions for adding a menu action.

topics/basics/getting_started/deploying_plugin.md

@@ -1,26 +0,0 @@
-[//]: # (title: Deploying a Plugin)
-
-<!-- Copyright 2000-2022 JetBrains s.r.o. and other contributors. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file. -->
-
-Before your custom plugin can be used, it must be deployed: built, installed, and then enabled using Plugin Manager.
-
-To deploy a plugin:
-
-* Make your project by invoking <menupath>Build | Build Project</menupath> or <menupath>Build | Build Module $MODULE_NAME$</menupath>.
-* Prepare your plugin for deployment.
-  In the main menu, select <menupath>Build | Prepare Plugin Module $MODULE_NAME$ for Deployment</menupath>.
-
-  ![Prepare Plugin for Deployment](prepare_plugin_for_deployment.png)
-
-* If the plugin module does not depend on any libraries, a JAR archive will be created.
-  Otherwise, a ZIP archive will be created, including all the plugin libraries specified in the project settings.
-
-  ![Jar Saved Notification](jar_saved_notification.png)
-
-* [Install](https://www.jetbrains.com/help/idea/managing-plugins.html#installing-plugins-from-disk)
-  the newly created archive/jar file from disk.
-  The `editor_basics` code sample builds the plugin archive/jar into the `editor_basics` project folder:
-
-  ![Jar File Location](jar_location.png)
-
-* Restart your IDE so the changes will take effect.

topics/basics/getting_started/plugin/developing_plugins.md

@@ -0,0 +1,46 @@
+[//]: # (title: Developing a Plugin)
+
+<!-- Copyright 2000-2022 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. -->
+
+<excerpt>Develop an IntelliJ Platform plugin using Gradle and Gradle IntelliJ Plugin.</excerpt>
+
+> In some cases, implementing an actual IntelliJ Platform plugin might not be necessary, as [alternative solutions](plugin_alternatives.md) exist.
+>
+{type="tip"}
+
+IntelliJ Platform plugins can be developed by using either [IntelliJ IDEA Community Edition](https://www.jetbrains.com/idea/download/) or [IntelliJ IDEA Ultimate](https://www.jetbrains.com/idea/download/) as your IDE (it is highly recommended to use the latest available version).
+Both include the complete set of plugin development tools.
+To become more familiar with IntelliJ IDEA, please refer to the [IntelliJ IDEA Web Help](https://www.jetbrains.com/idea/help/).
+
+## Gradle IntelliJ Plugin
+
+The recommended solution for building IntelliJ Platform plugins is [](tools_gradle_intellij_plugin.md).
+The IntelliJ IDEA Ultimate and Community editions bundle the necessary plugins to support Gradle-based plugin development: _Gradle_ and _Plugin DevKit_.
+To verify these plugins are installed and enabled, see the help section about [Managing Plugins](https://www.jetbrains.com/help/idea/managing-plugins.html).
+
+Gradle IntelliJ Plugin manages the dependencies of a plugin project - both the base IDE and other [plugin dependencies](plugin_dependencies.md).
+It provides tasks to run the IDE with your plugin and to package and [publish](publishing_plugin.md#publishing-plugin-with-gradle) your plugin to the [JetBrains Marketplace](https://plugins.jetbrains.com).
+To make sure that a plugin is not affected by [API changes](api_changes_list.md), which may happen between major releases of the platform, you can quickly verify your plugin against other IDEs and releases.
+
+There are two main ways of creating a new Gradle-based IntelliJ Platform plugin project:
+- dedicated generator available in the [New Project Wizard](https://www.jetbrains.com/help/idea/new-project-wizard.html) - it creates a minimal plugin project with all the required files
+- [](plugin_github_template.md) available on GitHub - in addition to the required project files, it includes configuration of the GitHub Actions CI workflows
+
+This documentation section describes plugin structure generated with the <control>New Project</control> wizard, but the project generated with _IntelliJ Platform Plugin Template_ covers all the described files and directories.
+See the [](plugin_github_template.md) section for more information about the advantages of this approach and instructions on how to use it.
+
+> The old Plugin DevKit workflow still supports existing projects and is recommended for [creating theme plugins](developing_themes.md).
+See how to [migrate a DevKit plugin to Gradle-based](migrating_plugin_devkit_to_gradle.md).
+>
+{type="tip"}
+
+> A dedicated [SBT plugin](https://github.com/JetBrains/sbt-idea-plugin) is available for plugins implemented in Scala.
+>
+{type="tip"}
+
+## Plugin Development Workflow
+
+* [Creating a Gradle-based Plugin Project](creating_plugin_project.md)
+* [Configuring the Gradle IntelliJ Plugin](configuring_plugin_project.md)
+  * [Adding Kotlin Support](using_kotlin.md) (optional)
+* [Publishing a Plugin](publishing_plugin.md)

topics/basics/getting_started/plugin/migrating_plugin_devkit_to_gradle.md

@@ -0,0 +1,22 @@
+[//]: # (title: Migrating DevKit Plugin to Gradle)
+
+<!-- Copyright 2000-2022 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. -->
+
+> See [Revamping Plugins #3 – Migrating from DevKit to the Gradle build system](https://blog.jetbrains.com/platform/2021/12/migrating-from-devkit-to-the-gradle-build-system/) blog post for a step-by-step walk-through.
+>
+{type="tip"}
+
+Converting a plugin created with the old DevKit approach (which can be used for [creating themes](creating_theme_project.md)) to a Gradle-based plugin project can be done using the <control>New Project</control> wizard to create a Gradle-based project around the existing DevKit-based project:
+* Ensure the directory containing the DevKit-based IntelliJ Platform plugin project can be fully recovered if necessary.
+* Delete all the artifacts of the DevKit-based project:
+    * <path>.idea</path> directory
+    * <path>[modulename].iml</path> file
+    * <path>out</path> directory
+* Arrange the existing source files within the project directory in the Gradle [source set](https://docs.gradle.org/current/userguide/java_plugin.html#sec:java_project_layout) format.
+* Use the <control>[New Project](creating_plugin_project.md#create-ide-plugin)</control> wizard as though creating a new Gradle-based plugin project from scratch. On the <control>New Project</control> page choose the <control>IDE Plugin</control> generator and set the values of:
+    * <control>Group</control> to the existing package in the initial source set.
+    * <control>Artifact</control> to the name of the existing plugin.
+    * <control>Name</control> to the name of the directory where the existing plugin is located, e.g. if the plugin project base directory is <path>/Users/john/Projects/old_plugin</path>, it should be the <path>old_plugin</path>.
+    * <control>Location</control> to the name of the plugin's parent directory, e.g. if the plugin project base directory is <path>/Users/john/Projects/old_plugin</path>, it should be the <path>/Users/john/Projects</path>.
+* Click <control>Finish</control> to create the new Gradle-based plugin.
+* [Add more modules](https://www.jetbrains.com/help/idea/gradle.html#gradle_add_module) using Gradle [source sets](https://www.jetbrains.com/help/idea/gradle.html#gradle_source_sets) as needed.

topics/basics/getting_started/plugin_compatibility.md

@@ -48,7 +48,7 @@ The following table lists modules that are currently available in all products.
 
 | Module for [`<depends>`](plugin_configuration_file.md#idea-plugin__depends) Element<br/>Declaration in <path>plugin.xml</path> File | <br/>Functionality                                                                                            |
 |-------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------|
-| **`com.intellij.modules.platform`**                                                                                                 | Messaging, UI Themes, UI Components, Files, Documents, Actions, Components, Services, Extensions, Editors     |
+| **`com.intellij.modules.platform`**                                                                                                 | Messaging, Themes, UI Components, Files, Documents, Actions, Components, Services, Extensions, Editors        |
 | `com.intellij.modules.lang`                                                                                                         | File Type, Lexer, Parser, Highlighting, References, Code Completion, Find, Rename, Formatter, Code Navigation |
 | `com.intellij.modules.xml`                                                                                                          | XML, XML DOM, XSD/DTD, DOM Model                                                                              |
 | `com.intellij.modules.vcs`                                                                                                          | VCS Revision Numbers, File Status, Change Lists, File History, Annotations                                    |
@@ -273,9 +273,9 @@ Continuing the example, search the PHP plugin's <path>plugin.xml</path> file for
 
 Before marking a plugin project as _dependent only on modules in a target product_ in addition to `com.intellij.modules.platform`, verify the plugin isn't implicitly dependent on any APIs that are specific to IntelliJ IDEA.
 
-For [Gradle-based](gradle_build_system.md) projects, [](verifying_plugin_compatibility.md#plugin-verifier) can be used to ensure compatibility with all specified target IDEs.
+For [Gradle-based](developing_plugins.md) projects, [](verifying_plugin_compatibility.md#plugin-verifier) can be used to ensure compatibility with all specified target IDEs.
 
-For [DevKit-based](using_dev_kit.md) projects, create an SDK pointing to an installation of the intended target IntelliJ Platform-based product, e.g., PhpStorm, rather than IntelliJ IDEA.
+For DevKit-based projects, [create an SDK](setting_up_theme_environment.md#add-intellij-platform-plugin-sdk) pointing to an installation of the intended target IntelliJ Platform-based product, e.g., PhpStorm, rather than IntelliJ IDEA.
 Use the same development version of the IntelliJ platform as the targeted product.
 
 Based on the tables above, the [JetBrains Marketplace](https://plugins.jetbrains.com/) automatically detects the JetBrains products with which a plugin is compatible, and makes the compatibility information available to plugin authors.

topics/basics/getting_started/publishing_plugin.md

@@ -2,18 +2,16 @@
 
 <!-- Copyright 2000-2022 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. -->
 
-When your plugin is ready, you can publish it to a plugin repository so that other users can install it.
-You can choose to publish it on the [JetBrains Marketplace](https://plugins.jetbrains.com) or a [](custom_plugin_repository.md).
+When your plugin is ready, you can publish it to a [JetBrains Marketplace](https://plugins.jetbrains.com) plugin repository so that other users can install it in IDE.
+The first plugin publication, even when a project uses the Gradle setup, must be [uploaded manually](#uploading-a-plugin-to-jetbrains-marketplace).
 
-> Please make sure to follow the guidelines from [Plugin Overview page](https://plugins.jetbrains.com/docs/marketplace/plugin-overview-page.html) for an optimal presentation of your plugin on JetBrains Marketplace.
->
-> The _Busy Plugin Developers. Episode 2_ discusses [5 tips for optimizing JetBrains Marketplace plugin page](https://youtu.be/oB1GA9JeeiY?t=52) in more detail.
->
-> See also [](marketing.md) about widgets and badges.
->
-{type="tip"}
+Before publishing a plugin, please make sure to follow the guidelines from [Plugin Overview page](https://plugins.jetbrains.com/docs/marketplace/plugin-overview-page.html) for an optimal presentation of your plugin on JetBrains Marketplace.
+The _Busy Plugin Developers. Episode 2_ discusses [5 tips for optimizing JetBrains Marketplace plugin page](https://youtu.be/oB1GA9JeeiY?t=52) in more detail.
+See also [](marketing.md) about widgets and badges.
 
-## Publishing to JetBrains Marketplace
+> If you plan to publish your plugin to a repository _other than_ the [JetBrains Marketplace](https://plugins.jetbrains.com), please refer to the [](custom_plugin_repository.md) documentation.
+
+## Uploading a Plugin to JetBrains Marketplace
 
 Before publishing your plugin, make sure it is signed.
 For more details on generating a proper certificate and configuring the signing process, check the [Plugin Signing](plugin_signing.md) article.
@@ -41,10 +39,143 @@ See also [Marketplace Docs](https://plugins.jetbrains.com/docs/marketplace/uploa
 
 ### Uploading a New Version
 
-When using Gradle, use the provided tasks as described in [](deployment.md).
-
 New versions can be uploaded manually on the plugin's detail page, see [Marketplace Docs](https://plugins.jetbrains.com/docs/marketplace/plugin-updates.html) for details.
 
-## Publishing a Plugin to a Custom Plugin Repository
+## Publishing Plugin With Gradle
 
-If you plan to publish your plugin to a repository _other than_ the [JetBrains Marketplace](https://plugins.jetbrains.com), please refer to the [](custom_plugin_repository.md) documentation.
+Once you have [configured Gradle support](configuring_plugin_project.md), and [uploaded the plugin](#uploading-a-plugin-to-jetbrains-marketplace) to the plugin repository at least once, you can automatically build and deploy your plugin to the [JetBrains Marketplace](https://plugins.jetbrains.com).
+
+### Building Distribution
+
+For initial upload, manual distribution or local installation, invoke the [`buildPlugin`](tools_gradle_intellij_plugin.md#tasks-buildplugin) Gradle task to create the plugin distribution.
+The resulting ZIP file is located in <path>build/distributions</path> and can then be installed via drag & drop (or using [plugin manager](https://www.jetbrains.com/help/idea/managing-plugins.html#installing-plugins-from-disk))
+or uploaded to a [](custom_plugin_repository.md).
+
+### Providing Your Personal Access Token to Gradle
+
+To deploy a plugin to the JetBrains Marketplace, you need to supply your Personal Access Token, which you can find on your profile page, in [My Tokens](https://plugins.jetbrains.com/author/me/tokens) section.
+
+To create a new token, provide its name and click the <control>Generate Token</control> button.
+A new token will be created and displayed right below.
+
+> Copy it before you close this page and keep it in a secure location.
+> This is the only time the token is visible.
+>
+{type="note"}
+
+This section describes two options to supply your _Personal Access Token_ via Gradle using:
+* Environment variables,
+* Parameters to the Gradle task.
+
+#### Using Environment Variables
+
+Start by defining an environment variable such as:
+
+```bash
+export ORG_GRADLE_PROJECT_intellijPublishToken='YOUR_TOKEN'
+```
+
+> On macOS systems, environment variables set in <path>.bash_profile</path> are only visible to processes you run from bash.
+> Environment variables visible to all processes need to be defined in [Environment.plist](https://developer.apple.com/library/archive/qa/qa1067/_index.html).
+>
+{type="note"}
+
+Now provide the environment variable in the run configuration with which you run the [`publishPlugin`](tools_gradle_intellij_plugin.md#tasks-publishplugin) task locally.
+To do so, create a Gradle run configuration (if not already done), choose your Gradle project, specify the [`publishPlugin`](tools_gradle_intellij_plugin.md#tasks-publishplugin) task, and then add the environment variable.
+
+<tabs group="languages">
+<tab title="Kotlin" group-key="kotlin">
+
+```kotlin
+publishPlugin {
+  token.set(System.getenv("ORG_GRADLE_PROJECT_intellijPublishToken"))
+}
+```
+
+</tab>
+<tab title="Groovy" group-key="groovy">
+
+```groovy
+publishPlugin {
+  token = System.getenv("ORG_GRADLE_PROJECT_intellijPublishToken")
+}
+```
+
+</tab>
+</tabs>
+
+
+Note that you still need to put some default values (can be empty) in the Gradle properties because otherwise, you will get a compilation error.
+
+#### Using Parameters for the Gradle Task
+
+Like using environment variables, you can also pass your token as a parameter to the Gradle task.
+For example, you can provide the parameter
+
+```bash
+-Dorg.gradle.project.intellijPublishToken=YOUR_TOKEN
+```
+on the command line or by putting it in the arguments of your Gradle run configuration.
+
+Note that also, in this case, you still need to put some default values in your Gradle properties.
+
+### Deploying a Plugin with Gradle
+
+The first step when deploying a plugin is to confirm that it works correctly.
+You may wish to verify this by [installing your plugin from disk](https://www.jetbrains.com/help/idea/managing-plugins.html) on a fresh instance of your target IDE(s).
+
+#### Signing a Plugin
+
+The Marketplace signing is designed to ensure that plugins are not modified over the course of the publishing and delivery pipeline.
+In version `1.x`, the Gradle IntelliJ Plugin provides the [`signPlugin`](tools_gradle_intellij_plugin.md#tasks-signplugin) task, which will be executed automatically right before the [`publishPlugin`](tools_gradle_intellij_plugin.md#tasks-publishplugin).
+
+For more details on generating a proper certificate and configuring the [`signPlugin`](tools_gradle_intellij_plugin.md#tasks-signplugin) task, check the [Plugin Signing](plugin_signing.md) article.
+
+#### Publishing a Plugin
+
+Once you are confident the plugin works as intended, make sure the plugin version is updated, as the JetBrains Marketplace won't accept multiple artifacts with the same version.
+
+To deploy a new version of your plugin to the JetBrains Marketplace, invoke the [`publishPlugin`](tools_gradle_intellij_plugin.md#tasks-publishplugin) Gradle task.
+
+Now check the most recent version of your plugin on the [JetBrains Marketplace](https://plugins.jetbrains.com/).
+If successfully deployed, any users who currently have your plugin installed on an available version of the IntelliJ Platform are notified of a new update available as soon as the update has been verified.
+
+### Specifying a Release Channel
+
+You may also deploy plugins to a release channel of your choosing, by configuring the [`publishPlugin.channels`](tools_gradle_intellij_plugin.md#publishplugin-task-channels) property.
+For example:
+
+<tabs group="languages">
+<tab title="Kotlin" group-key="kotlin">
+
+```kotlin
+publishPlugin {
+  channels.set(listOf("beta"))
+}
+```
+
+</tab>
+<tab title="Groovy" group-key="groovy">
+
+```groovy
+publishPlugin {
+  channels = ['beta']
+}
+```
+
+</tab>
+</tabs>
+
+When empty, this uses the default plugin repository, available to all [JetBrains Marketplace](https://plugins.jetbrains.com/) users.
+However, you can publish it to an arbitrarily-named channel.
+These non-default release channels are treated as separate repositories.
+
+When using a non-default release channel, users need to configure a new [custom plugin repository](https://www.jetbrains.com/help/idea/managing-plugins.html#repos) in their IDE to install your plugin.
+For example, if you specify `publishPlugin.channels = ['canary']`, then users need to add the `https://plugins.jetbrains.com/plugins/canary/list` repository to install the plugin and receive updates.
+
+Popular channel names include:
+* `alpha`: https://plugins.jetbrains.com/plugins/alpha/list
+* `beta`: https://plugins.jetbrains.com/plugins/beta/list
+* `eap`: https://plugins.jetbrains.com/plugins/eap/list
+
+More information about the available configuration options is in the [documentation of the IntelliJ Gradle Plugin](tools_gradle_intellij_plugin.md#tasks-publishplugin).

topics/basics/getting_started/running_and_debugging_a_plugin.md

@@ -1,21 +0,0 @@
-[//]: # (title: Running and Debugging a Plugin)
-
-<!-- Copyright 2000-2022 JetBrains s.r.o. and other contributors. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file. -->
-
-It's possible to run and debug a plugin directly from the IntelliJ IDEA.
-You need a configured special profile (a *Plugin* Run/Debug configuration) that specifies the plugin module, VM parameters, and other specific options.
-When you run such a profile, it launches the IDE with your plugin installed.
-
-See [](ide_development_instance.md) for more information about configuration and advanced settings.
-
-For information on how to change the Run/Debug configuration profile, refer to [Run/Debug Configuration](https://www.jetbrains.com/help/idea/run-debug-configuration.html) and [Run/Debug Configuration: Plugin](https://www.jetbrains.com/idea/help/run-debug-configuration-plugin.html) in IntelliJ IDEA Web Help.
-
-Using IntelliJ IDEA's debugger, you can find out the origin of the run-time errors and exceptions.
-
-**To debug a plugin**
-
-*  Select <menupath>Run | Debug...</menupath> in the main menu, or press <shortcut>Shift+F9</shortcut>.
-
-**To run a plugin**
-
-* Select <menupath>Run | Run...</menupath> in the main menu, or press <shortcut>Shift+F10</shortcut>.

topics/basics/getting_started/setting_up_environment.md

@@ -1,63 +0,0 @@
-[//]: # (title: Setting Up a Development Environment)
-
-<!-- Copyright 2000-2022 JetBrains s.r.o. and other contributors. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file. -->
-
-> For new projects, it is highly recommended to use [Gradle-based setup](getting_started.md).
->
-{type="note"}
-
-### Preliminary Steps
-
-Use the following checklist to ensure that you are ready to develop your custom plugins.
-- **Plugin DevKit** plugin must be [enabled in IntelliJ IDEA](https://www.jetbrains.com/help/idea/managing-plugins.html).
-- **IntelliJ Platform SDK** must be configured for your IDEA project.
-  For more information, see below.
-- (_Optional_) **Get IntelliJ IDEA CE source code** on your local computer.
-  Getting IntelliJ IDEA CE source code is not a requirement for plugin development, but having it makes debugging your plugins much more straightforward.
-  For detailed instructions, refer to the _Getting IntelliJ IDEA Community Edition Source Code_ section of [Check Out And Build Community Edition](%gh-ic%/README.md).
-  Note that building IntelliJ IDEA CE from source code is not required for plugin development.
-
-### Configuring IntelliJ Platform SDK
-
-> For more information about SDKs, see [SDKs section](https://www.jetbrains.com/help/idea/working-with-sdks.html) in the IntelliJ IDEA Web Help.
-
-To set up your plugin development environment:
-
-* Set up a required Java SDK.
-  See the _IntelliJ Build Configuration_ section of [Check Out And Build Community Edition](%gh-ic%/README.md) for instructions about creating **1.8** (**11** when targeting 2020.3 or later) Java SDK.
-
-> Do not use a more recent Java version than the one specified.
->
-{type="warning"}
-
-* Create a new <control>IntelliJ Platform Plugin SDK</control> under <menupath>File | Project Structure</menupath>:
-  ![Create IntelliJ Platform SDK](create_intellij_idea_sdk.png)
-  <br/>
-  <br/>
-* Specify the installation folder of the *IntelliJ IDEA Community Edition* as the home directory (on Mac, select application icon in <path>/Applications/</path>).
-  You can use the installation package built from sources or download it from the [Download IntelliJ IDEA page](https://www.jetbrains.com/idea/download/).
-  > You may use IntelliJ IDEA Ultimate as an alternative, but debugging the core code will only work with the *Community Edition*.
-  ![Set Home Directory](set_home_directory.png)
-  <br/>
-  <br/>
-* Select Java SDK from the first step as the default Java SDK.
-  ![Set IDEA JDK](set_java_sdk.png)
-  <br/>
-  <br/>
-* In the <control>Sourcepath</control> tab of the SDK settings, click the <control>Add</control> button (_this step can be skipped if your plugin doesn't require debugging_):
-  ![Add Sourcepath](add_sourcepath.png)
-  <br/>
-  <br/>
-* Specify the source code directory for the *IntelliJ IDEA Community Edition*:
-  ![Specify Source Paths](community_sources_directory.png)
-  <br/>
-  <br/>
-* Specify the <control>Sandbox Home</control> directory.
-  The <control>Sandbox Home</control> directory stores the settings of the IDE development instance launched from a Plugin Project's run configuration.
-  Shown below is the default <control>Sandbox Home</control> directory for a user on macOS.
-  Any directory can be chosen as the <control>Sandbox Home</control> location.
-  Use the ellipsis button (shown below) to define a custom location.
-
-  See the [IDE Development Instances](ide_development_instance.md) page for more information about the default <control>Sandbox Home</control> directory locations and contents.
-
-  ![Specify Sandbox Path](plugins-sandbox.png)

topics/basics/getting_started/theme/creating_theme_project.md

@@ -0,0 +1,63 @@
+[//]: # (title: Creating a Theme Project)
+
+<!-- Copyright 2000-2022 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. -->
+
+This documentation page describes a DevKit-based theme project generated with the [New Project Wizard](https://www.jetbrains.com/help/idea/new-project-wizard.html).
+
+## Creating a Theme with New Project Wizard
+
+Before creating a theme project, make sure that [development environment is set up](setting_up_theme_environment.md).
+
+<procedure title="Create Theme Plugin" id="create-theme">
+
+Launch the <control>New Project</control> wizard via the <menupath>File | New | Project...</menupath> action and provide the following information:
+1. Select the <control>IDE Plugin</control> generator type from the list on the left.
+2. Specify the project <control>Name</control> and <control>Location</control>.
+3. Choose the <control>Theme</control> option in the project <control>Type</control>.
+4. As the <control>JDK</control> select the [configured SDK](setting_up_theme_environment.md#configuring-intellij-platform-plugin-sdk).
+5. Click the <control>Create</control> button to generate the project.
+
+</procedure>
+
+### Components of a Wizard-Generated Gradle IntelliJ Platform Theme
+
+For the example `my_theme` created with the steps describes above, the _IDE Plugin_ generator creates the following directory content:
+
+```text
+my_theme
+├── resources
+│   ├── META-INF
+│   │   └── plugin.xml
+│   │   └── pluginIcon.svg
+│   └── theme
+│       └── my_theme.theme.json
+└── my_theme.iml
+```
+
+- <path>META-INF</path> directory with:
+  - <path>[plugin.xml](plugin_configuration_file.md)</path> configuration file containing preconfigured theme provider
+  - <path>pluginIcon.svg</path> file that is a [plugin logo](plugin_icon_file.md)<br/>
+    It is recommended to replace it with a custom icon.
+- <path>my_theme.theme.json</path> - a minimal [theme description file](themes_customize.md#introduction-to-theme-description-file-syntax)
+- <path>my_theme.iml</path> - [IntelliJ IDEA Module](https://www.jetbrains.com/help/idea/creating-and-managing-modules.html) configuration file
+
+See [](theme_structure.md) for more details.
+
+## Additional Plugin Themes
+
+Theme plugin project [created with the new project wizard](#create-theme) contains a single theme description file by default.
+In case a plugin needs to provide multiple themes (e.g., dark and light variants), it is possible to add them with the dedicated action.
+
+Additional plugin themes can be added using the DevKit Theme Wizard, which is a part of the Plugin DevKit bundled in IntelliJ IDEA.
+The wizard can be used for both DevKit-based and Gradle-based plugins.
+
+<procedure title="Add Theme" id="add-theme">
+
+1. In the <control>Project</control> tool window, select the <path>resources</path> directory and invoke the context menu with the right click.
+2. Select the <menupath>New | Plugin DevKit | Theme</menupath> action.<br/>
+   It is a good practice to include the name of the plugin in the created theme name.
+3. Check the <control>Dark theme</control> checkbox if the created theme should be based on IntelliJ IDEA _Darcula_ theme.
+   Otherwise, the _Light_ theme will be used as the base.
+4. Click <control>OK</control> button to generate the [theme description file](themes_customize.md#introduction-to-theme-description-file-syntax) with <path>$THEME_NAME$.theme.json</path> name. The generated theme will be automatically configured in the <path>plugin.xml</path> file.
+
+</procedure>

topics/basics/getting_started/theme/deploying_theme.md

@@ -0,0 +1,19 @@
+[//]: # (title: Deploying a Theme)
+
+<!-- Copyright 2000-2022 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. -->
+
+Before your custom theme plugin can be [uploaded to JetBrains Marketplace](publishing_plugin.md#uploading-a-plugin-to-jetbrains-marketplace) and used by users, it should be packaged and verified in the actual IDE.
+
+The deployment process prepares the plugin artifact that can be installed in IDE.
+
+<procedure title="Deploying Theme Plugin">
+
+1. Build the theme by invoking <menupath>Build | Build Project</menupath> or <menupath>Build | Build Module $MODULE_NAME$</menupath>.
+2. Create the deployment artifact by invoking <menupath>Build | Prepare Plugin Module $MODULE_NAME$ for Deployment</menupath>.<br/>
+   The resulting theme JAR file will be created in the project or module directory.<br/>
+   In the case of developing a regular plugin, and it specifies additional dependencies, a&nbsp;ZIP archive is created, including all the plugin libraries.
+3. [Install](https://www.jetbrains.com/help/idea/managing-plugins.html#installing-plugins-from-disk) the newly created JAR or ZIP file from disk.
+4. Click the <control>Apply</control> button.
+5. Select your theme in <menupath>Preferences | Appearance & Behavior | Appearance</menupath> and apply the changes.
+
+</procedure>

topics/basics/getting_started/theme/developing_themes.md

@@ -0,0 +1,16 @@
+[//]: # (title: Developing a Theme)
+
+<!-- Copyright 2000-2022 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. -->
+
+<excerpt>Develop an IntelliJ Platform-based IDE theme using Plugin DevKit.</excerpt>
+
+This documentation section will help you get started with developing theme plugins for the IntelliJ Platform-based IDEs.
+
+The DevKit-based theme development workflow includes:
+
+* [Setting Up a Development Environment](setting_up_theme_environment.md)
+* [Creating a Theme Project](creating_theme_project.md)
+* [Customizing a Theme](themes_customize.md)
+* [Building and Running a Theme](running_and_debugging_a_theme.md)
+* [Deploying a Theme in IDE](deploying_theme.md)
+* [Uploading a Theme to JetBrains Marketplace](publishing_plugin.md#uploading-a-plugin-to-jetbrains-marketplace)

topics/basics/getting_started/theme/running_and_debugging_a_theme.md

@@ -0,0 +1,35 @@
+[//]: # (title: Running and Debugging a Theme)
+
+<!-- Copyright 2000-2022 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. -->
+
+In most cases, the results of theme plugin can be previewed by running the <control>Preview Theme</control> action in the [theme description file](themes_customize.md) editor.
+Sometimes, when more advanced styling options are implemented, the previewing theme may not be enough to see all the changes.
+This page explains how to run or debug the theme plugin in the IDE configured as a part of [project SDK](setting_up_theme_environment.md).
+
+## Create Plugin Run Configuration
+
+To run and debug a plugin directly from a theme plugin project, a _Plugin_ run configuration must be added.
+
+> For more information about creating Run Configurations, refer to the [Run/Debug Configuration](https://www.jetbrains.com/help/idea/run-debug-configuration.html) section in IntelliJ IDEA Web Help.
+>
+{type="tip"}
+
+<procedure title="Add Plugin Run Configuration">
+
+1. Go to <menupath>Run | Edit Configurations...</menupath>.
+2. Click the <control>Add New Configuration...</control> button (<control>+</control>) and select the <control>Plugin</control> type.
+3. Provide the configuration <control>Name</control>, e.g., _Run Theme_.
+4. Ensure that <control>Use classpath of module</control> specifies the current theme plugin module.
+5. Click the <control>Apply</control> button.
+
+{type="tip"}
+
+</procedure>
+
+See the [](ide_development_instance.md) section for information about advanced run configuration settings.
+If additional settings, like system property, are needed, see [Run/Debug Configuration: Plugin](https://www.jetbrains.com/idea/help/run-debug-configuration-plugin.html) explaining how to configure them.
+
+## Run/Debug Theme Plugin
+
+To run the theme in the IDE development instance, choose <menupath>Run | Run...</menupath> and select the created run configuration.
+Debugging a theme is similar, but instead of <control>Run...</control>, select the <control>Debug...</control> action.

topics/basics/getting_started/theme/setting_up_theme_environment.md

@@ -0,0 +1,72 @@
+[//]: # (title: Setting Up a Development Environment)
+
+<!-- Copyright 2000-2022 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. -->
+
+<procedure title="Preliminary Steps">
+
+Use the following checklist to ensure that you are ready to develop your custom theme:
+
+1. **[IntelliJ IDEA Community Edition](https://www.jetbrains.com/idea/download/)** or **[IntelliJ IDEA Ultimate](https://www.jetbrains.com/idea/download/)** is installed.
+2. **Plugin DevKit** plugin is [enabled in IntelliJ IDEA](https://www.jetbrains.com/help/idea/managing-plugins.html).
+3.  **IntelliJ IDEA CE source code** is checked-out. _(Optional)_<br/>
+  This step is needed only when you plan to debug the IntelliJ Platform code.
+  See [](#get-intellij-idea-ce-source-code) for more details.
+4. **IntelliJ Platform SDK** is [configured](#configuring-intellij-platform-plugin-sdk).
+
+</procedure>
+
+## Get IntelliJ IDEA CE Source Code
+
+Getting the IntelliJ IDEA CE source code is not a requirement for theme development as debugging the platform code while developing a theme is a rare situation.
+In case you are developing a plugin extending IDE behavior, or you need to understand how some components work internally, having sources makes debugging much more straightforward.
+
+For detailed instructions on how to check out the code efficiently, refer to the _Getting IntelliJ IDEA Community Edition Source Code_ section of [IntelliJ IDEA Community Edition README file](%gh-ic%/README.md).
+Note that building the checked-out sources is not required in this case.
+
+## Configuring IntelliJ Platform Plugin SDK
+
+> For more information about SDKs, see [SDKs section](https://www.jetbrains.com/help/idea/working-with-sdks.html) in the IntelliJ IDEA Web Help.
+
+### Download IntelliJ-based IDE
+
+To see the effects of the developed plugin in real IDE, it is required to run the plugin in an [](ide_development_instance.md).
+In most cases, it is enough to download and use _[IntelliJ IDEA](https://www.jetbrains.com/idea/download/) Community Edition_.
+If it is required to style components used only in a specific IDE like _IntelliJ IDEA Ultimate_ or _WebStorm_, they can also be used as SDK, but debugging the core code will only work with the _IntelliJ IDEA Community Edition_.
+
+### Add JDK and IntelliJ Platform Plugin SDK
+
+The first step of configuring a theme plugin SDK is adding the JDK.
+
+> When targeting 2020.3 and later only, using Java 11 is required.
+> See the [IntelliJ project migrates to Java 11](https://blog.jetbrains.com/platform/2020/09/intellij-project-migrates-to-java-11/) blog post for details.
+>
+> When targeting 2022.2 and later only, using Java 17 is required.
+>
+{type="note"}
+
+<procedure title="Add JDK" id="add-jdk">
+
+1. Go to <menupath>File | Project Structure | Platform Settings | SDKs</menupath>.
+2. Click the <control>Add</control> button (<control>+</control>).
+3. If you have the required JDK installation on your machine, and it is detected, select it from the <control>Detected SDKs</control> list.
+  If your JDK is not detected, select the <control>Add JDK...</control> option and choose the installation folder.<br/>
+  If the required JDK is not installed on your machine, the simplest option is using <control>Download JDK...</control> and choosing the distribution options.
+4. Click the <control>Apply</control> button.
+
+</procedure>
+
+The second step is adding IntelliJ Platform Plugin SDK that will use the JDK configured in the first step.
+
+<procedure title="Add IntelliJ Platform Plugin SDK" id="add-intellij-platform-plugin-sdk">
+
+1. Go to <menupath>File | Project Structure | Platform Settings | SDKs</menupath>.
+2. Click the <control>Add</control> button (<control>+</control>).
+3. Select the <control>Add IntelliJ Platform Plugin SDK...</control> option.
+4. Choose the installation folder of the IDE [downloaded previously](#download-intellij-based-ide) (on macOS, select application icon in <path>/Applications/</path>).
+5. In the <control>Select Internal Java Platform</control> dialog, select the JDK configured in the [previous step](#add-jdk) and click <control>OK</control> button.
+6. In the added SDK, specify the <control>Sandbox Home</control> directory.<br/>
+   See [](ide_development_instance.md#the-development-instance-sandbox-directory) for details.
+7. If debugging is required, select the <control>Sourcepath</control> tab, click the <control>Add</control> button (<control>+</control>) and select the root folder of [the checked-out sources](#get-intellij-idea-ce-source-code).
+8. Click the <control>Apply</control> button.
+
+</procedure>

topics/basics/getting_started/theme/theme_structure.md

@@ -0,0 +1,65 @@
+[//]: # (title: Theme Structure)
+
+<!-- Copyright 2000-2022 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. -->
+
+Themes are components within [IntelliJ Platform plugins](plugin_structure.md).
+The theme plugins should be stand-alone and not combined with other plugin functionality.
+
+> To see a full example theme project, see the [Theme Basics](https://github.com/JetBrains/intellij-sdk-code-samples/tree/main/theme_basics) in IntelliJ SDK Code Samples.
+>
+{type="note"}
+
+Themes have several components:
+* A required Theme description (JSON) file in the plugin project's <path>resources</path> folder.
+* A required `themeProvider` declaration in the plugin's <path>[plugin.xml](plugin_configuration_file.md)</path> file, located in the plugin project's <path>META-INF</path> folder.
+* An optional Editor Scheme description (XML) file derived from an exported IDE editor scheme.
+  This file is located in the plugin project's <path>resources</path> folder.
+* An optional background image file, located in the plugin project's <path>resources</path> folder.
+* Optional icon image files, located in the plugin project's <path>resources</path> folder.
+
+![Theme Components](theme_components.png)
+
+## Theme Description File
+
+The most important file in every theme project is the theme description file.
+The content of the default file generated with the [Theme wizard](creating_theme_project.md) is a short set of key–value pairs:
+
+```json
+{
+  "name": "theme_basics",
+  "author": "",
+  "dark": false,
+  "editorScheme": "/theme_basics.xml",
+  "ui": {
+  }
+}
+```
+
+* `name` key matches the first portion of the Theme description <path>$THEME_NAME$.theme.json</path> file name. The value of `name` is displayed in the [Theme](https://www.jetbrains.com/help/idea/settings-appearance.html) <control>Preferences</control> dropdown when the theme's plugin is installed in the IDE.
+* `author` - specifies the theme author (empty by default).
+* `dark` - determines the base theme (_Light_ or _Darcula_) that is customized.
+* `editorScheme` - specifies the editor scheme file that describes fonts and colors used in editors (see [](themes_extras.md#adding-a-custom-editor-scheme) for more details).
+* `ui` - allows for overriding the base theme (_Light_ or _Darcula_) properties (see [](themes_customize.md#custom-ui-control-colors) for more details).
+
+The wizard also creates a `themeProvider` declaration in the [`<extensions>`](plugin_configuration_file.md#idea-plugin__extensions) section of the plugin's <path>plugin.xml</path> file.
+This declaration binds the theme description file to a theme provider extension using a generated unique `id`.
+
+```xml
+<extensions defaultExtensionNs="com.intellij">
+  <themeProvider
+      id="eb9b7461-397b-4b98-a422-224fc0a74564"
+      path="/theme_basics.theme.json"/>
+</extensions>
+```
+
+> Do not modify or re-use an existing value of the generated `id` attribute.
+>
+{type="warning"}
+
+## Theme Customization
+
+The following sections describe the theme customization possibilities in detail:
+* [](themes_customize.md#customizing-icons)
+* [](themes_customize.md#customizing-ui-controls)
+* [](themes_extras.md#adding-a-custom-editor-scheme)
+* [](themes_extras.md#adding-a-custom-background-image)

topics/basics/getting_started/theme/themes_customize.md

@@ -1,27 +1,32 @@
-[//]: # (title: Customizing UI Themes - Icons and UI Controls)
+[//]: # (title: Customizing Themes - Icons and UI Controls)
 
-<!-- Copyright 2000-2022 JetBrains s.r.o. and other contributors. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file. -->
+<!-- Copyright 2000-2022 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. -->
 
-A UI Theme is customized by adding information to the UI Theme description file that overrides the base (_Light_ or _Darcula_) UI Theme.
+A theme is customized by adding information to the theme description file that overrides the base (_Light_ or _Darcula_) theme.
+
+For plugin developers, [Exposing Theme Metadata](themes_metadata.md) discusses the format of customization keys and information about how to provide it to Theme authors.
 
 > [Color Highlighter Plugin](https://plugins.jetbrains.com/plugin/13309-color-highlighter) adds additional color preview inside the editor.
 >
 {type="tip"}
 
-## Introduction to UI Theme Description File Syntax
+## Introduction to Theme Description File Syntax
+
 The syntax of a Theme description file follows the JSON open-standard file format of key-value pairs.
-The minimum valid default file is the output of the [DevKit Theme Wizard](themes.md#creating-a-ui-theme-with-the-devkit-theme-wizard).
+The minimum valid default file is the output of the [DevKit Theme Wizard](creating_theme_project.md).
 Adding key-value pairs customizes a Theme.
 
-UI Theme key-value pairs often use color as the `value`.
+Theme key-value pairs often use color as the `value`.
 Colors are defined by six-digit RGB or eight-digit RGBA hexadecimal notation.
 
-### UI Theme Reference Implementations
+### Theme Reference Implementations
+
 When learning new syntax, it is often useful to have some existing implementations for reference.
 For example, refer to the [Theme description file](%gh-ic%/platform/platform-resources/src/themes/HighContrast.theme.json) for the IntelliJ IDEA _High Contrast_ Theme.
-It may also help to review some of the [UI Themes available](https://plugins.jetbrains.com/search?headline=164-theme&tags=Theme) at the JetBrains Marketplace.
+It may also help to review [themes available](https://plugins.jetbrains.com/search?headline=164-theme&tags=Theme) at the JetBrains Marketplace.
 
 ## Defining Named Colors
+
 Colors can always be defined individually as six-digit RGB or eight-digit RGBA hexadecimal notation.
 However, Theme definitions often use the same color in multiple places.
 Maintaining a Theme is more manageable if _Named Colors_ are globally defined in a `colors {}` block as part of the <path>*.theme.json</path> file.
@@ -46,14 +51,16 @@ For example, defining the Named Color `basicBackground` and then using it to set
 ```
 
 ## Customizing Icons
-UI themes can customize the color of default IntelliJ Platform UI icons or substitute custom icons for the default ones.
+
+Themes can customize the color of default IntelliJ Platform UI icons or substitute custom icons for the default ones.
 Customization is done by adding an `"icons": {}` section to the Theme description file.
 
 ### Overriding the Global Color of Icons
+
 Default global icon colors are customized by adding key-value pairs to a `"ColorPalette": {}` section.
 The `ColorPalette` must be inserted in the `icons` section.
 
-In the following example, the `key` - the default red color (#DB5860) used for `Action` icons in the _Light_ Theme - is overridden to the `value` of a different color (#D61A26):
+In the following example, the `key` - the default red color (`#DB5860`) used for `Action` icons in the _Light_ Theme - is overridden to the `value` of a different color (`#D61A26`):
 
 ```json
 {
@@ -68,9 +75,11 @@ In the following example, the `key` - the default red color (#DB5860) used for `
 This color substitution is applied throughout the IDE UI.
 
 ### Custom Icon Palette Colors
-Icon Palettes are predefined UI Theme color keys that describe a single color in an `Actions` or `Objects` context.
+
+Icon Palettes are predefined theme color keys that describe a single color in an `Actions` or `Objects` context.
 
 #### Icon Colors in "Actions" and "Objects" Contexts
+
 IntelliJ Platform has default icon colors defined for `Actions` and `Objects` contexts.
 * `Actions` are Theme keys for icons that appear in the context of toolbars, and represent actions such as _Compile_, _Run_, or _Debug_.
 * `Objects` are Theme keys for icons that appear in the contexts of lists and trees, and represent entities like files, symbols, or run and debug configurations.
@@ -79,6 +88,7 @@ The [JetBrains Platform UI Guideline for Icons](https://jetbrains.design/intelli
 Note that this document refers to `Objects` keys as "Noun icons."
 
 #### Customizing "Actions" and "Objects" Icon Colors
+
 An icon Palette color is customized by adding an `Actions` or `Objects` `key` and custom color `value` to the `"ColorPalette": {}` section in a Theme description file.
 The list of available icon `Actions` and `Objects` keys are provided by the editor's completion popup:
 
@@ -100,6 +110,7 @@ This more specific change to the `Actions.Blue` color overrides the default defi
 In the narrower context of blue `Actions` icons, it will also supersede any global color overrides of the default blue icon color.
 
 ### Custom Icons
+
 The default IntelliJ Platform UI icons can be replaced by custom icons.
 The file format for icons is SVG.
 The [JetBrains Platform UI Guideline for Icons](https://jetbrains.design/intellij/principles/icons/) has detailed specifications for icons.
@@ -112,7 +123,7 @@ This path is derived from the `AllIcons.[Group].[IconName]` path in icon section
 
 For example, the _Build_ (hammer) icon in the toolbar has the path `Allcons.Actions.Compile` as reported by the UI Inspector.
 Therefore the `key` for the _Build_ icon is `/actions/compile.svg`.
-The `value` is the replacement icon's file name, located in the `resources` folder of the UI Theme plugin project:
+The `value` is the replacement icon's file name, located in the `resources` folder of the theme plugin project:
 
 ```json
 {
@@ -129,12 +140,14 @@ The color of a replaced icon takes precedence over any `ColorPalette` overrides.
 {type="tip"}
 
 ## Customizing UI Controls
-UI Themes can change the appearance of more general controls in the IntelliJ Platform UI.
+
+Themes can change the appearance of more general controls in the IntelliJ Platform UI.
 Examples of these controls are labels, buttons, checkboxes, trees, lists, and menus.
 
 See also [Platform theme colors — UI components](https://jetbrains.design/intellij/principles/platform_theme_colors/#UI-components) in IntelliJ Platform UI Guidelines.
 
 ### Custom UI Control Colors
+
 A UI control's custom color is specified by adding a key-value pair to the `"ui": {}` section of a Theme description file.
 
 A UI control `key` has the compound format `element.property`, where:
@@ -149,12 +162,13 @@ However, for other purposes, the first section can be considered the `element`,
 Methods for finding UI control keys are in the [Finding Attribute Keys for UI Controls](#finding-attribute-keys-for-ui-controls) section.
 
 #### Customizing All UI Control Colors with the Same Property
+
 All UI Controls with the same `property` portion of their key can be set to the same color.
 This customization is done using the wildcard `"*": {}` section in the Theme description file.
 A key-value pair is inserted in this section, but only the `property` portion of the key is specified.
 The `value` is the custom color.
 
-The following example would change the default background color to #AED7E3 for all UI controls:
+The following example would change the default background color to `#AED7E3` for all UI controls:
 
 ```json
 {
@@ -169,10 +183,11 @@ The following example would change the default background color to #AED7E3 for a
 Note that the wildcard `"*": {}` section must be within the `"ui": {}` section.
 
 #### Customizing the Color of Specific UI Control Types
+
 The color of a specific UI control type is changed by adding a key-value pair to the `"ui": {}` section of a Theme description file.
 The `key` is the full `element.property` format, and the `value` is the custom color.
 
-The following example sets the background color for all labels to the color #F6E9C9
+The following example sets the background color for all labels to the color `#F6E9C9`.
 
 ```json
 {
@@ -188,6 +203,7 @@ The following example sets the background color for all labels to the color #F6E
 The `Label.background` entry supersedes, in the narrower context of label backgrounds, any default color, and any wildcard color assigned to backgrounds.
 
 #### Customizing the Color of UI Tabs
+
 UI Tab colors are changed by [key-value pairs](#custom-ui-control-colors) in a Theme description file.
 
 There are two implementations of tabs in the IntelliJ Platform:
@@ -236,6 +252,7 @@ Note that a Theme file can mix versions of `property` identifiers:
 ```
 
 ### Customizing the Borders of UI Controls
+
 The color and geometry of borders used in UI controls can be customized by key-value pairs in a Theme description file.
 The format of keys for borders is `element.property`, where:
 * `element` is the type of UI control containing a border, such as a window or a popup menu.
@@ -263,11 +280,13 @@ The following example sets a new border width and color for all windows:
 In this example, the customized border supersedes the default definition and any global color override.
 
 ## Finding Attribute Keys for UI Controls
+
 There are hundreds of UI control `element.property` keys defined in the IntelliJ Platform UI.
-Some keys and strategies for applying them can be gleaned from the [UI Theme reference implementations](#ui-theme-reference-implementations).
+Some keys and strategies for applying them can be gleaned from the [theme reference implementations](#theme-reference-implementations).
 For a general search, here some suggested methods for locating UI control keys.
 
 ### Finding a UI Control Key Using Code Completion in the Editor
+
 The preferred method of finding UI control keys is to use the [Code Completion](https://www.jetbrains.com/help/idea/auto-completing-code.html#Auto-Completing_Code.xml) feature in the editor.
 Note that some keys presented by the code completion feature may be deprecated.
 New entries in the `"ui": {}` section will invoke the code completion popup, as shown below:
@@ -280,5 +299,6 @@ In the Quick Documentation popup, the format is e.g., <control>Since: 2019.2</co
 The Code Completion popup is similar, but the format is e.g., <control>[Since 2019.2]</control>.
 
 ### Finding a UI Control Key Using Laf Defaults UI
+
 Using the [Laf Defaults](internal_ui_laf_defaults.md) inspector, enter the `element` portion of the key.
 The Laf Defaults inspector will prompt with a list of UI Control keys and their default color.

topics/basics/getting_started/theme/themes_extras.md

@@ -1,8 +1,8 @@
-[//]: # (title: UI Themes - Editor Schemes and Background Images)
+[//]: # (title: Themes - Editor Schemes and Background Images)
 
 <!-- Copyright 2000-2022 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. -->
 
-UI Themes can also provide custom color and font settings, as well as custom images for display in the IDE application window.
+Themes can also provide custom color and font settings, as well as custom images for display in the IDE application window.
 
 ## Adding a Custom Editor Scheme
 
@@ -14,7 +14,7 @@ These custom color and font settings are called _Editor Color Schemes_.
 Custom editor color schemes can be specified and exported using the IDE _Settings/Preferences_ dialog.
 Note that editor [Colors and Fonts](https://www.jetbrains.com/help/idea/configuring-colors-and-fonts.html), and [Colors for Version Control File Status](https://www.jetbrains.com/help/idea/file-status-highlights.html) are customized in different sections of _Settings/Preferences_.
 
-Use the following procedure to customize an editor color scheme for a UI Theme:
+Use the following procedure to customize an editor color scheme for a theme:
 * Create the desired custom editor color scheme using the IDE preferences.
 * Export the custom editor color scheme to the desired file name.
   In this example, the file is exported to <path>Lightning.icls</path>.
@@ -22,16 +22,16 @@ Use the following procedure to customize an editor color scheme for a UI Theme:
   In this example, the result is <path>Lightning.xml</path>.
 * See [Customizing Editor Scroll Bar Colors](#customizing-editor-scroll-bar-colors) to change the colors of editor scroll bars.
 
-### Incorporating the Editor Color Scheme in the Custom UI Theme
+### Incorporating the Editor Color Scheme in the Custom Theme
 
-The next step is to add the color scheme to the UI Theme plugin project:
+The next step is to add the color scheme to the theme plugin project:
 * Replace the default generated custom editor color scheme XML file (in this example, <path>theme_basics.xml</path>) in the project's <path>resources</path> folder with the exported custom editor color scheme.
   In this case, the action is to _replace_ <path>theme_basics.xml</path> with <path>Lightning.xml</path>.
-* In the UI Theme file (in this example <path>theme_basics.theme.json</path>), replace the name of the generated editor scheme file (<path>theme_basics.xml</path>) with the new (<path>Lightning.xml</path>) file name.
+* In the theme file (in this example <path>theme_basics.theme.json</path>), replace the name of the generated editor scheme file (<path>theme_basics.xml</path>) with the new (<path>Lightning.xml</path>) file name.
   The `key` is always "editorScheme".
   The `value` is the name of the editor color scheme file.
 
-The example below adds an editor scheme named "Lightning" to the _Theme Basics_ custom UI Theme:
+The example below adds an editor scheme named "Lightning" to the _Theme Basics_ custom theme:
 
 ```json
 {
@@ -79,7 +79,7 @@ For additional examples of `FILESTATUS` color `name` attributes, see the editor
 ### Customizing Editor Scroll Bar Colors
 
 Editor scroll bar colors should be coordinated with, and switch together with an editor color scheme.
-Please note that Custom UI Theme (<path>*.theme.json</path>) files also contain `ScrollBar.*` name attributes, but these are for scroll bars outside the context of the editor.
+Please note that custom theme (<path>*.theme.json</path>) files also contain `ScrollBar.*` name attributes, but these are for scroll bars outside the context of the editor.
 
 > The Editor Scroll Bar colors are the only editor scheme settings that cannot be customized and exported through IDE preferences.
 >
@@ -146,9 +146,9 @@ The wildcard portion of these patterns corresponds to the `usage` definitions ab
 The IDE supports setting an image as a background in the application window.
 Users can do this manually in [Preferences](https://www.jetbrains.com/help/idea/setting-background-image.html).
 
-UI Themes support specifying a background image as a key-value pair in the `"background": {}` (for editor and tools) and `"emptyFrameBackground": {}` (for empty frame) sections of a Theme description file:
+Themes support specifying a background image as a key-value pair in the `"background": {}` (for editor and tools) and `"emptyFrameBackground": {}` (for empty frame) sections of a Theme description file:
 * The `image` key uses the file name of the image as the value.
-The background image is placed in the UI Theme plugin project's <path>resources</path> folder.
+The background image is placed in the theme plugin project's <path>resources</path> folder.
 * The `transparency` key uses a `value` of 1-100.
 A `value` of 100 is opaque.
 * The `fill` key uses a value of `scale`, meaning to expand the image to fill the space as the window gets resized.

topics/basics/getting_started/theme/themes_getting_started.md

@@ -0,0 +1,47 @@
+[//]: # (title: Getting Started)
+
+<!-- Copyright 2000-2022 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. -->
+
+Beginning with the 2019.1 release, custom themes are supported.
+Custom themes give designers control of the appearance of built-in UI elements.
+The customization options include:
+
+- substitute icons,
+- change the colors of icons and UI controls,
+- alter the borders and insets of UI controls,
+- provide custom editor schemes,
+- add background images.
+
+The [themes available for download](https://plugins.jetbrains.com/search?headline=164-theme&tags=Theme) illustrate the creative possibilities.
+
+> See the [Themes in IntelliJ-based IDEs](https://blog.jetbrains.com/platform/2021/10/themes-in-intellij-based-ides/) blog post for an overview (available in multiple languages).
+>
+{type="tip"}
+
+## Theme Plugin Development
+
+Themes can be developed by using either [IntelliJ IDEA Community Edition](https://www.jetbrains.com/idea/download/) or [IntelliJ IDEA Ultimate](https://www.jetbrains.com/idea/download/) as your IDE (it is highly recommended to use the latest available version).
+Both include the complete set of development tools required to develop theme plugins.
+To become more familiar with IntelliJ IDEA, please refer to the [IntelliJ IDEA Web Help](https://www.jetbrains.com/idea/help/).
+
+A theme is one of the [plugin types](plugin_types.md#themes).
+Its structure doesn't significantly differ from plugins extending IDE behavior, and can be implemented by using one of the supported approaches: _DevKit_ or _Gradle_.
+The choice of the development approach depends on the project requirements and developer's experience.
+
+### DevKit-Based Theme Project
+
+Developing theme plugins with DevKit is the simplest solution and does not require experience with Gradle or similar build tools.
+The DevKit project structure is generated by default when an IDE Plugin theme project is created by using the New Project Wizard.
+
+See the [](developing_themes.md) section for the development instructions.
+
+### Gradle-Based Theme Project
+
+Developing theme plugins with Gradle requires experience with the Gradle or a similar build tool.
+It offers the possibility of automating some parts of the development process, like patching <path>[plugin.xml](plugin_configuration_file.md)</path> file with the theme plugin version and other data, as well as building the plugin distribution on CI servers and publishing it to [JetBrains Marketplace](https://plugins.jetbrains.com).
+
+If your project requires any of the mentioned capabilities, see [Developing a Plugin using Gradle](developing_plugins.md) for more details.
+
+> The recording of _Busy Plugin Developer. Episode 3_ shows how to [create a new theme](https://youtu.be/9J0j-90dC60?t=582) using the Gradle approach.
+>
+{type="note"}

topics/basics/getting_started/using_dev_kit.md

@@ -1,18 +0,0 @@
-[//]: # (title: Using DevKit)
-
-<!-- Copyright 2000-2022 JetBrains s.r.o. and other contributors. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file. -->
-
-> For new projects, it is highly recommended to use [Gradle-based setup](getting_started.md).
->
-{type="note"}
-
-_Plugin DevKit_ is a bundled IntelliJ IDEA plugin for developing plugins for the IntelliJ Platform using IntelliJ IDEA's build system.
-It provides its custom SDK type and a set of actions for building plugins within the IDE.
-
-In this section:
-
-* [Setting Up a Development Environment](setting_up_environment.md)
-* [Creating a Plugin Project](creating_plugin_project.md)
-* [Running and Debugging a Plugin](running_and_debugging_a_plugin.md)
-* [Deploying a Plugin](deploying_plugin.md)
-* [Publishing a Plugin](publishing_plugin.md)

topics/basics/ide_development_instance.md

@@ -1,9 +1,9 @@
 [//]: # (title: IDE Development Instance)
 
-<!-- Copyright 2000-2022 JetBrains s.r.o. and other contributors. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file. -->
+<!-- Copyright 2000-2022 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. -->
 
 A JetBrains feature for developing plugins is running or debugging a plugin project from within an IntelliJ Platform-based IDE such as IntelliJ IDEA.
-Selecting the [`runIde`](gradle_prerequisites.md#running-a-simple-gradle-based-intellij-platform-plugin) task for a Gradle-based project (or [Run](running_and_debugging_a_plugin.md) menu for a DevKit-based project) will launch a _Development Instance_ of the IDE with the plugin enabled.
+Selecting the [`runIde`](creating_plugin_project.md#running-a-plugin-with-the-runide-gradle-task) task for a Gradle-based project (or [Run](running_and_debugging_a_theme.md) menu for a DevKit-based project) will launch a _Development Instance_ of the IDE with the plugin enabled.
 This page describes how to control some of the settings for the Development Instance.
 
 > Please see also [Advanced Configuration](https://www.jetbrains.com/help/idea/tuning-the-ide.html) for general VM options and properties.
@@ -11,6 +11,7 @@ This page describes how to control some of the settings for the Development Inst
 {type="tip"}
 
 ## Using a JetBrains Runtime for the Development Instance
+
 An everyday use case is to develop (build) a plugin project against a JDK, e.g., Java 8, and then run or debug the plugin in a Development Instance of the IDE.
 In such a situation, Development Instance must use a JetBrains Runtime (JBR) rather than the JDK used to build the plugin project.
 
@@ -20,6 +21,7 @@ A version of the JetBrains Runtime is bundled with all IntelliJ Platform-based I
 To produce accurate results while running or debugging a plugin project in a Development Instance, follow the procedures below to ensure the Development Instance uses a JetBrains Runtime.
 
 ### Determining a JetBrains Runtime Version
+
 The JetBrains Runtime is determined from the JDK version used to build the plugin project, regardless of whether it is built on macOS, Windows, or Linux.
 For example, if a plugin is developed against the Java 8 SE Development Kit 8 for macOS (<path>jdk-8u212-macosx-x64.dmg</path>) to acquire the compatible JetBrains Runtime:
 
@@ -34,6 +36,7 @@ For example, if a plugin is developed against the Java 8 SE Development Kit 8 fo
     For example, the file is <path>jbrx-8u252-osx-x64-b1649.2.tar.gz</path>, meaning build 1649.2 for this JetBrains Runtime matching Java 8 JDK build 252.
 
 ### JetBrains Runtime Variants
+
 The JetBrains Runtime is delivered in various variants used for different purposes, like debugging, running for development purposes or bundling with the IDE.
 
 Available JBR variants are:
@@ -84,7 +87,7 @@ Please note that any unloading problems in a production environment will ask the
 
 Enabled by default for target platform 2020.2 or later.
 
-Set property `intellij.autoReloadPlugins` in [`runIde`](gradle_prerequisites.md#running-a-simple-gradle-based-intellij-platform-plugin) task to `true` for enabling it in earlier platform versions or `false` to disable it explicitly, see [](tools_gradle_intellij_plugin_faq.md#how-to-disable-automatic-reload-of-dynamic-plugins).
+Set property [`runIde.autoReloadPlugins`](tools_gradle_intellij_plugin.md#runide-task-autoreloadplugins) to `true` for enabling it in earlier platform versions or `false` to disable it explicitly, see [](tools_gradle_intellij_plugin_faq.md#how-to-disable-automatic-reload-of-dynamic-plugins).
 
 After starting the sandbox IDE instance, run [`buildPlugin`](tools_gradle_intellij_plugin.md#tasks-buildplugin) task after modifications in the plugin project and switch focus back to sandbox instance to trigger reload.
 
@@ -96,7 +99,7 @@ After starting the sandbox IDE instance, run [`buildPlugin`](tools_gradle_intell
 
 <tab title="DevKit" group-key="devkit">
 
-Add system property `idea.auto.reload.plugins` in the Plugin DevKit [run configuration](running_and_debugging_a_plugin.md).
+Add system property `idea.auto.reload.plugins` in the Plugin DevKit [run configuration](running_and_debugging_a_theme.md).
 
 To disable auto-reload, set `idea.auto.reload.plugins` to `false` explicitly (2020.1.2+).
 
@@ -105,35 +108,36 @@ To disable auto-reload, set `idea.auto.reload.plugins` to `false` explicitly (20
 </tabs>
 
 ## The Development Instance Sandbox Directory
+
 The _Sandbox Home_ directory contains the [settings, caches, logs, and plugins](#development-instance-settings-caches-logs-and-plugins) for a Development Instance of the IDE.
 This information is stored in a different location than for the [installed IDE itself](https://intellij-support.jetbrains.com/hc/en-us/articles/206544519-Directories-used-by-the-IDE-to-store-settings-caches-plugins-and-logs).
 
 <tabs group="project-type">
 <tab title="Gradle" group-key="gradle">
 
-For Gradle-based plugins, the default Sandbox Home location is defined by the [](tools_gradle_intellij_plugin.md).
-See [Configuring a Gradle Plugin Project](gradle_prerequisites.md) for more information about specifying a Sandbox Home location.
-
-The default Sandbox Home location is:
-* Windows: <path>$PROJECT_DIRECTORY$\build\idea-sandbox</path>
+The default Sandbox Home location in a plugin Gradle project is:
+* Windows: <path>$PROJECT_DIRECTORY$\\build\\idea-sandbox</path>
 * Linux/macOS: <path>$PROJECT_DIRECTORY$/build/idea-sandbox</path>
 
+The Sandbox Home location can be configured with the [`intellij.sandboxDir`](tools_gradle_intellij_plugin.md#intellij-extension-sandboxdir) property.
+
 </tab>
 
 <tab title="DevKit" group-key="devkit">
 
-For DevKit-based plugins, the default Sandbox Home location is defined in the IntelliJ Platform Plugin SDK.
-See specifying the [Sandbox Home for DevKit Projects](setting_up_environment.md) for more information.
+For DevKit-based plugins, the default <control>Sandbox Home</control> location is defined in the IntelliJ Platform Plugin SDK.
+See the [Setting Up a Theme Development Environment](setting_up_theme_environment.md#add-intellij-platform-plugin-sdk) for information about how to set up Sandbox Home in IntelliJ Platform SDK.
 
 The default Sandbox Home directory location is:
-* Windows: `<User home>\.<product_system_name><product_version>\system\plugins-sandbox\`
-* Linux: `~/.<product_system_name><product_version>/system/plugins-sandbox/`
-* macOS: `~/Library/Caches/<product_system_name><product_version>/plugins-sandbox/`
+* Windows: <path>$USER_HOME$\\.$PRODUCT_SYSTEM_NAME$$PRODUCT_VERSION$\\system\\plugins-sandbox\\</path>
+* Linux: <path>~/.$PRODUCT_SYSTEM_NAME$$PRODUCT_VERSION$/system/plugins-sandbox/</path>
+* macOS: <path>~/Library/Caches/$PRODUCT_SYSTEM_NAME$$PRODUCT_VERSION$/plugins-sandbox/</path>
 
 </tab>
 </tabs>
 
 ### Development Instance Settings, Caches, Logs, and Plugins
+
 Within the Sandbox Home directory are subdirectories of the Development Instance:
 * <path>config</path> contains settings for the IDE instance.
 * <path>plugins</path> contains folders for each plugin being run in the IDE instance.

topics/basics/plugin_structure/dynamic_plugins.md

@@ -5,7 +5,7 @@
 Starting with the **2020.1** release, installing, updating, and uninstalling plugins without restarting the IDE is available in the IntelliJ Platform.
 
 During plugin development, [Auto-Reload](ide_development_instance.md#enabling-auto-reload) also allows code changes to take effect immediately in the sandbox IDE instance.
-To test whether dynamic installation works correctly, verify installing [local build distribution](deployment.md#building-distribution) succeeds (see [Troubleshooting](#troubleshooting)).
+To test whether dynamic installation works correctly, verify installing [local build distribution](publishing_plugin.md#building-distribution) succeeds (see [Troubleshooting](#troubleshooting)).
 
 Please note that any unloading problems in a production environment will simply ask the user to restart the IDE.
 
@@ -86,7 +86,7 @@ If a plugin fails to reload, the log will contain a cause as to why.
 
 <procedure title="Finding leaks preventing unload">
 
-1. Verify that the IDE is running with the VM parameter `-XX:+UnlockDiagnosticVMOptions`. When using [Gradle](gradle_guide.md), specify `runIde.jvmArgs += "-XX:+UnlockDiagnosticVMOptions"` otherwise [Configure JVM Options](https://www.jetbrains.com/help/idea/tuning-the-ide.html#procedure-jvm-options).
+1. Verify that the IDE is running with the VM parameter `-XX:+UnlockDiagnosticVMOptions`. When using [Gradle](configuring_plugin_project.md), specify `runIde.jvmArgs += "-XX:+UnlockDiagnosticVMOptions"` otherwise [Configure JVM Options](https://www.jetbrains.com/help/idea/tuning-the-ide.html#procedure-jvm-options).
 2. Set Registry key `ide.plugins.snapshot.on.unload.fail` to `true` (Go to <menupath>Navigate | Search Everywhere</menupath> and type `Registry`).
 3. Trigger the plugin reload.
 4. Open the <path>.hprof</path> memory snapshot generated on plugin unload, look for the plugin ID string. [IntelliJ Ultimate](https://www.jetbrains.com/help/idea/analyze-hprof-memory-snapshots.html) can open memory snapshots directly.

topics/basics/plugin_structure/plugin_content.md

@@ -1,8 +1,8 @@
 [//]: # (title: Plugin Content)
 
-<!-- Copyright 2000-2022 JetBrains s.r.o. and other contributors. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file. -->
+<!-- Copyright 2000-2022 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. -->
 
-Plugin distribution will be built using [Gradle](deployment.md) or [Plugin DevKit](deploying_plugin.md).
+Plugin distribution will be built using [Gradle](tools_gradle_intellij_plugin.md#tasks-buildplugin) or [Plugin DevKit](deploying_theme.md).
 
 The plugin <path>jar</path> file must contain:
 - the configuration file (<path>META-INF/plugin.xml</path>) ([Plugin Configuration File](plugin_configuration_file.md))

topics/basics/plugin_structure/plugin_dependencies.md

@@ -53,7 +53,7 @@ See also [](extension_point_list.md#intellij-community-plugins) and [](plugin_co
 | IntelliLang               | `org.intellij.intelliLang`                   |
 | Java                      | `com.intellij.java`                          |
 | JavaScript and TypeScript | `JavaScript`                                 |
-| Kotlin                    | `org.jetbrains.kotlin` [](kotlin.md)         |
+| Kotlin                    | `org.jetbrains.kotlin`                       |
 | Markdown                  | `org.intellij.plugins.markdown`              |
 | Maven                     | `org.jetbrains.idea.maven`                   |
 | Spring                    | `com.intellij.spring` [](spring_api.md)      |
@@ -74,7 +74,7 @@ Depending on the chosen development workflow (Gradle or DevKit), one of the two
 >
 {type="note"}
 
-If the project uses [Gradle](gradle_build_system.md), add the dependency to the [`intellij.plugins`](tools_gradle_intellij_plugin.md#intellij-extension-plugins) parameter in your build script:
+Add the dependency to the [`intellij.plugins`](tools_gradle_intellij_plugin.md#intellij-extension-plugins) parameter in your build script:
 
 <tabs>
 <tab title="Kotlin">
@@ -104,11 +104,11 @@ intellij {
 
 <tab title="DevKit">
 
-> Existing DevKit-based projects can be converted to use [Gradle setup](gradle_prerequisites.md#adding-gradle-support-to-an-existing-devkit-based-intellij-platform-plugin) where dependency management is fully automated.
+> Existing DevKit-based projects can be [converted to use Gradle setup](migrating_plugin_devkit_to_gradle.md) where dependency management is fully automated.
 >
-{type="tip"}
+{type="note"}
 
-If the project uses [DevKit](using_dev_kit.md), add the JARs of the plugin on which the project depends to the <control>Classpath</control> of the *IntelliJ Platform SDK*.
+Add the JARs of the plugin on which the project depends to the <control>Classpath</control> of the [*IntelliJ Platform SDK*](setting_up_theme_environment.md#add-intellij-platform-plugin-sdk).
 
 > Do not add the plugin JARs as a library: this will fail at runtime because the IntelliJ Platform will load two separate copies of the dependency plugin classes.
 >

topics/basics/plugin_structure/plugin_extensions.md

@@ -42,7 +42,7 @@ See [](explore_api.md) for more information and strategies.
 
    See the [](plugin_extension_points.md#declaring-extension-points) section for details.
 
-   **NB:** When using Kotlin, use `class` and never `object` for all implementations ([more details](kotlin.md#caution)).
+   **NB:** When using Kotlin, use `class` and never `object` for all implementations ([more details](using_kotlin.md#caution)).
 
 To clarify this procedure, consider the following sample section of the <path>plugin.xml</path> file that defines two extensions designed to access the `com.intellij.appStarter` and `com.intellij.projectTemplatesFactory` extension points in the IntelliJ Platform,
 and one extension to access the `another.plugin.myExtensionPoint` extension point in another plugin `another.plugin`:

topics/basics/plugin_structure/plugin_icon_file.md

@@ -74,9 +74,9 @@ If one Plugin Logo design does not work on both light and dark backgrounds, crea
 The examples below illustrate how a Plugin Logo design may work well for a light background but not for a dark background.
 Consequently, a separate Plugin Logo for dark backgrounds is needed.
 
-| ![Plugin Logo on Light UI Theme](light_version.png){width="225"} |    ![Light Plugin Logo on Dark UI Theme](dark_bad.png){:width="225"}     |     ![Plugin Logo for Dark UI Theme](dark_good.png){:width="225"}     |
-|:----------------------------------------------------------------:|:------------------------------------------------------------------------:|:---------------------------------------------------------------------:|
-| _The light Plugin Logo design<br/>works well on light UI Theme_  | _The light Plugin Logo design does<br/>not work well on a dark UI Theme_ | _A separate, dark Plugin Logo design<br/>works well on dark UI Theme_ |
+| ![Plugin Logo on Light Theme](light_version.png){width="225"} |    ![Light Plugin Logo on Dark Theme](dark_bad.png){:width="225"}     |     ![Plugin Logo for Dark Theme](dark_good.png){:width="225"}     |
+|:-------------------------------------------------------------:|:---------------------------------------------------------------------:|:------------------------------------------------------------------:|
+| _The light Plugin Logo design<br/>works well on light theme_  | _The light Plugin Logo design does<br/>not work well on a dark theme_ | _A separate, dark Plugin Logo design<br/>works well on dark theme_ |
 
 ### Plugin Logo File Format
 All Plugin Logo images must be in SVG format.
@@ -89,8 +89,8 @@ This vector image format is required because the Plugin Logo file must be small
 ### Plugin Logo File Naming Convention
 Name the Plugin Logo files according to the following conventions:
 * <path>pluginIcon.svg</path> is the default Plugin Logo.
-  If a separate Logo file for dark UI Themes exists in the plugin, then this file is used solely for light UI Themes,
-* <path>pluginIcon_dark.svg</path> is an optional, alternative Plugin Logo for use solely with dark IDE UI Themes.
+  If a separate Logo file for dark themes exists in the plugin, then this file is used solely for light themes,
+* <path>pluginIcon_dark.svg</path> is an optional, alternative Plugin Logo for use solely with dark IDE themes.
 
 ## Adding Plugin Logo Files to a Plugin Project
 The Plugin Logo files must be in the <path>META-INF</path> folder of the plugin distribution file, i.e., the <path>plugin.jar</path> or <path>plugin.zip</path> file you upload to the plugin repository and install into an IDE.

topics/basics/plugin_types.md

@@ -11,7 +11,7 @@ The most common types of plugins include:
 * Framework integration
 * Tool integration
 * User interface add-ons
-* UI Themes
+* Themes
 
 > In some cases, implementing an actual IntelliJ Platform plugin might not be necessary, as [alternative solutions](plugin_alternatives.md) exist.
 >
@@ -60,15 +60,6 @@ Plugins in this category apply various changes to the standard user interface of
 Some newly added components are interactive and provide new functionality, while others are limited to visual modifications only.
 The [Random Background](https://plugins.jetbrains.com/plugin/9692-random-background) plugin may serve as an example.
 
-## UI Themes
+## Themes
 
-[UI Themes](themes_intro.md) give designers the ability to customize the appearance of built-in IDE UI elements.
-Custom UI Themes can:
-
-* substitute icons,
-* change the colors of icons and UI controls,
-* alter the borders and insets of UI controls,
-* provide custom editor schemes,
-* add background images.
-
-The [UI Themes available for download](https://plugins.jetbrains.com/search?headline=164-theme&tags=Theme) illustrate the creative possibilities.
+[Themes](themes_getting_started.md) give designers the ability to customize the appearance of built-in IDE UI elements.

topics/basics/plugins_quick_start.md

@@ -7,10 +7,14 @@ It will familiarize you with the working environment, project structure, and fre
 
 * [](plugin_alternatives.md)
 * [](plugin_required_experience.md)
-* [](types_of_plugins.md)
-* [](getting_started.md)
+* [](plugin_types.md)
+* [](developing_plugins.md)
 * [](plugin_structure.md)
-* [](kotlin.md)
+* [Implementing Plugin in Kotlin](using_kotlin.md)
 * [](plugin_signing.md)
 * [](ide_development_instance.md)
 * [](faq.md)
+
+> If you are interested in the UI theme development, please see [Part X - Themes](themes_getting_started.md).
+>
+{type="note"}

topics/intro/about.md

@@ -67,6 +67,11 @@ This section describes product-specific features, such as specific project model
 
 Documents how to use the IntelliJ Platform to create a new, custom IDE, rather than plugins to an existing product, e.g., WebStorm, or Android Studio.
 
+#### Part X — Themes
+
+Describes how to create a theme for IntelliJ Platform-based IDEs.
+Includes details on how to set up the theme project, customize, build, and publish it on JetBrains Marketplace.
+
 #### Appendix I — Resources
 
 Links to [useful resources](useful_links.md), a [](glossary.md), [](extension_point_list.md), tips on how to [](explore_api.md) and [](learning_resources.md).

topics/intro/code_samples.md

@@ -11,7 +11,7 @@ Links to the corresponding tutorial or reference page in this tutorial, as well
 
 ## Using Gradle
 
-All sample plugins are based on Gradle, see [Building Plugins with Gradle](gradle_build_system.md) to get started.
+All sample plugins are based on Gradle, see [](creating_plugin_project.md) to get started.
 
 Additionally, the [Working with Gradle in IntelliJ IDEA](https://youtu.be/6V6G3RyxEMk) screencast offers a thorough introduction to Gradle functionality inside IntelliJ IDEA.
 
@@ -32,4 +32,4 @@ Invoke <control>Reload All Gradle Projects</control> from the Gradle tool window
 
 ## Running Code Samples
 
-Run the plugin by using the Gradle [`runIde`](gradle_prerequisites.md#executing-the-plugin) task shown under the corresponding project's <control>Tasks</control> node in the <control>Gradle</control> tool window.
+Run the plugin by using the Gradle [`runIde`](creating_plugin_project.md#executing-the-plugin) task shown under the corresponding project's <control>Tasks</control> node in the <control>Gradle</control> tool window.

topics/intro/content_updates.md

@@ -15,6 +15,11 @@ See [GitHub Changelog](https://github.com/JetBrains/intellij-sdk-docs/commits/ma
 
 ### September-22
 
+Add Part X - Themes
+:
+All the content related to themes and creating a project using the DevKit approach has been moved to a new _Themes_ part.
+Content has been refreshed to match the current state of the project and SDK wizards.
+
 Spell Checking
 : Add [](spell_checking.md) section with an [accompanying tutorial](spell_checking_strategy.md) showing how to implement a spell checking for a custom language.
 
@@ -188,7 +193,7 @@ Dynamic Plugins update
 : Added new sections _Code_ and _Troubleshooting_ to [Dynamic Plugins](dynamic_plugins.md).
 
 GitHub IntelliJ Platform Plugin Template
-: Create new plugins with a preconfigured project scaffold and CI in [one click](github_template.md).
+: Create new plugins with a preconfigured project scaffold and CI in [one click](plugin_github_template.md).
 
 Disposer & Disposable
 : Added [reference](disposers.md) discussing resource cleanup/management.
@@ -209,7 +214,7 @@ JCEF Support
 ### February-20
 
 All Code Samples converted to Gradle
-: [All samples](https://github.com/JetBrains/intellij-sdk-docs/tree/main/code_samples) now use the [recommended solution](gradle_build_system.md) of setting up plugin projects.
+: [All samples](https://github.com/JetBrains/intellij-sdk-docs/tree/main/code_samples) now use the [recommended solution](creating_plugin_project.md) of setting up plugin projects.
 
 ### January-20
 

topics/intro/intellij_platform.md

@@ -31,7 +31,7 @@ It is also possible to distribute plugins using a [](custom_plugin_repository.md
 
 Plugins can extend the platform in many ways, from adding a simple menu item to adding support for a complete language, build system, and debugger.
 Many of the existing IntelliJ Platform features are implemented as plugins that can be included or excluded depending on the needs of the end product.
-See the [](basics.md) for more details.
+See the [](plugins_quick_start.md) for more details.
 
 > In some cases, implementing an actual IntelliJ Platform plugin might not be necessary, as [alternative solutions](plugin_alternatives.md) exist.
 >

topics/intro/key_topics.md

@@ -1,13 +1,13 @@
 [//]: # (title: Key Topics)
 
-<!-- Copyright 2000-2022 JetBrains s.r.o. and other contributors. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file. -->
+<!-- Copyright 2000-2022 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. -->
 
 The IntelliJ Platform is extensive and very capable, and its size and scope can initially be very daunting.
 This page is intended to list the key topics that a plugin author would be interested in, and provide quick links to the most common extension points.
 
 ## Essential Concepts
 
-- [](getting_started.md).
+- [](developing_plugins.md).
 - [](testing_plugins.md).
 - Component model - the IntelliJ Platform is a component-based application and is responsible for creating components and injecting dependencies.
   Understanding this is necessary for building plugins.

topics/intro/sdk_code_guidelines.md

@@ -128,17 +128,17 @@ code_samples/
 
 ## Gradle Build Script Conventions
 
-SDK code samples must be developed [using Gradle](gradle_build_system.md).
+SDK code samples must be developed [using Gradle](creating_plugin_project.md).
 As of this writing, the use of Gradle in SDK code samples still relies heavily on the <path>plugin.xml</path> for specifying the plugin configuration.
 At a later, second phase, the SDK code samples will transition to rely more on the Gradle configuration.
 
-The default contents of a Gradle build script file are produced by the [New Project Wizard](gradle_prerequisites.md#creating-a-gradle-based-intellij-platform-plugin-with-new-project-wizard).
+The default contents of a Gradle build script file are produced by the [New Project Wizard](creating_plugin_project.md#create-ide-plugin).
 A consistent structure for an SDK code sample's Gradle build script file is essential for clarity and is based on the default produced by the project wizard.
 Comments in SDK code sample Gradle build scripts should only draw attention to the parts of the Gradle configuration that are unique for a plugin.
 
 For SDK code samples, a few alterations are needed to the default <path>build.gradle.kts</path> file produced by the plugin wizard:
 * Maintain the Gradle properties `version` (`project.version`) and `group` (`project.group`).
-  See the [Plugin Gradle Properties](gradle_prerequisites.md#plugin-gradle-properties-and-plugin-configuration-file-elements) section for how these Gradle properties relate to the elements in <path>plugin.xml</path>.
+  See the [Plugin Gradle Properties](creating_plugin_project.md#plugin-gradle-properties-and-plugin-configuration-file-elements) section for how these Gradle properties relate to the elements in <path>plugin.xml</path>.
 * Add the following statement to the [Patching DSL](tools_gradle_intellij_plugin.md#tasks-patchpluginxml) (`patchPluginXml {...}`) section:
   ```kotlin
   // Patches <version> value in plugin.xml

topics/intro/sdk_style.md

@@ -72,7 +72,7 @@ Consistent text styles are used to standardize references and keywords:
   Menu paths to settings always start with "Settings/Preferences" to cover all platforms.
   Inside tables, use `|` instead of `|` to prevent escaping problems.
 * User interface element names like labels, buttons, checkboxes, etc. are wrapped using `<control>`: `Press <control>Continue</continue>`: Press <control>Continue</control>
-* Non-code keywords and quotations, or the names of non-code files, are formatted as italic style: \_UI Theme\_ (_UI Theme_), \_README.md\_ (_README.md_.)
+* Non-code keywords and quotations, or the names of non-code files, are formatted as italic style: \Theme\_ (_Theme_), \_README.md\_ (_README.md_.)
   Examples of this file type include _LICENSE.txt_ and _README.md_.
 * Code keywords and classnames are formatted as code style: \`interface\`: `interface`, \`AnAction\`: `AnAction`, \`name\` attribute: `name` attribute.
 * File names are wrapped using `<path>`: `<path>build.gradle.kts</path>` <path>build.gradle.kts</path>.

topics/intro/welcome.md

@@ -1,6 +1,6 @@
 [//]: # (title: IntelliJ Platform SDK)
 
-<!-- Copyright 2000-2022 JetBrains s.r.o. and other contributors. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file. -->
+<!-- Copyright 2000-2022 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. -->
 
 [![official JetBrains project](https://jb.gg/badges/official-flat-square.svg)](https://confluence.jetbrains.com/display/ALL/JetBrains+on+GitHub) [![Twitter Follow](https://img.shields.io/twitter/follow/JBPlatform?style=flat-square&logo=twitter)](https://twitter.com/JBPlatform/) [![Slack](https://img.shields.io/badge/Slack-%23intellij--platform-blue?style=flat-square&logo=slack)](https://plugins.jetbrains.com/slack)
 
@@ -27,7 +27,8 @@ Webinar
 * [](intellij_platform.md)
 * [](about.md)
 * [](plugin_alternatives.md)
-* [](getting_started.md)
+* [](developing_plugins.md)
+* [Developing a Theme](themes_getting_started.md)
 * [](explore_api.md)
 * [](useful_links.md)
 * [](learning_resources.md)

topics/products/androidstudio/android_studio.md

@@ -1,9 +1,9 @@
 [//]: # (title: Android Studio Plugin Development)
 
-<!-- Copyright 2000-2022 JetBrains s.r.o. and other contributors. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file. -->
+<!-- Copyright 2000-2022 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. -->
 
 Android Studio plugins extend or add functionality to the [Android Studio IDE](https://developer.android.com/studio).
-Plugins can be written in [Kotlin](kotlin.md) or Java, or a mix of both, and are created using IntelliJ IDEA and the [IntelliJ Platform](intellij_platform.md).
+Plugins can be written in [Kotlin](using_kotlin.md) or Java, or a mix of both, and are created using IntelliJ IDEA and the [IntelliJ Platform](intellij_platform.md).
 It's also helpful to be familiar with [Java Swing](https://docs.oracle.com/javase/8/javase-clienttechnologies.htm).
 Once completed, plugins can be packaged and distributed at [JetBrains Marketplace](https://plugins.jetbrains.com).
 
@@ -11,9 +11,9 @@ Android Studio plugins are not Android modules or apps to run in the Android ope
 
 ## Configuring IntelliJ Platform Projects for Android Studio Plugin Development
 
-To create a new Android Studio plugin project, follow the tutorial on the [Getting Started with Gradle](gradle_prerequisites.md) page.
+To create a new Android Studio plugin project, follow the tutorial on the [Getting Started with Gradle](creating_plugin_project.md) page.
 The tutorial produces a skeleton project suitable to use as a starting point for an Android Studio plugin.
-On the [New Project Screen](gradle_prerequisites.md#create-ide-plugin), choose <control>IDE Plugin</control> from the project generators list as described in the tutorial, **not** <control>Android</control>.
+On the [New Project Screen](creating_plugin_project.md#create-ide-plugin), choose <control>IDE Plugin</control> from the project generators list as described in the tutorial, **not** <control>Android</control>.
 Some minor modifications to the skeleton project are needed, as discussed below.
 
 ### Matching Versions of the IntelliJ Platform with the Android Studio Version
@@ -45,11 +45,11 @@ For the full list of Android Studio releases with more details, visit the [Andro
 
 ### Configuring the Plugin Gradle Build Script
 
-The use-case of developing for a non-IntelliJ IDEA IDE is reviewed in the [Plugins Targeting Alternate IntelliJ Platform-Based IDEs](gradle_guide.md#plugins-targeting-alternate-intellij-platform-based-ides) section of the [Configuring Gradle for IntelliJ Platform Plugins](gradle_guide.md) page.
+The use-case of developing for a non-IntelliJ IDEA IDE is reviewed in the [Plugins Targeting Alternate IntelliJ Platform-Based IDEs](dev_alternate_products.md#configuring-gradle-build-script-to-target-products-other-than-intellij-idea) section.
 The particular example in that section discusses configuring a plugin project for PhpStorm, so the details for an Android Studio plugin project are reviewed here.
 
 Here are the steps to configure the Gradle build script for developing a plugin to target Android Studio:
-* The Gradle plugin attributes describing the configuration of the [IntelliJ Platform used to build the plugin project](gradle_guide.md#configuring-the-gradle-intellij-plugin-for-building-intellij-platform-plugin-projects) must be explicitly set.
+* The Gradle plugin attributes describing the configuration of the [IntelliJ Platform used to build the plugin project](configuring_plugin_project.md#intellij-platform-configuration) must be explicitly set.
   Continuing with the example [above](#matching-versions-of-the-intellij-platform-with-the-android-studio-version), set the [`intellij.version`](tools_gradle_intellij_plugin.md#intellij-extension-version) value to `191.8026.42`.
   Alternatively, specify [`intellij.localPath`](tools_gradle_intellij_plugin.md#intellij-extension-localpath) to refer to a local installation of Android Studio.
 * Android Studio plugin projects that use APIs from the `android` plugin must declare a dependency on that plugin.

topics/products/dev_alternate_products.md

@@ -10,7 +10,7 @@ Once completed, the plugins can be packaged and distributed at [JetBrains Market
 Project configuration attributes common to projects targeting products other than IntelliJ IDEA are described on this page.
 Details particular to an IntelliJ Platform-based product are described on the individual product pages in _Part VIII — Product Specific_.
 
-All the Gradle configuration attributes described here are discussed in-depth on the [](gradle_guide.md) and the [](tools_gradle_intellij_plugin.md).
+All the Gradle configuration attributes described here are discussed in-depth on the [](configuring_plugin_project.md) and the [](tools_gradle_intellij_plugin.md).
 
 > Qualifying Open Source projects can [apply for free licenses](https://www.jetbrains.com/community/opensource/) of JetBrains products.
 >
@@ -18,7 +18,7 @@ All the Gradle configuration attributes described here are discussed in-depth on
 
 ## Getting Started
 
-To create a new Gradle plugin project, follow the tutorial on the [](gradle_prerequisites.md) page.
+To create a new Gradle plugin project, follow the tutorial on the [](creating_plugin_project.md) page.
 The tutorial produces a skeleton Gradle project suitable to use as a starting point.
 
 Modifications are needed to the skeleton project's Gradle build script and <path>[plugin.xml](plugin_configuration_file.md)</path> files, as described below, and on the individual product pages in _Part VIII — Product Specific_.
@@ -85,7 +85,7 @@ Understanding the relationship between build numbers is critical when using this
 * _targetIDE_ is the (version-specific) IntelliJ Platform-based IDE in which the plugin is intended to run, such as Android Studio or PhpStorm.
 * _baseIntelliJPlatformVersion_ is the (version-specific) IntelliJ Platform used in the build of the _targetIDE_.
   The IntelliJ Platform is defined by a specific build of the IntelliJ IDEA Community Edition.
-  The Gradle plugin attribute [`intellij.version`](gradle_guide.md#intellij-platform-configuration) is set to be _baseIntelliJPlatformVersion_.
+  The Gradle plugin attribute [`intellij.version`](configuring_plugin_project.md#intellij-platform-configuration) is set to be _baseIntelliJPlatformVersion_.
 
 For API compatibility, the IntelliJ Platform version used in the _targetIDE_ dictates the _baseIntelliJPlatformVersion_ used for developing a plugin.
 
@@ -118,11 +118,11 @@ This information is used to configure the plugin project's Gradle build script a
 Configuring a Gradle plugin project for using _baseIntelliJPlatformVersion_ requires changing some default settings in the Gradle build script.
 Changes need to be made in two places: [`intellij`](tools_gradle_intellij_plugin.md#configuration-intellij-extension) extension and [`runIde`](tools_gradle_intellij_plugin.md#tasks-runide) task.
 
-The Gradle plugin attributes describing the configuration of the [IntelliJ Platform used to build the plugin project](gradle_guide.md#configuring-the-gradle-intellij-plugin-for-building-intellij-platform-plugin-projects) must be explicitly set in the `intellij` task.
+The Gradle plugin attributes describing the configuration of the [IntelliJ Platform used to build the plugin project](configuring_plugin_project.md#intellij-platform-configuration) must be explicitly set in the `intellij` task.
 The [`intellij.type`](tools_gradle_intellij_plugin.md#intellij-extension-type) is `IU` because although the IntelliJ IDEA Community Edition defines the IntelliJ Platform, the PHP plugin is only compatible with IntelliJ IDEA Ultimate.
 The [`intellij.version`](tools_gradle_intellij_plugin.md#intellij-extension-version) is _baseIntelliJPlatformVersion_.
 
-Any [dependencies](gradle_guide.md#plugin-dependencies) on _targetIDE_-specific plugins or modules must be declared in the [`intellij`](tools_gradle_intellij_plugin.md#configuration-intellij-extension) extension.
+Any [dependencies](configuring_plugin_project.md#plugin-dependencies) on _targetIDE_-specific plugins or modules must be declared in the [`intellij`](tools_gradle_intellij_plugin.md#configuration-intellij-extension) extension.
 Use the Gradle plugin attribute [`intellij.plugins`](tools_gradle_intellij_plugin.md#intellij-extension-plugins) to declare a dependency.
 See the specific product pages in _Part VIII — Product Specific_ for the _targetIDE_ plugin or module name.
 

topics/products/idea/spring_api.md

@@ -15,7 +15,7 @@ To develop plugins, you will need to use _IntelliJ IDEA Ultimate Edition_ versio
 
 ## Setting up Project
 
-Setup [Gradle build script](gradle_guide.md#intellij-platform-configuration) to target IntelliJ IDEA Ultimate, then [add dependency](plugin_dependencies.md) to bundled Spring plugin with ID `com.intellij.spring`.
+Setup [Gradle build script](configuring_plugin_project.md#intellij-platform-configuration) to target IntelliJ IDEA Ultimate, then [add dependency](plugin_dependencies.md) to bundled Spring plugin with ID `com.intellij.spring`.
 
 Please use only Spring-related functionality exposed in <path>spring-api.jar</path> (sources are provided in <path>$IDEA_HOME$/lib/src/src_spring-boot-openapi.zip</path>) in your plugin.
 Using any other "internal" (implementation) classes from Spring plugin itself (<path>spring.jar</path>) is _not_ supported.

topics/products/rider/rider.md

@@ -13,7 +13,7 @@ Rider uses the IntelliJ Platform to provide the user interface for a C# and .NET
 ## IntelliJ IDEA Configuration for Rider Plugin Development
 
 Although there is no dedicated Rider SDK, the [ReSharper DevGuide](https://www.jetbrains.com/help/resharper/sdk/Products/Rider.html) addresses the subject of plugins for Rider.
-The documentation describes the [configuration](https://www.jetbrains.com/help/resharper/sdk/Products/Rider.html#plugin-project-jvm) of the Gradle build script and <path>settings.gradle</path> file to build a Rider plugin using the [Gradle project system](gradle_build_system.md) in IntelliJ IDEA.
+The documentation describes the [configuration](https://www.jetbrains.com/help/resharper/sdk/Products/Rider.html#plugin-project-jvm) of the Gradle build script and <path>settings.gradle</path> file to build a Rider plugin using the [Gradle project system](configuring_plugin_project.md) in IntelliJ IDEA.
 
 > See [](rider_extension_point_list.md) for the complete list.
 >

topics/reference_guide/ui_themes/themes.md

@@ -1,114 +0,0 @@
-[//]: # (title: Creating Custom UI Themes)
-
-<!-- Copyright 2000-2022 JetBrains s.r.o. and other contributors. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file. -->
-
-Creating a custom UI Theme is a process of choosing a base IDE Theme (_Light_ or _Darcula_,) then changing aspects of the base Theme definition.
-Custom UI Themes can:
-* substitute icons,
-* change the colors of icons and UI controls,
-* alter the borders and insets of UI controls,
-* provide custom editor schemes,
-* add background images.
-
-## The Structure of a UI Theme
-
-UI Themes are components within IntelliJ Platform plugins.
-The theme plugins should be stand-alone and not combined with other plugin functionality.
-This approach provides the best user experience because it avoids an IDE restart when installing a UI Theme plugin.
-
-UI Themes have several components:
-* A required Theme description (JSON) file in the plugin project's <path>resources</path> folder.
-* A required `themeProvider` declaration in the plugin's <path>[plugin.xml](plugin_configuration_file.md)</path> file, located in the plugin project's <path>META-INF</path> folder.
-* An optional Editor Scheme description (XML) file derived from an exported IDE editor scheme.
-  This file is located in the plugin project's <path>resources</path> folder.
-* An optional background image file, located in the plugin project's <path>resources</path> folder.
-* Optional icon image files, located in the plugin project's <path>resources</path> folder.
-
-![UI Theme Components](theme_components.png)
-
-## Custom UI Theme Workflow
-
-Creating a UI Theme follows this general sequence:
-* [Setup Development Environment](setting_up_environment.md)
-* [Start with a Plugin Project](creating_plugin_project.md)
-* [Add UI Theme components to the plugin](#creating-a-ui-theme-with-the-devkit-theme-wizard) by using the DevKit UI Theme Wizard.
-* [Customize the UI Theme](themes_customize.md) by adding data objects to the Theme description (JSON) file.
-* [Add an Editor Scheme or Background Image](themes_extras.md) to the plugin.
-* [Build and test](running_and_debugging_a_plugin.md) the UI Theme plugin.
-* [Deploy the UI Theme plugin](deploying_plugin.md)
-* [Publish the UI Theme plugin](publishing_plugin.md)
-
-## Creating Custom UI Themes
-
-A UI Theme is added to an IntelliJ Platform plugin using the DevKit UI Theme Wizard.
-
-### Creating a UI Theme with the DevKit Theme Wizard
-
-The DevKit Wizard is part of the DevKit plugin, which is bundled with IntelliJ IDEA.
-This Wizard can be used for both DevKit-based and Gradle-based plugins.
-
-While a plugin project is open in IntelliJ IDEA, select the <path>resources</path> folder in the _Project_ tool window.
-From the main menu, select the <menupath>New | Plugin DevKit | Theme</menupath> action.
-
-![DevKit Wizard Action](devkit_wiz_action.png)
-
-<br/>
-
-The Wizard then prompts for the name of the new Theme, and the basis for the Theme:
-
-![DevKit Dialog](devkit_wiz_dialog.png)
-
-The best practice is to name the new Theme the same as the name of the plugin.
-The checkbox indicates the basis for the Theme.
-Checking <control>Dark theme</control> means basing the custom Theme on _Darcula_.
-Leaving the box unchecked means basing the custom Theme on the default IntelliJ IDEA _Light_ Theme.
-For the SDK code sample `theme_basics` the box is _unchecked_.
-
-Clicking the <control>OK</control> button creates a default Theme description file named <path>$THEME_NAME$.theme.json</path> in the plugin project's <path>resources</path> folder.
-In this example, the file is named <path>theme_basics.theme.json</path>.
-The content of the default file is a short set of key–value pairs:
-
-```json
-{
-  "name": "theme_basics",
-  "dark": false,
-  "author": "",
-  "editorScheme": "/theme_basics.xml",
-  "ui": {
-  }
-}
-```
-
-The value of the `name` key matches the first portion of the Theme description <path>$THEME_NAME$.theme.json</path> file name.
-The value of `name` is displayed in the [Theme](https://www.jetbrains.com/help/idea/settings-appearance.html)  _Preferences_ dropdown when the UI Theme's plugin is installed in the IDE.
-The value of the `author` key is by default empty.
-The `editorScheme` section will be addressed in [Adding a Custom Editor Scheme](themes_extras.md#adding-a-custom-editor-scheme)
-The `ui` section will be addressed in [Customizing UI Control Colors](themes_customize.md#customizing-ui-controls).
-
-The Wizard also creates a `themeProvider` declaration in the [`<extensions>`](plugin_configuration_file.md#idea-plugin__extensions) section of the plugin's <path>plugin.xml</path> file.
-This declaration binds the Theme description file to a theme provider extension using a generated unique `id`.
-
-```xml
-<extensions defaultExtensionNs="com.intellij">
-  <themeProvider
-      id="eb9b7461-397b-4b98-a422-224fc0a74564"
-      path="/theme_basics.theme.json"/>
-</extensions>
-```
-
-> Do not modify or re-use an existing value of the generated `id` attribute.
->
-{type="warning"}
-
-At this point, the UI Theme `theme_basics` is a valid UI Theme.
-Its plugin can be built and tested in IntelliJ Platform-based IDEs, giving the user the opportunity to select _theme_basics_ in the [Theme](https://www.jetbrains.com/help/idea/settings-appearance.html) _Preferences_ dropdown.
-The custom Theme looks exactly like the IDE default `Light` Theme, but it is a valid custom Theme.
-
-### Completing the Default UI Theme Description File
-
-The default UI Theme definition can be directly edited to add or change some of the values for the default keys, if desired:
-The following values can be changed directly in the Theme (<path>*.theme.json</path>) description file:
-* The value of the `dark` key can be changed to `true`, which would switch the basis of the Theme to _Darcula_ instead of _Light_.
-* The value of the `author` key, which defaults to an empty string, can be set to a `String` literal.
-
-In the case of the `theme_basics` code sample, it is set to "IntelliJ Platform SDK".

topics/reference_guide/ui_themes/themes_intro.md

@@ -1,22 +0,0 @@
-[//]: # (title: Custom UI Themes)
-
-<!-- Copyright 2000-2022 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. -->
-
-Beginning with the 2019.1 release, custom UI Themes are supported.
-Custom UI Themes give designers control of the appearance of built-in UI elements.
-The [UI Themes available for download](https://plugins.jetbrains.com/search?headline=164-theme&tags=Theme) illustrate the creative possibilities.
-
-[Creating a new UI element](user_interface_components.md) for a plugin is distinctly different than Custom UI Themes.
-
-> See the [Themes in IntelliJ-based IDEs](https://blog.jetbrains.com/platform/2021/10/themes-in-intellij-based-ides/) blog post for an overview (available in multiple languages).
->
-> The recording of _Busy Plugin Developer. Episode 3_ shows how to [create a new UI Theme from scratch](https://youtu.be/9J0j-90dC60?t=582).
->
-{type="note"}
-
-This section discusses creating and customizing UI Themes:
-* [Creating UI Themes](themes.md)
-* [Customizing UI Themes](themes_customize.md)
-* [Adding Editor Schemes and Background Images](themes_extras.md)
-
-For plugin developers, [Exposing Theme Metadata](themes_metadata.md) discusses the format of customization keys and information how to provide it to Theme authors.

topics/tutorials/action_system/working_with_custom_actions.md

@@ -139,7 +139,7 @@ For more information, see [](basic_action_system.md#setting-the-override-text-el
 
 ## Testing the Minimal Custom Action Implementation
 
-After performing the steps described above, [compile and run](gradle_prerequisites.md#executing-the-plugin) the plugin to see the newly created action available as a <menupath>Tools</menupath> menu item, which is within the context of the main menu:
+After performing the steps described above, [compile and run](creating_plugin_project.md#executing-the-plugin) the plugin to see the newly created action available as a <menupath>Tools</menupath> menu item, which is within the context of the main menu:
 
 ![Register action](tools_menu_item_action.png){width="350"}
 

topics/tutorials/build_system/configuring_plugin_project.md

@@ -0,0 +1,109 @@
+[//]: # (title: Configuring Gradle IntelliJ Plugin)
+
+<!-- Copyright 2000-2022 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. -->
+
+This section presents a guided tour of Gradle plugin attributes to achieve the commonly desired functionality.
+For more advanced options, see the full [Gradle IntelliJ Plugin](tools_gradle_intellij_plugin.md) reference.
+
+## Keep Up To Date
+
+Gradle IntelliJ Plugin and [Gradle](https://gradle.org/install/) build system are constantly developed, and every new release brings important bug fixes, new features, and improvements that makes the development more efficient.
+It is highly recommended to keep updating both Gradle and Gradle IntelliJ Plugin to the latest versions.
+
+> Current Gradle IntelliJ Plugin version is ![GitHub Release](https://img.shields.io/github/release/jetbrains/gradle-intellij-plugin.svg?style=flat-square)
+>
+{type="note"}
+
+## Target Platform and Dependencies
+
+By default, the Gradle plugin will build a plugin project against the IntelliJ Platform defined by the latest EAP snapshot of the IntelliJ IDEA Community Edition.
+
+> Using EAP versions of the IntelliJ Platform requires adding the _Snapshots repository_ to the Gradle build script (see [IntelliJ Platform Artifacts Repositories](intellij_artifacts.md)).
+>
+{type="note"}
+
+If a matching version of the specified IntelliJ Platform is not available on the local machine, the Gradle plugin downloads the correct version and type.
+IntelliJ IDEA then indexes the build and any associated source code and JetBrains Java Runtime.
+
+### IntelliJ Platform Configuration
+
+Explicitly setting the [`intellij.version`](tools_gradle_intellij_plugin.md#intellij-extension-version) and [`intellij.type`](tools_gradle_intellij_plugin.md#intellij-extension-type) properties tells the Gradle plugin to use that configuration of the IntelliJ Platform to create the plugin project.
+
+> See the [Developing for Multiple Products](dev_alternate_products.md) page for information about how to develop a plugin that is compatible with multiple IntelliJ-based IDEs.
+>
+{type="tip"}
+
+All available platform versions can be browsed in the [](intellij_artifacts.md).
+
+If the chosen platform version is not available in the repositories, or a local installation of the target IDE is the desired type and version of the IntelliJ Platform, use [`intellij.localPath`](tools_gradle_intellij_plugin.md#intellij-extension-localpath) to point to that installation.
+If the `intellij.localPath` attribute is set, do not set the `intellij.version` and `intellij.type` attributes as this could result in undefined behavior.
+
+### Plugin Dependencies
+
+IntelliJ Platform plugin projects may depend on either bundled or third-party plugins.
+In that case, a project should build against a version of those plugins that match the IntelliJ Platform version used to build the plugin project.
+The Gradle plugin will fetch any plugins in the list defined by [`intellij.plugins`](tools_gradle_intellij_plugin.md#intellij-extension-plugins).
+See the Gradle plugin [IntelliJ Extension](tools_gradle_intellij_plugin.md#configuration-intellij-extension) for information about specifying the plugin and version.
+
+Note that this attribute describes a dependency so that the Gradle plugin can fetch the required artifacts.
+The runtime dependency must be added in the [Plugin Configuration](plugin_configuration_file.md) (<path>plugin.xml</path>) file as described in [Plugin Dependencies](plugin_dependencies.md#3-dependency-declaration-in-pluginxml).
+
+## Run IDE Task
+
+By default, the Gradle plugin will use the same version of the IntelliJ Platform for the IDE Development Instance as was used for building the plugin.
+Using the corresponding JetBrains Runtime is also the default, so for this use-case no further configuration is required.
+
+### Running Against Alternate Versions and Types of IntelliJ Platform-Based IDEs
+
+The IntelliJ Platform IDE used for the [Development Instance](ide_development_instance.md) can be different from that used to build the plugin project.
+Setting the [`runIde.ideDir`](tools_gradle_intellij_plugin.md#runide-task-idedir) property will define an IDE to be used for the Development Instance.
+This attribute is commonly used when running or debugging a plugin in an [alternate IntelliJ Platform-based IDE](intellij_platform.md#ides-based-on-the-intellij-platform).
+
+### Running Against Alternate Versions of the JetBrains Runtime
+
+Every version of the IntelliJ Platform has a corresponding version of the [JetBrains Runtime](ide_development_instance.md#using-a-jetbrains-runtime-for-the-development-instance).
+A different version of the runtime can be used by specifying the [`runIde.jbrVersion`](tools_gradle_intellij_plugin.md#runide-task-jbrversion) attribute, describing a version of the JetBrains Runtime that should be used by the IDE Development Instance.
+The Gradle plugin will fetch the specified JetBrains Runtime as needed.
+
+## Patching the Plugin Configuration File
+
+A plugin project's <path>plugin.xml</path> file has element values that are "patched" at build time from the attributes of the [`patchPluginXml`](tools_gradle_intellij_plugin.md#tasks-patchpluginxml) task.
+As many as possible of the attributes in the Patching DSL will be substituted into the corresponding element values in a plugin project's <path>plugin.xml</path> file:
+* If a `patchPluginXml` attribute default value is defined, the attribute value will be patched in <path>plugin.xml</path> _regardless of whether the `patchPluginXml` task appears in the Gradle build script_.
+  * For example, the default values for the attributes [`patchPluginXml.sinceBuild`](tools_gradle_intellij_plugin.md#patchpluginxml-task-sincebuild) and [`patchPluginXml.untilBuild`](tools_gradle_intellij_plugin.md#patchpluginxml-task-untilbuild) are defined based on the declared (or default) value of [`intellij.version`](tools_gradle_intellij_plugin.md#intellij-extension-version).
+    So by default `patchPluginXml.sinceBuild` and `patchPluginXml.untilBuild` are substituted into the [`<idea-version>`](plugin_configuration_file.md#idea-plugin__idea-version) element's `since-build` and `until-build` attributes in the <path>plugin.xml</path> file.
+* If a [`patchPluginXml`](tools_gradle_intellij_plugin.md#tasks-patchpluginxml) task's attribute value is explicitly defined, the attribute value will be substituted in <path>plugin.xml</path>.
+  * If both `patchPluginXml.sinceBuild` and `patchPluginXml.untilBuild` attributes are explicitly set, both are substituted in <path>plugin.xml</path>.
+  * If one attribute is explicitly set (e.g. `patchPluginXml.sinceBuild`) and one is not (e.g. `patchPluginXml.untilBuild` has a default value), both attributes are patched at their respective (explicit and default) values.
+* For **no substitution** of the `<idea-version>` element's `since-build` and `until-build` attributes, set [`intellij.updateSinceUntilBuild`](tools_gradle_intellij_plugin.md#intellij-extension-updatesinceuntilbuild) to `false`, and do not provide `patchPluginXml.sinceBuild` and `patchPluginXml.untilBuild` values.
+
+The best practice to avoid confusion is to replace the elements in <path>plugin.xml</path> that will be patched by the Gradle plugin with a comment.
+That way, the values for these parameters do not appear in two places in the source code.
+The Gradle plugin will add the necessary elements as part of the patching process.
+For those [`patchPluginXml`](tools_gradle_intellij_plugin.md#tasks-patchpluginxml) attributes that contain descriptions such as [`patchPluginXml.changeNotes`](tools_gradle_intellij_plugin.md#patchpluginxml-task-changenotes) and [`patchPluginXml.pluginDescription`](tools_gradle_intellij_plugin.md#patchpluginxml-task-plugindescription), a `CDATA` block is not necessary when using HTML elements.
+
+> To maintain and generate an up-to-date changelog, try using [Gradle Changelog Plugin](https://github.com/JetBrains/gradle-changelog-plugin).
+>
+{type="tip"}
+
+As discussed in [](creating_plugin_project.md#components-of-a-wizard-generated-gradle-intellij-platform-plugin), the Gradle properties `project.version`, `project.group`, and `rootProject.name` are all generated based on the input to the Wizard.
+However, the [](tools_gradle_intellij_plugin.md) does not combine and substitute those Gradle properties for the default [`<id>`](plugin_configuration_file.md#idea-plugin__id) and [`<name>`](plugin_configuration_file.md#idea-plugin__name) elements in the <path>plugin.xml</path> file.
+
+The best practice is to keep `project.version` current.
+By default, if you modify `project.version` in Gradle build script, the Gradle plugin will automatically update the [`<version>`](plugin_configuration_file.md#idea-plugin__version) value in the <path>plugin.xml</path> file.
+This practice keeps all version declarations synchronized.
+
+## Verifying Plugin
+
+The Gradle plugin provides tasks that allow for running integrity and compatibility tests:
+* [`verifyPluginConfiguration`](tools_gradle_intellij_plugin.md#tasks-verifypluginconfiguration) - validates the versions of SDK, target platform, APIs, etc., configured in a plugin project,
+* [`verifyPlugin`](tools_gradle_intellij_plugin.md#tasks-verifyplugin) - validates completeness and contents of <path>plugin.xml</path> descriptors as well as plugin's archive structure,
+* [`runPluginVerifier`](tools_gradle_intellij_plugin.md#tasks-runpluginverifier) - runs the [IntelliJ Plugin Verifier](https://github.com/JetBrains/intellij-plugin-verifier) tool to check the binary compatibility with specified IntelliJ IDE builds.
+
+Plugin Verifier integration task allows for configuring the exact IDE versions that your plugin will be checked against.
+See [](verifying_plugin_compatibility.md#plugin-verifier) for more information.
+
+## Publishing Plugin
+
+Please review the [](publishing_plugin.md) page before using the [`publishPlugin`](tools_gradle_intellij_plugin.md#tasks-publishplugin) task.
+That documentation explains different ways to use Gradle for plugin uploads without exposing account credentials.

topics/tutorials/build_system/creating_plugin_project.md

@@ -1,16 +1,10 @@
-[//]: # (title: Getting Started with Gradle)
+[//]: # (title: Creating a Plugin Gradle Project)
 
 <!-- Copyright 2000-2022 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. -->
 
-Gradle is the preferred solution for creating IntelliJ Platform plugins.
-The IntelliJ IDEA Ultimate and Community editions bundle the necessary plugins to support Gradle-based development.
-These IntelliJ IDEA plugins are _Gradle_ and _Plugin DevKit_, which are enabled by default.
-To verify these plugins are installed and enabled, see the help section about [Managing Plugins](https://www.jetbrains.com/help/idea/managing-plugins.html).
+This documentation page describes a Gradle-based plugin project generated with the [New Project Wizard](https://www.jetbrains.com/help/idea/new-project-wizard.html), but the project generated with [](plugin_github_template.md) covers all the described files and directories.
 
-## Creating a Gradle-Based IntelliJ Platform Plugin with New Project Wizard
-
-Creating new Gradle-based IntelliJ Platform plugin projects is performed using the dedicated generator available in the [New Project Wizard](https://www.jetbrains.com/help/idea/new-project-wizard.html).
-The generator creates all the necessary project files based on a few template inputs.
+## Creating a Plugin with New Project Wizard
 
 <procedure title="Create IDE Plugin" id="create-ide-plugin">
 
@@ -20,7 +14,7 @@ Launch the <control>New Project</control> wizard via the <menupath>File | New |
 3. Choose the <control>Plugin</control> option in the project <control>Type</control>.
 4. Choose the <control>Language</control> the plugin will use for implementation.
    For this example select the <control>Java</control> option.
-  See [Kotlin for Plugin Developers](kotlin.md) for more information.
+   See [Kotlin for Plugin Developers](using_kotlin.md) for more information.
 5. Provide the <control>Group</control> which is typically an inverted company domain (e.g. `com.example.mycompany`).
    It is used for the Gradle property `project.group` value in the project's Gradle build script.
 6. Provide the <control>Artifact</control> which is the default name of the build project artifact (without a version).
@@ -29,7 +23,8 @@ Launch the <control>New Project</control> wizard via the <menupath>File | New |
 7. Select <control>JDK</control> 11.
    This JDK will be the default JRE used to run Gradle, and the JDK version used to compile the plugin Java sources.
 
-> When targeting 2020.3 and later only, using Java 11 is now required. See the [IntelliJ project migrates to Java 11](https://blog.jetbrains.com/platform/2020/09/intellij-project-migrates-to-java-11/) blog post for details.
+> When targeting 2020.3 and later only, using Java 11 is required.
+> See the [IntelliJ project migrates to Java 11](https://blog.jetbrains.com/platform/2020/09/intellij-project-migrates-to-java-11/) blog post for details.
 >
 > When targeting 2022.2 and later only, using Java 17 is required.
 >
@@ -41,7 +36,7 @@ Launch the <control>New Project</control> wizard via the <menupath>File | New |
 
 ### Components of a Wizard-Generated Gradle IntelliJ Platform Plugin
 
-For the [example](#creating-a-gradle-based-intellij-platform-plugin-with-new-project-wizard) `my_plugin`, the _IDE Plugin_ generator creates the following directory content:
+For the example `my_plugin` created with the steps describes above, the _IDE Plugin_ generator creates the following directory content:
 
 ```text
 my_plugin
@@ -79,7 +74,7 @@ The generated `my_plugin` project <path>build.gradle.kts</path> file:
 ```kotlin
 plugins {
   id("java")
-  id("org.jetbrains.intellij") version "1.7.0"
+  id("org.jetbrains.intellij") version "1.9.0"
 }
 
 group = "com.example"
@@ -123,15 +118,15 @@ tasks {
 ```
 
 * Two Gradle plugins are explicitly declared:
-  * The [Gradle Java](https://docs.gradle.org/current/userguide/java_plugin.html) plugin.
-  * The [](tools_gradle_intellij_plugin.md).
+  * The [Gradle Java](https://docs.gradle.org/current/userguide/java_plugin.html) plugin (`java`).
+  * The [](tools_gradle_intellij_plugin.md) (`org.jetbrains.intellij`).
 * The <control>Group</control> from the [New Project](#create-ide-plugin) wizard is the `project.group` value.
 * The `sourceCompatibility` line is injected to enforce using Java 11 JDK to compile Java sources.
 * The values of the [`intellij.version`](tools_gradle_intellij_plugin.md#intellij-extension-version) and [`intellij.type`](tools_gradle_intellij_plugin.md#intellij-extension-type) properties specify the version and type of the IntelliJ Platform to be used to build the plugin.
 * The empty placeholder list for [plugin dependencies](tools_gradle_intellij_plugin.md#intellij-extension-plugins).
 * The values of the [`patchPluginXml.sinceBuild`](tools_gradle_intellij_plugin.md#patchpluginxml-task-sincebuild) and [`patchPluginXml.untilBuild`](tools_gradle_intellij_plugin.md#patchpluginxml-task-untilbuild) properties specifying the minimum and maximum versions of the IDE build the plugin is compatible with.
 * The initial [`signPlugin`](tools_gradle_intellij_plugin.md#tasks-signplugin) and [`publishPlugin`](tools_gradle_intellij_plugin.md#tasks-publishplugin) tasks configuration.
-  See the [](deployment.md) section for more information.
+  See the [](publishing_plugin.md#publishing-plugin-with-gradle) section for more information.
 
 > Consider using the [IntelliJ Platform Plugin Template](https://github.com/JetBrains/intellij-platform-plugin-template) which uses the Gradle setup and provides CI setup covered with GitHub Actions.
 >
@@ -147,29 +142,7 @@ The `<name>` element (used as the plugin's display name) is often the same as `r
 The `<id>` value must be a unique identifier over all plugins, typically a concatenation of the specified <control>Group</control> and <control>Artifact</control>.
 Please note that it is impossible to change the `<id>` of a published plugin without losing automatic updates for existing installations.
 
-## Adding Gradle Support to an Existing DevKit-Based IntelliJ Platform Plugin
-
-> See [Revamping Plugins #3 – Migrating from DevKit to the Gradle build system](https://blog.jetbrains.com/platform/2021/12/migrating-from-devkit-to-the-gradle-build-system/) blog post for a step-by-step walk-through.
->
-{type="tip"}
-
-Converting a [DevKit-based](using_dev_kit.md) plugin project to a Gradle-based plugin project can be done using the New Project Wizard to create a Gradle-based project around the existing DevKit-based project:
-* Ensure the directory containing the DevKit-based IntelliJ Platform plugin project can be fully recovered if necessary.
-* Delete all the artifacts of the DevKit-based project:
-  * <path>.idea</path> directory
-  * <path>[modulename].iml</path> file
-  * <path>out</path> directory
-* Arrange the existing source files within the project directory in the Gradle [source set](https://docs.gradle.org/current/userguide/java_plugin.html#sec:java_project_layout) format.
-* Use the New Project Wizard as though creating a [new Gradle project](#creating-a-gradle-based-intellij-platform-plugin-with-new-project-wizard) from scratch.
-* On the [New Project](#create-ide-plugin) choose the <control>IDE Plugin</control> generator and set the values of:
-  * <control>Group</control> to the existing package in the initial source set.
-  * <control>Artifact</control> to the name of the existing plugin.
-  * <control>Name</control> to the name of the directory where the existing plugin is located, e.g. if the plugin project base directory is <path>/Users/john/Projects/old_plugin</path>, it should be the <path>old_plugin</path>.
-  * <control>Location</control> to the name of the plugin's parent directory, e.g. if the plugin project base directory is <path>/Users/john/Projects/old_plugin</path>, it should be the <path>/Users/john/Projects</path>.
-* Click <control>Finish</control> to create the new Gradle-based plugin.
-* [Add more modules](https://www.jetbrains.com/help/idea/gradle.html#gradle_add_module) using Gradle [source sets](https://www.jetbrains.com/help/idea/gradle.html#gradle_source_sets) as needed.
-
-## Running a Simple Gradle-Based IntelliJ Platform Plugin
+## Running a Plugin With the `runIde` Gradle task
 
 Gradle projects are run from the IDE's Gradle Tool window.
 
@@ -186,10 +159,8 @@ To execute the Gradle `runIde` task directly, open the <control>Gradle</control>
 If it's not on the list, hit the re-import button in the [toolbar](https://www.jetbrains.com/help/idea/jetgradle-tool-window.html#1eeec055) at the top of the Gradle tool window.
 When the <control>runIde</control> task is visible, double-click it to execute.
 
-> See the IntelliJ IDEA help for more information about [Gradle tasks](https://www.jetbrains.com/help/idea/work-with-gradle-tasks.html).
-
 To debug your plugin in a _standalone_ IDE instance, please see [How to Debug Your Own IntelliJ IDEA Instance](https://medium.com/agorapulse-stories/how-to-debug-your-own-intellij-idea-instance-7d7df185a48d) blog post.
 
-> See the [Working with Gradle in IntelliJ IDEA](https://www.youtube.com/watch?v=6V6G3RyxEMk) screencast for more information about how to work with Gradle-based projects.
+> For more information about how to work with Gradle-based projects see the [Working with Gradle in IntelliJ IDEA](https://www.youtube.com/watch?v=6V6G3RyxEMk) screencast and working with [Gradle tasks](https://www.jetbrains.com/help/idea/work-with-gradle-tasks.html) in the IntelliJ IDEA help.
 >
 {type="tip"}

topics/tutorials/build_system/deployment.md

@@ -1,150 +0,0 @@
-[//]: # (title: Publishing Plugins with Gradle)
-
-<!-- Copyright 2000-2022 JetBrains s.r.o. and other contributors. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file. -->
-
-Once you have [configured Gradle support](gradle_guide.md), you can automatically build and deploy your plugin to the [JetBrains Marketplace](https://plugins.jetbrains.com).
-To automatically deploy a plugin, you need to have _already published the plugin to the plugin repository at least once._
-Please see the guide page for manually [publishing a plugin](publishing_plugin.md) for the first time and [Building Distribution](#building-distribution) on obtaining the initial plugin distribution artifact.
-
-> Please see [Marketing](marketing.md) for remarks on how to prepare your plugin for optimal presentation.
->
-{type="tip"}
-
-> When adding additional repositories to your Gradle build script, always use HTTPS protocol.
->
-{type="warning"}
-
-## Building Distribution
-
-For initial upload, manual distribution or local installation, invoke the [`buildPlugin`](tools_gradle_intellij_plugin.md#tasks-buildplugin) Gradle task to create the plugin distribution.
-The resulting ZIP file is located in <path>build/distributions</path> and can then be installed via drag & drop (or using [plugin manager](https://www.jetbrains.com/help/idea/managing-plugins.html#installing-plugins-from-disk))
-or uploaded to a [](custom_plugin_repository.md).
-
-## Providing Your Personal Access Token to Gradle
-
-To deploy a plugin to the JetBrains Marketplace, you need to supply your Personal Access Token, which you can find on your profile page, in [My Tokens](https://plugins.jetbrains.com/author/me/tokens) section.
-
-To create a new token, provide its name and click the <control>Generate Token</control> button.
-A new token will be created and displayed right below.
-
-> Copy it before you close this page and keep it in a secure location.
-> This is the only time the token is visible.
->
-{type="note"}
-
-This section describes two options to supply your _Personal Access Token_ via Gradle using:
-* Environment variables,
-* Parameters to the Gradle task.
-
-### Using Environment Variables
-
-Start by defining an environment variable such as:
-
-```bash
-export ORG_GRADLE_PROJECT_intellijPublishToken='YOUR_TOKEN'
-```
-
-> On macOS systems, environment variables set in <path>.bash_profile</path> are only visible to processes you run from bash.
-> Environment variables visible to all processes need to be defined in [Environment.plist](https://developer.apple.com/library/archive/qa/qa1067/_index.html).
->
-{type="note"}
-
-Now provide the environment variable in the run configuration with which you run the [`publishPlugin`](tools_gradle_intellij_plugin.md#tasks-publishplugin) task locally.
-To do so, create a Gradle run configuration (if not already done), choose your Gradle project, specify the [`publishPlugin`](tools_gradle_intellij_plugin.md#tasks-publishplugin) task, and then add the environment variable.
-
-<tabs group="languages">
-<tab title="Kotlin" group-key="kotlin">
-
-```kotlin
-publishPlugin {
-  token.set(System.getenv("ORG_GRADLE_PROJECT_intellijPublishToken"))
-}
-```
-
-</tab>
-<tab title="Groovy" group-key="groovy">
-
-```groovy
-publishPlugin {
-  token = System.getenv("ORG_GRADLE_PROJECT_intellijPublishToken")
-}
-```
-
-</tab>
-</tabs>
-
-
-Note that you still need to put some default values (can be empty) in the Gradle properties because otherwise, you will get a compilation error.
-
-### Using Parameters for the Gradle Task
-
-Like using environment variables, you can also pass your token as a parameter to the Gradle task.
-For example, you can provide the parameter
-
-```bash
--Dorg.gradle.project.intellijPublishToken=YOUR_TOKEN
-```
-on the command line or by putting it in the arguments of your Gradle run configuration.
-
-Note that also, in this case, you still need to put some default values in your Gradle properties.
-
-## Deploying a Plugin with Gradle
-
-The first step when deploying a plugin is to confirm that it works correctly.
-You may wish to verify this by [installing your plugin from disk](https://www.jetbrains.com/help/idea/managing-plugins.html) on a fresh instance of your target IDE(s).
-
-### Signing a Plugin
-
-The Marketplace signing is designed to ensure that plugins are not modified over the course of the publishing and delivery pipeline.
-In version `1.x`, the Gradle IntelliJ Plugin provides the [`signPlugin`](tools_gradle_intellij_plugin.md#tasks-signplugin) task, which will be executed automatically right before the [`publishPlugin`](tools_gradle_intellij_plugin.md#tasks-publishplugin).
-
-For more details on generating a proper certificate and configuring the [`signPlugin`](tools_gradle_intellij_plugin.md#tasks-signplugin) task, check the [Plugin Signing](plugin_signing.md) article.
-
-### Publishing a Plugin
-
-Once you are confident the plugin works as intended, make sure the plugin version is updated, as the JetBrains Marketplace won't accept multiple artifacts with the same version.
-
-To deploy a new version of your plugin to the JetBrains Marketplace, invoke the [`publishPlugin`](tools_gradle_intellij_plugin.md#tasks-publishplugin) Gradle task.
-
-Now check the most recent version of your plugin on the [JetBrains Marketplace](https://plugins.jetbrains.com/).
-If successfully deployed, any users who currently have your plugin installed on an available version of the IntelliJ Platform are notified of a new update available as soon as the update has been verified.
-
-### Specifying a Release Channel
-
-You may also deploy plugins to a release channel of your choosing, by configuring the [`publishPlugin.channels`](tools_gradle_intellij_plugin.md#publishplugin-task-channels) property.
-For example:
-
-<tabs group="languages">
-<tab title="Kotlin" group-key="kotlin">
-
-```kotlin
-publishPlugin {
-  channels.set(listOf("beta"))
-}
-```
-
-</tab>
-<tab title="Groovy" group-key="groovy">
-
-```groovy
-publishPlugin {
-  channels = ['beta']
-}
-```
-
-</tab>
-</tabs>
-
-When empty, this uses the default plugin repository, available to all [JetBrains Marketplace](https://plugins.jetbrains.com/) users.
-However, you can publish it to an arbitrarily-named channel.
-These non-default release channels are treated as separate repositories.
-
-When using a non-default release channel, users need to configure a new [custom plugin repository](https://www.jetbrains.com/help/idea/managing-plugins.html#repos) in their IDE to install your plugin.
-For example, if you specify `publishPlugin.channels = ['canary']`, then users need to add the `https://plugins.jetbrains.com/plugins/canary/list` repository to install the plugin and receive updates.
-
-Popular channel names include:
-* `alpha`: https://plugins.jetbrains.com/plugins/alpha/list
-* `beta`: https://plugins.jetbrains.com/plugins/beta/list
-* `eap`: https://plugins.jetbrains.com/plugins/eap/list
-
-More information about the available configuration options is in the [documentation of the IntelliJ Gradle Plugin](tools_gradle_intellij_plugin.md#tasks-publishplugin).

topics/tutorials/build_system/gradle_guide.md

@@ -1,156 +0,0 @@
-[//]: # (title: Configuring Gradle Projects)
-
-<!-- Copyright 2000-2022 JetBrains s.r.o. and other contributors. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file. -->
-
-This page serves as a guide to Gradle-based plugin configuration for IntelliJ Platform projects.
-The IntelliJ IDEA Ultimate and Community editions bundle the _Gradle_ and _Plugin DevKit_ plugins to support Gradle-based development.
-
-The [](gradle_prerequisites.md) page provides a tutorial for creating Gradle-based IntelliJ Platform plugins.
-It may be useful to review the IntelliJ Platform page, particularly the description of versioning in the [](intellij_platform.md#open-source) section.
-
-> When adding additional repositories to your Gradle build script, always use HTTPS protocol.
->
-{type="warning"}
-
-## Overview of the Gradle IntelliJ Plugin
-
-The Gradle plugin is built from the open-source project [](tools_gradle_intellij_plugin.md).
-This plugin adds Gradle tasks that enable developing IntelliJ Platform plugins.
-
-## Guide to Configuring Gradle IntelliJ Plugin Functionality
-
-This section presents a guided tour of Gradle plugin attributes to achieve the commonly desired functionality.
-
-### Configuring the Gradle IntelliJ Plugin for Building IntelliJ Platform Plugin Projects
-
-By default, the Gradle plugin will build a plugin project against the IntelliJ Platform defined by the latest EAP snapshot of the IntelliJ IDEA Community Edition.
-
-> Using EAP versions of the IntelliJ Platform requires adding the _Snapshots repository_ to the Gradle build script (see [IntelliJ Platform Artifacts Repositories](intellij_artifacts.md)).
->
-{type="note"}
-
-If a matching version of the specified IntelliJ Platform is not available on the local machine, the Gradle plugin downloads the correct version and type.
-IntelliJ IDEA then indexes the build and any associated source code and JetBrains Java Runtime.
-
-#### IntelliJ Platform Configuration
-
-Explicitly setting the [`intellij.version`](tools_gradle_intellij_plugin.md#intellij-extension-version) and [`intellij.type`](tools_gradle_intellij_plugin.md#intellij-extension-type) properties tells the Gradle plugin to use that configuration of the IntelliJ Platform to create the plugin project.
-
-All available platform versions can be browsed in the [](intellij_artifacts.md).
-
-If the chosen platform version is not available in the repositories, or a local installation of the target IDE is the desired type and version of the IntelliJ Platform, use [`intellij.localPath`](tools_gradle_intellij_plugin.md#intellij-extension-localpath) to point to that installation.
-If the [`intellij.localPath`](tools_gradle_intellij_plugin.md#intellij-extension-localpath) attribute is set, do not set the [`intellij.version`](tools_gradle_intellij_plugin.md#intellij-extension-version) and [`intellij.type`](tools_gradle_intellij_plugin.md#intellij-extension-type) attributes as this could result in undefined behavior.
-
-#### Plugin Dependencies
-
-IntelliJ Platform plugin projects may depend on either bundled or third-party plugins.
-In that case, a project should build against a version of those plugins that match the IntelliJ Platform version used to build the plugin project.
-The Gradle plugin will fetch any plugins in the list defined by [`intellij.plugins`](tools_gradle_intellij_plugin.md#intellij-extension-plugins).
-See the Gradle plugin [IntelliJ Extension](tools_gradle_intellij_plugin.md#configuration-intellij-extension) for information about specifying the plugin and version.
-
-Note that this attribute describes a dependency so that the Gradle plugin can fetch the required artifacts.
-The runtime dependency must be added in the [Plugin Configuration](plugin_configuration_file.md) (<path>plugin.xml</path>) file as described in [Plugin Dependencies](plugin_dependencies.md#3-dependency-declaration-in-pluginxml).
-
-### Configuring the Gradle Plugin for Running IntelliJ Platform Plugin Projects
-
-By default, the Gradle plugin will use the same version of the IntelliJ Platform for the IDE Development Instance as was used for building the plugin.
-Using the corresponding JetBrains Runtime is also the default, so for this use-case no further configuration is required.
-
-#### Running Against Alternate Versions and Types of IntelliJ Platform-Based IDEs
-
-The IntelliJ Platform IDE used for the Development Instance can be different from that used to build the plugin project.
-Setting the [`runIde.ideDir`](tools_gradle_intellij_plugin.md#runide-task-idedir) property will define an IDE to be used for the Development Instance.
-This attribute is commonly used when running or debugging a plugin in an [alternate IntelliJ Platform-based IDE](intellij_platform.md#ides-based-on-the-intellij-platform).
-
-#### Running Against Alternate Versions of the JetBrains Runtime
-
-Every version of the IntelliJ Platform has a corresponding version of the [JetBrains Runtime](ide_development_instance.md#using-a-jetbrains-runtime-for-the-development-instance).
-A different version of the runtime can be used by specifying the [`runIde.jbrVersion`](tools_gradle_intellij_plugin.md#runide-task-jbrversion) attribute, describing a version of the JetBrains Runtime that should be used by the IDE Development Instance.
-The Gradle plugin will fetch the specified JetBrains Runtime as needed.
-
-### Managing Directories Used by the Gradle Plugin
-
-There are several attributes to control where the Gradle plugin places directories for downloads and use by the IDE Development Instance.
-
-The location of the [sandbox home](ide_development_instance.md#the-development-instance-sandbox-directory) directory and its subdirectories can be controlled with Gradle plugin attributes.
-The [`intellij.sandboxDirectory`](tools_gradle_intellij_plugin.md#intellij-extension-sandboxdir) attribute is used to set the path for the sandbox directory to be used while running the plugin in an IDE Development Instance.
-Locations of the sandbox [subdirectories](ide_development_instance.md#development-instance-settings-caches-logs-and-plugins) can be controlled using the [`runIde.configDirectory`](tools_gradle_intellij_plugin.md#tasks-runide), [`runIde.pluginsDirectory`](tools_gradle_intellij_plugin.md#tasks-runide), and [`runIde.systemDirectory`](tools_gradle_intellij_plugin.md#tasks-runide) attributes.
-If the [`intellij.sandboxDirectory`](tools_gradle_intellij_plugin.md#intellij-extension-sandboxdir) path is explicitly set, the subdirectory attributes default to the new sandbox directory.
-
-The storage location of downloaded IDE versions and components defaults to the Gradle cache directory.
-However, it can be controlled by setting the [`intellij.ideaDependencyCachePath`](tools_gradle_intellij_plugin.md#intellij-extension-ideadependencycachepath) attribute.
-
-### Controlling Downloads by the Gradle Plugin
-
-As mentioned in the section about [configuring the IntelliJ Platform](#configuring-the-gradle-intellij-plugin-for-building-intellij-platform-plugin-projects) used for building plugin projects, the Gradle plugin will fetch the version of the IntelliJ Platform specified by the default or by the `intellij` attributes.
-Standardizing the versions of the Gradle plugin and Gradle system across projects will minimize the time spent downloading versions.
-
-There are controls for managing the [](tools_gradle_intellij_plugin.md) version, and the version of Gradle itself.
-The plugin version is defined in the `plugins {...}` section of a project's Gradle build script.
-The version of Gradle is defined in <path>$PROJECT_ROOT$/gradle/wrapper/gradle-wrapper.properties</path>.
-
-### Patching the Plugin Configuration File
-
-A plugin project's <path>plugin.xml</path> file has element values that are "patched" at build time from the attributes of the [`patchPluginXml`](tools_gradle_intellij_plugin.md#tasks-patchpluginxml) task.
-As many as possible of the attributes in the Patching DSL will be substituted into the corresponding element values in a plugin project's <path>plugin.xml</path> file:
-* If a [`patchPluginXml`](tools_gradle_intellij_plugin.md#tasks-patchpluginxml) attribute default value is defined, the attribute value will be patched in <path>plugin.xml</path> _regardless of whether the [`patchPluginXml`](tools_gradle_intellij_plugin.md#tasks-patchpluginxml) task appears in the Gradle build script_.
-  * For example, the default values for the attributes [`patchPluginXml.sinceBuild`](tools_gradle_intellij_plugin.md#patchpluginxml-task-sincebuild) and [`patchPluginXml.untilBuild`](tools_gradle_intellij_plugin.md#patchpluginxml-task-untilbuild) are defined based on the declared (or default) value of [`intellij.version`](tools_gradle_intellij_plugin.md#intellij-extension-version).
-    So by default [`patchPluginXml.sinceBuild`](tools_gradle_intellij_plugin.md#patchpluginxml-task-sincebuild) and [`patchPluginXml.untilBuild`](tools_gradle_intellij_plugin.md#patchpluginxml-task-untilbuild) are substituted into the [`<idea-version>`](plugin_configuration_file.md#idea-plugin__idea-version) element's `since-build` and `until-build` attributes in the <path>plugin.xml</path> file.
-* If a [`patchPluginXml`](tools_gradle_intellij_plugin.md#tasks-patchpluginxml) attribute value is explicitly defined, the attribute value will be substituted in <path>plugin.xml</path>.
-  * If both [`patchPluginXml.sinceBuild`](tools_gradle_intellij_plugin.md#patchpluginxml-task-sincebuild) and [`patchPluginXml.untilBuild`](tools_gradle_intellij_plugin.md#patchpluginxml-task-untilbuild) attributes are explicitly set, both are substituted in <path>plugin.xml</path>.
-  * If one attribute is explicitly set (e.g. [`patchPluginXml.sinceBuild`](tools_gradle_intellij_plugin.md#patchpluginxml-task-sincebuild)) and one is not (e.g. [`patchPluginXml.untilBuild`](tools_gradle_intellij_plugin.md#patchpluginxml-task-untilbuild) has a default value,) both attributes are patched at their respective (explicit and default) values.
-* For **no substitution** of the `<idea-version>` element's `since-build` and `until-build` attributes, one of the following must appear in the Gradle build script:
-  * Either set [`intellij.updateSinceUntilBuild`](tools_gradle_intellij_plugin.md#intellij-extension-updatesinceuntilbuild) to `false`, which will disable substituting both `since-build` and `until-build` attributes,
-
-The best practice to avoid confusion is to replace the elements in <path>plugin.xml</path> that will be patched by the Gradle plugin with a comment.
-That way, the values for these parameters do not appear in two places in the source code.
-The Gradle plugin will add the necessary elements as part of the patching process.
-For those [`patchPluginXml`](tools_gradle_intellij_plugin.md#tasks-patchpluginxml) attributes that contain descriptions such as [`patchPluginXml.changeNotes`](tools_gradle_intellij_plugin.md#patchpluginxml-task-changenotes) and [`patchPluginXml.pluginDescription`](tools_gradle_intellij_plugin.md#patchpluginxml-task-plugindescription), a `CDATA` block is not necessary when using HTML elements.
-
-> To maintain and generate an up-to-date changelog, try using [Gradle Changelog Plugin](https://github.com/JetBrains/gradle-changelog-plugin).
->
-{type="tip"}
-
-As discussed in [Components of a Wizard-Generated Gradle IntelliJ Platform Plugin](gradle_prerequisites.md#components-of-a-wizard-generated-gradle-intellij-platform-plugin), the Gradle properties `project.version`, `project.group`, and `rootProject.name` are all generated based on the input to the Wizard.
-However, the [](tools_gradle_intellij_plugin.md) does not combine and substitute those Gradle properties for the default [`<id>`](plugin_configuration_file.md#idea-plugin__id) and [`<name>`](plugin_configuration_file.md#idea-plugin__name) elements in the <path>plugin.xml</path> file.
-
-The best practice is to keep `project.version` current.
-By default, if you modify `project.version` in Gradle build script, the Gradle plugin will automatically update the [`<version>`](plugin_configuration_file.md#idea-plugin__version) value in the <path>plugin.xml</path> file.
-This practice keeps all version declarations synchronized.
-
-### Verifying Plugin
-
-The Gradle plugin provides two tasks that allow for running integrity and compatibility tests:
-* [`verifyPlugin`](tools_gradle_intellij_plugin.md#tasks-verifyplugin) task - validates completeness and contents of <path>plugin.xml</path> descriptors as well as plugin's archive structure,
-* [`runPluginVerifier`](tools_gradle_intellij_plugin.md#tasks-runpluginverifier) task - runs the [IntelliJ Plugin Verifier](https://github.com/JetBrains/intellij-plugin-verifier) tool to check the binary compatibility with specified IntelliJ IDE builds.
-
-Plugin Verifier integration task allows for configuring the exact IDE versions that your plugin will be checked against.
-See [](verifying_plugin_compatibility.md#plugin-verifier) for more information.
-
-### Publishing with the Gradle Plugin
-
-Please review the [](deployment.md) page before using the [`publishPlugin`](tools_gradle_intellij_plugin.md#tasks-publishplugin) task.
-That documentation explains different ways to use Gradle for plugin uploads without exposing account credentials.
-
-## Common Gradle Plugin Configurations for Development
-
-Different combinations of Gradle plugin attributes are needed to create the desired build or IDE Development Instance environment.
-This section reviews some of the more common configurations.
-
-### Plugins Targeting IntelliJ IDEA
-
-IntelliJ Platform plugins targeting IntelliJ IDEA have the most straightforward Gradle plugin configuration.
-* Determine the version of [IntelliJ IDEA to use for building the plugin project](#configuring-the-gradle-intellij-plugin-for-building-intellij-platform-plugin-projects); this is the desired version of the IntelliJ Platform.
-  This can be EAP (default) or determined from the [build number ranges](build_number_ranges.md).
-  * If a production version of IntelliJ IDEA is the desired target, set the [`intellij.version`](tools_gradle_intellij_plugin.md#intellij-extension-version) property accordingly.
-  * Set the necessary [plugin dependencies](#plugin-dependencies), if any.
-* If the plugin project should be run or debugged in an IDE Development Instance based on the same IntelliJ IDEA version, no further attributes need to be set for the IDE Development Instance.
-  This is the default behavior and is the most common use case.
-  * If the plugin project should be run or debugged in an IDE Development Instance based on an alternate version of the IntelliJ Platform, set the [Running](#running-against-alternate-versions-and-types-of-intellij-platform-based-ides) DSL attribute accordingly.
-  * If the plugin project should be run using a JetBrains Runtime other than the default for the IDE Development Instance, specify the [JetBrains Runtime version](#running-against-alternate-versions-of-the-jetbrains-runtime).
-* Set the appropriate attributes for [patching the <path>plugin.xml</path> file](#patching-the-plugin-configuration-file).
-
-### Plugins Targeting Alternate IntelliJ Platform-Based IDEs
-
-Gradle also supports developing plugins to run in IDEs that are based on the IntelliJ Platform.
-For more information, see the [Developing for Multiple Products](dev_alternate_products.md) page of this guide.

topics/tutorials/custom_language_support/annotator.md

@@ -84,7 +84,7 @@ Using the `com.intellij.annotator` extension point in the plugin configuration f
 
 ## Run the Project
 
-Run the plugin by using the Gradle [`runIde`](gradle_prerequisites.md#running-a-simple-gradle-based-intellij-platform-plugin) task.
+Run the plugin by using the Gradle [`runIde`](creating_plugin_project.md#running-a-plugin-with-the-runide-gradle-task) task.
 
 As a test, define the following Java file containing a Simple Language `prefix:value` pair:
 

topics/tutorials/custom_language_support/code_style_settings.md

@@ -70,7 +70,7 @@ The `SimpleLanguageCodeStyleSettingsProvider` implementation is registered with
 
 ## Run the Project
 
-Run the plugin by using the Gradle [`runIde`](gradle_prerequisites.md#running-a-simple-gradle-based-intellij-platform-plugin) task.
+Run the plugin by using the Gradle [`runIde`](creating_plugin_project.md#running-a-plugin-with-the-runide-gradle-task) task.
 
 In the IDE Development Instance, open the Simple Language code formatting page: <menupath>Settings/Preferences | Editor | Code Style | Simple</menupath>.
 

topics/tutorials/custom_language_support/commenter.md

@@ -37,7 +37,7 @@ The `SimpleCommenter` implementation is registered in the plugin configuration f
 
 ## Run the Project
 
-Run the plugin by using the Gradle [`runIde`](gradle_prerequisites.md#running-a-simple-gradle-based-intellij-platform-plugin) task.
+Run the plugin by using the Gradle [`runIde`](creating_plugin_project.md#running-a-plugin-with-the-runide-gradle-task) task.
 
 Open the example Simple Language [properties file ](lexer_and_parser_definition.md#run-the-project) in the IDE Development Instance.
 Place the cursor at the `website` line.

topics/tutorials/custom_language_support/completion_contributor.md

@@ -39,7 +39,7 @@ The `SimpleCompletionContributor` implementation is registered in the plugin con
 
 ## Run the Project
 
-Run the plugin by using the Gradle [`runIde`](gradle_prerequisites.md#running-a-simple-gradle-based-intellij-platform-plugin) task.
+Run the plugin by using the Gradle [`runIde`](creating_plugin_project.md#running-a-plugin-with-the-runide-gradle-task) task.
 
 Open the [`test.simple`](lexer_and_parser_definition.md#run-the-project) file.
 Erase the property "English" and invoke [Basic Code Completion](https://www.jetbrains.com/help/idea/auto-completing-code.html#invoke-basic-completion).

topics/tutorials/custom_language_support/find_usages_provider.md

@@ -41,7 +41,7 @@ The `SimpleFindUsagesProvider` implementation is registered with the IntelliJ Pl
 
 ## Run the Project
 
-Run the plugin by using the Gradle [`runIde`](gradle_prerequisites.md#running-a-simple-gradle-based-intellij-platform-plugin) task.
+Run the plugin by using the Gradle [`runIde`](creating_plugin_project.md#running-a-plugin-with-the-runide-gradle-task) task.
 
 The IDE now supports [Find Usages](https://www.jetbrains.com/help/idea/find-highlight-usages.html) for any property with a reference:
 

topics/tutorials/custom_language_support/folding_builder.md

@@ -51,7 +51,7 @@ The `SimpleFoldingBuilder` implementation is registered with the IntelliJ Platfo
 
 ## Run the Project
 
-Run the plugin by using the Gradle [`runIde`](gradle_prerequisites.md#running-a-simple-gradle-based-intellij-platform-plugin) task.
+Run the plugin by using the Gradle [`runIde`](creating_plugin_project.md#running-a-plugin-with-the-runide-gradle-task) task.
 
 Now when a Java file is opened in the editor, it shows the property's value instead of the key.
 This is because `SimpleFoldingBuilder.isCollapsedByDefault()` always returns `true`.

topics/tutorials/custom_language_support/formatter.md

@@ -65,7 +65,7 @@ The `SimpleFormattingModelBuilder` implementation is registered with the Intelli
 
 ## Run the Project
 
-Run the plugin by using the Gradle [`runIde`](gradle_prerequisites.md#running-a-simple-gradle-based-intellij-platform-plugin) task.
+Run the plugin by using the Gradle [`runIde`](creating_plugin_project.md#running-a-plugin-with-the-runide-gradle-task) task.
 
 Open the example Simple Language [properties file ](lexer_and_parser_definition.md#run-the-project) in the IDE Development Instance.
 Add some extra spaces around the `=` separator between `language` and `English`.

topics/tutorials/custom_language_support/go_to_symbol_contributor.md

@@ -60,7 +60,7 @@ The `SimpleChooseByNameContributor` implementation is registered with the Intell
 
 ## Run the Project
 
-Run the plugin by using the Gradle [`runIde`](gradle_prerequisites.md#running-a-simple-gradle-based-intellij-platform-plugin) task.
+Run the plugin by using the Gradle [`runIde`](creating_plugin_project.md#running-a-plugin-with-the-runide-gradle-task) task.
 
 The IDE now supports navigating to a property definition by name pattern via <menupath>Navigate | Symbol</menupath> action.
 

topics/tutorials/custom_language_support/language_and_filetype.md

@@ -104,7 +104,7 @@ The `SimpleFileTypeFactory` is registered using the `com.intellij.fileTypeFactor
 
 ## Run the Project
 
-Run the plugin by using the Gradle [`runIde`](gradle_prerequisites.md#running-a-simple-gradle-based-intellij-platform-plugin) task.
+Run the plugin by using the Gradle [`runIde`](creating_plugin_project.md#running-a-plugin-with-the-runide-gradle-task) task.
 
 Create an empty file with the extension <path>.simple</path>, and IntelliJ IDEA automatically associates it with our language.
 Note the appearance of the Simple Language file icon next to the <path>test.simple</path> file in the <control>Project</control> Tool Window, and the editor tab for the file.

topics/tutorials/custom_language_support/lexer_and_parser_definition.md

@@ -94,7 +94,7 @@ For example, see <path>simple_language_plugin/src/main/resources/META-INF/plugin
 
 ## Run the Project
 
-Run the plugin by using the Gradle [`runIde`](gradle_prerequisites.md#running-a-simple-gradle-based-intellij-platform-plugin) task.
+Run the plugin by using the Gradle [`runIde`](creating_plugin_project.md#running-a-plugin-with-the-runide-gradle-task) task.
 
 Create a <path>test.simple</path>  file with the following content:
 

topics/tutorials/custom_language_support/line_marker_provider.md

@@ -94,7 +94,7 @@ The `SimpleLineMarkerProvider` implementation is registered with the IntelliJ Pl
 
 ## Run the Project
 
-Run the plugin by using the Gradle [`runIde`](gradle_prerequisites.md#running-a-simple-gradle-based-intellij-platform-plugin) task.
+Run the plugin by using the Gradle [`runIde`](creating_plugin_project.md#running-a-plugin-with-the-runide-gradle-task) task.
 
 Open the Java [Test file](annotator.md#run-the-project).
 Now the icon appears next to line 3 on the gutter.

topics/tutorials/custom_language_support/prerequisites.md

@@ -23,4 +23,4 @@ Install and enable [Grammar-Kit](https://plugins.jetbrains.com/plugin/6606-gramm
 
 ## Create a Project
 
-Create an empty [IntelliJ Platform Plugin project](gradle_prerequisites.md) or start using [](github_template.md) when creating a plugin hosted on GitHub.
+Create an empty [IntelliJ Platform Plugin project](creating_plugin_project.md) or start using [](plugin_github_template.md) when creating a plugin hosted on GitHub.

topics/tutorials/custom_language_support/quick_fix.md

@@ -45,7 +45,7 @@ This method call registers the `SimpleCreatePropertyQuickFix` as the Intention A
 {src="simple_language_plugin/src/main/java/org/intellij/sdk/language/SimpleAnnotator.java"}
 
 ## Run the Project
-Run the project by using the Gradle [`runIde`](gradle_prerequisites.md#running-a-simple-gradle-based-intellij-platform-plugin) task.
+Run the project by using the Gradle [`runIde`](creating_plugin_project.md#running-a-plugin-with-the-runide-gradle-task) task.
 Open the test [Java file](annotator.md#run-the-project).
 
 To test `SimpleCreatePropertyQuickFix`, change `simple:website` to `simple:website.url`.

topics/tutorials/custom_language_support/reference_contributor.md

@@ -149,7 +149,7 @@ The `SimpleReferenceContributor` implementation is registered using the `com.int
 
 ## Run the Project with the Reference Contributor
 
-Run the project by using the Gradle [`runIde`](gradle_prerequisites.md#running-a-simple-gradle-based-intellij-platform-plugin) task.
+Run the project by using the Gradle [`runIde`](creating_plugin_project.md#running-a-plugin-with-the-runide-gradle-task) task.
 
 The IDE now resolves the property and provides [completion](https://www.jetbrains.com/help/idea/auto-completing-code.html#basic_completion) suggestions:
 
@@ -183,7 +183,7 @@ The `SimpleRefactoringSupportProvider` implementation is registered with the Int
 
 ## Run the Project
 
-Run the project by using the Gradle [`runIde`](gradle_prerequisites.md#running-a-simple-gradle-based-intellij-platform-plugin) task.
+Run the project by using the Gradle [`runIde`](creating_plugin_project.md#running-a-plugin-with-the-runide-gradle-task) task.
 
 The IDE now supports [refactoring](https://www.jetbrains.com/help/idea/rename-refactorings.html) suggestions:
 

topics/tutorials/custom_language_support/structure_aware_navbar.md

@@ -39,8 +39,7 @@ configuration file using the `com.intellij.navbar` extension point.
 
 ## Run the Project
 
-Run the project by using the Gradle
-[runIde task](gradle_prerequisites.md#running-a-simple-gradle-based-intellij-platform-plugin).
+Run the project by using the Gradle [`runIde`](creating_plugin_project.md#running-a-plugin-with-the-runide-gradle-task) task.
 
 Open the <path>test.simple</path> file and position the caret on any property.
 The navigation bar displays the name and icon of this property.

topics/tutorials/custom_language_support/structure_view_factory.md

@@ -62,7 +62,7 @@ The `SimpleStructureViewFactory` implementation is registered with the IntelliJ
 
 ## Run the Project
 
-Run the project by using the Gradle [`runIde`](gradle_prerequisites.md#running-a-simple-gradle-based-intellij-platform-plugin) task.
+Run the project by using the Gradle [`runIde`](creating_plugin_project.md#running-a-plugin-with-the-runide-gradle-task) task.
 
 Open the <path>test.simple</path> file and choose <menupath>View | Tool Windows | Structure</menupath>.
 The IDE now supports a structure view of the Simple Language:

topics/tutorials/custom_language_support/syntax_highlighter_and_color_settings_page.md

@@ -91,7 +91,7 @@ Register the Simple Language color settings page with the IntelliJ Platform in t
 
 ### Run the Project
 
-Run the project by using the Gradle [`runIde`](gradle_prerequisites.md#running-a-simple-gradle-based-intellij-platform-plugin) task.
+Run the project by using the Gradle [`runIde`](creating_plugin_project.md#running-a-plugin-with-the-runide-gradle-task) task.
 
 In the IDE Development Instance, open the Simple Language highlight settings page: <menupath>Settings/Preferences | Editor | Color Scheme | Simple</menupath>.
 Each color initially inherits from a <control>Language Defaults</control> value.

topics/tutorials/github_template.md

@@ -1,20 +0,0 @@
-[//]: # (title: IntelliJ Platform Plugin Template)
-
-<!-- Copyright 2000-2022 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. -->
-
-[IntelliJ Platform Plugin Template][gh:ippt] is a repository that provides a pure boilerplate template to make it easier to create a new plugin project using the recommended [Gradle setup](gradle_build_system.md).
-
-The main goal of this template is to speed up the setup phase of plugin development for both new and experienced developers by preconfiguring the project scaffold and CI, linking to the proper documentation pages, and keeping everything organized.
-
-GitHub Template allows you to create a new repository from the scaffold without having to copy and paste content, clone repositories, or clear the history manually.
-All you have to do is click the <shortcut>Use this template</shortcut> button on the GitHub project page (you must be logged in with your GitHub account).
-After that, the GitHub Actions workflow will be triggered to override or remove any template-specific configurations, such as the plugin name, current changelog, etc.
-
-Once this is complete, the project is ready to be cloned to your local environment and opened with [IntelliJ IDEA][jb:download-ij].
-
-For more details, please refer to the [IntelliJ Platform Plugin Template][gh:ippt] project documentation.
-
-The recording of the _Busy Plugin Developer. Episode 0_ webinar describes and shows [how to use the IntelliJ Platform Plugin Template](https://youtu.be/-6D5-xEaYig?t=230) in detail.
-
-[gh:ippt]: https://github.com/JetBrains/intellij-platform-plugin-template
-[jb:download-ij]: https://www.jetbrains.com/idea/download

topics/tutorials/gradle_build_system.md

@@ -1,27 +0,0 @@
-[//]: # (title: Building Plugins with Gradle)
-
-<!-- Copyright 2000-2022 JetBrains s.r.o. and other contributors. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file. -->
-
-The [](tools_gradle_intellij_plugin.md) is the recommended solution for building IntelliJ Platform plugins.
-The plugin takes care of the dependencies of your plugin project — both the base IDE and other [plugin dependencies](plugin_dependencies.md).
-It provides tasks to run the IDE with your plugin and to package and [publish](deployment.md) your plugin to the [JetBrains Marketplace](https://plugins.jetbrains.com).
-To make sure that a plugin is not affected by [API changes](api_changes_list.md), which may happen between major releases of the platform, you can quickly verify your plugin against other IDEs and releases.
-
-> [](github_template.md) makes it easier to create and maintain your IDE plugins, having the Gradle plugin already integrated and CI covered with GitHub Actions.
->
-{type="tip"}
-
-> If a new plugin is Scala-based, a dedicated [SBT plugin](https://github.com/JetBrains/sbt-idea-plugin) is available.
->
-{type="note"}
-
-
-> Please make sure to always upgrade [](tools_gradle_intellij_plugin.md) to the latest version [![GitHub Release](https://img.shields.io/github/release/jetbrains/gradle-intellij-plugin.svg?style=flat-square)](https://github.com/jetbrains/gradle-intellij-plugin/releases)
->
-{type="note"}
-
-Below are a series of guides to developing and deploying Gradle-based IntelliJ Platform Plugins:
-
-* [](gradle_prerequisites.md)
-* [](gradle_guide.md)
-* [](deployment.md)

topics/tutorials/plugin_github_template.md

@@ -0,0 +1,25 @@
+[//]: # (title: IntelliJ Platform Plugin Template)
+
+<!-- Copyright 2000-2022 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. -->
+
+<excerpt>IntelliJ Platform Plugin Template is a GitHub template containing a minimal preconfigured plugin project and GitHub Actions CI workflows that cover building, testing and deploying the plugin.</excerpt>
+
+The IntelliJ Platform Plugin Template is the alternative solution for creating a new Gradle-based IntelliJ Platform plugin with the [New Project Wizard](creating_plugin_project.md).
+
+[IntelliJ Platform Plugin Template][gh:ippt] is a GitHub repository that provides a pure boilerplate template to make it easier to create a new Gradle-based plugin project.
+
+The main goal of this template is to speed up the setup phase of plugin development for both new and experienced developers by preconfiguring the project scaffold and CI, linking to the proper documentation pages, and keeping everything organized.
+
+GitHub Template allows you to create a new repository from the scaffold without having to copy and paste content, clone repositories, or clear the history manually.
+All you have to do is click the <control>Use this template</control> button on the GitHub project page (you must be logged in with your GitHub account).
+After that, the GitHub Actions workflow will be triggered to override or remove any template-specific configurations, such as the plugin name, current changelog, etc.
+
+Once this is complete, the project is ready to be cloned to your local environment and opened with [IntelliJ IDEA](https://www.jetbrains.com/idea/download).
+
+For more details, please refer to the [IntelliJ Platform Plugin Template][gh:ippt] project documentation.
+
+> The recording of the _Busy Plugin Developer. Episode 0_ webinar describes and shows [how to use the IntelliJ Platform Plugin Template](https://youtu.be/-6D5-xEaYig?t=230) in detail.
+>
+{type="note"}
+
+[gh:ippt]: https://github.com/JetBrains/intellij-platform-plugin-template

topics/tutorials/project_wizard/adding_new_steps.md

@@ -7,7 +7,7 @@ This tutorial shows how to add an extra step to the Project Wizard to provide ad
 ## Pre-Requirements
 
 Create an empty plugin project.
-See [Creating a Plugin Project](gradle_build_system.md) to know how to do it.
+See the [](creating_plugin_project.md) section for details.
 
 ## Register Module Builder
 

topics/tutorials/project_wizard/module_types.md

@@ -10,7 +10,8 @@ The source code for the [`module`](%gh-sdk-samples%/module) and [`project_wizard
 
 ## Pre-Requirements
 
-Create an empty plugin project, see [Creating a Plugin Project](gradle_build_system.md).
+Create an empty plugin project.
+See the [](creating_plugin_project.md) section for details.
 
 > The UI for selecting module types and the creation of modules through project wizard is IntelliJ IDEA-specific.
 >

topics/tutorials/run_configurations.md

@@ -16,7 +16,8 @@ See [Code Samples](code_samples.md) on how to set up and run the plugin.
 
 ## Pre-Requirements
 
-Create an empty plugin project as described in [Creating a Plugin Project](gradle_build_system.md).
+Create an empty plugin project.
+See the [](creating_plugin_project.md) section for details.
 
 ## Register a New ConfigurationType
 
@@ -82,7 +83,7 @@ The UI Form should be bound with a Java class responsible for handling UI compon
 
 ## Compile and Run the Plugin
 
-Refer to [Running and Debugging a Plugin](gradle_prerequisites.md#executing-the-plugin).
+Refer to [Running and Debugging a Plugin](creating_plugin_project.md#executing-the-plugin).
 
 After going through the steps described above you can create a custom Run Configuration from your plugin.
 

topics/tutorials/using_kotlin.md

@@ -1,11 +1,17 @@
-[//]: # (title: Kotlin for Plugin Developers)
+[//]: # (title: Configuring Kotlin Support)
 
-<!-- Copyright 2000-2022 JetBrains s.r.o. and other contributors. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file. -->
+<!-- Copyright 2000-2022 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. -->
 
-## Why Kotlin?
+
+This page describes developing a plugin code in Kotlin programming language.
+
+> To implement a plugin operating on Kotlin code, configure Kotlin [plugin dependency](plugin_dependencies.md) (`org.jetbrains.kotlin`).
+> See also [UAST](uast.md) page for information about how to support multiple JVM-languages, including Kotlin.
+
+## Advantages of Developing a Plugin in Kotlin
 
 Using [Kotlin](https://kotlinlang.org) to write plugins for the IntelliJ Platform is very similar to writing plugins in Java.
-Existing plugin developers can get started by converting boilerplate Java classes to their Kotlin equivalents by using the [J2K compiler](https://kotlinlang.org/docs/mixing-java-kotlin-intellij.html#converting-an-existing-java-file-to-kotlin-with-j2k) bundled with the IntelliJ Platform (versions 143.+), and developers can easily mix and match Kotlin classes with their existing Java code.
+Existing plugin developers can get started by converting boilerplate Java classes to their Kotlin equivalents by using the [J2K converter](https://kotlinlang.org/docs/mixing-java-kotlin-intellij.html#converting-an-existing-java-file-to-kotlin-with-j2k) (part of Kotlin plugin), and developers can easily mix and match Kotlin classes with their existing Java code.
 
 In addition to [null safety](https://kotlinlang.org/docs/null-safety.html) and [type-safe builders](https://kotlinlang.org/docs/type-safe-builders.html), the Kotlin language offers many convenient features for plugin development, which make plugins easier to read and simpler to maintain.
 Much like [Kotlin for Android](https://kotlinlang.org/docs/android-overview.html), the IntelliJ Platform makes extensive use of callbacks, which are easy to express as [lambdas](https://kotlinlang.org/docs/lambdas.html) in Kotlin.
@@ -15,7 +21,7 @@ For example, it is common practice to [guard logging statements](https://www.slf
 
 ```java
 if (logger.isDebugEnabled()) {
-  logger.debug("...");
+  logger.debug("..." + expensiveComputation());
 }
 ```
 
@@ -29,21 +35,42 @@ inline fun Logger.debug(lazyMessage: () -> String) {
 }
 ```
 
-Now we can directly write `logger.debug { "..." }` to receive all the benefits of lightweight logging, with none of the verbosity.
+Now we can directly write:
+```kotlin
+logger.debug { "..." + expensiveComputation() }
+```
+to receive all the benefits of lightweight logging while reducing the code verbosity.
+
 With practice, you will be able to recognize many idioms in the IntelliJ Platform that can be simplified with Kotlin.
 To learn more about building IntelliJ Platform plugins with Kotlin, this tutorial will help you get started.
 
+### UI Forms in Kotlin
+
+The IntelliJ Platform provides the [type safe DSL](kotlin_ui_dsl_version_2.md) allowing to UI forms in declarative way.
+
+> Using a GUI designer with Kotlin is currently [not supported](https://youtrack.jetbrains.com/issue/KTIJ-791).
+>
+{type="tip"}
+
 ## Adding Kotlin Support
 
-> The [IntelliJ Platform Plugin Template](github_template.md) provides a preconfigured project using Kotlin.
->
-> See also [kotlin_demo](%gh-sdk-samples%/kotlin_demo) for a minimal sample plugin.
+> The [IntelliJ Platform Plugin Template](plugin_github_template.md) provides a preconfigured project using Kotlin.
 >
 {type="tip"}
 
 IntelliJ IDEA bundles the necessary Kotlin plugin, requiring no further configuration.
 For detailed instructions, please refer to the [Kotlin documentation](https://kotlinlang.org/docs/getting-started.html).
 
+### Kotlin Gradle Plugin
+
+Adding Kotlin source files compilation support to the Gradle-based project requires adding and configuring the [Kotlin JVM Gradle plugin](https://kotlinlang.org/docs/gradle.html#targeting-the-jvm).
+
+See the <path>build.gradle.kts</path> from [kotlin_demo](%gh-sdk-samples%/kotlin_demo) sample plugin:
+
+```kotlin
+```
+{src="kotlin_demo/build.gradle.kts" lines="2-"}
+
 ### Kotlin Standard Library
 
 Since Kotlin 1.4, a dependency on the standard library `stdlib` is added automatically ([API Docs](https://kotlinlang.org/api/latest/jvm/stdlib/)).
@@ -85,55 +112,20 @@ See [Dependency on the standard library](https://kotlinlang.org/docs/gradle.html
 
 Please see [Third-Party Software and Licenses](https://www.jetbrains.com/legal/third-party-software/).
 
-## Kotlin Gradle Plugin
-
-Plugins using the [Gradle Build System](gradle_build_system.md) use the [Kotlin JVM Gradle plugin](https://kotlinlang.org/docs/gradle.html#targeting-the-jvm).
-
-See the <path>build.gradle.kts</path> from [kotlin_demo](%gh-sdk-samples%/kotlin_demo) sample plugin:
-
-```kotlin
-```
-{src="kotlin_demo/build.gradle.kts" lines="2-"}
-
-### Use Kotlin for Gradle Build Scripts
-
-Gradle also supports using Kotlin in build scripts: <path>build.gradle.kts</path>.
-
-There are many good resources for learning how to write build scripts for an IntelliJ Platform plugin with Kotlin script, like
-[intellij-rust](https://github.com/intellij-rust/intellij-rust/blob/master/build.gradle.kts),
-[julia-intellij](https://github.com/JuliaEditorSupport/julia-intellij/blob/master/build.gradle.kts),
-[covscript-intellij](https://github.com/covscript/covscript-intellij/blob/master/build.gradle.kts) or
-[zig-intellij](https://github.com/ice1000/intellij-zig/blob/master/build.gradle.kts).
-
-Additionally, explore IntelliJ Platform Explorer's [list of open-source plugins](https://jb.gg/ipe?buildSystem=gradle_kts) using Gradle KTS.
-
-## UI in Kotlin
-
-The recommended way to create UI forms with Kotlin is to use a [type safe DSL](kotlin_ui_dsl_version_2.md).
-Using a GUI designer with Kotlin is currently [not supported](https://youtrack.jetbrains.com/issue/KTIJ-791).
-
-## Handling Kotlin Code
-
-If a plugin processes Kotlin code (e.g., providing inspections), it needs to add a dependency on the Kotlin plugin (Plugin ID `org.jetbrains.kotlin`) itself.
-Please refer to [Plugin Dependencies](plugin_dependencies.md) for more information.
-
-Depending on exact functionality, a plugin can also target [UAST (Unified Abstract Syntax Tree)](uast.md) to support multiple JVM languages, including Java and Kotlin.
-
-### Kotlin Code FAQ
-
-[How to shorten references](https://intellij-support.jetbrains.com/hc/en-us/community/posts/360010025120-Add-new-parameter-into-kotlin-data-class-from-IDEA-plugin?page=1#community_comment_360002950760)
-
 ## Caution
 
 Plugins *may* use [Kotlin classes](https://kotlinlang.org/docs/classes.html) to implement declarations in the [plugin configuration file](plugin_configuration_file.md).
 When registering an extension, the platform uses a dependency injection framework to instantiate these classes.
 For this reason, plugins *must not* use [Kotlin objects](https://kotlinlang.org/docs/object-declarations.html) to implement any <path>[plugin.xml](plugin_configuration_file.md)</path> declarations.
 
-## Examples
+## Kotlin Code FAQ
+
+[How to shorten references](https://intellij-support.jetbrains.com/hc/en-us/community/posts/360010025120-Add-new-parameter-into-kotlin-data-class-from-IDEA-plugin?page=1#community_comment_360002950760)
+
+## Example Plugins Implemented in Kotlin
 
 There are many [open-source Kotlin plugins](https://jb.gg/ipe?language=kotlin) built on the IntelliJ Platform.
-For a readily available source of up to date examples and applications of the Kotlin language for building developer tools with the IntelliJ Platform, developers may look to these projects for inspiration:
-
+For a readily available source of up-to-date examples of plugins implemented in Kotlin, developers may look to these projects for inspiration:
 * [Presentation Assistant](https://github.com/chashnikov/IntelliJ-presentation-assistant)
 * [Rust](https://github.com/intellij-rust/intellij-rust)
 * [TeXiFy IDEA](https://github.com/Hannah-Sten/TeXiFy-IDEA)

topics/user_interface_components/kotlin_ui_dsl_version_2.md

@@ -10,7 +10,7 @@
 
 Kotlin UI DSL Version 2 allows creating UI forms with input components bound to state objects.
 The forms are built by using a declarative Kotlin syntax and follow the official IntelliJ Platform UI conventions described in the [IntelliJ Platform UI Guidelines](https://jetbrains.design/intellij/).
-The library is written in [Kotlin](kotlin.md) and makes it easy to develop user interfaces like dialogs and settings pages.
+The library is written in [Kotlin](using_kotlin.md) and makes it easy to develop user interfaces like dialogs and settings pages.
 
 The Kotlin UI DSL is not intended to build general UIs, like tool windows controls that trigger some actions and do not contain any input components bound to state objects.
 For this purpose, use [custom Swing components](user_interface_components.md) from the IntelliJ Platform or the standard ones.