Markdown Viewer

A simple tool to view Markdown files rendered in your browser on Windows. Other platforms will be added later; the tech stack is cross-platform.

Description

This project provides a way to open .md and .markdown files directly in your default web browser, rendered as HTML using PowerShell's built-in Markdown conversion.

How It Works

When you open a Markdown file, the app uses PowerShell's ConvertFrom-Markdown cmdlet to transform the Markdown into HTML. To ensure the output doesn't look like it's 1995, it adds some basic CSS styling. The result is then saved as a temporary HTML file and opened in your default web browser. The browser tab will display the app's icon and the actual Markdown filename as the title.

Installation

Option 1: Microsoft Store (MSIX)

PowerShell 7 is bundled in the package—no separate installation required.

1. Install from the Microsoft Store
2. The app will optionally show the user how to make it the defailt handler for .md and .markdown files

Architecture support: x64 package is available (ARM64 at a future release)

Option 1b: Sideload MSIX (Developer)

For testing or development builds without the Store:

1. Clone this repository
2. Build the MSIX package:

   cd installers/win-msix
   .\build.ps1 -Sign  # Creates and signs with dev certificate

3. Double-click the generated .msix file in installers/win-msix/output/

Note: First-time sideloading requires either:

• Developer Mode enabled in Windows Settings, or
• A signed package (the -Sign flag handles this automatically)

Option 2: Ad-hoc Installer (Per-User)

For manual installation without the Store:

1. Download or clone this repository.
2. Navigate to installers/win-adhoc/
3. Run INSTALL.cmd (or install.ps1 directly) as a user (no admin required).
4. The installer will:
   • Copy files to %LOCALAPPDATA%\Programs\MarkdownViewer.
   • Register file associations for .md and .markdown files.
   • Optionally add a "View Markdown" context menu item.
   • Optionally open Default Apps settings to set this as the default handler.
5. If PowerShell 7 (pwsh) is not installed, the installer will prompt you to install it.

Usage

• After installation, double-click any .md or .markdown file to view it rendered in your default web browser.
• If the context menu was enabled during installation, right-click on a Markdown file and select "View Markdown".
• The rendered HTML includes basic styling for readability.
• Dark mode support: Use the "Theme" toggle button in the top-right corner of the page to switch between system theme (follows OS preference) and inverted theme (opposite of system preference).
• Theme variations: Click the theme variation button (e.g., "Light Theme: Default") below the Theme button to choose from 5 color scheme variations for each theme:
  • Light themes: Default, Warm, Cool, Sepia, High Contrast
  • Dark themes: Default, Warm, Cool, OLED Black, Dimmed
  • Hover over options to preview, click to select. Preferences are saved separately for light and dark modes.
• Syntax highlighting: Fenced code blocks with language tags (e.g., ```powershell, ```javascript) are automatically highlighted using highlight.js. Supported language aliases include:
  • PowerShell: powershell, ps1, pwsh, psm1, psd1
  • JavaScript/TypeScript: javascript, js, typescript, ts, jsx, tsx
  • Web: html, css, json, xml, yaml, yml
  • Other: python, py, bash, sh, sql, csharp, cs, cpp, c, java, go, rust, ruby, rb, php, markdown, md, diff, dockerfile
  • Supports all languages included in the bundled highlight.min.js (currently 192 languages)
  • Code blocks without a recognized language tag are displayed as plain preformatted text (no auto-detection).
• Linked markdown files: Clicking links to other local .md files within a document opens them in Markdown Viewer. First time you click a linked Markdown file, Chrome/Edge will ask to allow launching the Markdown Viewer. Check 'Always allow…' to avoid future prompts.

Uninstallation

MSIX Version

• Uninstall via Windows Settings > Apps > Installed apps (search for "Markdown Viewer")

Ad-hoc Version

• Navigate to installers/win-adhoc/ and run UNINSTALL.cmd (or uninstall.ps1 directly)
• Alternatively, uninstall via Windows Settings > Apps > Apps & features (search for "Markdown Viewer")

