showmd

showmd: The Ultimate Markdown Previewer for macOS

Markdown was never meant to be previewed as plain text. Yet, for years, macOS users have struggled with a native Quick Look experience that dumps raw source code—hashes, asterisks, and dashes—making documents difficult to scan. showmd solves this problem by providing the most readable way to preview any .md file on macOS.

Whether you are a developer, an AI engineer, or a technical writer, showmd transforms your workflow by rendering Markdown into beautiful, structured content instantly. It is an open-source, free, and privacy-focused tool that feels like a native part of the macOS ecosystem.

What's showmd?

showmd is a specialized Markdown viewer and Quick Look extension for macOS. It is not an editor or a note-taking app; instead, it is a high-performance utility designed to render Markdown files perfectly the moment you press the spacebar in Finder.

In the modern development era, AI-generated files like AGENTS.md, CLAUDE.md, and .cursorrules are often filled with complex XML tags and structured prompts. While traditional viewers render these as garbled text, showmd identifies these patterns and displays them as clean, labeled blocks. It bridges the gap between raw code and readable documentation.

Features of showmd

Comprehensive Rendering Capabilities

• GitHub Flavored Markdown (GFM): Full support for tables, task lists, strikethrough, autolinks, and footnotes powered by Apple’s swift-markdown parser.
• Syntax Highlighting: showmd includes language-aware highlighting for over 190 languages, making code blocks within your Markdown easy to read.
• LaTeX Math Support: Beautifully render inline and block math expressions using KaTeX.
• Mermaid Diagrams: Turn code into visual flowcharts, sequence diagrams, and state machines directly in the preview.
• Inline Images: Relative image paths resolve correctly in Quick Look, ensuring your local screenshots and diagrams appear as intended.

Advanced Metadata Handling

• YAML Frontmatter Parsing: showmd is unique in how it handles metadata. It parses YAML frontmatter into a collapsible table that is hidden by default, keeping your view clutter-free until you need the details.
• Agentic AI Tags: Specifically built for modern AI workflows, it renders custom XML tags like <instructions>, <thinking>, and <example> as bordered, labeled blocks.

User Experience and Performance

• Instant Open: With zero bloat, showmd opens in under a second. Set it as your default viewer and use the Spacebar to preview files without friction.
• Native macOS Feel: The app respects system fonts, follows Dark Mode settings automatically, and uses native keyboard shortcuts.
• Rendered & Source Toggle: Switch between the rendered view and raw Markdown with a single click, or copy the content as HTML for use elsewhere.
• Privacy by Default: There is no cloud, no telemetry, and no uploads. Your files never leave your machine.

Use Cases for showmd

• Developer Documentation: Quickly scan README.md or CHANGELOG.md files in a repository without opening a heavy IDE like VS Code.
• AI Prompt Engineering: View and organize .cursorrules or agent instructions that use XML tagging, ensuring the logic is clear and well-formatted.
• Academic Writing: Use showmd to preview technical notes containing complex LaTeX equations or Mermaid workflows.
• Quick File Audits: Check the contents of various Markdown flavors including .mdx, .rmd, .qmd, and .mdown directly from the Finder.

How to Use showmd

Setting up showmd is straightforward and requires no complex configuration:

1. Download & Install: You can download the signed and notarized .dmg file directly or use Homebrew by running:

   brew install --cask johannesnagl/tap/showmd

2. Initial Setup: Open the application once. On the first launch, macOS will ask for permission to "access data from other apps." Click Allow to enable the app and extension to share your preferences.
3. Enable the Extension: Go to System Settings → Privacy & Security → Extensions → Quick Look. Locate showmd in the list and toggle it to On.
4. Preview: Navigate to any Markdown file in Finder and press Space. Your file will now appear fully rendered.

FAQ

How do I enable showmd in Finder?

After installing and opening the app once, enable it under System Settings > Privacy & Security > Extensions > Quick Look. Once enabled, the Spacebar shortcut in Finder will trigger the showmd preview.

What happens to YAML frontmatter?

showmd parses the frontmatter block and displays it as a collapsible metadata table. It supports arrays, quoted strings, and multi-line blocks, remaining collapsed by default to save space.

Does showmd support dark mode?

Yes. It automatically follows your macOS system appearance, though you can manually override this to Light or Dark mode within the app settings.

Which file extensions does showmd handle?

It recognizes a wide variety of extensions including .md, .markdown, .mdx, .mdc, .rmd, .qmd, .mdown, .mkd, .mkdn, .mdtext, and .mdtxt.

Is showmd an editor?

No, showmd is strictly a viewer and Quick Look extension. It opens files in a read-only format to provide a fast and clean rendering experience.

Is showmd free?

Yes, it is completely free and open source under the MIT license. If you find it useful, you can support the developer by "buying them a pasta."