Merge pull request #5895 from MicrosoftDocs/main

Auto Publish – main to live - 2025-10-15 23:35 UTC

Author: learn-build-service-prod[bot]

hub/dev-environment/toc.yml

@@ -820,6 +820,8 @@ items:
                             href: ../powertoys/command-palette/microsoft-commandpalette-extensions-toolkit/utilities_ispackaged.md
         - name: Color Picker
           href: ../powertoys/color-picker.md
+        - name: Light Switch
+          href: ../powertoys/light-switch.md
         - name: PowerToys Run
           href: ../powertoys/run.md
         - name: Screen Ruler

hub/images/pt-light-switch-settings.gif

@@ -1,16 +1,25 @@
 ---
-title: Display markdown content
-description: Learn how to display markdown in your Command Palette extension.
-ms.date: 3/23/2025
+title: Display markdown content in Command Palette extensions
+description: Learn how to display markdown content in your Command Palette extension. Create rich documentation, file previews, and interactive tutorials with formatted text and embedded commands.
+ms.date: 09/30/2025
 ms.topic: how-to
 no-loc: [PowerToys, Windows, Insider]
-# Customer intent: As a Windows developer, I want to learn how to develop an extension for the Command Palette.
+# Customer intent: As a Windows developer, I want to learn how to develop an extension for the Command Palette that displays markdown content, so that I can provide rich documentation or previews within the Command Palette.
 ---
 
 # Display markdown content
 
 **Previous**: [Command Results](command-results.md)
 
+The Command Palette supports rich content display beyond simple command lists. You can create extensions that show formatted text, documentation, and interactive content using markdown. This capability is particularly useful for:
+
+- Displaying help documentation or user guides
+- Showing file previews or summaries
+- Providing formatted instructions or tutorials
+- Creating interactive content with embedded commands
+
+This article shows you how to create pages that display markdown content in your Command Palette extension.
+
 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.
 
 ## Working with markdown content
@@ -63,7 +72,7 @@ public <ExtensionName>CommandsProvider()
 
 In this example, a new `ContentPage` that displays a simple markdown string is created. The 'MarkdownContent' class takes a string of markdown content and renders it in the Command Palette.
 
-![Screenshot of extension using ContentPage for markdown](../../images/command-palette/markdown.png)
+:::image type="content" source="../../images/command-palette/markdown.png" alt-text="Screenshot of Command Palette extension displaying markdown content with formatted text and document icon.":::
 
 You can also add multiple blocks of content to a page. For example, you can add two blocks of markdown content.
 
@@ -122,9 +131,39 @@ public class <ExtensionName>Page : ContentPage
 1. Select \<ExtensionName\>
 1. Press `Enter` key, the docs should open
 
