Markdown, the way to write

We've updated the Markdown editor – the environment for writing texts which are longer than a tweet. The update introduces markup highlighting, full-screen mode, media embedding and other almost invisible yet important features, all for improving the writing experience and simplifying the complicated process of transferring thoughts on the screen.

Scroll below for a brief illustrative overview of the update, and also for some obvious thoughts on why Markdown is something useful, not yet another buzzword. As an editor, you might dislike it. That's okay, you're not alone. However, we encourage you to invest some time into understanding how Markdown improves authoring experience and what principles it's based upon.

The update

Markup highlighting

It's hard to believe it wasn't there before. The highlighting helps seeing how the finished copy would look like and simplifies editing.

Full-screen mode

Focus on writing. Switch to full-screen to hide all the interface elements – except for the text area.

You can also see an HTML preview of the Markdown-formatted content:

Media embedding

We've introduced better ways to embed non-textual content, such as images, videos and tweets, into Markdown-formatted texts.

More and more

There's also keyboard shortcuts, automatic inline links cleanup, and other things beyond the scope of this post. See the docs for in-depth coverage of the editor features and Markdown syntax. We followed the GitHub-flavored Markdown specification, so there should be few surprises on the way.

Enabling Markdown in Contentful

In case you forgot or somehow missed the Contentful built-in Markdown editor, see how to enable it below.

• Go to http://app.contentful.com

• Open the Content types section (note that it's visible only if you have the necessary access level – that is, Developer or Admin)

• Open a content type that contains a Long text field

• Open the settings of a Long text field

• Switch to the Appearance tab

• Select Markdown – and there you are

• Don't forget to save the new content type settings

Open any entry corresponding to that content type, and the Markdown editor will be waiting there.

Sympathetic sidenote about the role of a writer

If a CMS doesn't address the needs of the writers, it's doomed to be hated. The unhappy writers will revolt, and the CMS will be replaced.

Here at Contentful we respect the authors and the thoughts and ideas they put into words, so the writing experience is as important to us as a flexible API and stable infrastructure.

A brief introduction to Markdown

So, what is Markdown?

According to the project website, "Markdown is a plain text formatting syntax". Markdown helps format text – add headings, lists, bold, italic, inline images and so on – by applying relatively simple and non-intrusive markup.

How is Markdown different from 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.

Since its first release in 2004, Markdown has been growing more and more popular. It is used as a default markup language on GitHub, StackOverflow, Reddit and a number of CMS. That may not be convincing, sure, but it definitely indicates that some people agree with the Markdown principles and that the syntax is good for numerous tasks.

Why should I learn Markdown?

Many find Markdown confusing. Some writers are used to WISYWIG text editors, some prefer HTML or even BBCode/phpBB. There are also a bit more exotic markup languages such as Textile and MediaWiki. The paragraphs below highlight benefits of Markdown over other ways to structure text pieces.

Lightweight syntax

The asterisks, brackets and number signs used in Markdown, and the way they are placed within the text, are much less noisy than the HTML tags or dozens of BBCode square brackets. The syntax is also not very difficult to learn, and modern editors (such as our own), with the toolbars and syntax highlighting, make writing experience semi-WYSIWIG.

Prevalence

As mentioned above, Markdown is being used not only in Contentful – other CMS and websites implement it as a default markup language as well. It means that other editors also accept this approach, and that this skill could be used elsewhere.

Portable content

One of the reasons why Markdown was built is that HTML looks ugly – both to editors and to developers. Markdown-formatted content is much simpler to process, transform, and display across different platforms. In short, the developers responsible for putting your content live will thank you.

Final notes

We're constantly working on improving the writing experience (and overall user experience as well). More updates will be coming in the future.

If you're interested in Markdown a bit more, you might want to take a look at the thoughts about the future of Markdown and CommonMark, an initiative for Markdown standardization.

Subscribe for updates

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