# showmd

> The most readable way to preview any .md file on macOS.

showmd is a free, native macOS Quick Look extension that renders Markdown beautifully. Press Space on any Markdown file in Finder and get an instant, rich preview.

## Install

Requires macOS 26 (Tahoe) or later.

```
brew install --cask johannesnagl/tap/showmd
```

Then enable in System Settings → Privacy & Security → Extensions → Quick Look. On first launch, macOS will ask to "access data from other apps" — click Allow so settings sync between the app and extension.

## Features

- Full GitHub Flavored Markdown: tables, task lists, strikethrough, fenced code blocks
- Syntax highlighting for 190+ languages (highlight.js, bundled offline)
- Math rendering via KaTeX, inline $...$ and block $$...$$
- Mermaid diagrams (optional, toggle in settings)
- YAML frontmatter parsed as a collapsible metadata table
- GitHub-style alerts: NOTE, TIP, IMPORTANT, WARNING, CAUTION
- Agentic AI XML tag styling for prompt engineering files: example, instructions, thinking, reflection, planning, context, important, rule, system-prompt, user-prompt, assistant-response, tool-use, tool-result, constraints, guidelines, persona, task, step, output-format, example-agent — rendered as labeled bordered blocks
- Emoji shortcodes: :rocket: becomes a rocket emoji
- Footnotes, highlight (==text==), superscript (x^2^), subscript (H~2~O), smart quotes
- Rendered / Source toggle to switch between HTML and raw Markdown
- Copy as HTML
- Dark mode: follows macOS appearance, or override (Light / Dark / Auto)
- Adjustable font size: Small, Medium, Large
- Fully offline: all JS/CSS dependencies are bundled, no network needed
- XSS-hardened: all user content is escaped and raw HTML is sanitized

## Supported File Extensions

.md, .markdown, .mdx, .mdc, .rmd, .qmd, .mdown, .mkd, .mkdn, .mdtext, .mdtxt

## Architecture

Native macOS app with a Quick Look preview extension. The MarkdownRenderer Swift package is shared between the host app (SwiftUI settings window) and the extension. Settings sync via App Groups.

Dependencies: apple/swift-markdown for parsing, highlight.js for syntax highlighting, KaTeX for math, Mermaid for diagrams — all bundled offline.

## Links

- Website: https://showmd.yetanother.one
- GitHub: https://github.com/johannesnagl/showmd
- Author: Johannes Nagl

## License

MIT