Markdown Buddy › Markdown preview in Xcode
Markdown preview in Xcode
Xcode shows Markdown files as plain source. For a README, a CHANGELOG or an architecture note, that means reading the markup instead of the document. Markdown Buddy ships a native Source Editor extension: from the Editor menu, the file you are looking at opens rendered, without leaving your project.
Installing the extension
- Install Markdown Buddy from the Mac App Store and launch it once, so macOS registers the extension it carries.
- Open System Settings, go to General then Login Items and Extensions, and enable Markdown Buddy under Xcode Source Editor.
- Restart Xcode. Extensions are read at launch, so a running Xcode will not see a freshly enabled one.
- Open a .md file, then use Editor then Markdown Buddy. You can bind a keyboard shortcut in Xcode settings, under Key Bindings.
Why it matters on a repository
Project documentation lives next to the code, and it is the code editor that shows it worst:
- A README with tables and badges is unreadable as raw source
- A CHANGELOG is a long nested list, where indentation carries the meaning
- An architecture note often holds Mermaid diagrams, which Xcode renders as fenced text
- Relative links between documents cannot be followed from the source view
Beyond the extension
The same app opens a whole folder as a workspace, searches across every .md file in it, and draws the graph of links between your documents while flagging the broken ones. On a repository whose documentation has grown, that is often more useful than the preview itself.
If the command does not appear in the Editor menu
- Check that the extension is enabled in System Settings, under General, Login Items and Extensions, section Xcode Source Editor.
- Quit Xcode completely and relaunch it. The list of extensions is only read at startup.
- Launch Markdown Buddy once from the Applications folder, then try again.
- The command only shows up when the frontmost document is a Markdown file. On a .swift file, it stays hidden.
Common questions
Does it modify my project?
No. The extension only reads the document currently open in the editor, and opens it rendered. Nothing is written to your project.
Which Xcode versions work?
Every Xcode release that supports Source Editor extensions, on macOS 14.0 and later.
Can I assign a keyboard shortcut?
Yes, in Xcode settings under Key Bindings, by searching for the extension name. Xcode handles the binding, not the extension.
Does it work on any Markdown file, or only on README.md?
Any Markdown file open in the editor, whatever its name.
Stop reading your documentation as raw source
Markdown Buddy is a one-off purchase at €5.99, with no subscription and no in-app purchase.
Get it on the Mac App Store