MiaoYan: a local-first Markdown editor for macOS, installed three ways

What MiaoYan is for, and who it is not for

MiaoYan is a Markdown note-taking app for macOS, written in Swift 6 and distributed as a native binary rather than an Electron bundle. The README's framing is explicit: it is "local-first, no data collection," and it does not sign in to WebDAV or cloud-drive accounts. Instead you create a folder, point the app at it in Preferences, and let iCloud Drive, Nutstore, Dropbox or another desktop sync client move the files between machines.

That design answers a specific complaint. If you have ever wanted your notes to remain readable in a plain text editor twenty years from now, and you do not want a vendor holding the canonical copy, the folder-as-database model is the point. The app is the editor; the folder is the product.

It is not for everyone. There is no Windows or Linux build in the repository layout. The README describes a macOS app and an iPhone path that works through the system Files app, which means the mobile experience depends on whether your cloud provider exposes a writable folder there. If your team is mixed-platform, MiaoYan is the wrong tool and a cross-platform editor is the right one.

How the local-first folder model actually works

The data flow is unusually simple, which is why it is worth stating precisely. MiaoYan reads and writes the Markdown folder you select. Sync is not a feature of the app; it is a property of whatever client owns that folder. On a Mac, the README suggests creating a `MiaoYan` folder inside the folder the Nutstore desktop client already syncs, then setting that as the storage path in Preferences (⌘,).

There is one guardrail worth knowing about. According to the README, MiaoYan verifies read and write access before switching folders, and if the folder is unavailable the current storage path stays unchanged. That is a sensible failure mode: a bad path does not silently orphan your notes into a location you cannot find later.

The editor itself is a three-column layout with a split edit and preview mode, toggled with `⌘\`. The README claims 60fps bidirectional scroll sync between the two panes. It also documents wikilink backlinks, LaTeX, Mermaid diagrams, version history and keyboard shortcuts. On the WYSIWYG question the README is refreshingly direct: implementing it in native Swift is called "overly complex with reliability concerns," so the project chose split mode instead. That is a design trade-off stated as one, not hidden.

Installing MiaoYan and taking a first note

There are three install paths, and the README says all three share the same codebase and receive the same updates. The Mac App Store version is paid and handles automatic updates. The Homebrew cask is the fastest route for anyone already using Homebrew:

brew install --cask miaoyan

After that command completes, MiaoYan appears in your Applications folder like any other cask. The third option is downloading the latest DMG from GitHub Releases, which the README lists as requiring macOS 11.5 or later.

Once installed, the first real step is not writing but configuring storage. Create a `MiaoYan` folder in iCloud Drive, a desktop cloud-drive folder, or wherever you prefer, then open Preferences with ⌘, and set the storage path. If the folder is not writable, the app keeps the previous path, so a failed switch is visible rather than silent.

For terminal users there is a separate CLI, installed with a shell script:

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

The README lists `miao open <title|path>`, `miao new <title> [text]`, `miao search <query>`, `miao list [folder]`, `miao cat <title|path>` and `miao update` as the available commands. Note that piping a remote script into `bash` is a trust decision; the script lives in the repository's `scripts/` directory if you want to read it first.

Where MiaoYan gets in the way

The largest constraint is the one the README states plainly: MiaoYan is a macOS app. The repository contains a `MiaoYanMobile/` directory and mobile entitlements, and the README describes picking the same cloud-drive folder from the iPhone Files app, but it also warns that if a provider does not expose a writable folder in Files, you should use iCloud Drive or make the folder available offline in that provider's app first. That is a real dependency on third-party apps behaving well, and it is outside MiaoYan's control.

The split editor is the second trade-off. Anyone coming from Typora expects to type in the rendered document. MiaoYan does not do that, and its own justification is engineering complexity in native Swift. If live-rendered editing is the feature you actually want, this app will feel like a step backwards no matter how fast the scroll sync is.

Third, the CLI is a convenience layer over the same folder, not a headless editor. The README documents `open`, `new`, `search`, `list`, `cat` and `update`. There is no documented command for editing a note in place, so scripting a rewrite means touching the .md files directly. That is fine given the local-first model, but it means the CLI is not a substitute for the app.

MiaoYan compared with Obsidian and MarkEdit

The honest comparison is with Obsidian, because both store plain Markdown and both support wikilinks and backlinks. The difference is what sits between you and the files. Obsidian is an Electron application with a plugin ecosystem, and its own vault concept adds a layer of configuration and community extensions. MiaoYan is a native Swift app with no plugin system documented in the README; its feature surface is fixed by the maintainer. If you want to extend your editor, Obsidian wins. If you want fewer moving parts and a smaller binary, MiaoYan's approach is the argument.

MarkEdit is the closer comparison in spirit, a macOS Markdown editor rather than a vault platform. The practical difference is scope: MiaoYan ships a CLI, a documented presentation mode using `---` slide separators, and a published agent skill installed with `npx skills add tw93/MiaoYan/skills/miaoyan -g`. Those are opinionated additions that MarkEdit does not document. If you only need a fast place to type Markdown, the extra surface is overhead you will ignore.

One thing none of these comparisons settle: sync. MiaoYan delegates it entirely, so the reliability of your setup is the reliability of iCloud Drive or Nutstore, not of the editor.

Maintenance, licence and what the README does not say

The repository is not archived, and the last push was on 2026-08-15, which is recent enough that ongoing work is visible. The release history shows V4.0.0 on 2026-06-19, V4.1.0 on 2026-07-18 and V4.2.0 on 2026-08-15, roughly monthly cadence across three months. That is a maintained project, though the README does not publish a support policy, a deprecation timeline, or a minimum macOS version for future releases beyond the current 11.5+ note.

The licence is MIT, which permits use, modification and redistribution with the licence and copyright notice retained. For a desktop note app this mostly matters if you intend to fork it or ship a modified build; MIT is permissive on both counts. It does not, however, cover the paid Mac App Store listing, which is a distribution channel rather than a separate licence. Nothing here is legal advice, and the App Store build's terms come from Apple, not from the repository.

The README is silent on a few things worth flagging before you commit. It does not document rollback if a sync client corrupts a file, beyond the general claim of version history. It does not describe how conflicts between two devices are resolved. And it does not say whether the CLI and the GUI can run concurrently against the same folder. Those are the questions to answer from the source or the issue tracker rather than from the README.

Editorial conclusion

Adopt MiaoYan if you write Markdown on macOS and want your notes to stay as plain files in a folder you control, with a CLI for scripting and a split editor instead of a WYSIWYG canvas. Skip it if you need Windows, Linux, or a mobile-first workflow, since the README documents only a macOS app plus an iPhone path through the system Files app. Before committing, verify two things: that your chosen storage folder is writable from the Files app on iPhone, and that the Homebrew cask, App Store build and DMG all behave the same for your macOS version, because the README says they share one codebase but does not describe any feature differences between them.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes