Lets see what it complains about

zadjii · zadjii · commit 7a257119e7ae · 2025-03-24T15:33:34.000-05:00
diff --git a/hub/dev-environment/toc.yml b/hub/dev-environment/toc.yml
@@ -137,16 +137,20 @@ items:
                   href: ../powertoys/command-palette/adding-commands.md
                 - name: Update a list of commands
                   href: ../powertoys/command-palette/update-a-list-of-commands.md
-                - name: Command results
-                  href: ../powertoys/command-palette/command-results.md
                 - name: Add top-level commands to your extension
                   href: ../powertoys/command-palette/add-top-level-commands-to-your-extension.md
+                - name: Command results
+                  href: ../powertoys/command-palette/command-results.md
                 - name: Display markdown content
                   href: ../powertoys/command-palette/using-markdown-content.md
                 - name: Get user input with forms
                   href: ../powertoys/command-palette/using-form-pages.md
                 # - name: Handle the search text
                 #   href: ../powertoys/command-palette/dynamic-lists.md
+                # - name: Adding details
+                #   href: ../powertoys/command-palette/add-details.md
+                # - name: Tags
+                #   href: ../powertoys/command-palette/tags.md
                 # - name: "Advanced: Adding an extension to your package" 
                 #   href: ../powertoys/command-palette/adding-an-extension-to-your-package.md
             - name: Publishing your extension
diff --git a/hub/powertoys/command-palette/add-top-level-commands-to-your-extension.md b/hub/powertoys/command-palette/add-top-level-commands-to-your-extension.md
@@ -49,11 +49,10 @@ If we want to add another command to the top-level list of commands, we just nee
 
 There you have it. Now you can add additional top-level commands to your extension.
 
-If you'd like to update the list of top-level commands dynamically, you can do so in the same way as you would updating a list page. This can be useful for cases like an extension that might first require the user to log in, before showing certain commands. In that case, you can show the "log in" command at the top level initially. Then, once the user logs in successfully, you can update the list of top-level commands to include the commands that required authentication.
+If you'd like to update the list of top-level commands dynamically, you can do so in the same way as you would update a list page. This can be useful for cases like an extension that might first require the user to log in, before showing certain commands. In that case, you can show the "log in" command at the top level initially. Then, once the user logs in successfully, you can update the list of top-level commands to include the commands that required authentication.
 
 Once you've determined that you need to change the top level list, call [`RaiseItemsChanged()`](../microsoft-commandpalette-extensions-toolkit/commandprovider-raiseitemschanged.md) on your `CommandProvider`. Command Palette will then ask for the top-level commands via `TopLevelCommands()` again, and you can return the updated list.
 
-
 > [!TIP]
 > Create the `CommandItem`s for the top-level commands before calling `RaiseItemsChanged()`. This will ensure that the new commands are available when Command Palette asks for the top-level commands. This will help keep the work being done in call to `TopLevelCommands()` method to a minimum.
 
