docs: polish and format markdown documents

README.md

@@ -1,51 +1,51 @@
 # KCL Plugin for IntelliJ IDEA
 
-The KCL IntelliJ IDEA plugin provides rich language support for the [KCL language](https://kusionstack.io/docs/reference/lang/).
-
+The KCL IntelliJ IDEA plugin provides rich language support for the [KCL programming language](https://kcl-lang.io/).
 
 ## Quick Start
 
 Welcome to KCL developing! We hope this plugin enhances your development experience with KCL.
 
--   **Step 1.** Install kcl on your system. We highly recommend to [install the Kusion tools package](https://kusionstack.io/docs/user_docs/getting-started/install) which contains the KCL language support and other tools. 
--   **Step 2.** Install the KCL plugin for IntelliJ IDEA. Download the distribution from [here](distributions) and in IntelliJ IDEA, click Preference -> plugins -> install Plugin from Disk... -> select kcl-idea-plugin zip -> restart IDE. This plugin requires the IntelliJ IDEA 2020.2+
--   **Step 3.** Open or create a KCL file and begin your KCL tour!
+- **Step 1.** Install [KCL](https://kcl-lang.io/docs/user_docs/getting-started/install) on your system.
+- **Step 2.** Install the KCL extension for IntelliJ IDEA. Download the distribution from [here](distributions) and in IntelliJ IDEA, click Preference -> plugins -> install Plugin from Disk... -> select `kcl-idea-plugin` zip -> restart IDE. This plugin requires the IntelliJ IDEA 2020.2+
+- **Step 3.** Open or create a KCL file and begin your KCL tour!
 
 <div style="text-align: center;"><img src="docs/img/how-to-install.gif" alt="IntelliJ KCL Plugin install"></div>
 
 ## Features
+
 <!-- Plugin description -->
-This extension provides coding assistance such as basic syntax highlight, IntelliSense such as auto complete, and some basic code navigation. Other useful features such as diagnostics and testing are in development.
+
+This extension provides coding assistance such as basic syntax highlight, IntelliSense such as auto-complete, and some basic code navigation. Other useful features such as diagnostics and testing are in development.
+
 <!-- Plugin description end -->
 
 ### Highlight
+
 <div style="text-align: center;"><img src="docs/img/highlight.jpg" alt="highlight"></div>
 
 ### Code Formatting
 
-Right click on the editor and select KCL Tools -> Format File to format current KCL file:
+Right-click on the editor and select KCL Tools -> Format File to format the current KCL file:
 
 <div style="text-align: center;"><img src="docs/img/format-file.png" alt="format file"></div>
 
-Right click on the target directory in the project structure panel, select KCL Tools -> Format Directory to format all files under the selected folder:
+Right-click on the target directory in the project structure panel, and select KCL Tools -> Format Directory to format all files under the selected folder:
 
 <div style="text-align: center;"><img src="docs/img/format-directory.png" alt="format directory"></div>
 
-Right click on the project name in the project structure panel, select KCL Tools -> Format Project to format all files in the project:
+Right-click on the project name in the project structure panel, and select KCL Tools -> Format Project to format all files in the project:
 
 <div style="text-align: center;"><img src="docs/img/format-project.png" alt="format project"></div>
 
-
 ## Ask for help
 
 If the plugin isn't working as you expect, please reach out to us by filing an issue.
 
-
 ## Contributing
 
 We are working actively on improving the KCL development on IntelliJ IDEA, and we welcome all kinds of contributions. You can refer to our [contribution guide](docs/CONTRIBUTING.md). It introduces how to build and run the extension locally.
 
-
 ## License
 
 Apache License Version 2.0

docs/CONTRIBUTING.md

@@ -9,13 +9,13 @@
 
 - the `intellij-kcl` plugin: This project
 - Gradle Intellij Plugin: A Gradle IDE plugin that provides integration for compiling and building Gradle projects. This project uses Gradle for dependency management and building.
-- Intellij Platform: A development platform provided by JetBrains that is built on top of IntelliJ IDEA. It offers a set of APIs and tools for extending IntelliJ functionality through plugins. 
-- Gradle plugins: Plugin dependencies declared in the project's Gradle configuration, used for extending and customizing the gradle build process. The current project relies on various Gradle plugins such as `java`, `org.jetbrains.kotlin.jvm`, `org.jetbrains.intellij`, `org.jetbrains.changelog`, etc. 
+- Intellij Platform: A development platform provided by JetBrains that is built on top of IntelliJ IDEA. It offers a set of APIs and tools for extending IntelliJ functionality through plugins.
+- Gradle plugins: Plugin dependencies declared in the project's Gradle configuration, used for extending and customizing the gradle build process. The current project relies on various Gradle plugins such as `java`, `org.jetbrains.kotlin.jvm`, `org.jetbrains.intellij`, `org.jetbrains.changelog`, etc.
 - the `Target` IntelliJ version: Named in the format of `yyyy.m (e.g., 2023.2)` or `yym.a (e.g., 232.3)`, this refers to the target platform version(s) that the plugin should support. It needs to be declared in the plugin project.
 
 ## Project Structure
 
-For details, please see https://plugins.jetbrains.com/docs/intellij/creating-plugin-project.html#components-of-a-wizard-generated-gradle-intellij-platform-plugin
+For details, please see [https://plugins.jetbrains.com/docs/intellij/creating-plugin-project.html#components-of-a-wizard-generated-gradle-intellij-platform-plugin](https://plugins.jetbrains.com/docs/intellij/creating-plugin-project.html#components-of-a-wizard-generated-gradle-intellij-platform-plugin)
 
 ```markdown
 intellij-kcl
@@ -36,6 +36,7 @@ intellij-kcl
 ├── gradlew.bat
 └── settings.gradle.kts               # Project metadata, such as the project name.
 ```
+
 ## Build Guide
 
 ### Build
@@ -74,12 +75,11 @@ $ ./gradlew runIde
 This plugin is built on top of the [IntelliJ Platform SDK](https://plugins.jetbrains.com/docs/intellij/intellij-platform.html). When updating the Intellij-based IDE product, it is necessary to ensure the compatibility between the plugin and the IDE:
 
 - In the `build.gradle.kts` file, set the `intellij.version` to the version of the IntelliJ Platform SDK used for plugin build, and declare the lower bound and upper bound versions compatible with the IntelliJ product through `tasks.patchPluginXml.sinceBuild` and `tasks.patchPluginXml.untilBuild`.
-
 - Regularly check the compatibility between the version of the IDE and the plugin: when a new version of the intellij-based IDE is released, set `pluginUntilBuild` in the `gradle.properties` file to the version number of the new version (for example, 2023.1 for version number 231), and verify compatibility by running `./gradlew verifyPluginConfiguration` or trigger the `verifyPluginConfiguration` task in the IntelliJ IDEA > gradle toolbar.
 
 ### Publish Plugin
 
-To register and publish to the plugin marketplace, see: https://plugins.jetbrains.com/docs/intellij/plugin-signing.html#provide-secrets-to-ide https://plugins.jetbrains.com/docs/intellij/publishing-plugin.html
+To register and publish to the plugin marketplace, see: [https://plugins.jetbrains.com/docs/intellij/plugin-signing.html#provide-secrets-to-ide](https://plugins.jetbrains.com/docs/intellij/plugin-signing.html#provide-secrets-to-ide) [https://plugins.jetbrains.com/docs/intellij/publishing-plugin.html](https://plugins.jetbrains.com/docs/intellij/publishing-plugin.html)
 
 ## Lexer & Parser Generation
 
@@ -103,28 +103,33 @@ To register and publish to the plugin marketplace, see: https://plugins.jetbrain
 The plugin should be compatible across different IntelliJ Platform versions unless for special reasons. However, there may be some API changes that are not backward compatible between major IntelliJ versions.
 
 For version differences, please refer to:
-- https://plugins.jetbrains.com/docs/intellij/api-changes-list.html
-- https://plugins.jetbrains.com/docs/intellij/api-notable.html
 
-And we can use the predefined Gradle task (`verifyPluginConfiguration`) to verify the compatibility between the plugin and the platform: https://plugins.jetbrains.com/docs/intellij/verifying-plugin-compatibility.html
+- [https://plugins.jetbrains.com/docs/intellij/api-changes-list.html](https://plugins.jetbrains.com/docs/intellij/api-changes-list.html)
+- [https://plugins.jetbrains.com/docs/intellij/api-notable.html](https://plugins.jetbrains.com/docs/intellij/api-notable.html)
+
+And we can use the predefined Gradle task (`verifyPluginConfiguration`) to verify the compatibility between the plugin and the platform: [https://plugins.jetbrains.com/docs/intellij/verifying-plugin-compatibility.html](https://plugins.jetbrains.com/docs/intellij/verifying-plugin-compatibility.html)
 
 ### Gradle Intellij Plugin Version Compatibility
 
 It is recommended to always use the latest version. Here are some notable compatibility requirements:
+
 - For IntelliJ 2022.3+, Gradle IntelliJ Plugin version 1.10.1+ is required.
 - Note that starting from IntelliJ 2023.3+, the Gradle plugin is no longer built-in and needs to be installed separately.
 
 ### JDK Version Compatibility
 
 For different target intellij platform versions, we'll need different Java Runtime versions:
+
 - 2020.3 and before: Java 11
 - 2022.2 and after: Java 17
-For the compatibility table, please refer to: https://plugins.jetbrains.com/docs/intellij/build-number-ranges.html#platformVersions
+
+For the compatibility table, please refer to: [https://plugins.jetbrains.com/docs/intellij/build-number-ranges.html#platformVersions](https://plugins.jetbrains.com/docs/intellij/build-number-ranges.html#platformVersions)
 
 #### Which target Platform Versions to maintain
 
 The plugin needs to target different IntelliJ Platform versions. If necessary, separate branches can be created for different IntelliJ major versions (e.g., starting from 2023.2+, supporting LSP, we maintain the LSP-related plugin code in a separate branch).
-Which versions to focus on maintaining can be decided based on the distribution of user-side versions provided by Jetbrains: https://plugins.jetbrains.com/docs/marketplace/product-versions-in-use-statistics.html
+
+Which versions to focus on maintaining can be decided based on the distribution of user-side versions provided by Jetbrains: [https://plugins.jetbrains.com/docs/marketplace/product-versions-in-use-statistics.html](https://plugins.jetbrains.com/docs/marketplace/product-versions-in-use-statistics.html)
 
 ### Build Failed: Download Timeout
 
@@ -135,8 +140,9 @@ The first time you run ./gradlew build can be quite time-consuming (around 5-15
 When a test class is deleted and rebuilt, IntelliJ IDEA still attempts to run the deleted test class. You need to clear the cache.
 
 ## References
-- Custom Language Plugin Development Guide: https://plugins.jetbrains.com/docs/intellij/custom-language-support.html
-- Plugin Testing Guide: https://jetbrains.org/intellij/sdk/docs/tutorials/writing_tests_for_plugins.html
-- Plugin Project Configuration: https://plugins.jetbrains.com/docs/intellij/configuring-plugin-project.html
-- JDK and IntelliJ Platform SDK Compatibility: https://plugins.jetbrains.com/docs/intellij/build-number-ranges.html
-- Find all plugin repositories that implement a certain extension point: https://plugins.jetbrains.com/intellij-platform-explorer/extensions?extensions=com.intellij.lineIndentProvider
+
+- Custom Language Plugin Development Guide: [https://plugins.jetbrains.com/docs/intellij/custom-language-support.html](https://plugins.jetbrains.com/docs/intellij/custom-language-support.html)
+- Plugin Testing Guide: [https://jetbrains.org/intellij/sdk/docs/tutorials/writing_tests_for_plugins.html](https://jetbrains.org/intellij/sdk/docs/tutorials/writing_tests_for_plugins.html)
+- Plugin Project Configuration: [https://plugins.jetbrains.com/docs/intellij/configuring-plugin-project.html](https://plugins.jetbrains.com/docs/intellij/configuring-plugin-project.html)
+- JDK and IntelliJ Platform SDK Compatibility: [https://plugins.jetbrains.com/docs/intellij/build-number-ranges.html](https://plugins.jetbrains.com/docs/intellij/build-number-ranges.html)
+- Find all plugin repositories that implement a certain extension point: [https://plugins.jetbrains.com/intellij-platform-explorer/extensions?extensions=com.intellij.lineIndentProvider](https://plugins.jetbrains.com/intellij-platform-explorer/extensions?extensions=com.intellij.lineIndentProvider)