Merge pull request #10320 from microsoft/docs/markdown-code-block-editors

Update Markdown extension documentation to include code block editor providers

Author: ntrogh

api/extension-guides/markdown-extension.md

@@ -4,12 +4,12 @@ ContentId: 1664249a-ba7a-4a53-b3f0-9d757cff7d27
 DateApproved: 9/16/2026
 
 # Summarize the whole topic in less than 300 characters for SEO purpose
-MetaDescription: Learn how to extend Visual Studio Code's built-in Markdown preview.
+MetaDescription: Extend Visual Studio Code Markdown features with preview styles, scripts, markdown-it plugins, and interactive code block editors.
 ---
 
 # Markdown Extension
 
-Markdown extensions allow you to extend and enhance Visual Studio Code's built-in Markdown preview. This includes changing the look of the preview or adding support for new Markdown syntax.
+Markdown extensions allow you to extend and enhance Visual Studio Code's built-in Markdown support. You can change the look of the Markdown preview, add support for new Markdown syntax, and contribute interactive editors for fenced code blocks.
 
 ## Changing the look of the Markdown preview with CSS
 
@@ -85,3 +85,250 @@ For advanced functionality, extensions may contribute scripts that are executed
 Contributed scripts are loaded asynchronously and reloaded on every content change.
 
 The [Markdown Preview Mermaid Support](https://marketplace.visualstudio.com/items?itemName=bierner.markdown-mermaid) extension demonstrates using scripts to add [Mermaid](https://mermaid.js.org) diagrams and flowchart support to the markdown preview. You can review the Mermaid extension's source code on [GitHub](https://github.com/mjbvz/vscode-markdown-mermaid).
+
+## Add code block editors (Experimental)
+
+Extensions can replace fenced code blocks with interactive, iframe-based editors in the Markdown editor. For example, an extension can provide a form editor for JSON, a diagram editor, or a task progress view. The code block remains the canonical document content and stays synchronized with the contributed editor.
+
+> [!NOTE]
+> Markdown code block editors are experimental and apply to the Markdown editor, not the standard Markdown preview. The contribution point and extension export API might change.
+
+Code block editors only load in a [trusted workspace](/docs/editing/workspaces/workspace-trust.md). In Restricted Mode, the Markdown editor does not load contributed code block editors or their resources.
+
+### Register a static code block editor
+
+Use the `markdown.codeBlockEditorProviders` contribution point to select fenced code blocks and provide an HTML entry point:
+
+```json
+{
+  "contributes": {
+    "markdown.codeBlockEditorProviders": [
+      {
+        "id": "taskProgress",
+        "selector": {
+          "language": "task-progress"
+        },
+        "source": {
+          "kind": "static",
+          "entrypoint": "./editor/index.html"
+        },
+        "runtimeKey": "task-progress-v1",
+        "contentType": "text",
+        "initialHeight": 80
+      }
+    ]
+  }
+}
+```
+
+This contribution replaces fenced code blocks whose info string is exactly `task-progress`:
+
+````markdown
+```task-progress
+- [x] Create the extension
+- [ ] Publish the extension
+```
+````
+
+The provider supports these properties:
+
+| Property | Required | Description |
+| --- | --- | --- |
+| `id` | Yes | Identifies the provider within the extension. The value must not be empty. |
+| `selector` | Yes | Selects an exact info string with `language`, or all info strings that start with a value by using `languagePrefix`. Specify one selector type. Values must not be empty. |
+| `source` | Yes | Uses an extension-relative HTML `entrypoint` for a `static` provider, or an extension export API for an `exportApi` provider. |
+| `runtimeKey` | No | Identifies compatible iframe runtimes that can be reused. The value must contain 1 to 256 characters. |
+| `contentType` | No | Represents code block content as `text` or `json`. The default is `text`. |
+| `initialHeight` | No | Reserves a positive height in pixels until the editor reports its measured height. |
+| `sandbox` | No | Sets the maximum optional iframe permissions the provider can request. Supported properties are `forms`, `downloads`, `pointerLock`, and `clipboardWrite`. Each permission defaults to `false`. |
+
+The `entrypoint` path is relative to the extension root. Relative scripts, stylesheets, and other assets in the HTML resolve from the entry point's directory.
+
+### Connect the iframe editor
+
+Install and bundle the experimental `@vscode/web-editors` package into the iframe application. The package synchronizes content, read-only state, and sizing between the code block and the iframe.
+
+The HTML entry point can load a bundled JavaScript module:
+
+```html
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Task progress editor</title>
+</head>
+<body>
+  <textarea id="editor"></textarea>
+  <script type="module" src="./dist/main.js"></script>
+</body>
+</html>
+```
+
+Connect the iframe to its parent window, apply user edits to the root content value, and respond to updates from the host:
+
+```ts
+import { WebEditorClient } from '@vscode/web-editors';
+
+const editor = document.querySelector<HTMLTextAreaElement>('#editor');
+if (!editor) {
+  throw new Error('Task progress editor element not found');
+}
+
+const client = await WebEditorClient.connect({
+  connection: 'windowParent',
+  contentType: 'text'
+});
+
+const updateContent = (content: unknown) => {
+  if (typeof content === 'string' && editor.value !== content) {
+    editor.value = content;
+  }
+};
+
+updateContent(client.getContent());
+editor.readOnly = client.getReadOnly();
+
+client.onDidChangeContent(event => updateContent(event.content));
+client.onDidChangeReadOnly(event => {
+  editor.readOnly = event.readOnly;
+});
+
+editor.addEventListener('input', () => {
+  client.applyEdits([{
+    kind: 'replace',
+    path: [],
+    newValue: editor.value
+  }]);
+});
+
+const resizeObserver = new ResizeObserver(() => {
+  client.reportSize(document.documentElement.scrollHeight);
+});
+resizeObserver.observe(document.documentElement);
+
+window.addEventListener('beforeunload', () => {
+  resizeObserver.disconnect();
+  client.dispose();
+}, { once: true });
+```
+
+### Resolve editors from the extension host
+
+Use an `exportApi` source when the extension host needs to choose the HTML dynamically or communicate with an iframe runtime. Register the source with API version 2:
+
+```json
+{
+  "contributes": {
+    "markdown.codeBlockEditorProviders": [
+      {
+        "id": "taskProgress",
+        "selector": {
+          "languagePrefix": "task-progress"
+        },
+        "source": {
+          "kind": "exportApi",
+          "apiVersion": 2
+        },
+        "runtimeKey": "task-progress-v1",
+        "contentType": "text",
+        "initialHeight": 80
+      }
+    ]
+  }
+}
+```
+
+Return the `markdownCodeBlockEditors.apiV2` API from the extension's `activate` function. The provider ID returned by `getProvider` must match the contribution's `id`.
+
+```ts
+import * as vscode from 'vscode';
+
+interface ResolveRequest {
+  readonly providerId: string;
+  readonly language: string;
+  readonly documentUri: vscode.Uri;
+}
+
+interface HostTransport {
+  readonly runtimeKey: string;
+  readonly onDidReceiveMessage: vscode.Event<unknown>;
+  readonly onDidDispose: vscode.Event<void>;
+  sendMessage(message: unknown): void;
+}
+
+const providerId = 'taskProgress';
+
+export function activate(context: vscode.ExtensionContext) {
+  const provider = {
+    resolve(_request: ResolveRequest, _token: vscode.CancellationToken) {
+      return {
+        content: {
+          uri: vscode.Uri.joinPath(context.extensionUri, 'editor', 'index.html')
+        },
+        runtimeKey: 'task-progress-v1',
+        contentType: 'text' as const,
+        initialHeight: 80
+      };
+    },
+
+    createHostTransport(
+      transport: HostTransport,
+      token: vscode.CancellationToken
+    ) {
+      if (token.isCancellationRequested) {
+        return;
+      }
+
+      return transport.onDidReceiveMessage(message => {
+        if (isReadyMessage(message)) {
+          transport.sendMessage({ type: 'hostReady' });
+        }
+      });
+    }
+  };
+
+  return {
+    markdownCodeBlockEditors: {
+      apiV2: {
+        getProvider(id: string) {
+          return id === providerId ? provider : undefined;
+        }
+      }
+    }
+  };
+}
+
+function isReadyMessage(message: unknown): message is { type: 'ready' } {
+  return typeof message === 'object'
+    && message !== null
+    && 'type' in message
+    && message.type === 'ready';
+}
+```
+
+The `resolve` method receives the provider ID, full fenced code block info string, and Markdown document URI. It can return HTML directly with `content.html` and an optional `content.baseUri`, or return an HTML file with `content.uri`. Returned resources must be within the extension or workspace.
+
+The resolved editor can also override `runtimeKey`, `contentType`, `initialHeight`, and `sandbox`. A returned `runtimeKey` must also contain 1 to 256 characters. A returned sandbox permission is granted only when the contribution also permits it.
+
+API version 2 providers can implement `createHostTransport` for bidirectional notifications between the extension host and an iframe runtime. In the iframe, use the optional `WebEditorClient.hostTransport`:
+
+```ts
+const transport = client.hostTransport;
+if (transport) {
+  transport.onMessage(message => {
+    console.log('Message from the extension host', message);
+  });
+  transport.sendMessage({ type: 'ready' });
+}
+```
+
+The host buffers messages while `createHostTransport` initializes. Return a `vscode.Disposable` to clean up listeners and resources when the iframe runtime is disposed. Use `transport.onDidDispose` when the extension must react immediately to runtime disposal.
+
+### Reuse iframe runtimes
+
+The Markdown editor virtualizes and pools physical iframes. Editors with the same `runtimeKey` can reuse an iframe runtime as code blocks enter and leave the viewport. Use the same key only when the editors have compatible HTML, scripts, and runtime behavior.
+
+For a static provider, the default runtime key combines the provider ID and extension version. For an exported provider, the resolved `runtimeKey` takes precedence over the contribution value. If neither is present, the Markdown editor derives a key from the provider, extension version, and language.
+
+Runtime reuse preserves the iframe application and host transport, but the web editor protocol updates the code block content and read-only state for each logical editor. Do not store code block-specific state outside the synchronized content unless you reset that state when the content changes.

api/extension-guides/overview.md

@@ -40,7 +40,7 @@ Here are the guides on the VS Code website, including their usage of the [VS Cod
 | [Task Provider](https://code.visualstudio.com/api/extension-guides/task-provider) | [tasks.registerTaskProvider](https://code.visualstudio.com/api/references/vscode-api#tasks.registerTaskProvider)<br>[Task](https://code.visualstudio.com/api/references/vscode-api#Task)<br>[ShellExecution](https://code.visualstudio.com/api/references/vscode-api#ShellExecution)<br>[contributes.taskDefinitions](https://code.visualstudio.com/api/references/contribution-points#contributes.taskDefinitions) |
 | [Source Control](https://code.visualstudio.com/api/extension-guides/scm-provider) | [workspace.workspaceFolders](https://code.visualstudio.com/api/references/vscode-api#workspace.workspaceFolders)<br>[SourceControl](https://code.visualstudio.com/api/references/vscode-api#SourceControl)<br>[SourceControlResourceGroup](https://code.visualstudio.com/api/references/vscode-api#SourceControlResourceGroup)<br>[scm.createSourceControl](https://code.visualstudio.com/api/references/vscode-api#scm.createSourceControl)<br>[TextDocumentContentProvider](https://code.visualstudio.com/api/references/vscode-api#TextDocumentContentProvider)<br>[contributes.menus](https://code.visualstudio.com/api/references/contribution-points#contributes.menus) |
 | [Debugger Extension](https://code.visualstudio.com/api/extension-guides/debugger-extension) | [contributes.breakpoints](https://code.visualstudio.com/api/references/contribution-points#contributes.breakpoints)<br>[contributes.debuggers](https://code.visualstudio.com/api/references/contribution-points#contributes.debuggers)<br>[debug](https://code.visualstudio.com/api/references/vscode-api#debug) |
-| [Markdown Extension](https://code.visualstudio.com/api/extension-guides/markdown-extension) | markdown.previewStyles<br>markdown.markdownItPlugins<br>markdown.previewScripts |
+| [Markdown Extension](https://code.visualstudio.com/api/extension-guides/markdown-extension) | markdown.previewStyles<br>markdown.markdownItPlugins<br>markdown.previewScripts<br>markdown.codeBlockEditorProviders |
 | [Test Extension](https://code.visualstudio.com/api/extension-guides/testing) | [TestController](https://code.visualstudio.com/api/references/vscode-api#TestController)<br>[TestItem](https://code.visualstudio.com/api/references/vscode-api#TestItem) |
 | [Custom Data Extension](https://code.visualstudio.com/api/extension-guides/custom-data-extension) | contributes.html.customData<br>contributes.css.customData |
 <br>