The Beginner’s Guide to Writing WordPress Posts in Markdown
John Hughes November 20, 2017
If you’ve ever written a post in Microsoft Word and tried pasting the content into WordPress, you have probably experienced the irritating carryover of site-breaking document styles. In fact, any text editor with formatting options can experience the same issue.
‘Markdown’ is a plain-text syntax for writing articles without distraction. Agencies can streamline content creation by working in Markdown with both writers and editors. This standardizes the copy and reduces distracting visual styling issues. Then, after approving the content, you can handle stylization directly within WordPress.
In this article, we’ll introduce you to Markdown formatting and how you can learn to write using the syntax. Then we’ll show you how to enable it in WordPress for publishing. Let’s get started!
Introducing Markdown for Content Creation
Markdown is syntax for converting text to HTML, made especially for web content writers. The idea is for writers to create plain text content in a consistent way, so it can be easily converted to valid HTML. It was introduced in 2004 by John Gruber and Aaron Swartz. Due to its simplicity, Markdown hasn’t seen any major changes over the years but has gone through a few variants as different projects have adopted it for standard input.
Due to its focus on plain text, Markdown is remarkably quick to write. There are only a few basic syntaxes to learn upfront, which lets you focus on your content, minimizes distractions, and reduces the possibilities of lost formatting between shared documents.
Because of its simplicity, agencies can streamline content creation by using Markdown to standardize text delivery and editing. The learning curve is not steep – as Brett Terpstra said, if you can write an emoji, you can write in Markdown!
To summarize, Markdown is:
- Easy, any writer or editor can pick it up quickly.
- Clean, meaning style is only about writing style and nothing else.
- Portable, without any concerns about file compatibility between computers.
- Flexible, meaning the content can be output in multiple formats.
You will find it relatively painless to add this tool to your agency’s workflow while reaping all of its benefits. Many major companies and projects also use Markdown, so you’ll be in good company.
For example, GitHub uses Markdown for all their project wikis, Readme files, and comments, meaning more than 100,000 businesses are using Markdown in their GitHub-based projects. Even core WordPress groups use Markdown to write important documents for WordPress teams.
Markdown comes ready-to-go for WordPress.com sites, but if you’re running a self-hosted version you’ll need to do a little configuration. Let’s have a look at the steps you’ll need to take.
How to Write WordPress Posts Using Markdown In 3 Steps
Writing WordPress posts in Markdown is a relatively simple process. The only extra step is enabling Markdown support in the first place. Once that’s set up, you can default to writing WordPress posts in Markdown without a second thought.
Step 1: Enable Markdown in Jetpack
Jetpack is a multifunctional plugin provided by Automattic to replicate many of the features built into WordPress.com blogs. Using it on your website gives you access to a number of features such as:
- Site stats and analysis.
- Brute force attack protection.
- Downtime and uptime monitoring.
- A high-speed Content Delivery Network (CDN) for your images.
- Fully-customizable contact forms.
This is an incomplete list, but as you can see, it comes packed with quite a few useful elements. Most importantly, it also includes support for Markdown when writing posts. You can choose to enable or disable the rest as you please.
Once Jetpack is installed on your website, visit Jetpack > Settings in your WordPress dashboard:
Then, scroll down to Composing under the default Writing tab. Toggle the Write posts or pages in plain-text Markdown syntax option to the On setting:
Now, WordPress is ready for you to write posts in Markdown. Let’s take it out for a spin!
Step 2: Write a New Post Using Markdown
Once WordPress is prepared, it’s time to write your new post using the Markdown syntax. While you could write Markdown directly into WordPress, that won’t be very useful in an agency context. Instead, we recommend working with Markdown files directly to reap the full, ‘styleless’ benefits of the format.
You can write Markdown in any text editor. However, there are a few apps available to make it even simpler and more enjoyable than it already is. Here are a few of our free favorites:
There are plenty of premium editors available for power users as well. For example, this post was written using Ulysses. Ultimately, the right app comes down to personal and team preference.
To write your post, you’ll need to use the basic syntax of Markdown. There are a number of complete Markdown guides available, including the original and a master series from GitHub. We’ll summarize the basics for you here.
Let’s start with headings. There are six levels of headings, which you can indicate with the pound sign or use symbols to underscore:
The Best Markdown Plugins for WordPress
With more and more information floating around the interwebs, it has become a quite challenging task to keep your head cool. Content creators are often limited by the software or formats they’re using, effectively locking them into a silo ecosystem (looking at you Google Docs and Evernote!). With this in mind, John Gruber created the famous Markdown format in 2004. Today, it empowers writers and bloggers with the ability to write in HTML, without the use of overcomplicated and visually exhausting code.
Yes, basically my grandma would be able to read Markdown without giving me a confused look. Its extended portability and precision, coupled with its simplistic implementation, make it one of the few tools one simply needs to love.
Further, Markdown is the de facto syntax language for GitHub and Stack Overflow, two sites where most web developers spend most of their time.
As Markdown combines the best things from two worlds, it’s also greatly accessible in WordPress, allowing you to have more power over your content than with the WYSIWYG (What You See Is What You Get) editor.
In this article we’ll cover four of the best Markdown plugins for WordPress.
WP Markdown provides a few extra features apart the usual Markdown ones. You are able to activate or deactivate it in Settings > Writing, depending if you want to use Markdown for posts, pages, custom post types or comments.
However, WP Markdown might be a bit intimidating if you are not used to Markdown, as it will disable the visual editor altogether, on post types it’s activated. You will need to be aware that all of the future posts will need to be written using the Markdown syntax, so if you are not ready for the switch yet, try using some of the other plugins covered here.
Disclaimer: When activated, WP Markdown will convert all old posts or pages it has been assigned to, to the Markdown format. You can specifically select if pages, posts and/or comments should have markdown enabled.
One of the extra features WP Markdown can call its own, is the help bar for the post editor and/or comments. Once activated, you will notice a new toolbar at the top of your post editor. You are able to insert links, images, block quotes and various other formatting elements by making use of the help bar. The formatting you selected will be inserted into your post as proper Markdown.
Probably the best part of the help bar is that you are able to also add a preview box at the bottom of the post editor, allowing you to see your text when it’s output. Pretty neat when you want to avoid constantly checking whether your formatting is correct.
Markdown is a fairly prominent feature of Jetpack. For those unaware, Jetpack is an entire toolset for WordPress users, with features that support social media publishing, carousels, advanced comments, infinite scroll, and a whole lot more. The plugin works by allowing you to activate or deactivate different ‘modules’, which each represent a different piece of functionality. One of those modules is also Markdown. Markdown support in Jetpack is probably the flagship one for WordPress, so if you are unsure on what plugin you want to try first, Jetpack is a very solid start.
Jetpack utilizes Markdown Extra, which provides support for features which aren’t included in standard Markdown; such as tables, inline HTML, code blocks and more.
Jacco Blankenspoor has written about Jetpack previously; have a look if you want to see what else it offers.
Unlike most other options, typewriter completely removes the ‘Visual Editor’ feature in WordPress and replaces it with a straightforward Markdown editor. More technically, Typewriter removes the TinyMCE editor and defaults to a Markdown specific “Text” editor and parses the output using MarkdownExtra.
Typewriter is a good deal if you work a lot with code and don’t mind handling pure markdown. However if you are dependent on having a live preview or switching to WYSIWYG from time to time, you might be better off with another alternative.
Deserving a special place, PrettyPress reinvents the usage of the post editor as it is, making it not only a Markdown plugin. After installing it, a new button in the sidebar of the post editor “Launch PrettyPress” will appear. Pressing that button will launch a new editor window entirely, splitting the screen in half. On the left side, the usual WYSIWYG post editor is placed, while on the right side, you can see a live preview of the actual post within the activated theme. So you can basically have a visual editor for drafting posts side by side.
PrettyPress, does not support Markdown in the comments. It is limited to the post editor, most likely not a deal breaker.
Usually, everyone has an opinion on the internet; but oddly, the voices supporting Markdown are united and I personally haven’t seen any content creator despising Markdown. In fact, this very article you are reading is written in Markdown.
If you want to go even further and enhance your Markdown experience with a separate editor (yay for portability), you can check out other offline editor tools to continue writing outside WordPress. Zack Wallace has some good suggestions for that.
So what do you think? Are Markdown plugins for WordPress something which has made your life easier, or do you prefer writing in a separate editor? Let us know in the comments!
Get Jetpack’s Markdown Module Without Using Jetpack
Anas H. Sulaiman is a WordPress plugin developer who has created several extensions that extract modules from Jetpack so that they can be used independently. He recently renamed his WordPress.org profile to “JP Bot” and is gradually adding to his collection of Jetpack-extractions:
One of his most popular plugins is JP Markdown, which essentially duplicates Jetpack’s Markdown module. It allows you to compose WordPress content in Markdown and have it published as HTML. I gave the plugin a test run and found that it works as advertised:
JP Markdown even includes the “Use Markdown for Comments” feature that you can enable under Settings > Discussion. This plugin is a solid option if you like the Markdown module in Jetpack but don’t want everything else that comes with it.
The JP Bot family of plugins extracted from Jetpack currently includes:
- JP Sharing – Share content with Facebook, Twitter, et al.
- JP Widget Visibility – Control what pages your widgets appear on.
- JP Markdown – Write in Markdown, publish in HTML.
- JP Custom CSS – Customize your site’s CSS without modifying your theme.
- JP Gravatar Hovercards – Show a pop-up business card of your users’ gravatar profiles in comments.
- JP Omnisearch – A single search box, that lets you search many different things.