Pellucid

A native macOS markdown viewer built with Swift and SwiftUI. No web views, no JavaScript, no Electron — just fast, native rendering that feels like a first-class Mac app. Pellucid is a viewer, not an editor. Open a markdown file, see it rendered beautifully, and let your editor of choice handle the writing while Pellucid live-reloads on every save.

Features

• GitHub Flavored Markdown — full GFM spec: tables, task lists, strikethrough, fenced code blocks
• Table of contents — auto-generated sidebar from headings, click to scroll
• Themes — Default and Solarized, with automatic light/dark mode
• Live reload — watches the file for changes and re-renders instantly, keeping your scroll position
• Syntax highlighting — 19 languages with regex-based tokenization
• LaTeX math — native rendering via SwiftMath (no MathJax/KaTeX)
• PlantUML diagrams — rendered via CLI subprocess as SVG
• Multiple open methods — File > Open, drag-and-drop, CLI argument, or registered .md file handler

Supported Markdown

• Headings, paragraphs, blockquotes, horizontal rules
• Bold, italic, strikethrough
• Links and images (rendered at actual size)
• Ordered, unordered, and task lists
• Tables
• Fenced code blocks with syntax highlighting (19 languages)
• LaTeX math via math/latex code blocks
• PlantUML diagrams via plantuml code blocks

See test.md for rendered examples of everything supported.

Requirements

• macOS 14 (Sonoma) or later
• Swift 6 toolchain
• PlantUML (optional, for diagram rendering)

  sudo port install plantuml
  

Note: Running the bare executable (not the .app bundle) may cause window focus issues on macOS. Use the .app bundle for normal use.

Install

MacPorts

Requires MacPorts and Xcode Command Line Tools.

git clone https://github.com/ehkropf/Pellucid-Markdown-Viewer.git
sudo port install Pellucid-Markdown-Viewer/ports/aqua/pellucid

# Or with PlantUML diagram support:
sudo port install Pellucid-Markdown-Viewer/ports/aqua/pellucid +plantuml

The app installs to /Applications/MacPorts/Pellucid.app.

Homebrew

Requires Homebrew and Xcode Command Line Tools.

brew tap ehkropf/pellucid
brew install pellucid

# Then symlink to /Applications:
ln -sf $(brew --prefix)/opt/pellucid/Pellucid.app /Applications/Pellucid.app

Manual

Build first, then install:

make
make install

Or copy the built app yourself:

make
cp -R build/Pellucid.app /Applications/

Usage

Once installed, open any markdown file with:

open -a Pellucid file.md

Or during development:

make open          # build and launch

You can also:

• Drag and drop a .md file onto the app icon or window
• File > Open (⌘O) to browse for a file
• Double-click a .md file if Pellucid is set as the default handler

Architecture

Sources/Pellucid/
  App/           — @main entry point (PellucidApp), menu commands (AppCommands)
  Models/        — MarkdownDocument, WindowManager, FileIdentity, TOCEntry, FileWatcher, ThemeManager
  Views/         — DocumentWindowView, ContentView, TOCSidebarView, MathBlockView, DiagramBlockView
  Services/      — TOCExtractor, SyntaxHighlighter, PlantUMLRenderer, LocalImageProvider
  Utilities/     — Slugify, MathPreprocessor, Clipboard

Built entirely with Swift Package Manager — no Xcode project required.

Dependencies

Package	Purpose
swift-markdown	GFM AST parsing
swift-markdown-ui	SwiftUI markdown rendering
SwiftMath	LaTeX math rendering

License

GPL-3.0-or-later. See LICENSE for details.