A beginner’s guide to Markdown and Rich Text Format

A person surrounded by rich text and markdown text types
May 25, 2020


Google Docs, Microsoft Word, Medium –– there is a good chance you have used one of these text editors today. And even if you haven’t been productive, you’ve probably still used one in the form of Facebook Messenger, Reddit, or Apple Notes.

Text editors allow us to record and render our important thoughts and information, enabling us to share our stories and communicate with each other.

In this article, we'll be looking at the two types of text editors that you can use with Contentful: Rich Text Format (RTF) and Markdown. You can choose to work with either, so the question is: How do I choose which text editor to use? The answer might not be as straightforward as you may think.

What is Markdown? 

Markdown is a lightweight markup language that you can use to add formatting elements to plain text. It was created by John Gruber of Daring Fireball in 2004 to make text as readable as possible. Markdown is one of the most popular markup languages and has a loyal fanbase.

While you might not have heard of it, you’ve probably encountered it on Facebook Messenger or even Skype. The philosophy behind the markup language is that plain text documents should be readable without tags, excessive syntax or formatting messing it up. 

Markdown is called lightweight because it doesn’t have any excessive features that might get in the way of the mechanics of writing; Its beauty is in its simplicity. This description might sound a little poetic, but there is something about the language that inspires loyalty amongst its fans.

When Slack decided to do away with it in favor of a WYSIWYG editor, posts like this, and this went viral. They had such a strong reaction that they decided to bring Markdown back as an option. 

There are a several reasons for this strong reaction. The first is that Markdown has always been a power-user tool. Regular users have always preferred using rich-text editors, but for those who get familiar with Markdown, trying to stop using it is a little like trying to unlearn a language.

The second is that Markdown results in better quality control over the resulting HTML. The simplicity of the language means that it turns into really clean, really good HTML. While Markdown is formatting syntax, it is also considered a software tool that converts plain text to structurally valid HTML or XHTML. 

Another reason users love it is that Markdown is platform-independent and future-proof. You can open Markdown-formatted text with any application, which makes it good for omnichannel distribution. And it means that if the application you’re using stops working at some point, you can still view your text. 

Here is an example of what a sentence looks like in markdown: 

You can make some words **bold** and other words *italic* with markdown. You can even [link web pages](http://www.contentful.com). 

This would render as: 

You can make some words bold and other words italic with markdown. You can even link web pages

A note on Markdown flavors 

One of the more confusing aspects of Markdown is there are different flavors. Every application of the formatting syntax uses a slightly different version. These variants of Markdown are referred to as flavors. At Contentful, we like to use the GitHub flavor of Markdown

Sign up for your free Contentful account and start building in minutes.

What is rich text formatting? 

Rich text is a formatting type that gives authors a wide range of formatting options. It gives editors the power to design how their writing and elements look on the page. It creates highly readable content without having to get into the HTML or source code.

Most editors love using rich text formatting because it’s intuitive and familiar. Most people are familiar with this way of working because word processors such as Microsoft Word and Pages create rich text documents. Google Docs uses it, too. These are also examples of What You See Is What You Get (WYSIWYG) editors.

WYSIWYG editors are sometimes called rich text editors because that is the type of formatting they use. They allow editors to make changes and see them immediately. Since it is so widely adopted, most people know how to use rich text formatting without requiring any training.  

What does rich text allow you to do? 

  • Everything Markdown can do and more

  • Link to assets and entries dynamically by embedding them within the flow of the text 

  • Create a semantic structure within a piece of writing with headings and tags 

  • Embed images, create columns, and insert bullet points

  • Link to Contentful entries and assets (in Contentful) 

  • When you’re setting up your content types in Contentful, you can customize the formatting options

Rich text gives the editor the ability to do all this while maintaining a rich format on the API response. The API response is in JSON format thereby eliminating the empty <p></p> tags (associated with an HTML response) or shortcodes. 

Using Markdown or rich text in Contentful 

Screenshot of adding new text type box in Contentful

There are two field types in Contentful that are used for text. When you’re setting up your content model or adding content types, you can choose to stick to one field type, or have a mixture of the two. 

Scrrenshot of the New Text Field box in the Contentful app

Text is the field type that uses Markdown. Within text, you can select long or short, which determines the character limit on the field. If you choose the long option, this will look like a larger text editor box for your editors. In the context of a blog post entry, the short Text field would be good for a meta description, URLs, emails, or titles. The longer Text field would be appropriate for a longer introduction or the bulk of the writing.    

Screenshot of rich text field box on the Contentful app

Rich Text is the field type that uses rich text. From a developer perspective the structure of the data from a Text field is different from the structure of data from a Rich Text field. Once you have selected Rich Text, you can customize it by making a Content Management API (CMA) call and change up the formatting options.  

If you want the power to design how each element looks on your final product, rich text is your best option; it’s much more dynamic and customizable.  

For more on rich text, you can check out these resources: 

And if you haven't already done so, don't forget to sign up for your free Contentful account (no credit card required).

About the author

Don't miss the latest

Get updates in your inbox
Discover how to build better digital experiences with Contentful.
add-circle arrow-right remove style-two-pin-marker subtract-circle