Table of Contents
- Introduction
- Installation
- Post sidebar sections
- Dedicated menus
- 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.
Categories
The Categories menu allows you to create categories of documents. You can optionally use this feature to better organize large archives of documents.
Create a category
- Enter the Name of the category
- Select the Description of the category
- Click the Add Category button
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.
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