Ultimate Markdown Pro

Introduction
Installation
Post Sidebar Sections
Dedicated Menus
Image Handling
Front Matter
REST API
Additional Information

Introduction

Ultimate Markdown Pro helps you work with the Markdown syntax by providing tools to import, export, and modify Markdown documents.

Installation

Refer to the installation guide for setup and update instructions. The information available in this document applies to all our WordPress plugins.

Post Sidebar Sections

The plugin adds four new sections in the sidebar of your posts, pages, or custom post types.

To access these sections, open the post sidebar using the cog icons available in the top-right area of the screen. Then select the Post tab of the sidebar.

Import Markdown

Use the Import Markdown section to generate the post content from a Markdown file available on your computer.

Open the Import Markdown section
Click the Upload file and import button
Select a Markdown file available on your computer

Load Markdown

With this section, you can replace the existing post content with content generated from a document stored in the plugin. See the Documents and Import menu for more information on creating a document.

Open the Load Markdown section
Select a document stored in the plugin with the Markdown document selector
Click the Submit document button to complete the process

Submit Markdown

The Submit Markdown section allows you to generate the post content from a provided text string.

Open the Submit Markdown section
Enter the text using Markdown syntax in the Markdown text textarea
Click the Submit text button to complete the process

Export Markdown

The Export Markdown section allows you to generate a Markdown file from the content of the currently edited post.

Open the Export Markdown section
Click the Export button

The generated Markdown file will be available in the download location configured in your browser.

Dedicated menus

Documents

From the Documents menu you can create, duplicate, download, edit, or delete Markdown documents.

Create a document

Use this procedure to create a document:

Enter the Title of the document
Select the Category of the document or leave “None”
Enter the Content of the document
Click the Add Document button

Download a document

To download a document, click the Export link available in the first column of the table used to list the existing documents.

Tools

This menu provides centralized access to bulk import and export operations. It’s divided into two sections: the Import section, which is used to import Markdown content into the plugin, and the Export section, which allows you to export existing website content, including plugin-managed Markdown documents or WordPress posts.

Import

Use the Import section to generate content from Markdown files available on your computer. Follow these steps:

Select the import destination (Documents or Posts).
Click the Choose files button to select one or more Markdown files from your computer.
Click the Upload files and import button to start the process.
Once the import is complete, a dismissible notice will display the list of generated items.

Importing to Documents

When Documents is selected as the import destination, the plugin will generate plugin-managed Markdown documents from your import. The generated material will be available in the Documents menu.

Importing to Posts

When Posts is selected as the import destination, the plugin will generate posts in Draft status. You can define the post type of the imported content using the Advanced → Import → Post Type option available in the Options menu.

With the Block Editor active, the imported content will appear in a single Classic Block, not as individual blocks. If needed, you can click on the Convert to blocks button available in the tools of the Classic Block to manually perform the conversion.

The recommended workflow to use when the Block Editor is active on the site is the following:

Import the Markdown files into Documents (as described above).
In the post editor, use the Load Markdown section in the sidebar to load the desired document.

Export

Use the Export section to generate compressed archives (.zip) of Markdown files from existing content. You can export either plugin-managed Markdown Documents or existing Posts from your site.

Export from Documents

To export content stored in the plugin:

Set the Source selector to Documents.
Click the Export button.

Export from Posts

To export posts, pages, or custom post types:

Set the Source selector to Posts.
Use the Post Types option to select which types of content to include.
Use the Categories option to filter by category (leave empty to include all).
Use the Tags option to filter by tag (leave empty to include all).
Click the Export button.

Image Handling

Ultimate Markdown Pro offers two different ways to include images when importing Markdown files: by referencing publicly available images or by packaging local images within a ZIP archive.

In this section, both methods are explained in detail.

Including Publicly Available Images in Markdown Files

The plugin can import images referenced in Markdown files using publicly available URLs. These images are downloaded during the import process and integrated into the WordPress Media Library.

Before starting, make sure that image uploading during import for publicly available images is enabled. To do this, navigate to the Options menu, open the Conversion tab, and locate the External Images section. Enable the toggle corresponding to the import feature where you want image upload for publicly available images enabled.

