MiaoYan: A Local-First Markdown Editor for macOS That Skips the Cloud Account

What MiaoYan Actually Solves

MiaoYan targets a specific annoyance: Markdown notes scattered across apps that lock you into a proprietary database or a cloud account. It solves that by treating a folder of plain .md files as the entire note store. The README calls it local-first and says it 'does not sign in to WebDAV or cloud-drive accounts.' For someone who already keeps files in iCloud Drive, Nutstore, or Dropbox, this means notes are just files, readable by any tool that can handle Markdown. The intended user is a macOS writer or note-taker who wants speed and simplicity, not a team looking for shared editing. The description 'Lightweight Markdown app to help you write great sentences' fits that solo-writing profile. The trade-off is clear from the start: you bring your own sync, and you accept that collaboration is out of scope.

The Mechanism: Files as the Source of Truth

The core architecture is visible in the storage model. After installation, you create a MiaoYan folder in iCloud Drive, a desktop cloud-drive folder, or any location you prefer, then open Preferences (⌘,) and set the storage path. The app reads and writes that folder directly. There is no import step, no vault format, no hidden database. The README's folder check adds a concrete safeguard: 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 for a local-first app, since a broken path would otherwise leave you typing into a void. The split editor and preview mode uses a 60fps bidirectional scroll sync, which is a specific performance claim, though the README does not explain how it is implemented. The parser is swift-cmark-gfm, per the acknowledgments, so GFM compatibility is a reasonable expectation, but the README does not detail which GFM extensions are active.

Getting It Running: Three Install Paths and a CLI

There are three install options, and they all share the same codebase. The Mac App Store version is paid and includes automatic updates. Homebrew users can run 'brew install --cask miaoyan'. GitHub Releases offers a DMG for macOS 11.5 and later. The README does not specify the price or whether the App Store version has a free trial, so that is a gap to verify. The CLI is a separate install: 'curl -fsSL https://raw.githubusercontent.com/tw93/MiaoYan/main/scripts/install.sh | bash'. It provides commands like 'miao open <title|path>', 'miao new <title> [text]', 'miao search <query>', 'miao list [folder]', 'miao cat <title|path>', and 'miao update'. This is a real productivity hook for terminal users, but the README does not say whether the CLI is bundled with the app or installed independently, nor does it mention any dependencies. The install script is a raw curl-pipe-to-bash, which some users will want to inspect before running.

Sync Without an Account: The Cloud-Folder Pattern

MiaoYan's sync strategy is to delegate to an external cloud client. On Mac, you create a MiaoYan folder inside the local folder synced by Nutstore, Dropbox, or iCloud Drive, then point MiaoYan at it. On iPhone, you pick the same folder from the system Files app. The README adds a caveat: 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 app first. This is a real constraint. Not all cloud providers expose a writable folder to the Files app, and the README does not list which providers work beyond the named ones. The folder check before switching is a good guard, but it does not solve the deeper issue: if the cloud client pauses sync or the folder becomes unavailable, MiaoYan will not switch paths, and you may be stuck with the old location. For a single user with one Mac and one iPhone, this pattern is workable. For anyone expecting seamless multi-device sync, the README's instructions show that the burden is on the user to configure the cloud client correctly.

Where MiaoYan Is the Wrong Tool

The README is explicit about one limitation: no WYSIWYG editing. The authors say implementing WYSIWYG in native Swift is 'overly complex with reliability concerns,' so they chose split mode. That is an honest trade-off, but it means users coming from Typora or Notion will find the editing experience different. More importantly, MiaoYan has no built-in sync, no real-time collaboration, and no mobile app of its own. The iPhone is only supported through the Files app, which is a second-class experience for quick capture. The CLI helps, but it is terminal-only and not mentioned for iOS. So the wrong tool is anyone who needs to edit the same note from multiple devices with low friction, or who wants a live preview that feels like a word processor. Also, the README mentions 'version history' as a feature, but it does not explain how it works. Is it Git-based, or does the app keep snapshots? Without that detail, users who rely on version history should test it before trusting it.

Alternatives and the Real Difference in Approach

The obvious alternative is Obsidian, which also works on local Markdown files. The difference is in the sync model and extensibility. Obsidian has a paid sync service that handles end-to-end encrypted sync across devices, and it supports plugins that can add WYSIWYG-like editing, backlinks, and a mobile app that feels native. MiaoYan, by contrast, has no sync service and no plugin system. Its backlinks are wikilink-based, similar to Obsidian's, but the README does not mention a graph view or a plugin API. Another alternative is Typora, which offers WYSIWYG editing but is not open source and does not have a CLI. The README explicitly positions MiaoYan against Typora by explaining why it chose split mode. So the real difference is that MiaoYan is a narrower tool: it does one thing, Markdown editing with a few advanced features, and leaves sync and extensibility to the user. For someone who wants a minimal, fast editor without the Obsidian ecosystem, MiaoYan fits. For someone who wants plugins or a polished mobile experience, it does not.

Maintenance and License Costs

The project is MIT licensed, which is permissive and allows commercial use and modification. The README includes a support section that promotes the author's paid app Mole, and a cat-feeding page, which suggests the project is maintained by a single person. The last push was August 2026, and the release cadence shows three versions in three months, so the project is actively maintained. However, the README does not list a roadmap or a contribution guide. The acknowledgments list several upstream libraries, including swift-cmark-gfm and Prettier, which means the project depends on external code for parsing and formatting. Upgrade cost is low for users because the App Store version auto-updates, but Homebrew and DMG users must manually update. The CLI has its own update command, 'miao update', which is a small convenience. The main maintenance risk is bus factor: if the author stops, the project may stagnate. The MIT license at least allows forking, but the README does not mention any governance or community process. For a solo project, that is a typical but real consideration.

Editorial conclusion

Adopt MiaoYan if you want a fast, native Markdown editor that treats notes as plain files and you already manage sync through iCloud Drive, Nutstore, or Dropbox. Do not adopt it if you need real-time collaboration, a WYSIWYG editing mode, or a built-in sync service, because MiaoYan deliberately has none of those. Before committing, verify that your chosen cloud folder is writable from the Files app on iPhone, and test the CLI on your macOS version, since the README only guarantees macOS 11.5+ for the DMG. Also check the App Store version's paid status if you prefer automatic updates over Homebrew or GitHub releases.

Official sources

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