Readme markdown not rendering in Xcode

In Xcode 11.1, I created a 'README.md' markdown file, but it always renders as its raw text (yet font size changes depending on header level). For example, in Xcode's editor I see:


# AppName

## Version
1.0


Where the first line is in a larger font size than the lines 3 and 4.


Anyhow, if I open up a project from Apple (e.g. BuildingCustomViewsInSwiftUI), it's README renders correctly.


If I paste my project's contents into Apple's sample project README, it then renders a-ok. The reverse though (taking the contents from Apple's sample and pasting into my project; even dragging in the original project) won't render it (I then see all the markup symbols such as #.


I've checked every possible setting between the two projects and cannot figure out why this is happening. The type of file (markdown), encoding, etc. are identical.


However, one item I have noticed is that in Apple's sample project, when I view the README.md file, the Editor | Minimap menu choice is disabled and unchecked. Whereas in my project, the menu choice is enabled. Toggling that on/off though has no effect in my project.


Thus, there must be some reason why Apple's sample has the Minimap option disabled. And my guess is this is the reason why Apple's sample in then rendering the markdown file correctliy in the editor.


Anyone know how to fix this?


Note: I also viewed the contents of the various files under the .xcodeproj package and couldn't find anything useful (i.e.. I was hoping to find some settings difference regarding the readme file, but couldn't find any).

Up vote post of InstantInteractive Down vote post of InstantInteractive
15k views
Posted by
InstantInteractive
Reply
Add a Comment

Replies

Seems as if the command Editor > Show Rendered Markup is missing from the menus in Xcode 11. I believe that was the way to switch between raw and renderd markup in earlier verisions.


Curiously there is still the possibility to set a key binding to the command, but that is unfortunately no workaround since the command is missing from the menus.

Posted by
callenordangard
Up vote reply of callenordangard Down vote reply of callenordangard
Add a Comment

Ah, thanks. Didn't know that menu item once existed. Bug filed: FB7440240

Posted by
InstantInteractive
Up vote reply of InstantInteractive Down vote reply of InstantInteractive
Add a Comment

Place the .xcodesamplecode.plist in your foo.xcworkspace directory if you have a workspace named foo. If you are just working with a project, place it in your foo.xcodeproj dir.


The content should be:

<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <array/> </plist>

As soon as I did that, Xcode 11 immediately rendered my README file. It looked quite good too.


I did not need to tweak the display mode for that file.

Unfortunatley, local file navigation does not work, but external links do and the default browser in your system immediately navigates to them in a new tab. This content is also readonly, so I have to use MacDown to edit externally. Thankfully, saving the file immediately causes Xcode to re-render the new content.


Good luck!

Posted by
MCStoufer_veeva
Post not yet marked as solved Up vote reply of MCStoufer_veeva Down vote reply of MCStoufer_veeva

  • Unfortunately this works like a charm. I said unfortunately, because we shouldn't have to apply this trick, Xcode 12. Thanks for sharing

    —
    alejandro171
Add a Comment

As MCStoufer_veeva said, adding .xcodesamplecode.plist to the correct location will cause the read-only markup to render. My solution is to create a README.playground for the project. Then, Show Rendered/Raw Markup menu/key commands work in the playground editor.

Posted by
bmorrison
Post not yet marked as solved Up vote reply of bmorrison Down vote reply of bmorrison
Add a Comment
It's not rendering for me either in XC 12.4. MCSToufer's hack works on a project by project basis.
Posted by
thinking-out
Post not yet marked as solved Up vote reply of thinking-out Down vote reply of thinking-out
Add a Comment

This is insane. I remember that from back then and now I wonder how to do exactly that in Xcode 13. Wow.

Posted by
stuffmc
Post not yet marked as solved Up vote reply of stuffmc Down vote reply of stuffmc
Add a Comment

In Xcode .md files may show as editing mode. To show in formatted mode(design mode, as shown in GitHub), open Terminal and navigate to projects’ projectName.xcodeproj directory and create .xcodesamplecode.plist file using touch command touch .xcodesamplecode.plist. Then open the file in Xcode and it will be shown in markdown format.

It will restrict editing all .md files. For enabling editing, navigate to the same directory and use the terminal command ls -a to see if it exists then delete it using rm .xcodesamplecode.plist. You'll be reverted to a non-formatted version of .md files.

I hope this will help you.

Posted by
asadchattha
Post not yet marked as solved Up vote reply of asadchattha Down vote reply of asadchattha
Add a Comment

Really ? Why did apple make this so hard. I remember there used to be a menu on Xcode to switch this feature on and off. I guess we need to use 3rd party markdown editors.

Posted by
kdeda
Up vote reply of kdeda Down vote reply of kdeda
Add a Comment

This is pathetic. I can't find a single way to render markdown on the Mac. Not even a Safari extension or in TextEdit. There are plenty of editors on the App Store that can do it, but not what I want.

Apple is promoting Swift Package Manager, so there really is no excuse.

Posted by
EA7K
Post not yet marked as solved Up vote reply of EA7K Down vote reply of EA7K
Add a Comment

@EA7K

All we can do is file FB tickets and pester our WWDR reps about them if they don't get addressed.

The squeaky wheel gets grease.

Posted by
O_G
Post not yet marked as solved Up vote reply of O_G Down vote reply of O_G
Add a Comment

This is the droid you are looking for:

Editor > Syntax Coloring > Markdown

Posted by
maciekish
Post not yet marked as solved Up vote reply of maciekish Down vote reply of maciekish

  • Thanks. This is definitely the droid I was looking for! 🤖

    —
    maninvan
Add a Comment

@maciekish No, it's not.

Posted by
eldarsadykov
Post not yet marked as solved Up vote reply of eldarsadykov Down vote reply of eldarsadykov
Add a Comment

The hack with .plist file I saw in one of the apple's examples. I was wondering how they did it. Unfortunately it is not usable for any other md files. It is good for readme.md only.

Posted by
juraj
Up vote reply of juraj Down vote reply of juraj
Add a Comment