MiaoYan puts a Markdown folder on your Mac and makes you assemble the sync yourself

Two builds under one name, and only one of them grows

MiaoYan reaches you through three doors, and they do not deliver the same product. The Mac App Store edition is paid, updates itself, and bundles the iPhone and iPad app. The Homebrew cask installs a separate open-source build, and the DMG on GitHub Releases gives you the same open-source build for macOS 12.0 or later. The README says Homebrew and GitHub Releases install the same free, open-source Mac app, which keeps being developed.

The practical consequence is a choice at install time. Anyone who reaches for the cask gets the free Mac app but not the mobile apps. Anyone who wants the iPhone and iPad app has to buy the App Store edition, which the README recommends: one purchase covers iPhone, iPad and Mac, all opening the same iCloud Drive folder, with automatic updates.

The repository is still moving. The last push is dated 2026-11-02, and V4.6.0 shipped 2026-10-26, after V4.5.0 on 2026-09-25 and V4.3.2 on 2026-09-20. Each release carries a name, Lagiacrus, Nargacuga, Seregios, so the versions you can trace in the releases list are not just numbers.

MiaoYan never signs in, so sync is a folder you assemble by hand

There is no account, no WebDAV login, and no OAuth handshake anywhere in the design. MiaoYan is local-first and does not sign in to WebDAV or cloud-drive accounts. It reads and writes one Markdown folder that you choose, and cross-device sync is somebody else's job. iCloud Drive, Nutstore, Dropbox, or another cloud-drive client handles it.

That means the folder has to exist in two places, and you are the one who wires them together. On a Mac, the documented path is to create a `MiaoYan` folder inside the local folder that the Nutstore desktop client is already syncing, then point MiaoYan's storage location at it in Preferences. On an iPhone, you pick the same cloud-drive folder from the system Files app.

Here is the failure mode to plan around. MiaoYan has no view of which folders your cloud client is watching, so it cannot warn you that you aimed storage at a directory the client ignores. If you pick a plausible-looking folder outside the synced tree, MiaoYan will keep writing there happily, every note lands on the Mac only, and the two devices drift apart with no error message. Verification of the path is on you.

The folder check fails quietly and keeps your old storage path

Before MiaoYan switches storage folders it verifies read and write access. If the folder is unavailable, the current storage path stays unchanged. The README says the problem is not reported as a MiaoYan sync failure.

This is the right default for a note app, and it is also the setting most likely to confuse a new user. Consider the iPhone case the project calls out: if a provider does not expose a writable folder in Files, you are told to use iCloud Drive, or to make the folder available offline in that provider's own app before choosing it. Skip that step and the folder check keeps your previous storage path.

The consequence is that a failed folder switch is not reported as a sync failure. If you are scripting an onboarding flow, or migrating a machine to a new cloud drive, verify the path after the switch rather than assuming the switch took effect.

First launch is create a folder, then set the path in Preferences

After installing, you create a `MiaoYan` folder in iCloud Drive, in a desktop cloud-drive folder, or wherever you prefer, then open Preferences (⌘,) and point the app at it.

The Homebrew cask is the shortest route on a Mac:

brew install --cask miaoyan

The GitHub Releases route is a manual DMG download and needs macOS 12.0 or later, which is a real constraint if you keep older Macs around. The App Store route costs money, updates without you thinking about it, and is the only one that includes the iPhone and iPad app.

For a first run, pick the Homebrew cask or the App Store edition, create the folder before opening the app for real work, and set the path once in Preferences. The storage path is the only setup the README asks for, which is a smaller setup than editors that ask you to choose a sync backend, an account, and a vault structure before you can type a sentence.

Split view is a keystroke away, and WYSIWYG is a decision, not a gap

