microsoft / microsoft/PowerToys
[New PowerToy] Markdown Reader - Persistent viewer with TOC and Mermaid support
- Dominant language
- C
- Stars
- 139k
- Forks
- 8.6k
- PR merge metrics
- PR metrics pending
Description
### Description of the new feature / enhancement
### What is the user problem or growth opportunity you want to see solved?
Currently, PowerToys offers **Peek** and **File Explorer Preview**, which are excellent for quick inspections. However, Windows lacks a native, lightweight, and "read-only" application for sustained reading of Markdown files.
**The Gap:**
* **Peek is transient**: It’s designed to disappear once focus is lost or a task is done. It's not suitable for keeping a README open on the side while coding ("Side-by-side documentation").
* **Editors are cluttered**: VS Code or Obsidian are "heavy" for just reading; they occupy system resources and screen real estate with editing UI.
* **Browser dependency**: Using a browser requires changing file associations and lacks a native OS feel (no Mica, no Snap Layouts integration).
### Comparison: Peek vs. Markdown Reader
| Feature | Peek / Preview Pane | Markdown Reader (Proposed) |
| :--- | :--- | :--- |
| **Interaction** | Transient (Dismissable) | **Persistent Window** |
| **Navigation** | Scroll only | **Table of Contents (TOC)** |
| **Use Case** | Quick Glance | **Long-form Reading / Ref** |
| **Search** | Basic | **Global Search & Jump** |
| **Diagrams** | Basic | **Mermaid.js Support** |
### How do you want to see this implemented?
I propose a new module: **Markdown Reader** — a standalone, WinUI 3-based viewer optimized for documentation consumption.
**Key Features:**
* **Persistent Navigation**: A clickable **Table of Contents (TOC)** sidebar parsed from Markdown headers.
* **Optimized Reading Experience**: Support for Zoom, text search (Ctrl + F), and **GFM (GitHub Flavored Markdown)** rendering (including robust **Mermaid diagram** and Table support).
* **PowerToys Synergy**: Native support for "Always on Top" and standard Snap Layouts.
* **Lightweight Entry**: Accessible via File Explorer context menu and PowerToys Run.
* **Multi-Instance**: Supports opening multiple independent windows for side-by-side comparison.
**Technical Approach:**
* **Project Structure**: Follow the `src/modules/` pattern (similar to `PowerToys.Peek`).
* **Renderer**: Leverage **Markdig** (already used in PowerToys) for robust GFM parsing.
* **UI**: WinUI 3 with Mica backdrop. A wrapped `WebView2` utilizing logic similar to [`MonacoPreviewHandlerControl.cs`](https://github.com/microsoft/PowerToys/blob/main/src/modules/previewpane/MonacoPreviewHandler/MonacoPreviewHandlerControl.cs) ensures 100% GFM compatibility while maintaining a native shell.
I am willing to contribute to this implementation and have started analyzing the architecture.
### Scenario when this would be used?
1. **Documentation Reading**: A developer downloads a library and wants to read the `README.md` and `docs/*.md` without opening their heavy IDE. They double-click the file, and it opens in Markdown Reader with a clear TOC.
2. **Spec Review**: A PM reviews a feature spec (like this one!). They keep the Markdown Reader window open on a second monitor while checking the implementation.
3. **Local Knowledge Base**: A user reads their Obsidian/Logseq notes in a "Read-Only" mode without risking accidental edits.
### Supporting information
I have a local prototype plan and am ready to start working on a PR once the concept is approved.
Contributor guide
Research direction
Start by reviewing the src/modules/ pattern and the existing PowerToys.Peek implementation. Read MonacoPreviewHandlerControl.cs, then assess how Markdig and a WinUI 3 WebView2 shell could support the proposed viewer. Done would require an approved scope and an implementation covering the persistent window, TOC, GFM rendering, search, Mermaid support, and integration points.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- csharp, markdown
- Domain
- desktop, documentation
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Needs clarification
- Newbie friendliness
- 30/100