Download for Windows

Troubleshooting MD View

Fixes for the install, runtime, and feature issues we see most often. Concrete steps, not abstract advice.

Last updated

If something’s not working, this page lists the issues we see most often along with a fix. If your problem isn’t here, email [email protected] with the version (Help → About) and what you tried.

Install

winget says “package not found”

Update winget to the latest manifest list:

winget source update
winget search mdview

If winget search still doesn’t return mdview, your winget client is older than 1.7. Update via the Microsoft Store (“App Installer”), then retry.

MSI install fails with “WebView2 missing”

The .msi auto-installs WebView2 if it’s not present, but on some locked-down Windows builds the auto-install is blocked. Install WebView2 manually from the Microsoft download page, then re-run the MD View installer.

”Windows protected your PC” SmartScreen warning

Windows may show a SmartScreen warning while MD View is new. Click More info → Run anyway to proceed. Only download MD View from mdview.dev — if you got the installer from somewhere else, stop and re-download from the official source.

Where did the installer put the binaries?

%LOCALAPPDATA%\Programs\md-view\ for per-user installs (winget default). C:\Program Files\md-view\ for system-wide MSI installs. The mdview.exe shim and md-view.exe GUI both live there; the installer adds the directory to your user PATH.

Runtime

”mdview” not recognized in terminal

The shim was installed but PATH wasn’t picked up by your existing terminal session. Close the terminal, open a new one, and try again. If it still doesn’t resolve:

$env:PATH -split ';' | Select-String md-view

If that prints nothing, the install didn’t add the directory. Repair: winget install --force mdview or reinstall the .msi.

Double-clicking a .md opens the wrong app

Windows file associations are sticky. Reset:

  1. Right-click any .md → Open with → Choose another app.
  2. Pick MD View from the list.
  3. Tick Always use this app.
  4. Click OK.

If MD View doesn’t appear in the picker, click More apps and browse to %LOCALAPPDATA%\Programs\md-view\md-view.exe.

File association is gone after a Windows update

Some major Windows updates reset associations to the in-box default. Re-run the .msi installer (it’s idempotent) or use the picker fix above. We also rebind on every app launch when MD View detects the association is missing — so just opening MD View once and clicking “Set as default” fixes it.

Fonts look wrong / boxed / fallback

WebView2 needs the system fonts available. If you’ve stripped the default Windows font set or run in a heavily-locked container, MD View may fall back to a plain serif. Install the standard Windows Segoe UI / Cascadia / Consolas trio. Custom themes can also pull in fonts the system doesn’t have — try cycling themes (Alt+T) to confirm whether the issue is theme- specific.

Mermaid diagrams don’t render

Mermaid is lazy-loaded — the first diagram in a session takes a moment longer to draw because the library is fetching. If a diagram shows raw source instead of a graph after several seconds:

  1. Reload the document with Alt+R.
  2. If still raw, the Mermaid syntax has a parse error. Check the browser-style devtools console (F12 in dev builds, otherwise toggle on in Settings → Advanced) — Mermaid logs parse errors there.

Export

PDF export fails or produces an empty file

The Pro PDF export uses a hidden WebView2 instance. If it fails:

  • Free up memory. Very large documents (over 10 MB) can fail under RAM pressure. Close other apps and retry.
  • Check the doc renders normally in the main window. If the in-app render works but export fails, email [email protected] with the document size and any error message you can see.
  • Try the browser print dialog (Ctrl+P) as a fallback — same content, no nested bookmarks.

DOCX export needs Pandoc

DOCX export shells out to Pandoc. Install Pandoc:

winget install pandoc

Then retry the export. MD View finds pandoc.exe on PATH; if your install is in a non-standard location, add the install directory to your PATH.

Licensing

License file won’t activate

MD View licenses are .mdview files signed offline. Activation is fully offline — there is no online validation step, no account, and no per-device activation limit. To activate:

  • Save the .mdview attachment from your order email anywhere on disk (Downloads is fine).
  • Drag the file onto the running MD View window, or open Help → Enter License… and paste the contents.
  • The status row in About flips to Pro — Licensed to <your name>.

If activation fails, the most common causes are:

  • The file was opened in a text editor that re-encoded the line endings or stripped the trailing newline. Re-download from your order email and try again without opening it first.
  • The file is for a different major version of MD View than the one you’re running. v2 licenses work in v2.x; v3 (when shipped) would ship its own license file as a separate purchase.

Lost the license email — how do I get a new one?

Visit mdview.dev/recover, enter the email address you used at purchase, and click Send my license. The same .mdview file is re-sent to you.

Pro features locked after the trial ended

Expected — the in-app trial is exactly 14 days from first launch. Buy a license; the .mdview file arrives by email within a minute. Drop it on the app to re-unlock Pro.

Performance

Slow on large files (10+ MB markdown)

The render pipeline is fast for typical documents (under 2 MB) but markdown-it slows down on multi-megabyte single files. If you’re hitting that:

  • Split the file into smaller documents and use a workspace (Ctrl+Shift+O) for navigation.
  • Disable Mermaid if the doc has hundreds of diagrams — Settings → Render → Disable Mermaid.
  • Increase the syntax-highlight cap in Settings → Render if code blocks are the bottleneck (highlighting falls back to plain text above the cap to keep render times sub-second).

High CPU when watching a folder

The file-system watcher runs on the main thread. If a build script is rewriting hundreds of files per second in the watched folder, the debouncer absorbs most of the noise — but a runaway script (rename loops, infinite test reruns) can keep MD View busy. Stop the script; CPU returns to baseline within a few seconds.

Still stuck?

Email [email protected] with:

  • MD View version (Help → About).
  • Windows version (winver in Run).
  • What you ran / clicked, what you expected, what happened.
  • Logs from %LOCALAPPDATA%\md-view\logs\ if relevant.

We reply within 48 hours, usually faster.