Requirements

• Windows 10 (version 2004/19041) or later
• PowerShell 7 (pwsh)
  • MSIX: Bundled in the package
  • Ad-hoc: Automatically installed if missing

Security

This tool includes several security measures for viewing Markdown files safely:

• Content Security Policy (CSP): The rendered HTML uses a strict CSP with a cryptographic nonce. Only the app's own scripts and styles execute; any scripts embedded in the Markdown (malicious or otherwise) are blocked by the browser. The CSP allows loading local files (file: scheme) for syntax highlighting assets, but HTML sanitization (below) ensures no unauthorized file references exist in the rendered output.

• HTML Sanitization: Before rendering, the app strips dangerous HTML elements and attributes from the Markdown output:

  • Removes <script>, <iframe>, <object>, <embed>, <meta>, <base>, <link>, <style> tags
  • Removes event handlers (onclick, onerror, etc.)
  • Neutralizes javascript: URIs in links and sources
  • Blocks data: URIs in links (but allows them in images)

  This sanitization is the primary security barrier. The CSP provides defense-in-depth, blocking execution even if sanitization were bypassed.

• Mark-of-the-Web (MOTW) detection: Files downloaded from the internet are flagged by Windows with a Zone Identifier. When you open such a file, the app displays a warning dialog with options to:

  • Open — view this time (will warn again next time)
  • Unblock & Open — permanently trust this file
  • Cancel — don't open

• Read-only installation: Installed files are marked read-only to deter casual tampering.

• No network access: The CSP blocks all network requests (connect-src 'none'). The rendered page cannot phone home or load remote resources.

• Remote images opt-in: By default, external images (badges, etc.) are blocked. If a Markdown file contains remote images, an "Images" button appears. Clicking it prompts for confirmation before enabling remote image loading. This preference is stored per-document and can be toggled back to local-only at any time.

Limitations

• Not a sandbox: The app opens HTML in your default browser. While CSP blocks scripts and sanitization removes dangerous elements, a malicious Markdown file could still contain misleading HTML content (e.g., fake login forms). Exercise caution with files from untrusted sources.

• No code signing: The scripts are not digitally signed. If you're security-conscious, review the source code before running.

Reporting issues

If you discover a security vulnerability, please open an issue on GitHub.

Project Structure

MarkdownViewer/
├── src/
│   ├── core/                    # Cross-platform engine + assets
│   │   ├── Open-Markdown.ps1    # Main PowerShell engine
│   │   ├── script.js            # Client-side JavaScript
│   │   ├── style.css            # Client-side CSS
│   │   ├── highlight.min.js     # Syntax highlighting (highlight.js)
│   │   ├── highlight-theme.css  # Highlight.js theme
│   │   └── icons/               # Application icons
│   ├── win/                     # Windows-specific files
│   │   ├── MarkdownViewer.psm1  # Shared PowerShell module
│   │   ├── viewmd.vbs           # VBScript launcher (ad-hoc)
│   │   └── uninstall.vbs        # Silent uninstall helper
│   └── host/                    # Windows Host EXE (MSIX)
│       └── MarkdownViewerHost/  # .NET project
├── installers/
│   ├── win-adhoc/               # Per-user ad-hoc installer
│   │   ├── INSTALL.cmd
│   │   ├── UNINSTALL.cmd
│   │   ├── install.ps1
│   │   └── uninstall.ps1
│   └── win-msix/                # MSIX packaging
│       ├── Package/
│       │   ├── AppxManifest.xml
│       │   └── Assets/
│       └── build.ps1
├── tests/
│   ├── MarkdownViewer.Tests.ps1 # PowerShell Pester tests
│   └── MarkdownViewerHost.Tests/# C# xUnit tests
└── dev/
    └── docs/                    # Development documentation

License

This project is licensed under the MIT License - see the LICENSE file for details.

This project includes third-party software (highlight.js) under separate licenses - see THIRD-PARTY-LICENSES.md for details.