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
Please use the installation guide for installation 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 with 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 generate the post content from a provided text string.
- Open the Submit Markdown section
- Enter text with the Markdown markup 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 Download icon (the first icon of the group) available in the last 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
Import
Use this menu to generate documents from Markdown files available on your computer.
- Visit the Import menu
- Click the Choose Files button to select one or more files available on your computer
- Click the Upload files and import button to execute the operation
- At the end of the process, the plugin will provide you a list of the generated documents in a dismissible notice
Import (Classic)
This menu allows you to generate posts in draft status from Markdown files available on your computer.
- Visit the Import menu
- Click the Choose Files button to select one or more files available on your computer
- Click the Upload files and import button to execute the operation
- At the end of the process, the plugin will provide you a list of the generated documents in a dismissible notice
Configure the post type
You can define the post type of the generated posts with the Advanced -> Post Type option available in the Options menu.
Important note
We recommend using this menu only if the Classic Editor plugin is active in the targeted post type. Using this menu with the Block Editor will generate a single Classic Block instead of separate blocks for all the post elements.
The correct import workflow to use with the block editor active is as follows:
- Create documents from existing Markdown files with the Import menu
- Generate the post content from a selected document with the Load Markdown section in the post sidebar
Export
The Export menu allows you to mass export plugin documents or WordPress posts as compressed archives of Markdown files.
Export documents
To export the documents stored in the plugin, proceed as follows:
- Set the Source selector to Documents
- Click the Export Data button
Export posts
Use the procedure below to export posts, pages, or custom post types:
- Set the Source selector to Posts
- Open the Advanced section
- Select the post types used as a source with the Post Types option
- Select the categories of posts used as a source with the Categories option. Leave this option empty to use all the categories as a source.
- Select the tags used as a source with the Tags option. Leave this option empty to use all the tags as a source
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 processed in the Import and Import (Classic) menus.
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 | Language | Parser |
|---|---|---|---|
| Markdown editor available in the Documents menu | Markdown to HTML | JavaScript | Marked |
| Export functionality available in the Documents menu | HTML to Markdown | PHP | HTML To Markdown for PHP |
| In the upload process of the Import (Classic) menu | Markdown to HTML | PHP | Defined in the plugin settings. The options are: Parsedown, Cebe Markdown. |
| In the Export menu, when “Posts” is selected as the source. | HTML to Markdown | PHP | HTML To Markdown for PHP |
| Import Markdown section in post editor sidebar | Markdown to HTML | JavaScript | Marked |
| Submit Markdown section in the post editor sidebar | Markdown to HTML | JavaScript | Marked |
| Export Markdown section in the post editor sidebar | HTML to Markdown | PHP | HTML To Markdown for PHP |
Supported Markdown file extensions
The forms available in the Import and Import (Classic) menus support 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
- Composer licensed under the MIT License
- HTML To Markdown for PHP licensed under the MIT License
- FrontYAML licensed under the MIT License