docs: nested indentation and include rule

README.md

@@ -99,7 +99,7 @@ Additionally, the following aspects of PCRE2 syntax are supported:
 
 Since VSCode **[v1.73.0](https://code.visualstudio.com/updates/v1_73#_default-folding-provider)**, it's hightly recommanded to use the following settings:
 
-```
+```jsonc
 "editor.foldingStrategy": "auto",
 "editor.defaultFoldingRangeProvider": "zokugun.explicit-folding",
 ```
@@ -108,7 +108,7 @@ Wildcard Exclusions
 -------------------
 
 By default, the wildcard rule, like the following, are applied to all languages.
-```
+```jsonc
 "explicitFolding.rules": {
     "*": {
         "begin": "{{{",
@@ -120,7 +120,7 @@ By default, the wildcard rule, like the following, are applied to all languages.
 But, for languages which are using the indentation to define foldable blocks of code (such as in Python syntax), the wildcard rule will prevent the use of the indentation provider.<br />
 To avoid that, you need to add an exclusion:
 
-```
+```jsonc
 "explicitFolding.wildcardExclusions": ["python"]
 ```
 
@@ -129,7 +129,7 @@ Per Files
 
 You can define a complete new set of rules for specific files with the property `explicitFolding.perFiles`.
 
-```
+```jsonc
 "[javascript]": {
     "explicitFolding.rules": [...],
     "explicitFolding.perFiles": {
@@ -146,14 +146,67 @@ You can define a complete new set of rules for specific files with the property
 
 [minimatch](https://github.com/isaacs/minimatch) is used to determine if a filename is matching the pattern or not.
 
+Language List
+-------------
+
+The root `explicitFolding.rules` allows a list of languages as a language identifier. The rules will be applied to all the specified language.
+
+```jsonc
+"explicitFolding.rules": {
+    "javascript,snippets": [
+        {
+            "begin": "{",
+            "end"  : "}",
+            "foldLastLine": true,
+        },
+        {
+            "begin": "`",
+            "end"  : "`",
+            "foldLastLine": true,
+        },
+    ],
+},
+```
+
+Include Rule
+------------
+
+The `include` rule allows to include the rules from another language.
+
+```jsonc
+"explicitFolding.rules": {
+    "#region": [
+        {
+            "beginRegex": "#[\\s]*region[\\s]+([\\w]+)",
+            "endRegex": "#[\\s]*endregion",
+        },
+    ],
+},
+"[shellscript]": {
+    "explicitFolding.rules": [
+        { "include": "#region" },
+    ],
+},
+"[dockerfile]": {
+    "explicitFolding.rules": [
+        { "include": "shellscript" },
+    ],
+},
+```
+
+`#region` isn't a valid language identifier so it won't be matched to any files.<br/>
+But it can be used as a group of language features that can be included by different languages.<br/>
+It needs to defined in the root `explicitFolding.rules`.
+
 Auto Fold
 ---------
 
 You can define the automatic folding of the ranges with the property `explicitFolding.autoFold` (an enum, `none` by default).<br/>
 Each rule can overwrite that property with its own property `autoFold` (a boolean, `false` by default).
 
 So you can auto fold only the imports with:
-```
+
+```jsonc
 "[javascript]": {
     "explicitFolding.rules": [
         {

docs/rules/indentation.md

@@ -19,7 +19,11 @@ The builtin indentation provider is only used when there no other folding provid
 
 With the previous config, a python file can be folded by its **indentation** **and** with **docstring**s.
 
-`offSide` (default: false) decide whether empty lines belong to the previous or the next block.
+### `offSide`
+
+The `offSide` property is a **boolean** (set to `false` by default).
+
+It decides whether empty lines belong to the previous or the next block.
 Used by the default indentation provider and defined by language’s configuration (not accessible by an extension).
 
 Another quirk is that the default indentation provider use the tab size given given with the document, but an extension doesn’t have access to that info.
@@ -38,3 +42,23 @@ When used, the first line of the folding region needs to be matched be the regex
     }
 }
 ```
+
+### nested rules
+
+When the `nested` property is an **array**, it lists the rules generating new foldings. Only the lines with the same indentation are matched together.
+
+```
+"[python]": {
+    "explicitFolding.rules": [
+        {
+            "indentation": true,
+            "nested": [
+                {
+                    "separatorRegex": "#\\s+::\\s+",
+                    "foldBOF": false,
+                },
+            ],
+        },
+    ],
+}
+```