Merge branch 'main' into vnext

Author: ntrogh

api/extension-guides/chat.md

@@ -11,7 +11,6 @@ MetaDescription: A guide to creating an AI extension in Visual Studio Code
 
 Visual Studio Code's Copilot Chat architecture enables extension authors to integrate with the [GitHub Copilot Chat](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot-chat) experience. A chat extension is a VS Code extension that uses the Chat extension API by contributing a *Chat participant*.
 
-
 Chat participants are domain experts that can answer user queries within a specific domain. Participants can use different approaches to process a user query:
 
 - Use AI to interpret the request and generate a response, for example by using the [Language Model API](/api/extension-guides/language-model)
@@ -20,13 +19,7 @@ Chat participants are domain experts that can answer user queries within a speci
 
 Participants can use the language model in a wide range of ways. Some participants only make use of the language model to get answers to custom prompts, for example the [sample chat participant](https://github.com/microsoft/vscode-extension-samples/tree/main/chat-sample). Other participants are more advanced and act like [autonomous agents](https://learn.microsoft.com/semantic-kernel/agents/) that invoke multiple tools with the help of the language model. An example of such an advanced participant is the built-in `@workspace` that knows about your workspace and can answer questions about it. Internally, `@workspace` is powered by multiple tools: GitHub's knowledge graph, combined with semantic search, local code indexes, and VS Code's language services.
 
-When a user explicitly mentions a `@participant` in their chat prompt, that prompt is forwarded to the extension that contributed that specific chat participant. The participant then uses a `ResponseStream` to respond to the request. To provide a smooth user experience, the Chat API is streaming-based. A `ResponseStream` can include:
-
-- Markdown for simple text and image responses
-- Buttons that invoke VS Code commands
-- Progress for longer running operations
-- References to URIs or editor locations
-- File trees (for example, to show a workspace preview when a chat participant proposes to create a new workspace)
+When a user explicitly mentions a `@participant` in their chat prompt, that prompt is forwarded to the extension that contributed that specific chat participant. The participant then uses a `ResponseStream` to respond to the request. To provide a smooth user experience, the Chat API is streaming-based. A chat response can contain rich content, such as Markdown, file trees, command buttons, and more. Get more info about the [supported response output types](#supported-chat-response-output-types).
 
 To help the user take the conversation further, participants can provide *follow-ups* for each response. Follow-up questions are suggestions that are presented in the chat user interface and might give the user inspiration about the chat extension's capabilities.
 
@@ -36,7 +29,6 @@ Participants can also contribute *commands*, which are a shorthand notation for
 
 Alternatively, it is possible to extend GitHub Copilot by creating a GitHub App that contributes a chat participant in the Chat view. A GitHub App is backed by a service and works across all GitHub Copilot surfaces, such as github.com, Visual Studio, or VS Code. On the other hand, GitHub Apps do not have full access to the VS Code API. To learn more about extending GitHub Copilot through a GitHub App see the [GitHub documentation](https://docs.github.com/en/copilot/building-copilot-extensions/about-building-copilot-extensions).
 
-
 ## Links
 
 - [Chat extension sample](https://github.com/microsoft/vscode-extension-samples/tree/main/chat-sample)
@@ -96,7 +88,7 @@ The first step to create a chat extension is to register it in your `package.jso
 }
 ```
 
-We suggest to use a lowercase `name` to align with existing chat participants. `name` can not contain spaces. Users can then reference the chat participant in the Chat view by using the `@` symbol and the `name` you provided. We suggest to use title case for the `fullName`, which is shown in the title area of a response from your participant. Some participant names are reserved, and in case you use a reserved name VS Code will display the fully qualified name of your participant (including the extension id). The `description` is shown in the chat input field as a placeholder text.
+We suggest using a lowercase `name` to align with existing chat participants. `name` can not contain spaces. Users can then reference the chat participant in the Chat view by using the `@` symbol and the `name` you provided. We suggest using title case for the `fullName`, which is shown in the title area of a response from your participant. Some participant names are reserved, and in case you use a reserved name VS Code will display the fully qualified name of your participant (including the extension ID). The `description` is shown in the chat input field as a placeholder text.
 
 The `isSticky` property controls whether the chat participant is persistent, which means that the participant name is automatically prepended in the chat input field after the user has started interacting with the participant.
 
@@ -202,6 +194,8 @@ stream.button({
 });
 ```
 
+Get more info about the [supported chat response output types](#supported-chat-response-output-types).
+
 In practice, extensions typically send a request to the language model. Once they get a response from the language model, they might further process it, and decide if they should stream anything back to the user. The VS Code Chat API is streaming-based, and is compatible with the streaming [Language Model API](/api/extension-guides/language-model). This allows extensions to report progress and results continuously with the goal of having a smooth user experience. Learn how you can use the [Language Model API](/api/extension-guides/language-model).
 
 #### Use the chat message history
@@ -269,11 +263,154 @@ cat.followupProvider = {
 
 > **Tip:** Follow-ups should be written as questions or directions, not just concise commands.
 
+## Supported chat response output types
+
+To return a response to a chat request, you use the [`ChatResponseStream`](/api/references/vscode-api#ChatResponseStream) parameter on the [`ChatRequestHandler`](/api/references/vscode-api#ChatRequestHandler).
+
+The following list provides the output types for a chat response in the Chat view. A chat response can combine multiple different output types.
+
+- **Markdown**
+
+    Render a fragment of Markdown text simple text or images. You can use any Markdown syntax that is part of the [CommonMark](https://commonmark.org/) specification. Use the [`ChatResponseStream.markdown`](/api/references/vscode-api#ChatResponseStream.markdown) method and provide the Markdown text.
+
+    Example code snippet:
+
+    ```typescript
+    // Render Markdown text
+    stream.markdown('# This is a title \n');
+    stream.markdown('This is stylized text that uses _italics_ and **bold**. ');
+    stream.markdown('This is a [link](https://code.visualstudio.com).\n\n');
+    stream.markdown('![VS Code](https://code.visualstudio.com/assets/favicon.ico)');
+    ```
+
+- **Code block**
+
+    Render a code block that supports IntelliSense, code formatting, and interactive controls to apply the code to the active editor. To show a code block, use the [`ChatResponseStream.markdown`](/api/references/vscode-api#ChatResponseStream.markdown) method and apply the Markdown syntax for code blocks (using backticks).
+
+    Example code snippet:
+
+    ```typescript
+    // Render a code block that enables users to interact with
+    stream.markdown('```bash\n');
+    stream.markdown('```ls -l\n');
+    stream.markdown('```');
+    ```
+
+- **Command link**
+
+    Render a link inline in the chat response that users can select to invoke a VS Code command. To show a command link, use the [`ChatResponseStream.markdown`](/api/references/vscode-api#ChatResponseStream.markdown) method and use the Markdown syntax for links `[link text](command:commandId)`, where you provide the command ID in the URL. For example, the following link opens the Command Palette: `[Command Palette](command:workbench.action.showCommands)`.
+
+    To protect against command injection when you load the Markdown text from a service, you have to use a [`vscode.MarkdownString`](/api/references/vscode-api#MarkdownString) object with the `isTrusted` property set to the list of trusted VS Code command IDs. This property is required to enable the command link to work. If the `isTrusted` property is not set or a command is not listed, the command link will not work.
+
+    Example code snippet:
+
+    ```typescript
+    // Use command URIs to link to commands from Markdown
+    let markdownCommandString: vscode.MarkdownString = new vscode.MarkdownString(`[Use cat names](command:${CAT_NAMES_COMMAND_ID})`);
+    markdownCommandString.isTrusted = { enabledCommands: [ CAT_NAMES_COMMAND_ID ] };
+
+    stream.markdown(markdownCommandString);
+    ```
+
+    If the command takes arguments, you need to first JSON encode the arguments and then encode the JSON string as a URI component. You then append the encoded arguments as a query string to the command link.
+
+    ```typescript
+    // Encode the command arguments
+    const encodedArgs = encodeURIComponent(JSON.stringify(args));
+
+    // Use command URIs with arguments to link to commands from Markdown
+    let markdownCommandString: vscode.MarkdownString = new vscode.MarkdownString(`[Use cat names](command:${CAT_NAMES_COMMAND_ID}?${encodedArgs})`);
+    markdownCommandString.isTrusted = { enabledCommands: [ CAT_NAMES_COMMAND_ID ] };
+
+    stream.markdown(markdownCommandString);
+    ```
+
+- **Command button**
+
+    Render a button that invokes a VS Code command. The command can be a built-in command or one that you define in your extension. Use the [`ChatResponseStream.button`](/api/references/vscode-api#ChatResponseStream.button) method and provide the button text and command ID.
+
+    Example code snippet:
+
+    ```typescript
+    // Render a button to trigger a VS Code command
+    stream.button({
+        command: 'my.command',
+        title: vscode.l10n.t('Run my command')
+    });
+    ```
+
+- **File tree**
+
+    Render a file tree control that lets users preview individual files. For example, to show a workspace preview when proposing to create a new workspace. Use the [`ChatResponseStream.filetree`](/api/references/vscode-api#ChatResponseStream.filetree) method and provide an array of file tree elements and the base location (folder) of the files.
+
+    Example code snippet:
+
+    ```typescript
+    // Create a file tree instance
+    var tree: vscode.ChatResponseFileTree[] = [
+        { name: 'myworkspace', children: [
+            { name: 'README.md' },
+            { name: 'app.js' },
+            { name: 'package.json' }
+        ]}
+    ];
+
+    // Render the file tree control at a base location
+    stream.filetree(tree, baseLocation);
+    ```
+
+- **Progress message**
+
+    Render a progress message during a long-running operation to provide the user with intermediate feedback. For example, to report the completion of each step in a multi-step operation. Use the [`ChatResponseStream.progress`](/api/references/vscode-api#ChatResponseStream.progress) method and provide the message.
+
+    Example code snippet:
+
+    ```typescript
+    // Render a progress message
+    stream.progress('Connecting to the database.');
+    ```
+
+- **Reference**
+
+    Add a reference for an external URL or editor location in the list references to indicate which information you use as context. Use the [`ChatResponseStream.reference`](/api/references/vscode-api#ChatResponseStream.reference) method and provide the reference location.
+
+    Example code snippet:
+
+    ```typescript
+    const fileUri: vscode.Uri = vscode.Uri.file('/path/to/workspace/app.js');  // On Windows, the path should be in the format of 'c:\\path\\to\\workspace\\app.js'
+    const fileRange: vscode.Range = new vscode.Range(0, 0, 3, 0);
+    const externalUri: vscode.Uri = vscode.Uri.parse('https://code.visualstudio.com');
+
+    // Add a reference to an entire file
+    stream.reference(fileUri);
+
+    // Add a reference to a specific selection within a file
+    stream.reference(new vscode.Location(fileUri, fileRange));
+
+    // Add a reference to an external URL
+    stream.reference(externalUri);
+    ```
+
+- **Inline reference**
+
+    Add an inline reference to a URI or editor location. Use the [`ChatResponseStream.anchor`](/api/references/vscode-api#ChatResponseStream.anchor) method and provide the anchor location and optional title. To reference a symbol (for example, a class or variable), you would use a location in an editor.
+
+    Example code snippet:
+
+    ```typescript
+    const symbolLocation: vscode.Uri = vscode.Uri.parse('location-to-a-symbol');
+
+    // Render an inline anchor to a symbol in the workspace
+    stream.anchor(symbolLocation, 'MySymbol');
+    ```
+
+> **Important**: Images and links are only available when they originate from a domain that is in the trusted domain list. Get more info about [link protection in VS Code](/docs/editor/editingevolved.md#outgoing-link-protection).
+
 ## Variables
 
 > **Note:** The Variables API is still in a proposed state and we are actively working on it.
 
-Chat extensions can also contribute chat *variables*, which provide context about the extension's domain. For example, a C++ extension might contribute a variable `#cpp` that would get resolved based on the state of the language service - what C++ version is being used and what C++ programming approach is preferred.
+Chat extensions can also contribute chat *variables*, which provide context about the extension's domain. For example, a C++ extension might contribute a variable `#cpp` that would get resolved based on the state of the language service - what C++ version is used and what C++ programming approach is preferred.
 
 Users can refer to a chat variable in a prompt by using the `#` symbol. A variable is resolved by either the chat extension that contributed that variable, or by VS Code when it's a built-in variable (for example, `#file` or `#selection`). VS Code offers the list of registered variables upon typing the `#` symbol in the chat input.
 

api/references/theme-color.md

@@ -318,7 +318,6 @@ Editor Groups are the containers of editors. There can be many editor groups. A
 - `tab.unfocusedActiveBorder`: Bottom border for the active tab in an inactive editor group.
 - `tab.activeBorderTop`: Top border for the active tab.
 - `tab.unfocusedActiveBorderTop`: Top border for the active tab in an inactive editor group
-- `tab.dragAndDropBorder`: Border between tabs to indicate that a tab can be inserted between two tabs. Tabs are the containers for editors in the editor area. Multiple tabs can be opened in one editor group. There can be multiple editor groups.
 - `tab.lastPinnedBorder`: Border on the right of the last pinned editor to separate from unpinned editors.
 - `tab.inactiveBackground`: Inactive Tab background color.
 - `tab.unfocusedInactiveBackground`: Inactive Tab background color in an unfocused group
@@ -629,7 +628,6 @@ For coloring inserted and removed text, use either a background or a border colo
 - `chat.slashCommandForeground`: The foreground color of a chat slash command.
 - `chat.avatarBackground`: The background color of a chat avatar.
 - `chat.avatarForeground`: The foreground color of a chat avatar.
-- `chat.requestBackground`: The background color of a chat request.
 
 ## Inline Chat colors
 
@@ -709,7 +707,6 @@ Peek views are used to show references and declarations as a view inside the edi
 - `peekViewEditorGutter.background`: Background color of the gutter in the peek view editor.
 - `peekViewEditor.matchHighlightBackground`: Match highlight color in the peek view editor.
 - `peekViewEditor.matchHighlightBorder`: Match highlight border color in the peek view editor.
-  `peekViewEditorStickyScroll.background`: Background color of sticky scroll in the peek view editor.
 - `peekViewResult.background`: Background color of the peek view result list.
 - `peekViewResult.fileForeground`: Foreground color for file nodes in the peek view result list.
 - `peekViewResult.lineForeground`: Foreground color for line nodes in the peek view result list.

docs/azure/aksextensions.md

@@ -1,5 +1,5 @@
 ---
-Order: 7
+Order: 5
 Area: azure
 TOCTitle: Azure Kubernetes Service
 ContentId: 131f9633-5446-4384-96ca-7bff2e3dc0fc

docs/azure/deployment.md

@@ -1,5 +1,5 @@
 ---
-Order: 2
+Order: 3
 Area: azure
 TOCTitle: Deployment
 PageTitle: Visual Studio Code Azure Tutorials
@@ -9,9 +9,9 @@ DateApproved: 02/1/2024
 ---
 # Deploying Applications to Azure
 
-Visual Studio Code makes it easy to deploy your applications to the cloud with [Azure](https://azure.microsoft.com) and we've created walkthroughs to help you get started.
+Visual Studio Code makes it easy to deploy your applications to the cloud with Azure and we've created walkthroughs to help you get started.
 
-Whether your workflow is through the [Azure CLI](https://learn.microsoft.com/cli/azure) or [Azure App Service](https://azure.microsoft.com/services/app-service), using a Docker container, or creating serverless [Azure Functions](https://azure.microsoft.com/services/functions/), you'll find the deployment steps you need.
+Whether you're a fullstack, backend, API developer, or DevOps engineer,  you'll find the deployment steps you need.
 
 ## Deployment tutorials
 
@@ -29,7 +29,6 @@ You can find additional tutorials and walkthroughs on the
 
 ## Next steps
 
+* [Deploy to Azure Container Apps](https://learn.microsoft.com/en-us/azure/container-apps/deploy-visual-studio-code) - Run microservices and containerized applications on a serverless platform.
+* [Visual Studio Code Azure Extensions](/docs/azure/overview.md) - The Azure Tools extension pack is designed to deploy your application to Azure within minutes.
 * [Working with Docker](/docs/azure/docker.md) - Put your application in a Docker container for easy reuse and deployment.
-* [Azure Extensions](/docs/azure/extensions.md) - The VS Code Marketplace has hundreds of extensions for Azure and the cloud.
-* [Working with MongoDB](/docs/azure/mongodb.md) - Create, manage and query MongoDB databases from within VS Code.
-* [Working with Kubernetes](/docs/azure/kubernetes.md) - for automating deployment, scaling, and management of application.