Blocks

Blocks »Markdown Block

The Markdown Block 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 write rich text, without having to take their hands off the keyboard, and without learning a lot of complicated codes and shortcuts.

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

Enabling Markdown
Enabling Markdown for Business Plan Sites Using Plugins
Adding Markdown
Block Interface
Writing with Markdown
Markdown Extra and Markdown in Jetpack
Block Settings
Advanced
Classic Editor

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


Enabling Markdown

Before you can use the Markdown Block, you will need to enable Markdown for your site.

These instructions refer to the WP Admin dashboard. You can get to this dashboard by adding /wp-admin to the end of your site’s url (e.g.: my.blog/wp-admin)

  1. In WP Admin go to Settings → Writing.
  2. Check the checkbox next to “Use Markdown for posts and pages.”
  3. Click Save Changes to activate Markdown on your site.
Markdown Block - Activate Markdown
Activate Markdown from WP Admin → Settings → Writing

↑ Table of Contents ↑

Enabling Markdown for Business Plan Sites Using Plugins

These instructions refer to the WP Admin dashboard. You can get to this dashboard by adding /wp-admin to the end of your site’s url (e.g.: my.blog/wp-admin)

Markdown for Posts and Pages
  1. In WP Admin, go to Jetpack → Settings → Writing.
  2. Under Composing click the button next to “Write posts or pages in plain-text Markdown syntax.”
  3. If the Save Settings button is not grayed out, click it to save the changes.
Markdown - Enable Composing in Jetpack
WP Admin → Jetpack → Writing → Composing
Markdown for Comments
  1. In WP Admin, go to Jetpack → Settings → Discussion.
  2. Under Comments click the button next to “Enable Markdown use for comments.”
  3. If the Save Settings button is not grayed out, click it to save the changes.
Markdown - Enable Comments in Jetpack
WP Admin → Jetpack → Discussion → Comments

↑ Table of Contents ↑

Adding Markdown

In order to add a Markdown Block, click on the Inserter icon.

You can also type /markdown and hit enter in a new Paragraph Block to add one quickly.

Detailed instructions on adding blocks can be found here.

↑ Table of Contents ↑

Block Interface

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.

jetpack-markdown-editing

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.)

jetpack-markdown-preview

If you click Preview and still see Markdown code, there’s one of two reasons for this.

  1. Markdown has not yet been enabled. Enable Markdown with these steps.
  2. The Markdown is incorrect. Check here for our quick reference guide.

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


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

writing-with-markdown
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 in Jetpack

The Markdown Block 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. Code blocks can use three or more back ticks (```), as well as tildes (~~~).

See the WordPress.com 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 ↑

Block Settings

Every block has specific options in the editor sidebar in addition to the options found in the block toolbar. If you do not see the sidebar click the ‘cog’ icon next to the Publish button.


↑ Table of Contents ↑

Advanced

The advanced tab lets you add a CSS class to your block, allowing you to write custom CSS and style the block as you see fit.

The advanced section lets you add a CSS class to your block.
The advanced section lets you add a CSS class to your block.

↑ Table of Contents ↑

Classic Editor

If you are using the Classic Editor, you will need to enable Markdown, and insert markdown using the HTML tab.

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

Not quite what you're looking for?

Get Help