Add section on webview context menus

Currently only document in old release notes

.vscode/settings.json

@@ -13,7 +13,10 @@
     ],
     "markdown.copyFiles.destination": {
         // /release-notes/v123.md -> /release-notes/images/123/img.png
-        "/release-notes/**/*": "/release-notes/images/${documentBaseName/v(.*)/$1/}/"
+        "/release-notes/**/*": "/release-notes/images/${documentBaseName/v(.*)/$1/}/",
+
+        // Put into 'images' directory next to file
+        "/api/**/*": "images/${documentBaseName}/"
     },
     "editor.codeActionsOnSave": {
         "source.organizeLinkDefinitions": true

api/extension-guides/images/webview/webview-context-menus.png

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:c21c8ad6e64a2de333bfbce114822007d42d664d9ded8c4f9ca59dd02cbc0fb6
+size 24785

api/extension-guides/webview.md

@@ -583,6 +583,64 @@ The following video formats can be used in webviews:
 
 For video files, make sure that both the video and audio track's media formats are supported. Many `.mp4` files for example use `H.264` for video and `AAC` audio. VS Code will be able to play the video part of the `mp4`, but since `AAC` audio is not supported there won't be any sound. Instead you need to use `mp3` for the audio track.
 
+### Context menus
+
+Advanced webviews can customize the context menu that shows when a user right-clicks inside of a webview. This is done using a [contribution point](/api/references/contribution-points.md#contribution-points) similarly to VS Code's normal context menus, so custom menus fit right in with the rest of the editor. Webviews can also show custom context menus for different sections of the webview.
+
+To add a new context menu item to your webview, first add a new entry in `menus` under the new `webview/context` section. Each contribution takes a `command` (which is also where the item's title comes from) and a `when` clause. The [when clause](/api/references/when-clause-contexts) should include `webviewId == 'YOUR_WEBVIEW_VIEW_TYPE'` to make sure the context menus only apply to your extension's webviews:
+
+```json
+"contributes": {
+  "menus": {
+    "webview/context": [
+      {
+        "command": "catCoding.yarn",
+        "when": "webviewId == 'catCoding'"
+      },
+      {
+        "command": "catCoding.insertLion",
+        "when": "webviewId == 'catCoding' && webviewSection == 'editor'"
+      }
+    ]
+  },
+  "commands": [
+    {
+      "command": "catCoding.yarn",
+      "title": "Yarn 🧶",
+      "category": "Cat Coding"
+    },
+    {
+      "command": "catCoding.insertLion",
+      "title": "Insert 🦁",
+      "category": "Cat Coding"
+    },
+    ...
+  ]
+}
+```
+
+Inside of the webview, you can also set the contexts for specific areas of the HTML using the `data-vscode-context` [data attribute](https://developer.mozilla.org/docs/Learn/HTML/Howto/Use_data_attributes) (or in JavaScript with `dataset.vscodeContext`). The `data-vscode-context` value is a JSON object that specifies the contexts to set when the user right-clicks on the element. The final context is determined by going from the document root to the element that was clicked.
+
+Consider this HTML for example:
+
+```html
+<div class="main" data-vscode-context='{"webviewSection": "main", "mouseCount": 4}'>
+  <h1>Cat Coding</h1>
+
+  <textarea data-vscode-context='{"webviewSection": "editor", "preventDefaultContextMenuItems": true}'></textarea>
+</div>
+```
+
+If the user right-clicks on the `textarea`, the following contexts will be set:
+
+* `webviewSection == 'editor'` - This overrides `webviewSection` from the parent element.
+* `mouseCount == 4` - This is inherited from the parent element.
+* `preventDefaultContextMenuItems == true` - This is a special context that hides the copy and paste entries that VS Code normally adds to webview context menus.
+
+If the user right-clicks inside of the `<textarea>`, they will see:
+
+![Custom context menus showing in a webview](images/webview/webview-context-menus.png)
+
 ## Scripts and message passing
 
 Webviews are just like iframes, which means that they can also run scripts. JavaScript is disabled in webviews by default, but it can easily re-enable by passing in the `enableScripts: true` option.