一只喵喵的本地 Markdown 笔记应用
A cute, local-first Markdown notes app for macOS
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
.mdfile 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
| 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 |
- macOS 12 or later (Apple Silicon or Intel)
- iCloud Drive is optional — without it the library lives in
~/Documents/MiaomiaoNotes
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.
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/Add a .env at the repo root before packaging so the in-app Check for updates
and the anonymous launch ping know where the site lives (the file is git-ignored,
so the production domain never enters the repo):
SITE_URL=https://your-site.example
CONTACT_EMAIL=you@example.com # optional: mail entry in the developer panel, hidden when unsetnpm run dist refuses to build without it, 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.
~/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 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
- 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
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.
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 hello@wordtk.com.
The name "喵喵笔记 / Miaomiao Notes" and the cat icon are not covered by the open-source grant.