diff --git a/hub/powertoys/command-palette/adding-commands.md b/hub/powertoys/command-palette/adding-commands.md
@@ -14,7 +14,7 @@ no-loc: [PowerToys, Windows, Insider]
 Now that you've created your extension, it's time to add some commands to it. We can start by navigating to the `ExtensionNamePage.cs` file. This file is the [`ListPage`](./microsoft-commandpalette-extensions-toolkit/listpage.md) that will be displayed when the user selects your extension. In there you should see:
 
 ```csharp   
-    public DocsSamplePage()
+    public ExtensionNamePage()
     {
         Icon = IconHelpers.FromRelativePath("Assets\\StoreLogo.png");
         Title = "My sample extension";
@@ -108,7 +108,7 @@ There are two different kinds of pages you can show:
 * [`ListPage`](./microsoft-commandpalette-extensions-toolkit/listpage.md) - This is a page that shows a list of commands. This is what we've been working with so far.
 * [`ContentPage`](./microsoft-commandpalette-extensions-toolkit/contentpage.md) - This is a page that shows rich content to the user. This allows you to specify abstract content, and let Command Palette worry about rendering the content in a native experience. There are two different types of content supported so far:
   * [Markdown content](./using-markdown-content.md) - This is content that's written in Markdown, and is rendered in the Command Palette. See [`MarkdownContent`](./microsoft-commandpalette-extensions-toolkit/markdowncontent.md) for details.
-  * [Form content](./using-form-pages.md) - This is content that shows a form to the user, and then returns the results of that form to the extension. These are powered by [Adaptive Cards](aka.ms/adaptive-cards) This is useful for getting user input, or displaying more complex layouts of information. See [`FormContent`](./microsoft-commandpalette-extensions-toolkit/formcontent.md) for details.
+  * [Form content](./using-form-pages.md) - This is content that shows a form to the user, and then returns the results of that form to the extension. These are powered by [Adaptive Cards](https://aka.ms/adaptive-cards) This is useful for getting user input, or displaying more complex layouts of information. See [`FormContent`](./microsoft-commandpalette-extensions-toolkit/formcontent.md) for details.
 
 
 We'll start by adding a new page that shows a list of commands. We can create a new class that implements `ListPage`:
diff --git a/hub/powertoys/command-palette/command-results.md b/hub/powertoys/command-palette/command-results.md
@@ -1,6 +1,6 @@
 ---
 title: Command results
-description: Learn how to add new commands to your Command Palette extension.
+description: Learn what the different kinds of Command Palette command results do.
 ms.date: 3/23/2025
 ms.topic: concept-article
 no-loc: [PowerToys, Windows, Insider]
diff --git a/hub/powertoys/command-palette/creating-an-extension.md b/hub/powertoys/command-palette/creating-an-extension.md
@@ -18,7 +18,7 @@ The form will ask you for the following information:
   * The project will be created in a subdirectory of the path you provided. 
   * If this path doesn't exist, it will be created for you.
 
-![](../../images/command-palette/create-extension-page.png)
+![The "Create a new extension" page of the Windows Command Palette](../../images/command-palette/create-extension-page.png)
 
 Once you submit the form, Command Palette will automatically generate the project for you. At this point, your projects structure should look like the following:
 
@@ -64,7 +64,7 @@ From here, you can immediately build the project and run it. Once your package i
 
 You should be able to see your extension in the Command Palette at the end of the list of commands. Entering that command should take you to the page for your command, and you should see a single command that says "TODO: Implement your extension here".
 
-![](../../images/command-palette/initial-created-extension-list.png)
+![A screenshot of the empty extension template, running in the command palette](../../images/command-palette/initial-created-extension-list.png)
 
 Congrats! You've made your first extension! Now let's go ahead and actually add some commands to it.
 
diff --git a/hub/powertoys/command-palette/extensibility-overview.md b/hub/powertoys/command-palette/extensibility-overview.md
@@ -15,14 +15,15 @@ The fastest way to get started writing extensions is from the Command Palette it
 
 For more detailed instructions, you can follow these pages:
 
-* [Creating an extension](../powertoys/command-palette/creating-an-extension.md)
-* [Update a list of commands](../powertoys/command-palette/update-a-list-of-commands.md)
-* [Command results](../powertoys/command-palette/command-results.md)
-* [Add top-level commands to your extension](../powertoys/command-palette/add-top-level-commands-to-your-extension.md)
-* [Display markdown content](../powertoys/command-palette/using-markdown-content.md)
-* [Get user input with forms](../powertoys/command-palette/using-form-pages.md)
-* [Handle the search text](../powertoys/command-palette/dynamic-lists.md)
-* [Advanced: Adding an extension to your package](../powertoys/command-palette/adding-an-extension-to-your-package.md)
+* [Creating an extension](../command-palette/creating-an-extension.md)
+* [Adding commands](../command-palette/adding-commands.md)
+* [Update a list of commands](../command-palette/update-a-list-of-commands.md)
+* [Add top-level commands to your extension](../command-palette/add-top-level-commands-to-your-extension.md)
+* [Command results](../command-palette/command-results.md)
+* [Display markdown content](../command-palette/using-markdown-content.md)
+* [Get user input with forms](../command-palette/using-form-pages.md)
+<!-- * [Handle the search text](../command-palette/dynamic-lists.md) -->
+<!-- * [Advanced: Adding an extension to your package](../command-palette/adding-an-extension-to-your-package.md) -->
 
 
 ## Extension details
diff --git a/hub/powertoys/command-palette/microsoft-commandpalette-extensions-toolkit/commandresult.md b/hub/powertoys/command-palette/microsoft-commandpalette-extensions-toolkit/commandresult.md
@@ -38,3 +38,7 @@ The **CommandResult** class is used to specify the result of a command execution
 | [KeepOpen()](commandresult_keepopen.md) | Do nothing. This leaves the palette in its current state, with the current page stack and query. |
 | [ShowToast(String)](commandresult_showtoast_string.md) | Display a transient desktop-level message to the user. Creates a new [CommandResult](commandresult.md) with **Args** set to a new [ToastArgs](toastargs.md) object with its [Message](toastargs.md#properties) set to **String**. |
 | [ShowToast(ToastArgs)](commandresult_showtoast_toastargs.md) | Display a transient desktop-level message to the user. Creates a new `CommandResult` instance with **Args** set to [ToastArgs](toastargs.md). |
+
+## Example
+
+See [Command Results](../command-results.md) for an example of how to use this.
diff --git a/hub/powertoys/command-palette/microsoft-commandpalette-extensions-toolkit/commandresult_confirm.md b/hub/powertoys/command-palette/microsoft-commandpalette-extensions-toolkit/commandresult_confirm.md
@@ -25,3 +25,7 @@ The arguments for the command. This should be an instance of [ConfirmationArgs](
 ## Returns
 
 A [CommandResult](commandresult.md) instance.
+
+## Example
+
+See [Command Results](../command-results.md) for an example of how to use this.
diff --git a/hub/powertoys/command-palette/microsoft-commandpalette-extensions-toolkit/commandresult_dismiss.md b/hub/powertoys/command-palette/microsoft-commandpalette-extensions-toolkit/commandresult_dismiss.md
@@ -19,3 +19,7 @@ Creates a new [CommandResult](commandresult.md) instance with its [Kind](command
 ## Returns
 
 A [CommandResult](commandresult.md) instance.
+
+## Example
+
+See [Command Results](../command-results.md) for an example of how to use this.
diff --git a/hub/powertoys/command-palette/microsoft-commandpalette-extensions-toolkit/commandresult_goback.md b/hub/powertoys/command-palette/microsoft-commandpalette-extensions-toolkit/commandresult_goback.md
@@ -19,3 +19,7 @@ Creates a new [CommandResult](commandresult.md) instance with its [Kind](command
 ## Returns
 
 A [CommandResult](commandresult.md) instance.
+
+## Example
+
+See [Command Results](../command-results.md) for an example of how to use this.
diff --git a/hub/powertoys/command-palette/microsoft-commandpalette-extensions-toolkit/commandresult_gohome.md b/hub/powertoys/command-palette/microsoft-commandpalette-extensions-toolkit/commandresult_gohome.md
@@ -22,3 +22,7 @@ Creates a new [CommandResult](commandresult.md) instance with its [Kind](command
 ## Returns
 
 A [CommandResult](commandresult.md) instance.
+
+## Example
+
+See [Command Results](../command-results.md) for an example of how to use this.
diff --git a/hub/powertoys/command-palette/microsoft-commandpalette-extensions-toolkit/commandresult_gotopage.md b/hub/powertoys/command-palette/microsoft-commandpalette-extensions-toolkit/commandresult_gotopage.md
@@ -25,3 +25,7 @@ The arguments for the command. This should be an instance of [GoToPageArgs](goto
 ## Returns
 
 A [CommandResult](commandresult.md) instance.
+
+## Example
+
+See [Command Results](../command-results.md) for an example of how to use this.
diff --git a/hub/powertoys/command-palette/microsoft-commandpalette-extensions-toolkit/commandresult_hide.md b/hub/powertoys/command-palette/microsoft-commandpalette-extensions-toolkit/commandresult_hide.md
@@ -20,4 +20,4 @@ A [CommandResult](commandresult.md) instance.
 
 ## Example
 
-See [Add a command](../samples.md#add-a-command) for an example of how to use this method in a command.
+See [Command Results](../command-results.md) for an example of how to use this.
diff --git a/hub/powertoys/command-palette/microsoft-commandpalette-extensions/icommand.md b/hub/powertoys/command-palette/microsoft-commandpalette-extensions/icommand.md
@@ -24,4 +24,4 @@ Action a user can take within the Command Palette.
 
 ## Example
 
-See the [Add a command](../samples.md#add-a-command) section for an example of how to use this interface.
+See the [Add a command](../adding-commands.md) page for an example of how to use this interface.
diff --git a/hub/powertoys/command-palette/microsoft-commandpalette-extensions/iinvokablecommand_invoke.md b/hub/powertoys/command-palette/microsoft-commandpalette-extensions/iinvokablecommand_invoke.md
@@ -33,4 +33,4 @@ An [ICommandResult](icommandresult.md) object that represents the result of the
 
 ## Example
 
-See [Add a command](../samples.md#add-a-command) for a sample of how to implement this method.
+See [Add a command](../adding-commands.md) for a sample of how to implement this method.
diff --git a/hub/powertoys/command-palette/update-a-list-of-commands.md b/hub/powertoys/command-palette/update-a-list-of-commands.md
@@ -1,6 +1,6 @@
 ---
 title: Update a list of commands
-description: Learn how to add new commands to your Command Palette extension.
+description: Learn how to update the elements in your Command Palette extension.
 ms.date: 3/23/2025
 ms.topic: concept-article
 no-loc: [PowerToys, Windows, Insider]
diff --git a/hub/powertoys/command-palette/using-form-pages.md b/hub/powertoys/command-palette/using-form-pages.md
@@ -0,0 +1,53 @@
+---
+title: Get user input with forms
+description: Learn how to use Adaptive Cards forms in your Command Palette extension.
+ms.date: 3/23/2025
+ms.topic: concept-article
+no-loc: [PowerToys, Windows, Insider]
+# Customer intent: As a Windows developer, I want to learn how to develop an extension for the Command Palette.
+---
+
+# Get user input with forms
+
+**Previous**: [Display markdown content](using-markdown-content.md)
+
+Now that we know how to present basic markdown content, let's try displaying something more elaborate. 
+
+Command Palette supports [Adaptive Cards](https://adaptivecards.io/), which are a way to create rich, interactive content. This can be useful for creating forms, or for displaying more complex content.
+
+You can create a card in the Command Palette with the `IFormContent` interface (see [`FormContent`](./microsoft-commandpalette-extensions-toolkit/formcontent.md) for the toolkit implementation). This allows you to provide the Adaptive Card JSON, and the Command Palette will render it for you. When the user submits the form, Command Palette will call the `SubmitForm` method on your form, with the JSON payload and inputs from the form.
+
+Adaptive card payloads can be created using the [Adaptive Card Designer](https://adaptivecards.io/designer/). You can design your card there, and then copy the JSON payload into your extension. 
+
+For a full example of using Forms and Content pages, head on over to [`SamplePagesExtension/Pages/SampleContentPage.cs`](https://github.com/microsoft/PowerToys/blob/main/src/modules/cmdpal/Exts/SamplePagesExtension/Pages/SampleContentPage.cs). Some brief things to note:
+
+* Set the `TemplateJson` property of your form to the JSON payload of your Adaptive Card. (this is the "CARD PAYLOAD EDITOR" value in the Adaptive Card Designer)
+* Set the `DataJson` property of your FormContent to the data you want to use to fill in your card template. (This is the "SAMPLE DATA EDITOR" value in the Adaptive Card Designer). This is optional, but can make authoring cards easier.
+* Implement the `SubmitForm` method to handle the form submission. This method will be called when the user submits the form, and will be passed the JSON payload of the form.
+
+```csharp
+    public override CommandResult SubmitForm(string payload)
+    {
+        var formInput = JsonNode.Parse(payload)?.AsObject();
+        if (formInput == null)
+        {
+            return CommandResult.GoHome();
+        }
+
+        // retrieve the value of the input field with the id "name"
+        var name = formInput["name"]?.AsString();
+         
+        // do something with the data
+
+        // and eventually
+        return CommandResult.GoBack();
+    }
+```
+
+Of course, you can mix and match `IContent` in whatever way you'd like. For example, you could use a block markdown first for the body of a post, and have a FormContent next to reply to the post.
+
+## Related content
+
+- [PowerToys Command Palette utility](overview.md)
+- [Extensibility overview](extensibility-overview.md)
+- [Extension samples](samples.md)
diff --git a/hub/powertoys/command-palette/using-markdown-content.md b/hub/powertoys/command-palette/using-markdown-content.md
@@ -0,0 +1,88 @@
+---
+title: Display markdown content
+description: Learn how to display markdown in your Command Palette extension.
+ms.date: 3/23/2025
+ms.topic: concept-article
+no-loc: [PowerToys, Windows, Insider]
+# Customer intent: As a Windows developer, I want to learn how to develop an extension for the Command Palette.
+---
+
+# Display markdown content
+
+**Previous**: [Command Results](command-results.md)
+
+So far, we've only shown how to display a list of commands in a `ListPage`. However, you can also display rich content in your extension, such as markdown. This can be useful for showing documentation, or a preview of a document.
+
+[`IContentPage`](./microsoft-commandpalette-extensions/icontentpage.md) (and its toolkit implementation, [`ContentPage`](./microsoft-commandpalette-extensions-toolkit/contentpage.md)) is the base for displaying all types of rich content in the Command Palette. To display markdown content, you can use the [`MarkdownContent`](./microsoft-commandpalette-extensions-toolkit/markdowncontent.md) class.
+
+As a simple example, we can create the following page:
+
+```csharp
+public class MarkdownPage : ContentPage
+{
+    public MarkdownPage()
+    {
+        Icon = IconHelpers.FromRelativePath("Assets\\StoreLogo.png");
+        Title = "Markdown page";
+    }
+
+    public override IContent[] GetContent()
+    {
+        return [
+            new MarkdownContent("# Hello, world!\n This is a **markdown** page."),
+        ];
+    }
+}
+```
+
+Here, we're creating a new `MarkdownPage` that displays a simple markdown string. The `MarkdownContent` class takes a string of markdown content, and renders it in the Command Palette. 
+
+You can also add multiple blocks of content to a page. For example, you can add two blocks of markdown content:
+
+```csharp
+public override IContent[] GetContent()
+{
+    return [
+        new MarkdownContent("# Hello, world!\n This is a **markdown** page."),
+        new MarkdownContent("## Second block\n This is another block of content."),
+    ];
+}
+```
+
+This allows you to mix-and-match different types of content on a single page.
+
+## Adding commands
+
+You can also add commands to a `ContentPage`. This allows you to add additional commands to be invoked by the user, while in the context of the content. For example, if you had a page that displayed a document, you could add a command to open the document in File Explorer:
+
+```csharp 
+
+public class MarkdownExamplePage : ContentPage
+{
+    public MarkdownExamplePage()
+    {
+        Icon = new("\uE8A5"); // Document icon
+        Title = "Markdown page";
+        Name = "Preview file";
+
+        Commands = [
+            new CommandContextItem(new OpenUrlCommand("C:\\Path\\to\\file.txt")) { Title = "Open in File Explorer" },
+        ];
+    }
+    public override IContent[] GetContent()
+    {
+        return [
+            new MarkdownContent("# Hello, world!\n This is a **markdown** document.\nI live at `C:\\Path\\to\\file.txt`"),
+        ];
+    }
+}
+
+```
+
+### Next up: [Get user input with forms](using-form-pages.md)
+
+## Related content
+
+- [PowerToys Command Palette utility](overview.md)
+- [Extensibility overview](extensibility-overview.md)
+- [Extension samples](samples.md)
