QLMarkdown Free and Open Source Desktop App CookApps CookApps Marketplace

Overview

QLMarkdown is a premier, feature-rich macOS Quick Look extension dedicated to high-fidelity Markdown previews right inside Finder. Built in Swift on top of cmark-gfm, QLMarkdown supports MathJax LaTeX formulas, live Mermaid diagrams, YAML frontmatter headers, Emoji shortcodes, syntax-highlighted code fences, custom CSS themes, and CLI/Shortcuts HTML conversion.

How It Works

QLMarkdown operates through structured, deterministic execution stages:

cmark-gfm High-Fidelity Renderer: Evaluates CommonMark and GitHub Flavored Markdown documents cleanly inside macOS Quick Look windows.

Live MathJax & Mermaid Pipelines: Compiles TeX mathematical notation via MathJax and renders live Mermaid flowcharts and sequence diagrams natively.

Themeable CSS & Code Extensions: Customizes typography, dark/light styling, YAML frontmatter display, and syntax highlight presets from the companion GUI.

CLI Converter & Shortcuts Support: Exports rendered HTML directly via CLI or macOS Shortcuts workflows for batch documentation pipelines.

QLMarkdown macOS Quick Look preview rendering Markdown, tables, and equations

QLMarkdown settings interface for customization and extensions

Key Technical Features & Capabilities

cmark-gfm Exact GitHub Parity: Renders tables, strikethrough, task lists, footnotes, and auto-linked URLs matching GitHub Markdown styling.

MathJax & Mermaid Diagram Rendering: Automatically evaluates inline/block LaTeX formulas via MathJax and renders live Mermaid flowcharts inside previews.

Companion Settings GUI & Themes: Includes a dedicated macOS interface to configure typography, light/dark CSS themes, YAML metadata tables, and file extensions.

CLI Tool & macOS Shortcuts Support: Converts Markdown inputs directly to clean standalone HTML via command line (qlmarkdown_cli) or native Shortcuts actions.

Architecture & Technology Stack

Primary Languages: Swift, C / C++ (cmark-gfm Engine), JavaScript (Mermaid & MathJax)

Frameworks & APIs: Apple QuickLookUI, WebKit (WKWebView), AppIntents / Shortcuts

Supported Extensions: .md, .rmd, .mdx, .qmd, .mdc, .apib, .textbundle, .mermaid

Supported Platforms: macOS 12+ (Universal Apple Silicon & Intel)

System Requirements

Specification	Minimum Requirement	Recommended Specification
Operating System	macOS 12.0+ (Universal Apple Silicon & Intel)	Latest stable release build
Processor Architecture	4-Core x86_64 or Apple Silicon M1	8-Core Apple Silicon / Core i7+
Memory (RAM)	4 GB Unified Memory	16 GB+ High-Speed RAM
Disk Space	1 GB free SSD storage	5 GB+ free SSD storage

Installation & Setup Guide

macOS Installation

bash

brew install --cask qlmarkdown

Or download QLMarkdown.zip from CookApps, extract QLMarkdown.app to /Applications, launch once, and enable QLMarkdown Extension under System Settings › Extensions › Quick Look.

Building from Source

bash

git clone --recursive https://github.com/sbarex/QLMarkdown.git
cd QLMarkdown
open QLMarkdown.xcodeproj

How to Use & Workflow

Enable Quick Look Extension: Open QLMarkdown.app once and verify its extension switch in System Settings.

Customize Rendering Features: Toggle MathJax equations, Mermaid diagrams, Inline Local Images, and Dark CSS styling inside the app settings window.

Preview Instant Docs: Select any .md, .mdx, or .qmd file in Finder and hit Spacebar.

Troubleshooting & Common Issues

Issue: Local relative images inside Markdown fail to render inside Quick Look.

*Cause*: Apple Quick Look extensions run inside a strict read-only sandbox restricted to the single selected file URL unless permitted.

*Resolution*: Toggle "Inline local images" in QLMarkdown preferences or store assets inside .textbundle packages.

QLMarkdown

Overview

How It Works

Key Technical Features & Capabilities

Architecture & Technology Stack

System Requirements

Installation & Setup Guide

macOS Installation

Building from Source

How to Use & Workflow

Troubleshooting & Common Issues

How to Use & Getting Started

Ready to run QLMarkdown?

More in system-utilities

Cyberduck

Glance

V2rayU