miaomiao-notes

---

Why another notes app?

Because your notes should be files, not someone else's database.

• Three-column layout borrowed from Apple Notes: folders → notes → content
• Every note is a plain .md file inside iCloud Drive, so it syncs across your Macs for free
• No account, no server, no subscription — completely free, no sign-up
• A deliberately small, warm UI — one carefully made theme instead of twenty mediocre ones

Features

Area	What you get
Layout	Folder column, note column, editor — native macOS chrome; position, size, zoom and fullscreen are remembered across relaunches
Editing	CodeMirror 6, Markdown syntax highlighting, colored code blocks / inline code / list markers, one-click line wrapping for every code block in the preview, live preview (⌘E), five macOS body fonts (PingFang, Songti, Kaiti, Yuanti, Hiragino)
Storage	Plain .md files; iCloud Drive when available, otherwise ~/Documents
Sync	macOS iCloud Drive, no extra service
Safety	Atomic writes, .trash soft delete, iCloud conflict detection
Interface	Chinese / English and light / dark, with two one-click icon buttons in the editor header; settings take effect instantly and save themselves
Updates	Manual check in Settings, plus one silent check per day

Requirements

• macOS 12 or later (Apple Silicon or Intel)
• iCloud Drive is optional — without it the library lives in ~/Documents/MiaomiaoNotes

Install

Download the latest build from notes.wordtk.com, open the dmg and drag the app into Applications.

The build is ad-hoc signed, not notarised, so the first launch needs a right click → Open. After that it starts normally.

Development

npm install
npm run dev      # Vite + Electron with hot reload
npm run start    # build once, then launch Electron
npm run dist     # package macOS dmg for arm64 and x64 (prunes stale artifacts)
npm run clean    # keep only the current version in release/

The public origin lives in exactly one file: site/site.config.json (siteUrl). It is committed on purpose — a public origin is an identifier, not a secret — so a clone builds the real site and app with no setup. Everything that needs the domain reads that one value: canonical links, Open Graph URLs, the sitemap, robots.txt, and the origin baked into the app bundle for Check for updates.

Forks override it without touching files by setting SITE_URL in the environment (or in a local, git-ignored .env):

SITE_URL=https://your-site.example npm run dist
[email protected]   # optional: mail entry in the developer panel, hidden when unset

npm run dist refuses to build when no origin is known, so a release can never ship a dead update checker.

The check itself uses a 15s timeout plus one retry and pins the DNS result order to ipv4first: on slow dual-stack networks an AAAA record is often a blackhole — Chromium falls back to IPv4 via Happy Eyeballs while Node's fetch waits for the timeout, which reads as "the browser opens the site, the app cannot check". A failure now also says why (no site configured / network unreachable / server error) instead of one generic sentence.

Where notes live

~/Library/Mobile Documents/com~apple~CloudDocs/MiaomiaoNotes/   # iCloud available
~/Documents/MiaomiaoNotes/                                      # fallback

The path is resolved once on first launch and stored in Settings, so signing into iCloud later never moves your library. You can change it at any time under Settings → Storage, which switches the pointer without moving or deleting files.

iCloud conflicts

iCloud sync is eventually consistent. If the same note is edited on two Macs before syncing, iCloud creates a copy like 笔记 2.md. Miaomiao Notes:

• detects those copies before and after each write
• shows a warning banner in the editor
• never merges automatically — silent merging loses data more often than it saves it

Privacy

• The app sends one anonymous launch signal (a random device id) and nothing else
• No IP, no user agent, no hardware details are stored
• The toggle lives in Settings → Behaviour → Anonymous usage
• The website has no analytics, no ads, no cookies and no third-party requests

Architecture

electron/       Main process: window, vault paths, file IO, native menu, IPC
src/            Renderer: three-column UI, CodeMirror editor, Markdown preview
src/styles/     Design tokens and theme (a new theme is one [data-theme] block)
build/          App icon sources (PNG + generated icns)
site/           Official site: Cloudflare Worker plus static assets

The renderer never touches the filesystem directly — everything goes through a narrow contextBridge surface with contextIsolation and sandbox enabled.

License

Dual-licensed:

• Open source — AGPL-3.0-only. Free to use, modify and self-host. If you distribute a modified version, or expose it as a network service, the AGPL requires you to publish the corresponding source as well.
• Commercial — if AGPL does not fit your product (for example, you want to ship a closed-source derivative), a commercial license is available. Contact [email protected].

The name "喵喵笔记 / Miaomiao Notes" and the cat icon are not covered by the open-source grant.