Markdown Block Editor

Overview

Markdown Block Editor adds a native Markdown block to the WordPress block editor.

It is built for site owners, editors, technical writers, and content teams who want to write in Markdown while still using the native block editor for page layout and publishing.

Current features include:

• writing or pasting Markdown into a block textarea
• switching between Edit and Preview modes
• rendering Markdown as HTML on the frontend
• importing .md and .markdown files into a block
• using multiple Markdown blocks on the same page
• shifting heading levels up or down across a block
• generating a table of contents from Markdown headings
• enhancing code blocks with language labels and copy buttons
• language-ready plugin strings and bundled translations
• private updates through the WellPlayedWP Library license flow

Requirements

• WordPress 6.3 or newer
• PHP 7.4 or newer
• the WordPress block editor

For private updates:

• the WellPlayedWP Library plugin must be active
• a valid library license must be connected through that plugin

Installation

1. Upload the plugin to /wp-content/plugins/markdown-block-editor/.
2. Activate Markdown Block Editor in WordPress.
3. Open the block editor for a post or page.
4. Insert the Markdown block.

Using the Markdown Block

Add the Block

1. Open the block inserter.
2. Search for Markdown.
3. Insert the block into your post or page.

You can add more than one Markdown block to the same page. Each block stores and renders its own content independently.

Write or Paste Markdown

The block opens in Edit mode by default. Use the textarea to:

• write Markdown directly
• paste Markdown from another source
• manage long-form content in a single block

Preview the Output

Use the Preview button to see how the Markdown will render on the frontend.

Use the Edit button to return to the textarea.

Preview uses the plugin’s own rendering pipeline so it stays closely aligned with the published output.

Import a Markdown File

In the block sidebar:

1. Open Import .md File.
2. Select a .md or .markdown file from your computer.

Important behavior:

• importing a file replaces the current content in that block
• importing affects only the selected block
• unsupported file types are rejected

Block Settings

Navigation

The Navigation panel controls the optional table of contents.

Options:

• Show Table of Contents
• Table of Contents Title

When enabled, the plugin scans headings in the Markdown block and creates a linked heading outline above the rendered content.

This is especially useful for:

• tutorials
• documentation pages
• changelogs
• long-form technical articles

Heading Levels

The Heading Levels panel provides two block-wide heading tools:

• Remove # from Headings
• Add # to Headings

These tools:

• work on Markdown headings that begin with #
• shift headings by one level at a time
• keep heading levels within the Markdown range of # through ######

Example:

# Heading One
## Heading Two
### Heading Three

After Add # to Headings:

## Heading One
### Heading Two
#### Heading Three

After Remove # from Headings:

# Heading One
# Heading Two
## Heading Three

Code Blocks

The Code Blocks panel controls enhanced code block output.

Option:

• Enable Copy Buttons and Language Labels

When enabled:

• fenced code blocks receive a toolbar
• the toolbar can show a detected language label
• readers can click Copy to copy the code block contents

If a language is not detected, the block uses a generic Code label.

Example fenced block:

```js
console.log('Hello world');
```

Using tildes for the outer example fence is the clearest way to show triple-backtick examples inside Markdown documentation.

Frontend Output

The plugin renders Markdown on the frontend as HTML.

That output can include:

• headings
• paragraphs
• lists
• links
• code blocks
• an optional table of contents
• enhanced copyable code blocks

The plugin also sanitizes rendered output for safety.

Multiple Markdown Blocks

You can use multiple Markdown blocks on the same page or post.

Each block keeps its own:

• Markdown content
• preview state
• table of contents setting
• code block enhancement setting

Languages

The plugin is translation-ready and currently includes bundled translations for:

• German
• Spanish
• French
• Chinese
• Japanese

Private Updates

The plugin includes private update support for WellPlayedWP customers.

Update checks are available only when:

• the WellPlayedWP Library plugin is active
• a valid license is available through that plugin

If updates do not appear:

1. Confirm that the WellPlayedWP Library plugin is active.
2. Confirm that your license is connected.
3. Visit the Plugins screen or Dashboard > Updates.

Uninstall

Removing the plugin deletes its internal version and compatibility housekeeping data.

If the plugin is uninstalled, WordPress will no longer be able to render the Markdown block unless the plugin is installed again.

Troubleshooting

Preview Shows an Error

If Preview fails:

• check whether another plugin or theme is causing admin or REST API errors
• check for PHP warnings or fatal errors on the site
• refresh the editor and try again

The plugin uses its own preview endpoint to reduce problems with large or complex Markdown content.

A Code Example Breaks Rendering

If you are documenting Markdown that itself contains fenced code blocks, use a longer or different outer fence for the example.

Best practice:

```js
console.log('Hello world');
```

This avoids ambiguity when showing code fences inside code fences.

Copy Buttons Do Not Work

If copy buttons are visible but copying fails:

• test in a current modern browser
• make sure JavaScript is not being blocked by another plugin or theme
• try again on the frontend after confirming the setting is enabled

The plugin includes both modern clipboard support and a fallback copy method, but another script conflict can still interfere.

Table of Contents Does Not Appear

Check the following:

• Show Table of Contents is enabled
• the block contains headings
• the headings are written in Markdown heading syntax

Developers

This plugin’s documentation is primarily for users and site integrators.

At this time, the plugin does not publish a documented set of custom action hooks, filter hooks, template tags, or public PHP helper functions intended for third-party extension.

For third-party developers, the supported integration surface is currently limited to normal WordPress behavior such as:

• inserting and rendering the block in content
• styling the frontend output with theme CSS
• controlling block availability through standard WordPress editor capabilities

If the plugin introduces documented public hooks or filters in a future release, they should be listed in this section.

Support

For support, licensing help, or update access, use the WellPlayedWP support channel associated with your purchase or account.