-![Screenshot of extension using CommandContextItem](../../images/command-palette/command-context-item.png)
+:::image type="content" source="../../images/command-palette/command-context-item.png" alt-text="Screenshot of Command Palette extension showing CommandContextItem with Open in File Explorer option.":::
+
+## Add images to markdown content
+
+With Command Palette in PowerToys 0.95 and later, you can add images to your markdown content from additional sources using one of the following schemes:
+
+- File scheme: Enables loading images using the `file:` scheme.
+  - This scheme intentionally restricts file URIs to absolute paths to ensure correct resolution when passed through the Command Palette extension/host boundary. In most cases, 3rd-party extensions provide the paths. However, the Command Palette host performs the actual loading and would otherwise resolve paths relative to itself.
+- Data scheme: Enables loading images from URIs with the `data:` scheme (both Base64 and URL-encoded forms).
+  - **Note**: Before the changes introduced in PowerToys 0.95 and later, the markdown control could hang or become unresponsive when processing very large input, such as images larger than 5 MB or with dimensions exceeding 4000×4000 pixels, or markdown files exceeding 1 MB in size. Even with the changes, it is recommended to keep image file sizes below 5 MB and resize images to reasonable dimensions before embedding. For best results, compress images and split very large markdown content into smaller sections where possible.
+- `ms-appx` scheme: This scheme is now supported for loading images.
+  - **Note**: Since the Command Palette host performs the loading, `ms-appx:` resolution applies to the host and not the extensions, which limits its usefulness.
+- `ms-appdata` scheme: This scheme is now supported for loading images.
+  - Similar to `ms-appx:`, `ms-appdata:` resolution applies to the host, not the extensions. This limits its usefulness for 3rd-party extensions.
+
+Additionally, Command Palette in PowerToys 0.95 and later introduces the concept of image source hints, implemented as query string parameters piggy-backed on the original URI.
+
+These hints allow extension developers to influence the behavior of images within the markdown content.
+
+- `--x-cmdpal-fit`
+  - `none`: No automatic scaling, provides image as is (default)
+  - `fit`: Scale to fit the available space
+- `--x-cmdpal-upscale`
+  - `true`: Allow upscaling
+  - `false`: Downscale only (default)
+- `--x-cmdpal-width`: Desired width in pixels
+- `--x-cmdpal-height`: Desired height in pixels
+- `--x-cmdpal-maxwidth`: Max width in pixels
+- `--x-cmdpal-maxheight`: Max height in pixels
+
+See the [SampleMarkdownImages](https://github.com/microsoft/PowerToys/blob/main/src/modules/cmdpal/ext/SamplePagesExtension/Pages/SampleMarkdownImagesPage.cs) page in the [SamplePagesExtension](https://github.com/microsoft/PowerToys/tree/main/src/modules/cmdpal/ext/SamplePagesExtension) generic sample project in the PowerToys GitHub repository for examples of using images in your extension's markdown content.
 
-### Next up: [Get user input with forms](using-form-pages.md)
+## Next up: [Get user input with forms](using-form-pages.md)
 
 ## Related content
 

hub/images/pt-light-switch.png

@@ -184,6 +184,17 @@ The currently available utilities include:
     :::column-end:::
 :::row-end:::
 
+### Light Switch
+
+:::row:::
+    :::column:::
+        [![A screenshot of the Light Switch PowerToys utility for Windows.](../images/pt-light-switch.png)](light-switch.md)
+    :::column-end:::
+    :::column span="2":::
+        [Light Switch](light-switch.md) allows you to automatically switch between light and dark themes in Windows based on the time of day.
+    :::column-end:::
+:::row-end:::
+
 ### Mouse utilities
 
 :::row:::

hub/powertoys/command-palette/using-markdown-content.md

@@ -0,0 +1,40 @@
+---
+title: Manage your Windows theme with Light Switch
+description: Learn how to automatically switch between light and dark themes in Windows using PowerToys Light Switch. Reduce eye strain and save battery life.
+ms.date: 09/30/2025
+ms.topic: concept-article
+ms.localizationpriority: medium
+no-loc: [PowerToys, Windows, themes, Light Switch]
+# Customer intent: As a Windows power user, I want to use PowerToys Light Switch to automatically change my Windows theme based on the time of day, so that I can have a more comfortable viewing experience.
+---
+
+# Light Switch utility
+
+Light Switch is a PowerToys utility that automatically switches your Windows theme between light and dark modes based on time of day. You can configure Light Switch to change themes automatically using sunrise and sunset times in your location, or set custom schedules that work best for your daily routine.
+
+Benefits of using Light Switch include:
+
+- **Reduced eye strain** - Dark themes are easier on your eyes in low-light environments
+- **Better battery life** - Dark themes can help extend battery life on devices with OLED displays
+- **Automatic adaptation** - No need to manually change themes throughout the day
+
+## How to activate and use Light Switch
+
+Light Switch is enabled by default, but you can activate or deactivate it by opening PowerToys Settings and changing the **Enable Light Switch** toggle. You can then configure the settings to specify the times for switching between light and dark themes based on your local sunrise and sunset times or manually set times.
+
+:::image type="content" source="../images/pt-light-switch-settings.gif" alt-text="An animated GIF of the Light Switch settings.":::
+
+The following settings are available for Light Switch:
+
+| Setting | Description |
+| :-- | :-- |
+| Enable Light Switch | Turn the Light Switch utility on or off. |
+| Theme toggle shortcut | Set a keyboard shortcut to manually toggle between light and dark themes. |
+| Mode | Choose between using dark mode from **Sunset to Sunrise** (automatic based on your location) or **Manual** (set specific times). Note that you must have location services enabled and synced for automatic mode to work. |
+| Location | Sync your location to enable automatic switching based on local sunrise and sunset times. |
+| Offset in minutes | Adjust the time for switching themes by a specified number of minutes before or after sunrise and sunset. |
+| Turn on dark mode | Set the time to switch to dark mode when using manual mode. |
+| Turn on light mode | Set the time to switch to light mode when using manual mode. |
+| Apply dark mode to | Choose whether Light Switch applies dark mode to **System** (Taskbar, Start, and other system UI) and/or **Apps** (supported apps). |
+
+[!INCLUDE [install-powertoys.md](../includes/install-powertoys.md)]