Markdown editor documentation
This article contains some information about the Contentful Markdown editor which is not immediately obvious from the user interface and common sense. Specifically, it explains the keyboard shortcuts, links organization, media embedding and HTML rendering.
Use keyboard shortcuts
The time and effort required for learning shortcuts generally pays off: you can get things done quicker, because keyboard is more comfortable to use than a mouse or a trackpad.
Here are the shortcuts supported by the editor. If you're on Windows, press Ctrl instead of Cmd.
Cmd+Z - Undo
Cmd+R - Redo
Cmd+B - Make text bold
Cmd+I - Make text italic
Tab - Indent text
Shift+Tab - Unindent text
Esc - Exit full-screen mode
Keep links organized
There are two ways to have links in Markdown. The first is called inline links:
markdown inline links example
Read more [in the recent blog post](http://127.0.0.1:4567/blog/post/1/).
The URLs are placed directly inside the text. This approach works all right when you have only two or three of them, but is not that good for larger amounts of links, because it gets messy.
An alternative way is to keep a list of all the links at the end, so they would look like this:
markdown link list example (a.)
[1]: https://twitter.com/mslopatto/status/632225738767208448
[2]: http://daringfireball.net/projects/markdown/
[3]: https://help.github.com/articles/github-flavored-markdown/
[10]: http://blog.codinghorror.com/the-future-of-markdown/
[11]: http://commonmark.org/
[20]: TODO__LINK_TO_DOCS_GOES_HERE
Instead of placing the entire URL inline, you would only use its number:
markdown link list example (b.)
[CommonMark][11] is an initiative for Markdown standartization.
The reason we're telling you all that is because the Markdown editor can organize the links automatically. Organize links is the button you want to click:
Once you press it, all the inline links will be replaced with references, and the URLs will be moved to the end of the document.
Embed media content with embed.ly
Writer's perspective
Contentful enables embedding many kinds of external media content, including but not limited to images, videos, tweets and PDFs, into Markdown-formatted texts. Click Embed external content, paste the link to the external resource, and the editor will do the rest. Although you'll only see code snippet in the text editing mode, the preview will display the media resource as it should look like.
See the list of supported services.
Developer's perspective
We use Embedly to display external content. To show Embedly cards in your sites and apps, you should use the relevant libraries provided by Embedly. See the documentation for more information.
Use HTML when Markdown is not enough
As good as Markdown syntax is, some things can't be achieved with it. Admittedly, formatting tables in Markdown doesn't feel wonderful. It's also impossible to set custom image size in Markdown.
HTML can be helpful in these cases. Certainly it's not helpful for developers who will need to process the content you're preparing for them, but it can give the editor a basic understanding how the finished piece of content will look like.
The Contentful Markdown editor supports basic HTML tags. We encourage you to format the content with Markdown markup, but sometimes it's just difficult to avoid writing that <img src="../screenshot-3.png" width="400"/> tag.