From c9839de1c087c2928f85fbf9f208a6c36dd95f50 Mon Sep 17 00:00:00 2001
From: Karol Lewandowski <karol.lewandowski@jetbrains.com>
Date: Fri, 20 Dec 2024 20:17:54 +0100
Subject: [PATCH] Add live templates configuration file documentation

---
 .../generate_descriptor_pages.main.kts        |   6 +-
 ijs.tree                                      |   4 +-
 topics/tutorials/live_templates.md            |   5 +-
 .../live_templates_configuration_file.md      | 243 ++++++++++++++++++
 .../providing_live_templates.md               |   4 +
 5 files changed, 256 insertions(+), 6 deletions(-)
 create mode 100644 topics/tutorials/live_templates/live_templates_configuration_file.md

diff --git a/.github/scripts/generate_descriptor_pages.main.kts b/.github/scripts/generate_descriptor_pages.main.kts
index 6545df9d7..002363687 100755
--- a/.github/scripts/generate_descriptor_pages.main.kts
+++ b/.github/scripts/generate_descriptor_pages.main.kts
@@ -3,8 +3,7 @@
 // Copyright 2000-2024 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license.
 
 /**
- * Generates the elements content for the plugin_configuration_file.md page.
- * It fetches the elements data from <TODO>.
+ * Generates the elements content for pages defined in [descriptors].
  */
 
 @file:DependsOn("org.yaml:snakeyaml:2.3")