Next, create a Markdown file that uses the standard Markdown image syntax with absolute URLs to public images. In the example below, https://example.com/image.jpg represents a publicly accessible image URL. The image can be hosted on your own website or any other website:

## Heading

Content.

![Image Example](https://example.com/image.jpg)

During the import process, the plugin will download the image from https://example.com/image.jpg, upload it to the WordPress Media Library, and update the image URL in the resulting document or WordPress post content accordingly.

In the WordPress block editor, the content is rendered as shown below. In this context, https://example.com/wp-content/uploads/2025/12/image.jpg represents an image of the WordPress Media Library located on your WordPress website:

<!-- wp:heading -->
<h2 class="wp-block-heading">Heading</h2>
<!-- /wp:heading -->

<!-- wp:paragraph -->
<p>Content.</p>
<!-- /wp:paragraph -->

<!-- wp:image -->
<figure class="wp-block-image">
  <img src="https://example.com/wp-content/uploads/2025/12/image.jpg" alt="Image Example" />
</figure>
<!-- /wp:image -->

If instead the document is imported as a plugin-managed Markdown document, the content is rendered as follows:

## Heading

Content.

![Image Example](https://example.com/wp-content/uploads/2025/12/image.jpg)

This method applies only when images are publicly accessible via absolute URLs (for example, URLs starting with http:// or https://). Relative paths or local file references are not supported with single Markdown file uploads. To import local images, refer to the next section on ZIP uploads.

Also note that an image will be uploaded to the WordPress Media Library only if it is publicly accessible. If the image URL is not available, protected, requires authentication, or is blocked, the plugin will skip the image during the import process.

How the Plugin Technically Handles Image Imports

During the import process, the plugin performs the following steps:

Download the referenced images
Upload the images to the WordPress Media Library
Replace the original public URLs with the URLs of the images stored in the WordPress Media Library
Create a document or a post using the updated content with the correct image URLs from the media library

Importing Markdown Files with Local Images Using a ZIP Archive

Ultimate Markdown Pro can also import Markdown files that reference local images. To do this, you must package the Markdown file and its associated images into a ZIP archive.

ZIP uploads are supported only in specific import contexts. You can upload ZIP archives when using the import operations available in the Tools menu and when using the Import Markdown section in the post editor sidebar.

When you upload a ZIP file containing a Markdown file and its related images, the plugin extracts the images from the archive, uploads them to the WordPress Media Library, and updates the image URLs in the resulting content accordingly.

Consider the following example ZIP file structure:

my-markdown-import.zip
├── document.md
└── images
    ├── image1.jpg
    └── image2.png

In this example, document.md is the Markdown file that references two local images (image1.jpg and image2.png) located in the images folder.

The content of document.md might look like this:

## Sample Document

The first image:

![Image 1](images/image1.jpg)

The second image:

![Image 2](images/image2.png)

When referencing local images, you should always use relative paths. The paths used in the Markdown file must match the structure of the ZIP archive exactly.

For example, if the images are located in the same folder as the Markdown file, you can reference them like this:

![Image 1](image1.jpg)

or:

![Image 1](./image1.jpg)

If the images are located in a subfolder named images, you can reference them like this:

![Image 1](images/image1.jpg)

or:

![Image 1](./images/image1.jpg)

Avoid using leading slashes (/) when referencing local images in ZIP uploads. In URLs, a leading slash (/) refers to the root path of the current domain. When working with ZIP archives, there is no equivalent concept of a site root, so leading slashes in image paths are ambiguous and may prevent images from being correctly resolved.

How the Plugin Technically Handles ZIP Files with Local Images

During the ZIP import process, the plugin will:

Extract the Markdown file and images from the ZIP archive
Upload the local images to the WordPress Media Library
Replace relative image paths (for example, images/image1.jpg) with the corresponding WordPress Media Library URLs (for example, https://example.com/wp-content/uploads/2025/12/image1.jpg)
Create a document or a post using the updated content with the correct image URLs from the media library

Note that you can also upload multiple ZIP files during the upload process. Each ZIP archive must contain only one Markdown file, along with its related images. Do not include multiple Markdown files in the same ZIP archive.

Best Practices

Ensure that image paths in the Markdown file exactly match the ZIP archive structure. Double-check image paths before uploading. If referenced images are not found, they will be skipped during import.
Keep paths simple and avoid deeply nested folder structures. When possible, place images in the same folder as the Markdown file or in a single subfolder.

Choosing the Right Method

Including Publicly Available Images in Markdown Files

Use this method when your Markdown content references images that are already publicly available. Typical examples include images hosted on your own website or on other websites that allow reuse. During import, these images will be downloaded and added to your WordPress Media Library.

When referencing images hosted on third-party websites, make sure you have the right to download them, import them into your WordPress Media Library, and use them on your site.

Importing Markdown Files with Local Images Using a ZIP Archive

Use this method when the Markdown file references local images that are not publicly available. This approach is ideal when you prepare articles with images on your local computer and want to upload everything in a single step. It is also well suited for editorial workflows where contributors provide content as a ZIP archive containing the Markdown file and all related images.

Note that when uploading ZIP files, only local images included in the archive will be processed. Publicly available images referenced in the Markdown file will not be downloaded during ZIP uploads.

Front Matter

The Front Matter feature of Ultimate Markdown allows you to configure a WordPress post by adding key-value pairs at the beginning of the Markdown file.

Using Front Matter

Front Matter must be included at the beginning of the file and take the form of valid YAML set between triple-dashed lines.

In the following Markdown file, Front Matter is used to configure post title, post excerpt, and post status:

---
title: The post title
excerpt: The post excerpt
status: private
---

## First Heading

Paragraph Content.

Supported keys

The plugin supports the following Front Matter keys:

Key	Value	WordPress Post Setting
title	String	Post title
excerpt	String	Post excerpt
categories	Array (An array of category IDs or category names)	Post categories
tags	Array (An array of tag IDs or tag names)	Post tags
author	String (The ID or login name of the author)	Post author
date	String (The post date in the “YYYY-MM-DD hh:mm:ss” format) (E.g. 2022-04-16 10:30:42)	Post date
status	String (The accepted values are: publish, future, draft, pending, private, trash)	Post status
slug	String (The last part of the URL)	Permalink (slug)
thumbnail	String (The thumbnail ID or the URL of a publicly available image. Note that when a publicly available image is specified, the plugin creates the corresponding image in the media library.)	Featured image
thumbnail_alt	String (The alt text of the image uploaded in the media library. Note that this key is only used when a publicly available image is specified in the “thumbnail” key.)	Feature image alt text
thumbnail_title	String (The title attribute of the image uploaded in the media library. Note that this key is only used when a publicly available image is specified in the “thumbnail” key.)	Feature image title attribute

Examples

Set the post title

---
title: The post title
---

## First Heading

Paragraph Content.

Set the post excerpt

---
excerpt: The post excerpt
---

## First Heading

Paragraph Content.

Set the categories

---
categories:
  - Category 1
  - Category 2
---

## First Heading

Paragraph Content.

Set the tags

---
tags:
  - Tag 1
  - Tag 2
---

## First Heading

Paragraph Content.

Set the post status

---
status: private
---

## First Heading

Paragraph Content.

Set the post author

---
author: John Doe
---

## First Heading

Paragraph Content.

Set the post date

---
date: 2022-04-16 10:30:42
---

## First Heading

Paragraph Content.

An implementation that uses all the supported keys

---
title: The post title
excerpt: The post excerpt
categories:
  - Category 1
  - Category 2
tags:
  - Tag 1
  - Tag 2
author: John Doe
date: 2022-04-16 10:30:42
status: private
slug: my-first-article
thumbnail: https://example.com/laptop-computer.png
thumbnail_alt: Laptop computer displaying the logo of WordPress
thumbnail_title: WordPress is a free and open-source content management system written in PHP
---

## First Heading

Paragraph Content.

Common parsing problems

The plugin may ignore all the defined Front Matter keys or specific Front Matter keys when:

The YAML format is not valid.
The Front Matter keys don’t exist.
The Front Matter values are not valid. (E.g. When the post date is specified in the wrong format, when the configured post status doesn’t exist.)

REST API

This plugin adds the following REST API endpoints.

List documents

Use this endpoint to read the Markdown document stored in the plugin.

Base route

/wp-json/ultimate-markdown-pro/v1/documents

Method

GET

URL Parameters

Name	Value	Required
document_id	The ID of the document that you want to retrieve. Leave this field empty to retrieve all the documents.	No

Import documents

With this endpoint, you can add Markdown documents in the plugin database or create posts in draft status.

Base route

/wp-json/ultimate-markdown-pro/v1/import

Method

POST

URL Parameters

Name	Value	Required
title	The title of the submitted document.	Yes
content	The content of the submitted document. The Markdown syntax is supported.	Yes

Additional Information

Uploads

The maximum number of files you can upload in a single upload operation is limited by the max_file_uploads directive defined in the php.ini file.

This directive’s value determines the maximum number of files that can be processed in the Tools menu during import operations.

Parsers

The plugin uses multiple libraries to convert Markdown to HTML and vice-versa. This table lists the plugin contexts and the related parsers.

Context	Use	Parser
Markdown editor available in the Documents menu	Markdown to HTML	Defined in plugin settings using the Live Preview option under the Markdown Parsers section.
Export functionality available in the Documents menu	HTML to Markdown	HTML To Markdown for PHP
In the Tools menu, when “Posts” is selected as the destination of the import operation.	Markdown to HTML	Defined in plugin settings using the Bulk Import option under the Markdown Parsers section.
In the Tools menu, when “Posts” is selected as the source of an export operation.	HTML to Markdown	HTML To Markdown for PHP
Import Markdown section in the post editor sidebar	Markdown to HTML	Defined in plugin settings using the Editor option under the Markdown Parsers section.
Load Markdown section in the post editor sidebar	Markdown to HTML	Defined in plugin settings using the Editor option under the Markdown Parsers section.
Submit Markdown section in the post editor sidebar	Markdown to HTML	Defined in plugin settings using the Editor option under the Markdown Parsers section.
Export Markdown section in the post editor sidebar	HTML to Markdown	HTML To Markdown for PHP

Supported Markdown file extensions

The import form available in the Tools menu supports Markdown files with the following extensions:

.md
.markdown
.mdown
.mkdn
.mkd
.mdwn
.mdtxt
.mdtext
.text
.txt

Credits

This product makes use of the following resources:

DOMPurify licensed under the Apache License Version 2.0
Marked licensed under the MIT License
Select2 licensed under the MIT License
Parsedown licensed under the MIT License
Cebe Markdown licensed under the MIT License
League\CommonMark licensed under the BSD 3-Clause License
Composer licensed under the MIT License
HTML To Markdown for PHP licensed under the MIT License
FrontYAML licensed under the MIT License

Ultimate Markdown Pro

Table of Contents

Introduction

Installation

Post Sidebar Sections

Import Markdown

Load Markdown

Submit Markdown

Export Markdown

Dedicated menus

Documents

Create a document

Download a document

Categories

Create a category

Tools

Import

Importing to Documents

Importing to Posts

Export

Export from Documents

Export from Posts

Image Handling

Including Publicly Available Images in Markdown Files

How the Plugin Technically Handles Image Imports

Importing Markdown Files with Local Images Using a ZIP Archive

How the Plugin Technically Handles ZIP Files with Local Images

Best Practices

Choosing the Right Method

Front Matter

Using Front Matter

Supported keys

Examples

Set the post title

Set the post excerpt

Set the categories

Set the tags

Set the post status

Set the post author

Set the post date

An implementation that uses all the supported keys

Common parsing problems

REST API

List documents

Base route

Method

URL Parameters

Import documents

Base route

Method

URL Parameters

Additional Information

Uploads

Parsers

Supported Markdown file extensions

Credits