Markdown Block

The Markdown block allows you to compose posts and comments with links, lists, and other styles using standard characters and punctuation marks. Writers and bloggers use Markdown to quickly and easily write rich text without having to take their hands off the keyboard and without learning countless complicated codes and shortcuts. You can use Markdown for posts, pages, and comments. This guide will detail how to enable Markdown on your blog and write with it.

If you are already familiar with Markdown, enable it on your blog and start writing. You can refer to this Markdown Reference page for help. The Markdown Block follows the CommonMark spec (click the latest version link to see what features are currently enabled.)

Before you can use the Markdown block, you must enable Markdown for your site. Depending on whether your site uses plugins, there are two different methods for enabling Markdown for your site.

If your site does not have plugins installed, you will follow these steps to activate Markdown for Posts and Pages and Comments on your site:

1. Visit your site’s dashboard.
2. Go to Settings → Writing.
3. Toggle on the option labeled “Use Markdown for posts and pages.”
4. Click Save Settings.

If you have plugins active on your site, you have the option to enable Markdown for Posts and Pages, as well as Comments, separately.

On plugin-enabled sites, follow these steps to activate Markdown for Posts and Pages:

1. Visit your site’s dashboard.
2. Go to Jetpack → Settings
3. Click the “Writing” tab.
4. Under “Composing“, click the button next to “Write posts or pages in plain-text Markdown syntax.”
5. If the Save Settings button is active, click it to save the changes.

On plugin-enabled sites, follow these steps to activate Markdown for Comments:

1. Visit your site’s dashboard.
2. Go to Jetpack → Settings
3. Click the tab labeled “Discussion”
4. Under Comments, click the button next to “Enable Markdown use for comments.”
5. If the Save Settings button is not grayed out, click it to save the changes.

You can add Markdown to any page, post, or template using the Markdown block. Follow these steps to add the Markdown block to your content:

1. Visit your dashboard.
2. Depending on where you want to add the image, navigate to a page, post, or template and edit or create a new:
   • Page: Navigate to the Pages section of your menu.
   • Post: Navigate to the Posts section of your menu.
   • Template: Navigate to Appearance → Editor and select the template.
3. Click the plus icon and search for “Markdown”.
   • Or, type /image wherever you see “Type / to choose a block”.

For more information, visit our detailed instructions on adding blocks.

Each block has its own block-specific controls that allow you to manipulate the block right in the editor. The Markdown block offers the Markdown and Preview tabs, and more option control.

When writing in a Markdown block, you will see the Markdown tab selected, indicating that you should write your Markdown code here (more information on Markdown formatting below).

You can click the Preview tab to see an approximation of more information. Markdown content will appear when published. (Note that the actual appearance will vary depending on the styles added by your theme.)

If you navigate away from the Markdown block, the block will show the Preview of the Markdown. When you click the Markdown block again, it will switch back to the Markdown tab so you can continue writing.

Markdown uses special characters and punctuation marks to indicate styles and links. The specific characters you use and how you place them in the document are key to formatting your document. Markdown converts these special characters to the appropriate formatting when the document is published.

Here are some examples, and a full Markdown reference guide from CommonMark

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 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](https://wordpress.com/). When published, it will be a standard link: WordPress.com.

The original Markdown text you write will always remain in Markdown, so 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, it’ll still be in Markdown.

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

The Markdown block follows the CommonMark spec. It does not support Markdown Extra. However, Markdown Extra is supported in the Classic Editor.

What is Markdown Extra?

Markdown Extra by Michel Fortin includes some features not originally available in Markdown, including improved support for inline HTML, code blocks, tables, and more. Code blocks can use three or more back ticks (“`), as well as tildes (~~~).

For more detailed information on this, see the original reference guide for Markdown, and the Markdown Extra page.

When you select a block, you will find additional block settings in the right sidebar. If you do not see the sidebar, you may need to click the Settings icon in the top-right corner to bring up the settings. This icon looks like a square with two uneven columns:

The Markdown block will include a setting for Dimensions, with options for padding or margin. More details for this option can be found in the following guide for Dimensions Settings.

For more information, visit our detailed instructions on Advanced Settings.

If you are using the Classic Editor, you must enable Markdown and insert markdown using the HTML tab. Here’s our markdown reference guide for the classic editor. The Classic Editor uses Markdown Extra, which has a handful of options different from the CommonMark Spec used in the Markdown block.

One important item to note with the Classic Editor is that once you save your changes, you cannot edit the content as Markdown. It will show as formatted content or HTML. Instead, switch to the Block Editor and use the Markdown block.