The editor and preview sit side by side with real-time preview and 60fps scroll sync. Toggling it is `⌘\`, or you can make it the default in Preferences by going to Editor and setting Default Mode to Split. That is the whole visual feedback story: a raw Markdown pane on one side, the rendered result on the other, scrolling in step.

There will be no inline WYSIWYG formatting, and the reasoning is written down rather than left to guesswork. The author asks why not WYSIWYG like Typora and answers that pure Markdown editing is the priority, and that implementing WYSIWYG in native Swift is overly complex with reliability concerns. Split mode is presented as the compromise that keeps editing clean while still giving instant visual feedback.

For a reader, that means you always see the actual syntax you are typing, including link targets, LaTeX delimiters, and Mermaid blocks, and you can fix a broken construct by editing the characters rather than hunting for a toolbar button that no longer applies. If your habits come from a rendered editor where you never see markup, the first few sessions will feel slower, because nothing is hidden and nothing is abstracted away.

Six miao verbs, installed by piping a remote script into bash

A separate command-line interface handles quick note operations, and it installs on its own, apart from the app:

# 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 the Markdown files in a folder
miao cat <title|path>     # Print note content
miao update               # Update CLI

Read the verb list as a boundary. The interface opens, creates, searches, lists, prints, and updates itself. Nothing in that list renames a note, moves one between folders, or deletes one, so destructive or reorganizing changes still belong to the app or to a file manager. And `miao update` refreshes the CLI only, which means your terminal tooling and the Mac app can sit at different versions without any warning.

Also note how the install works: a fetched script is piped straight into bash, with no checksum, no review step, and no package manager in the loop. That is the documented path, so if you lock down machines where that pattern is blocked by policy, you will need to fetch and inspect the script yourself before running it.

Rendering is assembled from four acknowledged open-source projects

The acknowledgments section names where the heavy lifting comes from: glushchenko/fsnotes as the initial project structure reference, stackotter/swift-cmark-gfm as the Swift Markdown parser, simonbs/Prettier for Markdown formatting utilities, raspu/Highlightr for syntax highlighting, and hakimel/reveal.js as the presentation framework. MiaoYan is the native shell around that stack, and the repository keeps `Package.swift` and `Package.resolved` at the top level for it.

On top of the parser sit the features the description advertises: wikilinks, LaTeX, Mermaid, version history, auto-formatting, and PPT presentations, presented as folders, notes, and editor in three columns, with dark mode and no plugin system to maintain. The stated advantage is being lighter than web wrappers, attributed to being built natively with Swift 6.

The layout of the tree shows how the code is organized: `Controllers/`, `Views/`, `Helpers/`, `Extensions/`, and `Resources/` alongside `MiaoYan.xcodeproj/`, `MiaoYanTests/`, `Info.plist`, and `MiaoYan.entitlements`, plus `ARCHITECTURE.md`, `AGENTS.md`, `DEPENDENCIES.md`, `.swiftlint.yml`, and `.swift-format`. Two consequences for contributors: there is a test target and a lint configuration, and a separate `Business/` directory sits apart from the UI directories, which is worth reading before you change behavior that looks presentation-level but is not.

Slides are three dashes, and an agent skill carries the syntax

Presentation mode is built on the `---` slide separator, and the guide for using it is a document in the repository, `Resources/Initial/MiaoYan PPT.md`. The full Markdown reference, including the advanced features, lives beside it as `MiaoYan Markdown Syntax Guide.md`. Both are files in the source tree rather than a hosted manual, so the documentation version is tied to whatever release you have rather than to a website that can change under you.

There is also a MiaoYan Agent Skill under `skills/miaoyan` that teaches an agent MiaoYan syntax, attachments, PPT patterns, and CLI workflows, installed with:

npx skills add tw93/MiaoYan/skills/miaoyan -g

What this does not give you is a WYSIWYG slide editor. Slides are Markdown separated by three dashes and rendered through reveal.js, so layout, ordering, and styling are decided by the markup and the framework, not by dragging boxes. The same split shows up in attachments and syntax: the skill exists so a language model writes MiaoYan-flavored Markdown correctly, which is a strong hint that hand-editing wikilink targets and slide breaks is the expected workflow.

Editorial conclusion

MiaoYan fits a reader who wants a small, local-first Markdown folder on a Mac and is willing to assemble cloud sync from a separate client. Pass on it if you need a WYSIWYG editor or cloud synchronization handled inside the app itself. Before installing from Homebrew, note that it does not include the iPhone and iPad app, and confirm the storage folder you pick in Preferences is the same folder your cloud client is actually watching.

Frequently asked questions

Official sources

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