Keep straight quotes in Markdown and code on Mac

You're writing docs in Markdown, drop a fenced code block or a bit of YAML front matter, and macOS "helpfully" curls your quotes and turns -- into an en-dash — so the parser chokes and your rendered page shows the wrong characters. The fix is to switch off smart quotes and smart dashes, in System Settings → Keyboard → Text Input → Edit or with a quick defaults write, so every mark stays exactly as you typed it.

Keep quotes and dashes literal

1. Open System Settings → Keyboard.
2. In the Text Input section, click Edit….
3. Turn off Use smart quotes and dashes.
4. Click Done.

Quotes and dashes are the two conversions that ruin Markdown; both live under that single checkbox in Settings, and under two keys in Terminal:

# straight quotes: "key" stays "key", not curly
defaults write NSGlobalDomain NSAutomaticQuoteSubstitutionEnabled -bool false
# literal hyphens: -- stays --, not an en-dash
defaults write NSGlobalDomain NSAutomaticDashSubstitutionEnabled -bool false

# undo — re-enable both
defaults delete NSGlobalDomain NSAutomaticQuoteSubstitutionEnabled
defaults delete NSGlobalDomain NSAutomaticDashSubstitutionEnabled

No logout is needed; relaunch the app you're writing in so it re-reads the setting. This works the same on macOS 13 Ventura, 14 Sonoma, and 15 Sequoia.

Why Markdown specifically hates curly quotes

Prose is forgiving about typographic quotes; structured text is not. In a Markdown or docs workflow the damage is concrete:

• YAML front matter — title: "My Post" needs straight quotes; a curly one is not a valid string delimiter and the build fails.
• Link and image titles — [text](url "title") silently breaks when the quotes curl.
• Inline command examples — a documented --flag that becomes –flag is now wrong for every reader who copies it.
• Code fences — quotes inside a fenced block should render verbatim, and a curly quote pasted from elsewhere stands out as a bug.

Turning the setting off keeps what you type identical to what ships. When you genuinely want a real dash in prose, our guide to typing an em dash on Mac shows the deliberate keystroke.

Write in a plain-text editor too

Even a plain-text editor applies the system smart-quote setting, so turning it off globally is what actually fixes this — but a plain-text default keeps other rich-text surprises out of your notes. See how to make TextEdit default to plain text on Mac to pair with the change above.