--- title: "Syncing Markdown notes with iCloud Drive, and what can go wrong" author: Pedro Thomaz source: https://coffeetext.app/blog/sync-markdown-icloud-drive --- # Syncing Markdown notes with iCloud Drive, and what can go wrong > Checked November 2026 against Apple's guides to [storing files in iCloud Drive](https://support.apple.com/guide/mac-help/store-files-in-icloud-drive-mchle5a61431/mac), [file status](https://support.apple.com/guide/mac-help/check-icloud-drive-file-folder-status-mac-mchlc994344b/mac) and [conflicts](https://support.apple.com/guide/mac-help/document-versions-conflict-icloud-drive-mac-mh40780/mac). Coffee isn't affiliated with Apple. Put your notes folder inside iCloud Drive and iCloud does the rest, because Markdown notes are ordinary files. To stay out of trouble, keep the folder downloaded if you ever work offline, and don't edit the same note on two devices while one is disconnected. The problems to plan for are files that have been offloaded, versions that conflict, and iCloud storage that has run out. ## Setting it up [Apple's steps](https://support.apple.com/guide/mac-help/store-files-in-icloud-drive-mchle5a61431/mac) are short. Open System Settings, click your name, click iCloud, click Drive, then turn on "Sync this Mac". iCloud Drive then appears in the Finder sidebar, and you can create or move your notes folder there. Those settings also hold Optimise Mac Storage. With it on, your Mac can move older documents to iCloud when it needs more space. If space isn't needed, Apple says the full contents of iCloud Drive stay on your Mac. You can do the same with a folder inside Documents, by turning on Desktop & Documents Folders. Coffee counts a library there as being in iCloud when macOS reports it as synced. Apple warns that you may need to turn off any other app or cloud service that syncs those folders. That's good advice for any notes folder: one sync service per folder. ## What the Finder is telling you Finder shows a [status icon](https://support.apple.com/guide/mac-help/check-icloud-drive-file-folder-status-mac-mchlc994344b/mac) beside each item in iCloud Drive. These are the ones that matter for notes: | Status | What it means | What to do | |---|---|---| | In iCloud | The item is only in iCloud, and you need a connection to use it | Control-click, then Download Now | | Downloaded | Up to date on both sides, and usable with or without a connection | Nothing | | Keep Downloaded | Kept on your Mac even when space is needed | Nothing | | Waiting to Upload | Not yet stored in iCloud | Wait, and check your connection before you rely on another device | | Out of Space | There isn't enough iCloud storage left | Free up iCloud storage or buy more | | Ineligible | Couldn't be stored in iCloud, usually for going over 50 GB | Not a concern for a text note, but it could be for a large attachment | For an overall picture, hold the pointer over iCloud Drive in the Finder sidebar and click the status icon there. ## What can go wrong ### A note isn't on your Mac when you need it With Optimise Mac Storage on, older documents can be moved to iCloud when space is tight. Any of them then needs a connection, or a download first. If you open your notes on a plane, that's the moment you find out. The fix is to [keep the folder downloaded](https://support.apple.com/en-gb/guide/mac-help/mchl1a02d711/mac). Control-click your notes folder in iCloud Drive and choose Keep Downloaded. A folder of text notes takes up little room, though large attachments can change that. Remove Download reverses it if you ever need the space back. ### Two versions of the same note [Apple says conflicts](https://support.apple.com/guide/mac-help/document-versions-conflict-icloud-drive-mac-mh40780/mac) arise when you edit the same document on more than one device while they're offline. Once they reconnect, each saves its changes, and a dialog asks which versions to keep when you open the document. If you keep several, numbers are added to the names of all but the first. Versions you don't select are deleted from iCloud Drive on every device with it turned on, so look before you click. There's a full guide to [fixing conflicted copies](https://coffeetext.app/blog/fix-conflicted-copies-icloud-dropbox). ### You closed the lid too soon A note showing Waiting to Upload hasn't reached iCloud. If you close one Mac and open another straight away, you may see the older text and start editing it, which sets up the conflict above. Check the status when it matters. ### iCloud is full Apple says a file that hits this limit can't be stored in iCloud, so your other devices won't get it. The Out of Space icon is your warning, and a similar icon appears beside iCloud Drive in the sidebar. ### Two services on one folder Pointing Dropbox, a Git tool's automatic sync and iCloud at the same folder gives each of them a chance to see the others' half-finished changes. Pick one. ## What Coffee does and doesn't do Coffee has no sync of its own, and there's no Coffee server for your notes to travel through. If your library is in iCloud Drive, Apple is doing all the syncing, and Coffee is an app reading and writing files in a folder. **Choosing iCloud Drive.** When the iCloud Drive folder exists on your Mac, Coffee offers it the first time you run it, and uses a folder called Coffee inside it. Settings has a Use iCloud Drive button that moves an existing library there. The move never overwrites anything: a clash gets a new name. If it stops partway, each file is in one place or the other, and Coffee tells you to check both. **Offloaded notes.** When a library opens, Coffee looks for notes iCloud has offloaded, and asks iCloud to download each one. It knows both forms: a file keeping its own name with its contents gone, which is what recent macOS does, and the hidden placeholder older systems leave. That's a request made once, and Coffee doesn't report on its progress. A note that's still in iCloud is only readable once it arrives, so Keep Downloaded is still the better choice if you work offline. **Sync status.** Coffee shows whether your library is in iCloud Drive or on this Mac, but not whether a file has finished uploading. Finder is the place to look for that. **Changes arriving while you work.** Coffee watches the folder for changes. Before each save, it also compares the file on disk with what it last read. If they differ, it sets the other text aside in a copy named `Your note (conflict).md` instead of overwriting it, and tells you another version was kept. **Conflicts.** For a note in iCloud Drive, Coffee reads iCloud's unresolved versions and shows them in its own "Two versions of this note" panel, along with numbered copies whose title heading still matches. You choose, nothing is merged, and the version you don't keep goes to the Trash rather than vanishing. **Renames on another Mac.** If a note you have open is renamed elsewhere and arrives by sync as a new file, Coffee follows it when the new file's text is identical. If the text has changed too, it can't tell they're the same note. **What stays on one Mac.** Version history, the search index and Spotlight's index are all kept on each Mac, outside your notes folder. They don't travel with your files, so a second Mac starts its own history for a note. **Private notes.** A locked note syncs as an encrypted file, which is what protects it from someone who has the synced folder without the key. The key doesn't travel through iCloud Keychain, so a second Mac needs your recovery key before it can open the note. The file name, size and dates aren't hidden. More detail is in the guide to [private notes](https://coffeetext.app/blog/password-protect-notes-mac). **Other devices.** Coffee runs on a Mac only, with macOS 15 or later. Your files can still reach other devices through iCloud Drive, but opening them there needs a different app. I'm describing what Coffee is built to do here, and iCloud's timing is Apple's to decide. Keep a backup you don't depend on sync for, such as Time Machine, whichever editor you use. ## Questions ### Can I use iCloud Drive to sync Markdown files? Yes. Markdown notes are ordinary files, so any folder in iCloud Drive syncs them. You don't need anything specific to Markdown. ### Why does Finder show a note as In iCloud? It's stored only in iCloud at the moment. Control-click it and choose Download Now to bring it back, or choose Keep Downloaded on the folder to stop it happening again. ### Should I turn off Optimise Mac Storage for my notes? You don't have to. Choosing Keep Downloaded on your notes folder keeps those files on your Mac even with the option on. ### Does Coffee sync my notes? No. Coffee has no sync of its own. It works on a folder, and iCloud Drive or a similar service moves the files between devices. ### What happens if I edit the same note on two Macs? iCloud may hold two versions until you choose. In Coffee, they appear in a panel where you can compare them and keep one, and the other goes to the Trash. --- Written by Pedro Thomaz, who makes Coffee, a Markdown editor for the Mac on macOS 15 or later. It's free for 14 days with no card or account, then €3 a month, €29 a year, or €79 once with two years of updates. More at https://coffeetext.app/llms-full.txt