What is Markdown? A beginner’s guide to Markdown and Rich Text Format

Google Docs, Microsoft Word, Medium – there’s a good chance you’ve used one of these text editors today. And even if you haven’t, you’ve probably  edited text in apps like Facebook Messenger, Reddit, or Apple Notes.

Text editors allow us to record and structure our ideas and information, enabling us to share our stories and communicate with each other.

In this post, we’ll be looking at the two types of text editors that you can use with Contentful: Markdown and Rich Text Format (RTF). 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.

Markdown, simply explained

Markdown is a lightweight markup language that you can use to add formatting elements to plain text. The markdown syntax 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 fierce 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.

Markdown as a bridge between plain text and HTML

There are several reasons for this strong devotion. The first is that Markdown has always been a power-user tool. Regular users may always prefer using rich-text editors, but for those who are familiar with Markdown and its nifty editing shortcuts, 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 tags. The simplicity of the language means that it turns into really clean, really good HTML. While Markdown is a text formatting syntax, it’s also considered a software tool that converts plain text to structurally valid HTML or XHTML. 

Another reason users love it is that Markdown documents are platform-independent and future-proof. 

Whether you’re using Mac, Linux, iOS or Android, you can open a Markdown file with any application, which makes it good for content management systems and omnichannel distribution. And it means that if the application you’re using stops working at some point, you can still view your text without worrying about markdown support.

Examples of Markdown formatting

We won’t go into the full details of markdown formatting here, but to demonstrate its simplicity here are some simple examples of the markdown syntax. Try it out and see how easy it is. 

You can quickly make italicized text by surrounding it with either asterisks or underscores. To make bold text, simply surround it with two asterisks or two underscores on each side.

Next, you can quickly add links by surrounding the text in square brackets and the URL in parentheses. 

Taking all of the above into consideration, here’s an example of what a sentence looks like in markdown: 

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

This would render as: 

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

Another useful tidbit is that you can strikethrough by surrounding text with dashes. And you can quickly create new headlines by starting a new line with a pound sign followed by a space. 

For example, "# Header" on a new line would make the full-size headline. To make smaller headlines simply add more pound signs, "## Another Header" for an H2 headline and "### Yet Another Header" for an H3 headline, and so forth.

If you’d like to learn more about the syntax, including blockquotes, a bulleted list or code blocks, then check out this Markdown Tutorial for the full rundown.

A note on Markdown flavors 

One of the more confusing aspects of Markdown is there are different flavors. The fundamentals are the same, but every application of this text formatting syntax uses a slightly different version. These variants of Markdown are referred to as flavors. At Contentful, we like to use the GitHub flavored Markdown. You can read all about it in our Markdown editor documentation.

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 (JavaScript Object Notation) format thereby eliminating the empty <p></p> tags (associated with an HTML response) or shortcodes. 

Using Markdown or rich text 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. 

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.    

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: 

• Learn more about rich text 

• Getting started with rich text 

• Migrate content to rich text

Start building

Sign up for a free Contentful account

Use your favorite tech stack, language, and framework of your choice.

Subscribe for updates

Build better digital experiences with Contentful updates direct to your inbox.