@@ -44,7 +43,8 @@ val renderedPageNameToTopicNames = mutableMapOf<String, String>().apply {
 val renderedElementPaths = mutableListOf<String>()
 
 val descriptors = listOf(
-  DescriptorInfo("https://jb.gg/sdk-docs/plugin-descriptor.yaml", "topics/basics/plugin_structure/plugin_configuration_file.md")
+  DescriptorInfo("https://jb.gg/sdk-docs/plugin-descriptor.yaml", "topics/basics/plugin_structure/plugin_configuration_file.md"),
+  DescriptorInfo("https://jb.gg/sdk-docs/templates-descriptor.yaml", "topics/tutorials/live_templates/live_templates_configuration_file.md")
 )
 
 descriptors.forEach { descriptor ->
diff --git a/ijs.tree b/ijs.tree
index 16c95baa1..7b6f6e20c 100644
--- a/ijs.tree
+++ b/ijs.tree
@@ -195,7 +195,9 @@
         <toc-element topic="advanced_postfix_templates.md"/>
       </toc-element>
       <toc-element topic="live_templates.md">
-        <toc-element topic="providing_live_templates.md" accepts-web-file-names="template-support.html"/>
+        <toc-element topic="providing_live_templates.md" accepts-web-file-names="template-support.html">
+          <toc-element topic="live_templates_configuration_file.md"/>
+        </toc-element>
         <toc-element topic="creating_live_template_functions.md" accepts-web-file-names="new-macros.html"/>
       </toc-element>
       <toc-element topic="file_and_code_templates.md" accepts-web-file-names="templates.html">
diff --git a/topics/tutorials/live_templates.md b/topics/tutorials/live_templates.md
index 2cd10d104..12a07301a 100644
--- a/topics/tutorials/live_templates.md
+++ b/topics/tutorials/live_templates.md
@@ -54,5 +54,6 @@ public void testMethod() {
 For more information about creating Custom Live Templates, refer to the [corresponding documentation](https://www.jetbrains.com/idea/help/creating-and-editing-live-templates.html).
 
 These sections describe how to add Live Templates, and their associated building blocks, to plugins.
- * [Providing Live Templates](providing_live_templates.md)
- * [Creating New Functions for Live Templates](creating_live_template_functions.md)
+ * [](providing_live_templates.md)
+   * [](live_templates_configuration_file.md)
+ * [](creating_live_template_functions.md)
diff --git a/topics/tutorials/live_templates/live_templates_configuration_file.md b/topics/tutorials/live_templates/live_templates_configuration_file.md
new file mode 100644
index 000000000..d013579d2
--- /dev/null
+++ b/topics/tutorials/live_templates/live_templates_configuration_file.md
@@ -0,0 +1,243 @@
+<!-- Copyright 2000-2024 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. -->
+
+# Live Templates Configuration File
+
+<show-structure for="chapter" depth="4"/>
+
+<link-summary>Live templates configuration file contains all the information about templates provided by the plugin.</link-summary>
+
+This page lists and describes all the elements and attributes used in live templates configuration files.
+
+## Configuration Structure Overview
+
+[//]: # (GENERATED CONTENT START)
+
+[//]: # (This content is generated by generate_descriptor_pages.main.kts script.)
+[//]: # (DO NOT EDIT IT MANUALLY)
+
+- [`<templateSet>`](#templateSet)
+  - [`<template>`](#templateSet__template)
+    - [`<variable>`](#templateSet__template__variable)
+    - [`<context>`](#templateSet__template__context)
+      - [`<option>`](#templateSet__template__context__option)
+
+## `templateSet`
+{#templateSet}
+
+<tldr>
+
+**Reference:** [Live Templates](live_templates.md)
+, [Live Templates (IntelliJ IDEA Web Help)](https://www.jetbrains.com/help/idea/settings-live-templates.html)
+
+</tldr>
+
+The live templates file root element.
+
+{style="narrow"}
+Required
+: **yes**
+
+
+Attributes
+:
+- `group` _(optional)_<br/>
+  Name of the template set group, which is displayed in <ui-path>Settings | Editor | Live Templates</ui-path> list.
+  If the group name is not provided, then templates' XML file name is used by default.
+- `replace` _(optional)_<br/>
+
+    Name of a template group that this template set replaces.
+    Templates from the replaced group are removed and are skipped in settings and completion.
+
+Children
+:
+  - [`<template>`](#templateSet__template)
+
+### `template`
+{#templateSet__template}
+
+Describes a template.
+
+{style="narrow"}
+Required
+: no
+
+
+Attributes
+:
+- `id` _(optional)_<br/>
+  Optional template identifier.
+- `name` _(**required**)_<br/>
+  The template abbreviation typed by users in the editor to expand it.
+  The abbreviation must be unique in the group containing the template.
+- `value` _(**required**)_<br/>
+  The text that the template is expanded to.<br/>
+  It may contain plain text and reference [variables](#templateSet__template__variable) in the format `$VARIABLE_NAME$`.
+  To escape a dollar sign `$` in the template text, use `$$`.
+- `resource-bundle` _(optional)_<br/>
+  Message bundle containing the template description specified by `key`.
+- `key` _(optional)_<br/>
+  The key of the template description provided in a message bundle defined by `resource-bundle`.
+  Description is used in the UI.
+  Overrides the value of `description`.
+- `description` _(optional)_<br/>
+  The template description used in the UI.
+  It is ignored if the description is provided with `resource-bundle` and `key`.
+- `shortcut` _(optional)_<br/>
+  Defines a character that expands the template.
+  Allowed values:
+    - `SPACE` - space key
+    - `TAB` - tab key
+    - `ENTER` - enter key
+    - `CUSTOM` - key defined in the <control>By default expand with</control> field in <ui-path>Settings | Editor | Live Templates</ui-path>
+    - `NONE` - disables expanding with a key
+- `toReformat` _(optional)_<br/>
+  Defines whether the inserted code should be reformatted according to the language code style.<br/>
+  Default value: `false`.
+- `toShortenFQNames` _(optional)_<br/>
+  Defines whether qualified names in the expanded code should be shortened,
+  for example, fully qualified names of Java classes are imported.<br/>
+  Shortening qualified names is performed in implementations of [`TemplateOptionalProcessor`](%gh-ic%/platform/analysis-impl/src/com/intellij/codeInsight/template/impl/TemplateOptionalProcessor.java).<br/>
+  Default value: `false`.
+- `useStaticImport` _(optional)_<br/>
+  Defines whether symbols used in the expanded code should be statically imported, if possible.<br/>
+  Importing symbols statically is performed in implementations of [`TemplateOptionalProcessor`](%gh-ic%/platform/analysis-impl/src/com/intellij/codeInsight/template/impl/TemplateOptionalProcessor.java).<br/>
+  Default value: `false`.
+- `deactivated` _(optional)_<br/>
+
+    Allows deactivating the template.
+    Deactivated templates are listed in the UI and can be activated by users.<br/>
+    Default value: `false`.
+
+Children
+:
+  - [`<context>`](#templateSet__template__context)
+  - [`<variable>`](#templateSet__template__variable)
+
+#### `variable`
+{#templateSet__template__variable}
+
+<tldr>
+
+**Reference:** [Template Variables](https://www.jetbrains.com/help/idea/edit-template-variables-dialog.html)
+
+</tldr>
+
+Defines a variable to be used in the template `value`.
+A single template can provide multiple variables.
+
+The order of the variables determines the order in which the IDE will switch between
+the corresponding input fields when the template is expanded.
+
+{style="narrow"}
+Required
+: no
+
+
+Attributes
+:
+- `name` _(optional)_<br/>
+  The variable name that is referenced in the [`<template>`](#templateSet__template) element's `value` attribute.
+- `expression` _(optional)_<br/>
+  Expression to calculate the value of the corresponding template input field automatically.<br/>
+  The expression may contain the following constructs:
+    - string constants in escaped double quotes, for example, `&quot;value&quot;`
+    - names of other variables defined in the template, for example, `ANOTHER_VAR`
+    - functions ([built-in](https://www.jetbrains.com/help/idea/template-variables.html#predefined_functions) or [custom](creating_live_template_functions.md)) with possible arguments
+- `defaultValue` _(optional)_<br/>
+  The default value for the corresponding input field of the expanded template
+  if the expression does not give any result after calculation.<br/>
+  It can refer to other live template variables, for example, `ANOTHER_VAR`.<br/>
+  To define the default value as a literal, enclose it in escaped quotation marks, for example, `&quot;value&quot;`.
+- `alwaysStopAt` _(optional)_<br/>
+
+    If `true`, the IDE will always stop at the corresponding input of the expanded template.<br/>
+    If `false`, the IDE will skip the corresponding input of the expanded template if the input value is defined.<br/>
+    Default value: `false`.
+
+Examples
+:
+- Empty variable allowing to provide a value manually by a user:
+    ```xml
+    <variable
+        name="MY_VAR"
+        expression=""
+        defaultValue=""
+        alwaysStopAt="true"/>
+    ```
+- Variable inserting the content of the clipboard,
+and referencing the `PLACEHOLDER` variable if the clipboard content is empty:
+    ```xml
+    <variable
+        name="PLACEHOLDER"
+        expression=""
+        defaultValue=""
+        alwaysStopAt="true"/>
+    <variable
+        name="MY_VAR"
+        expression="clipboard()"
+        defaultValue="PLACEHOLDER"
+        alwaysStopAt="true"/>
+    ```
+- Variable invoking completion and providing the `myValue` value if the completion doesn't provide any result:
+    ```xml
+    <variable
+        name="MY_VAR"
+        expression="complete()"
+        defaultValue="&quot;myValue&quot;"
+        alwaysStopAt="true"/>
+    ```
+
+#### `context`
+{#templateSet__template__context}
+
+Defines a mapping of a context type (for example, a Java method, a Markdown file) to applicability of the template
+in this context type.
+
+{style="narrow"}
+Required
+: no
+
+Children
+:
+  - [`<option>`](#templateSet__template__context__option)
+
+Example
+:
+  ```xml
+  <context>
+    <option name="JAVA_CODE" value="true"/>
+    <option name="JAVA_COMMENT" value="false"/>
+    <option name="JAVA_STRING" value="false"/>
+  </context>
+  ```
+
+##### `option`
+{#templateSet__template__context__option}
+
+An entry specifying whether a given context type defined by the
+`name` attribute is applicable for the template.
+
+{style="narrow"}
+Required
+: no
+
+
+Attributes
+:
+- `name` _(**required**)_<br/>
+  The context type name.<br/>
+  To implement a custom context type, see the
+  [context type implementation](providing_live_templates.md#implement-templatecontexttype)
+  tutorial.
+- `value` _(**required**)_<br/>
+
+    A boolean value determining whether the context type defined with the
+    [`<option>`](#templateSet__template__context__option) element's
+    `name`
+    attribute is applicable for the template.<br/>
+    As context types are hierarchical, the `false` value can be used when the parent context type is applicable,
+    and it is required to disable the applicability of more specific child context types.
+
+[//]: # (GENERATED CONTENT END)
+
+<include from="snippets.md" element-id="missingContent"/>
diff --git a/topics/tutorials/live_templates/providing_live_templates.md b/topics/tutorials/live_templates/providing_live_templates.md
index b27bcb912..1d4615b25 100644
--- a/topics/tutorials/live_templates/providing_live_templates.md
+++ b/topics/tutorials/live_templates/providing_live_templates.md
@@ -35,6 +35,10 @@ There are many [predefined functions](https://www.jetbrains.com/help/idea/templa
 Once the Live Template produces the expected result, [export the Live Template](https://www.jetbrains.com/help/idea/sharing-live-templates.html).
 The export produces a file called <path>Markdown.xml</path> with the following contents:
 
+> See [](live_templates_configuration_file.md) for a detailed description of the templates XML file structure and elements.
+>
+{style="note"}
+
 ```xml
 <templateSet group="Markdown">
   <template