Writing & Editing

Markdown

Markdown lets you compose posts and comments with links, lists, and other styles using regular characters and punctuation marks. Markdown is used by writers and bloggers who want a quick and easy way to style their text, without having to take their hands off the keyboard, and without learning a lot of complicated codes and shortcuts.

You can use Markdown on your WordPress.com blog for posts, pages and comments. This document will detail how to enable Markdown on your blog, and how to write with it.

If you are already familiar with Markdown, just enable it on your blog and start writing; refer to our Markdown Quick Reference page for help. WordPress.com uses Markdown Extra, which adds some features not originally available in Markdown. See below for more details.

Enabling Markdown

To enable Markdown for posts and pages, go to SettingsWriting in your dashboard, and check the box labeled Use Markdown for posts and pages. Click on Save Changes at the bottom of the page to apply. You will now be able compose posts and pages using Markdown.

Enabling Markdown for posts and pages

Enabling Markdown for posts and pages

To enable Markdown for comments, go to SettingsDiscussion in your dashboard, and check the box labeled Use Markdown for comments. Click on Save Changes at the bottom of the page to apply. Visitors to your blog will now be able to compose comments using Markdown.

Enabling Markdown for comments

Enabling Markdown for comments

Once enabled, it will be available to all users on your blog.

When writing with Markdown, make sure you always use the Text editor and not the Visual editor. Using the Visual editor may cause unexpected results with Markdown.

↑ Table of Contents ↑

Writing with Markdown

Markdown makes use of special characters and punctuation marks to indicate styles and links. The specific characters you use and how you place them in the document is key to how your document will be formatted. When the document is published, Markdown converts these special characters to the appropriate formatting.

For example, in Markdown, to emphasize a word, you wrap it with an asterisk on both ends, like this: *emphasized*. When your writing is published, it will instead look like this: emphasized. Similarly, two asterisks denote strong text: **strong** will be published as strong.

To indicate links, use regular and square parentheses. Wrap the text you want to link in square parentheses, and immediately after it, insert the link target, wrapped in regular parentheses. The actual Markdown could look like this: [WordPress.com](http://wordpress.com/). When published, it will be a standard link: WordPress.com.

On the left: using Markdown to compose a post in the fullscreen editor. On the right: The published post.

On the left: using Markdown to compose a post in the fullscreen editor. On the right: The published post.

The original Markdown text you write will always remain in Markdown, this way you can go back and edit it using Markdown. Only the published document – the post or the page – will be converted. If you write a post in Markdown, it will be published as a fully formatted post on your blog, but when you go back and edit, it’ll still be in Markdown.

The best way to get started with Markdown is to experiment. Open the Markdown Quick Reference guide, start a draft post on your blog, and try to use the different features.

↑ Table of Contents ↑

Markdown Extra and Markdown on WordPress.com

WordPress.com uses Markdown Extra by Michel Fortin. It includes some features not originally available in Markdown, including improved support for inline HTML, code blocks, tables, and more.

There are two important changes made to how Markdown Extra works on WordPress.com, affecting code blocks:

  1. Code blocks can use three or more back ticks (```), as well as tildes (~~~).
  2. Syntax highlighting can be added to code blocks by specifying the code language in the first line of back ticks:
     ```css
     .ninja {
       visibility: hidden;
     }
     ``` 
    

    The list of supported languages can be found in the Posting Source Code support page.

See the Markdown Quick Reference page for the most useful formatting and features offered by Markdown Extra. For more detailed information, see the original reference guide for Markdown, and the Markdown Extra page.

↑ Table of Contents ↑

About Markdown

Markdown was created by John Gruber and Aaron Swartz in 2004 as a solution for easily composing richly formatted text on the web. It employs plain text only and is based on conventions established in the computer and technology industry for writing emails and other documents with limited resources.

In plain text documents, the text you see on the screen represents all the information in the file, with essentially no formatting or other data hidden from view. Plain text documents have been used for decades for their simplicity, portability, and reliability. You can probably still open and edit any plain text document from the past 40 years in any computing device available today.

Markdown has seen popular adoption on the web since it was first introduced, and it is now included in many sites and software programs.

  • Markdown Project.
  • Markdown on Wikipedia.
  • Mou is a free Markdown editor for Mac.
  • MarkPad is an open source Markdown editor for Windows.
  • Texts is a Markdown editor for Mac and Windows which can convert Markdown to many formats, including PDF and Word documents.
  • Byword is a Markdown editor for Mac, iPhone and iPad.
  • Draft is a Markdown editor for Android devices.
  • Simplenote is a cross-platform note-taking service by Automattic, with Markdown support.

Not quite what you're looking for?

Get Help