docs: Improve feature & settings documentation (#52)

harrydowning · Sep 15, 2024 · cd873b1 · cd873b1
1 parent 5b214ec
commit cd873b1
Show file tree

Hide file tree

Showing 7 changed files with 49 additions and 16 deletions.
diff --git a/.vscodeignore b/.vscodeignore
@@ -2,6 +2,7 @@
 
 !dist/extension.js
 !syntaxes/
+!snippets/snippets.json
 !images/icon.png
 !package.json
 !README.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -8,7 +8,8 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/) and this p
 
 ### Added
 
-- Language command snippet
+- Comment snippet
+- Feature & settings documentation
 
 ### Changed
 
@@ -18,7 +19,7 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/) and this p
 
 ### Added
 
-- Comment commands to allow highlighting complete sections
+- Ability highlight all blocks from a point onwards
 
 ## [1.0.6] - 2024-09-12
 

diff --git a/README.md b/README.md
@@ -14,6 +14,31 @@ Syntax highlighting within YAML block-scalars for [50+ built-in languages](#buil
 
 ![Example yaml file showing syntax highlighting](https://raw.githubusercontent.com/harrydowning/yaml-embedded-languages/master/images/example.png)
 
+### Usage
+
+To highlight a single block, place a comment with the language identifier next to the block identifier.
+
+```yaml
+example: | # <language-identifier>
+  highlighted
+```
+
+To highlight all blocks from a point onwards, place a comment with the extension name followed by the language identifier.
+
+```yaml
+# yaml-embedded-languages: <language-identifier>
+example: |
+  highlighted
+```
+
+To stop highlighting blocks place a comment with the extension name.
+
+```yaml
+# yaml-embedded-languages
+example: |
+  not highlighted
+```
+
 ### Built-In Languages
 
 The following list shows all valid identifiers for the built-in languages:
@@ -92,9 +117,9 @@ None
 
 ## Extension Settings
 
-| Name                              | Description                                                                                                                                                                                                                                                                                                                                                                                                         |
-| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `yaml-embedded-languages.include` | Allows the user to include their own languages, the languages of other extensions, or aliases for existing languages. Use the key to define the language identifier with regex. Use the value to specify the language TextMate `scopeName`. By default the language identifier will be used as the language name. To change this, an object can be specified with the properties `name` and `scopeName` (required). |
+| Name                              | Description                                                                                                                                                                                                                                                                                                                                                                           |
+| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `yaml-embedded-languages.include` | An object where the key defines the language identifier with regex and the value specifies the language TextMate scope name. By default the language identifier will be used as the language name. To change this, the value can be specified as an object with properties including `name`, `scopeName` (required), and `stripIndent`. Hover over these in VS Code to find out more. |
 
 ## Known Issues
 

diff --git a/images/icon.png b/images/icon.png
diff --git a/images/icon.svg b/images/icon.svg
diff --git a/package.json b/package.json
@@ -201,22 +201,26 @@
               ],
               "properties": {
                 "name": {
-                  "type": "string"
+                  "type": "string",
+                  "description": "The name of the language"
                 },
                 "scopeName": {
-                  "type": "string"
+                  "type": "string",
+                  "description": "The language TextMate scope name"
                 },
                 "stripIndent": {
-                  "type": "boolean"
+                  "type": "boolean",
+                  "description": "Ignore any indentation caused by nested properties"
                 }
               },
               "required": [
                 "scopeName"
-              ]
+              ],
+              "description": "The language identifier"
             }
           },
           "default": {},
-          "description": "Use the key to define the language identifier with regex. Use the value to specify the language TextMate `scopeName`. By default the language identifier will be used as the language name. To change this, an object can be specified with the properties `name` and `scopeName` (required)."
+          "description": "An object where the key defines the language identifier with regex and the value specifies the language TextMate scope name. By default the language identifier will be used as the language name. To change this, the value can be specified as an object with properties including `name`, `scopeName` (required), and `stripIndent`. Hover over these in VS Code to find out more."
         }
       }
     },

diff --git a/snippets/snippets.json b/snippets/snippets.json
@@ -2,6 +2,6 @@
   "yaml-embedded-languages": {
     "prefix": "yaml-embedded-languages",
     "body": ["# yaml-embedded-languages: $1"],
-    "description": "Language command"
+    "description": "Highlight all blocks from this point onwards with the specified language"
   }
 }