Product Introduction
Definition: showmd is a native macOS Quick Look extension and utility designed to provide high-fidelity rendering for Markdown files within the Finder. Built using Apple’s native swift-markdown parser, it functions as a lightweight plugin that replaces the default plain-text preview provided by macOS with a rich, formatted document viewer accessible instantly via the Spacebar.
Core Value Proposition: The product exists to bridge the gap between raw Markdown source code and readable documentation without requiring the user to open a full-scale IDE or text editor. By optimizing for modern developer workflows, showmd serves as an essential productivity tool for users interacting with GitHub Flavored Markdown (GFM), AI-generated prompt files, and technical documentation. Its primary value lies in its ability to parse complex elements like YAML frontmatter, LaTeX math, and Mermaid diagrams—features typically ignored by standard macOS previewers.
Main Features
Advanced YAML Frontmatter Parsing: Unlike standard viewers that display metadata as raw text blocks, showmd automatically identifies YAML frontmatter (the block between --- delimiters). It converts this data into a structured, collapsible metadata table. This feature is "collapsed by default," ensuring that technical metadata does not clutter the visual hierarchy of the document while remaining accessible with a single click.
Agentic AI XML Tag Rendering: Designed for the era of LLMs and AI agents, showmd includes specialized support for agentic AI XML tags such as
, , , and 17 others. Rather than displaying these as raw, unescaped angle brackets that break visual flow, the extension renders them as labeled, bordered blocks with distinct backgrounds, making AI system prompts and structured outputs significantly easier to audit and read. Comprehensive Technical Rendering (Math, Diagrams, and Code): The extension integrates KaTeX for high-performance LaTeX math rendering (supporting both inline $ and block $$ expressions) and provides built-in support for Mermaid.js diagrams. This allows flowcharts, sequence diagrams, and state machines to render directly in the Quick Look window. Furthermore, it features syntax highlighting for over 190 programming languages, ensuring that fenced code blocks are legible and contextually color-coded.
Native macOS Integration and Performance: As a native Swift application, showmd respects system-wide Dark Mode settings and utilizes system fonts to maintain a "First Party" feel. It supports a wide array of extensions beyond .md, including .mdx, .mdc, .rmd, .qmd, and .markdown. It includes a "Rendered vs. Source" toggle and a "Copy as HTML" function, allowing developers to quickly transition from viewing to sharing or debugging.
Problems Solved
Raw Text Unreadability in Finder: The default macOS Quick Look behavior for .md files often displays raw source code, including hashes (#) and asterisks (*), which obscures the actual content. showmd solves this by providing a clean, formatted interface that mimics a rendered GitHub README or a published blog post.
Cluttered AI Configuration Files: Files like AGENTS.md or .cursorrules are often dense with XML tags and structured prompts that are difficult to parse visually. showmd solves this by treating these tags as UI elements, providing clear visual separation between instructions, thought processes, and examples.
Target Audience: The primary users include Software Engineers who manage project documentation, AI Researchers/Prompt Engineers working with structured XML prompts, Data Scientists using RMarkdown (.rmd) or Quarto (.qmd), and Technical Writers who need to verify formatting without leaving the file system.
Use Cases: High-frequency scenarios include previewing CHANGELOG.md files to check version history, auditing complex Mermaid flowcharts in documentation folders, and quickly reviewing LaTeX equations in academic notes—all without the overhead of launching VS Code or Obsidian.
Unique Advantages
Differentiation from Competitors: While tools like "Markdown Preview by Anybox" exist as paid alternatives, and "QLMarkdown" serves as an older open-source option, showmd differentiates itself by including a standalone settings app for customization and offering specific support for modern AI-centric workflows (XML tag rendering) and collapsible YAML frontmatter, which most competitors treat as standard text.
Key Innovation: The specific innovation is the "Agentic-Aware" rendering engine. By recognizing that Markdown is increasingly used as a container for AI instructions and structured data (XML), showmd is the first Quick Look extension to prioritize the legibility of these specific structures alongside traditional Markdown elements.
Frequently Asked Questions (FAQ)
How do I enable showmd as the default Markdown viewer on macOS? After downloading and opening showmd once, you must navigate to System Settings > Privacy & Security > Extensions > Quick Look and toggle the checkbox for showmd. Once enabled, simply select any .md file in Finder and press the Spacebar to see the rendered output.
Does showmd require an internet connection to render Math or Diagrams? No. showmd is private by default and performs all rendering locally on your machine. It does not use telemetry, cloud processing, or external APIs for KaTeX (math) or Mermaid (diagrams), making it suitable for secure environments and offline use.
Can I toggle between the rendered view and the raw Markdown source? Yes. showmd includes a dedicated "Source" toggle at the top of the preview window. This allows users to quickly inspect the underlying Markdown syntax without closing the Quick Look interface. There is also a "Copy as HTML" button for easy porting of rendered content into emails or CMS platforms.
What file extensions are supported by showmd? showmd supports a comprehensive list of Markdown-related extensions including .md, .markdown, .mdx (MDX), .mdc, .rmd (RMarkdown), .qmd (Quarto), .mdown, .mkd, .mkdn, .mdtext, and .mdtxt. It automatically registers these extensions with macOS upon installation.
