microsoft / microsoft/PowerToys

[New PowerToy] Markdown Reader - Persistent viewer with TOC and Mermaid support

Open
#45,267 5 comments 1 reaction 0 assignees View on GitHub
Idea-New PowerToy Needs-Triage Product-PowerToys Run
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.