← All guides

Sync Markdown notes between Mac, iPad and iPhone

mrkdwn guide · Based on mrkdwn 1.5 ·

Syncing plain files is easy. The hard part is what happens when two copies of one file disagree. Most tools settle it by keeping whichever copy is newest, and whatever was in the other copy is simply gone. mrkdwn does not do that. This guide explains what it does instead, and the few habits that keep sync uneventful.

Where your notes sync through

mrkdwn has no sync server of its own. Your library is a folder, and when that folder is in iCloud Drive it appears as a folder named mrkdwn. Apple moves the files between your devices, and you can see them in Finder on the Mac and in the Files app on iPhone and iPad.

Because it is your iCloud account, there is no mrkdwn account to create and no second copy of your notes on anyone else’s servers. If you want a folder to stay on one device, you can choose which folders sync.

What mrkdwn adds on top of iCloud Drive

On its own, iCloud Drive moves files. When two devices change the same file before either has synced, it keeps both versions and leaves you to work out which is which. mrkdwn adds a sync engine over the files that does three things:

  • Three-way merge. It remembers what the note looked like when your devices last agreed, and compares each device’s edits with that. Edits to different parts of a note merge cleanly on their own.
  • Notes that follow the file. A note created on your iPhone shows up as a note on your Mac, not just as a file in the folder.
  • Deletions that travel. Delete a note on one device and the deletion reaches the others, instead of the next sync bringing it back.

What a conflict looks like

When two devices change the same passage, a merge cannot know which version you meant. So mrkdwn keeps both, marked the way git marks them:

The bread needs a long, cold rise.
<<<<<<< This Device
Shape it the night before and bake straight from the fridge.
=======
Shape it in the morning and give it an hour on the counter.
>>>>>>> Other Device
Score it just before it goes in.

Keep the line you want, delete the other and the three marker lines, and the conflict is resolved. It is plain text, so you can do this in mrkdwn or in any other editor.

Two copies of a sentence can look untidy, but nothing was lost. The tools that never show a conflict marker are usually the ones that dropped one side without telling you.

Stay out of conflicts

Conflicts only happen when two devices edit the same note before either has synced. A few habits make them rare:

  • Let a note settle before you switch devices. Sync status indicators show whether your changes have gone up. Give them a moment when you have just finished a long edit on one device.
  • Split long working notes. Two devices editing different notes never conflict. A single huge running document is where edits from the phone and the Mac are most likely to meet.
  • Use daily notes for capture on the go. Jot things on the phone into today’s daily note, and do the heavier editing somewhere else. They are different files, so they cannot collide.

When something goes wrong anyway

Every note has a version history: a 30-day timeline with word-level diffs, synced between your devices. Restoring an old version does not throw away the current one, so you can go back to see what a paragraph used to say, take what you need, and carry on.

Two other safety nets are worth knowing about. Deleted notes go to a trash you can recover from. And when iCloud frees up space on a device by evicting a file (leaving a placeholder until it is needed), mrkdwn treats that note as still there. It is not moved to the trash.

What stays on each device

A few things are deliberately local to each device:

  • AI keys. A Claude API key is stored in that device’s Keychain. It is not synced and not included in backups, so a key you add on the Mac does not appear on your iPhone.
  • Folder layout. Which folders you have expanded in the sidebar is remembered per device.

The notes themselves, their version history and their authorship marks all travel.

Where to go next

mrkdwn is on the App Store for iPhone and iPad. The Mac app is still in pre-release testing. See where each platform stands.