Readme markdown not rendering in Xcode

Question

Created Oct ’19

Replies 13

Boosts 0

Views 17k

Participants 15

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).

Boost

Answer 1

callenordangard OP

Nov ’19

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.

0

Answer 2

InstantInteractive OP

Nov ’19

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

0

Answer 3

MCStoufer_veeva OP

Nov ’19

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!

4

Answer 4

bmorrison OP

Jan ’20

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.

1

Answer 5

thinking-out OP

Feb ’21

It's not rendering for me either in XC 12.4. MCSToufer's hack works on a project by project basis.

1

Answer 6

stuffmc OP

Oct ’21

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

1

Answer 7

asadchattha OP

Jan ’22

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.

3

Answer 8

kdeda OP

Jan ’22

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.

0

Answer 9

EA7K OP

Jan ’22

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.

2

Answer 10

O_G OP

Jan ’22

@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.

1

Answer 11

maciekish OP

May ’22

This is the droid you are looking for:

Editor > Syntax Coloring > Markdown

3

Answer 12

eldarsadykov OP

Aug ’23

@maciekish No, it's not.

4

Answer 13

juraj OP

Nov ’23

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.

0