https://github.com/pluk-inc/markdown-preview
A simple Markdown viewer for reading .md files
https://github.com/pluk-inc/markdown-preview
macos markdown
Last synced: about 1 month ago
JSON representation
A simple Markdown viewer for reading .md files
- Host: GitHub
- URL: https://github.com/pluk-inc/markdown-preview
- Owner: pluk-inc
- License: mit
- Created: 2026-04-28T04:55:41.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-05-06T10:54:40.000Z (about 2 months ago)
- Last Synced: 2026-05-06T12:37:54.786Z (about 2 months ago)
- Topics: macos, markdown
- Language: Swift
- Homepage: http://markdownpreview.app
- Size: 13 MB
- Stars: 474
- Watchers: 2
- Forks: 26
- Open Issues: 9
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
Markdown Preview
A fast, native macOS app for reading Markdown files.
---
> Drop a `.md` on the icon (or set Markdown Preview as your default handler) and get a clean, scrollable preview with a real document outline — no Electron, no browser tab.
## Installation
```sh
brew install --cask pluk-inc/tap/markdown-preview
```
Or grab the latest signed and notarized DMG from the [Releases](https://github.com/pluk-inc/md-preview.app/releases) page.
## Screenshots
Quick Look preview — spacebar a .md in Finder:
Customize the toolbar — drag in Print, Copy, Zoom and the rest from View → Customize Toolbar…
## Features
- **Native rendering** — `WKWebView` pipeline backed by [swift-markdown](https://github.com/swiftlang/swift-markdown), with heading anchors and link handling.
- **Mermaid diagrams** — fenced `mermaid` code blocks render as diagrams in both the app and Quick Look previews, using a bundled renderer so previews work offline without a CDN request.
- **Math equations** — LaTeX inline (`$x_1 + x_2$`), display (`$$\int_0^1 x^2\,dx$$`), and fenced `math` blocks render with a bundled KaTeX. Selecting a rendered formula and copying yields the original LaTeX source (via the official `copy-tex` extension).
- **Document outline** — sidebar TOC that mirrors your headings; click to jump.
- **Inspector panel** — toggleable side panel with file metadata.
- **In-document search** — toolbar search field plus standard ⌘F / ⌘G / ⌘⇧G for next/previous match.
- **Open With** — switch to your real editor (VS Code, Cursor, Zed, Sublime, BBEdit, Nova, CotEditor, TextMate, MacVim, Xcode, TextEdit) without leaving the preview. The list filters to apps that actually declare an editor role for Markdown, and remembers your pick.
- **Text zoom** — bump preview text up or down with the toolbar's A A control or ⌘+ / ⌘− / ⌘0. Discrete Safari-style stops from 50% to 300%.
- **Customizable toolbar** — drag in the items you actually use (Print, Copy, Zoom, Sidebar, Open With, Inspector, Share, Search) via *View → Customize Toolbar…* Standard AppKit affordance, your layout sticks across launches.
- **Share = copy the source** — the share toolbar feeds the picker the Markdown text itself, so **Copy** writes the raw source to the clipboard (great for pasting into ChatGPT / Claude), and Mail, Messages, and Notes get the content in the body instead of a file URL.
- **Quick Look extension** — system-wide `.md` previews from Finder spacebar, Spotlight, and Mail attachments without launching the app.
- **Default handler** — offers to register itself as the default `.md` opener on first launch.
## Supported file types
`.md`, `.markdown`, `.mdown`, `.txt`
UTI: `net.daringfireball.markdown`
## Requirements
- macOS 15 or later
- Apple Silicon or Intel
## Building from source
```sh
git clone git@github.com:pluk-inc/markdown-preview.git
cd markdown-preview
open markdown-preview.xcodeproj
```
Build and run the `markdown-preview` scheme. Swift Package Manager will resolve [Sparkle](https://github.com/sparkle-project/Sparkle) and [swift-markdown](https://github.com/swiftlang/swift-markdown) on first build.
## Project layout
```
md-preview/ Main app target (AppKit, WKWebView)
quick-look/ Quick Look extension (.appex)
scripts/ Release & rollback automation
Version.xcconfig Marketing & build version (single source of truth)
appcast.xml Sparkle update feed
```
## Releasing
Releases are driven by [Amore](http://amore.computer/) — it handles building, code signing, notarization, DMG creation, S3 upload, and Sparkle appcast publishing in one shot.
Bump `MARKETING_VERSION` and `CURRENT_PROJECT_VERSION` in `Version.xcconfig`, then:
```sh
./scripts/release.sh
```
Use `./scripts/rollback-release.sh` to revert the appcast pointer if a release misbehaves.
## Contributing
Pull requests are welcome. For larger changes, please open an issue first to discuss what you'd like to change.
1. Fork the repo and create your branch from `main`.
2. Run the app and verify the change end-to-end (UI changes need a manual smoke test — there's no UI test suite yet).
3. Keep PRs focused; one logical change per PR.
4. Match the existing Swift style (no formatter is enforced; mirror nearby code).
Special Sponsor
## Acknowledgments
- [swift-markdown](https://github.com/swiftlang/swift-markdown) — Markdown parser (Apple, cmark-gfm-backed)
- [Mermaid](https://mermaid.js.org/) — bundled diagram renderer for `mermaid` fenced code blocks
- [KaTeX](https://katex.org/) — bundled math typesetter for inline `$…$`, display `$$…$$`, and ` ```math ` blocks
- [Sparkle](https://sparkle-project.org) — Auto-update framework
- [Amore](http://amore.computer/) — macOS release automation (signing, notarization, DMG, hosting, appcast)
## License
[MIT](LICENSE)