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.
This post was originally published on danielinoa.com
Top comments (6)
The easiest way to render markdown in Xcode is by using QuickLook.
qlmarkdownplugin github.com/toland/qlmarkdownOpen as>Quick lookHi,
I was using this technique but when I add the .plist in some old project and add README.md file it doesn't render it as markdown :/ Any ideas what could be it? Maybe some setting.
PS: For newer projects it works properly.
It can be used even without the .xcodesamplecode.plist
Just set the file type in File Inspector (under Identity and Type) to markdown.
It is either set automatically based on extension or you can set it here manually.
Then choose "Editor -> Syntax Coloring -> Markdown".
xcode will remember this in project settings and will keep it after project is re-opened.
Enjoy!
Just create a new plist file named .xcodesamplecode.plist, then move it under your .xcodeproj .
All is done!
I can't extract the zip file, check this please.
The link is dead unfortunately.