📜 Rendering Markdown in Xcode 9

Recently while exploring Apple’s new sample projects for iOS 11, I stumbled upon this sample ARKit project. Aside from the cool ARKit stuff going on, I saw how the README.md would actually get rendered.

This has been possible in Playgrounds for a while but never in an actual Xcode project, until now. This markdown rendition is different from the one advertised, where the Markdown is partially rendered and the syntax is included (see image below).

After some “extensive” research and excavation I found that .xcodesamplecode.plist is what triggers Xcode to render the Markdown as seen in their sample. This file can be found under the .xcodeproj (within Package Contents).

It seems Apple intended for Markdown files to be rendered only if they are under a sample project. Ideally there would be a way to toggle when it renders, similar to Playgrounds, but for now the simplest way is to drop the .xcodesamplecode.plist file under your .xcodeproj project. After dropping .xcodesamplecode.plist under the TestProject.xcodeproject I created it now renders the Markdown as expected. Download .xcodesamplecode.plist here.

TADA!!!

I think having renderable README.md files within Xcode could go a long way in helping make large projects easier to document and unpack, without the need to have external Markdown renderers. In addition to code comments this could greatly improve discoverability for new people coming into your project, as long as your project is well structured.

Thanks for reading!

Questions about any of this? Ask me on Twitter or email.