MiaoYan is a lightweight, local-first Markdown note-taking app for macOS, written in Swift and released under the MIT licence, aimed at people who want fast plain-text notes on their own disk without accounts, telemetry, or a hosted service.

What it is

MiaoYan is a native macOS Markdown editor and notes application built with Swift 6. It presents a three-column layout with a split editor and preview, dark mode, keyboard shortcuts, auto-formatting, version history, wikilink backlinks, LaTeX and Mermaid rendering, and a distraction-free mode. The defining design choice is that it is local-first: it reads and writes the Markdown folder the user selects and does not collect data or sign in to WebDAV or cloud-drive accounts. The Markdown files remain ordinary files in a folder, and the app verifies read and write access before switching storage paths, leaving the current path unchanged if the new folder is unavailable.

The concrete problem it solves is note ownership. Instead of binding notes to a proprietary account or an opaque internal database, MiaoYan makes a plain Markdown folder the source of truth and delegates cross-device sync to whatever cloud-drive client the user already runs, such as iCloud Drive, Nutstore, or Dropbox. It also positions itself against heavier Electron-based editors on performance and against WYSIWYG editors such as Typora on editing model, since the README states that WYSIWYG in native Swift is overly complex and reliability-risky, so the project keeps split mode with clean Markdown editing and real-time preview instead.

Key capabilities

• Split editor and preview mode with real-time preview and 60fps bidirectional scroll sync, toggled with ⌘\ or set under Preferences → Interface → Edit Mode → Split Mode.
• Local-first storage model with no WebDAV or cloud-account sign-in: the app reads and writes the Markdown folder chosen in Preferences (⌘,).
• Command-line interface installed with curl -fsSL https://raw.githubusercontent.com/tw93/MiaoYan/main/scripts/install.sh | bash, exposing miao open, miao new [text], miao search, miao list [folder], miao cat, and miao update.
• PPT Presentation Mode, which builds presentations using --- slide separators on top of the reveal.js framework.
• MiaoYan Agent Skill, installable with npx skills add tw93/MiaoYan/skills/miaoyan -g, which teaches an agent MiaoYan syntax, attachments, PPT patterns, and CLI workflows.
• Markdown authoring features including wikilink backlinks, LaTeX, Mermaid, syntax highlighting, auto-formatting, and version history.
• Minimalist interface with three-column layout, dark mode, and macOS 26 glass styling.

Who uses it and how

• Individual macOS users running macOS 11.5 or newer who keep a MiaoYan folder in iCloud Drive or another synced location and point the app's storage path at it in Preferences.
• Nutstore or Dropbox users who create a MiaoYan folder inside the locally synced folder, letting the desktop client handle cross-device sync while MiaoYan handles editing.
• iPhone users who select the same cloud-drive folder from the system Files app, or fall back to iCloud Drive when a provider does not expose a writable folder in Files.
• Terminal-centric users and automation setups that script note capture, search, and listing through the miao CLI rather than the GUI.
• People producing slide decks from Markdown notes via PPT Presentation Mode, and agent workflows that install the skills/miaoyan skill for syntax and CLI knowledge.

Getting started

Install from the Mac App Store (paid, automatic updates), with Homebrew via brew install --cask miaoyan, or by downloading the latest DMG from GitHub Releases for macOS 11.5 and newer; all three options share the same codebase and receive the same updates. After installing, create a MiaoYan folder in iCloud Drive, a desktop cloud-drive folder, or another location, then open Preferences (⌘,) and set the storage path.

How it compares

Among the tools named in its own documentation, MiaoYan differs from Typora by rejecting WYSIWYG in favour of split editor and preview, and it credits FSNotes as the reference for its initial project structure. Its distribution model also splits against itself: the Homebrew cask and the GitHub Releases DMG are free under the MIT licence, while the Mac App Store build is paid, with the README stating that all three share the same codebase and receive the same updates. Sync is deliberately not a product feature, so MiaoYan sits alongside cloud-drive clients rather than replacing them.

When to use it — and when not to

A self-hoster operates no server, database, or SMTP stack here: the requirements are a Mac running macOS 11.5 or newer, a writable folder, and a third-party cloud-drive client if notes must reach other devices. It is a poor fit for anyone not on macOS, for anyone who wants built-in sync and account management rather than folder-level sync, and for anyone who prefers WYSIWYG editing, since the project explicitly declines that model. Note also that the README is a feature and installation overview rather than a deep operations manual, and that providers without a writable folder in the system Files app force an iCloud Drive fallback or an offline-folder workaround.

# Install
curl -fsSL https://raw.githubusercontent.com/tw93/MiaoYan/main/scripts/install.sh | bash

# Usage
miao open <title|path>    # Open note or folder
miao new <title> [text]   # Create new note
miao search <query>       # Search notes in terminal
miao list [folder]        # List top-level folders, or markdown in folder
miao cat <title|path>     # Print note content
miao update               # Update CLI