How to Sync Markdown Notes with iCloud Without Lock-in (2026)

To sync markdown notes with iCloud without lock-in, keep your notes as plain .md files inside a folder in iCloud Drive, then point any markdown app at that same folder. The files sync across your Macs, iPhone, and iPad through iCloud, and because they stay as plain text you can switch editors any time. No single app owns your data.

This approach to sync markdown notes iCloud trades app-specific features for portability. You give up proprietary sync magic and in exchange you get files that open in any text editor for the next 20 years. This guide walks the setup, the gotchas, and the apps that work with it.

Why iCloud Drive for markdown

iCloud Drive ships on every Mac and syncs with the iPhone and iPad you already own. The free tier gives you 5 GB, and markdown files are tiny, so a thousand notes might use a few megabytes. You add no new account, no subscription, and no third-party sync service.

The advantage is decoupling. Your notes live as .md files on disk. iCloud handles the bytes moving between devices. The editor stays interchangeable. Compare that to a database-backed app like Notion, where your content lives inside their servers and export turns into a messy conversion. Plain files in iCloud Drive keep the format durable regardless of which tool you open them with.

What you need

• A Mac with iCloud Drive turned on (System Settings, your name, iCloud, iCloud Drive)
• A markdown editor that reads from a folder you choose, not its own private library
• A few minutes to move existing notes into place

Step 1: Create a notes folder in iCloud Drive

Open Finder and go to iCloud Drive in the sidebar. Create a folder named Notes. Its path on disk is:

~/Library/Mobile Documents/com~apple~CloudDocs/Notes

That path looks ugly because Apple hides the iCloud Drive container there. You can ignore the raw path most of the time and work through Finder, but knowing it helps when an editor asks you to pick a folder and shows the full filesystem.

Step 2: Move your .md files into the folder

Drag your existing .md files into the new Notes folder. If your notes currently live in a proprietary app, export them as markdown first. Bear and Obsidian both export to plain .md. Apple Notes does not export markdown, so you copy text out by hand or use a converter.

Once the files land in iCloud Drive, a small cloud icon appears next to ones that have not finished uploading. Wait until those icons clear before you move to the next step.

Step 3: Point your editor at the folder

Open your markdown app and set its working folder, vault, or library to the Notes folder you created. The exact wording varies:

App	Setting
Obsidian	Open folder as vault, pick Notes
iA Writer	Add Location, pick the iCloud folder
Typora	Open the folder from the file sidebar
Stik	Saves to its own folder; copy or symlink into iCloud

The app should now list every .md file in that folder. Edits write back to disk, and iCloud syncs them out.

Step 4: Verify on a second device

Open Files on your iPhone or another Mac and browse to iCloud Drive, then Notes. Your files should appear within a minute on a decent connection. Open one and edit a line. Switch back to the first Mac and confirm the change arrived. This round trip proves sync works before you trust it with real notes.

If a file does not show up, check that iCloud Drive is enabled on both devices and that neither is paused for low battery.

Step 5: Confirm conflict handling

Edit the same note on two devices while one is offline, then bring it back online. iCloud does not merge text inside a markdown file. Instead it keeps both versions, naming the second something like note 2.md. You open both, compare, and merge by hand.

This behavior is blunt but safe. You always see when a conflict happened, and you never lose either version. Apps with custom sync sometimes merge in the background and corrupt a note. For more on why file-level safety beats clever merging, see our take on local-first note apps.

Gotchas to avoid

• Optimize Mac Storage offloads files. If macOS runs low on space it may evict the bytes and leave a placeholder. An editor that scans the folder can choke on a file it cannot read yet. Keep your Notes folder small enough to stay local, or turn off offloading for it.
• Conflict copies pile up. Those note 2.md files do not clean themselves. Scan the folder now and then and merge or delete the duplicates.
• The raw folder path breaks scripts. The com~apple~CloudDocs path contains tildes that some shell scripts mishandle. Quote the path, and test any automation before you rely on it.
• Subfolders sync fine, but symlinks do not. iCloud Drive ignores symbolic links. If your editor wants a symlinked vault, that link will not survive the trip to another device.

Apps that work with this iCloud markdown setup

Any app that reads plain .md from a folder you pick will work. That rules out apps with a closed library and rules in most of the markdown editors built for Mac. Obsidian, iA Writer, and Typora all open a folder directly. For a wider survey of file-based tools, our local-first roundup covers the trade-offs.

Stik takes a narrower role. It is a free, open-source quick-capture app for macOS that saves each note as a plain .md file in ~/Documents/Stik/. Capture a thought with a global shortcut, and it lands on disk as markdown. Stik does not write into iCloud Drive itself, so you either change where you store the captures or copy them into your iCloud Notes folder. Its search runs on-device through Apple's NaturalLanguage framework with no account or cloud, which fits the same local-first idea this guide is built on. Full disclosure: I build Stik, and the code is on GitHub.

If you are still deciding between a file-based setup and a single all-in-one app, the Obsidian vs Apple Notes comparison and the markdown vs rich text breakdown both help you weigh portability against polish.

Frequently asked questions

Can I sync markdown notes with iCloud across iPhone and Mac?

Yes. Put the .md files in an iCloud Drive folder and they sync to every device signed into the same Apple ID. On iPhone you browse them in the Files app, and any iOS markdown editor that reads from Files can open them.

Does iCloud merge markdown files when two devices edit at once?

No. iCloud keeps both versions instead of merging the text, usually adding a second file like note 2.md. You open both and merge by hand, so you never lose content but you do clean up duplicates.

Is iCloud Drive sync as reliable as Obsidian Sync or Dropbox?

For plain markdown it stays dependable on a normal connection, though it can lag a minute or two and offers no conflict merging. Obsidian Sync and Dropbox add version history and faster propagation, while iCloud Drive wins on cost and zero extra setup. Pick based on whether you value built-in versioning over a free, account-free option.

What happens if iCloud offloads my notes to save space?

macOS replaces the file with a placeholder and downloads it on demand when you open it. An editor scanning the folder may fail to read an offloaded file until it downloads. Turn off Optimize Mac Storage for the notes folder, or keep the folder small enough that macOS leaves it local.

Can I use Stik notes with this iCloud setup?

Yes, with one extra step. Stik saves .md files to ~/Documents/Stik/ rather than iCloud Drive, so you copy or move those captures into your iCloud Notes folder to sync them. The files are plain markdown, so any editor on the other end opens them without conversion.