In this article, I will show you how to create ready-to-be-published WordPress articles from plain-text files using Markdown and Front Matter.
By applying the described methods, you can improve your blog writing workflow and save the time normally required to manually prepare your post with manual edits on the WordPress editor.
Why Markdown and Front Matter
Markdown is a lightweight markup language used to create HTML content, while Front Matter is a method to configure the post settings by proving key-value pairs. By combining these two technologies, you can create articles ready for the web from a plain-text file.
Front Matter Basics
Front Matter is an optional section of valid YAML which should be placed at the beginning of the document and enclosed inside the --- delimiters.
In this basic example, a Front Matter block is used to set the article title and excerpt.
--- title: Hello World excerpt: The excerpt of the Hello World article ---
Let’s see another example. In this documentation page from the Gatsby open source framework, Front Matter is used to configure the article slug, data, and title.
--- slug: "/my-first-blog-post" date: "2022-11-24" title: "My first blog post" ---
Advantages of Front Matter
Articles on the web are not only composed of content. Meta data are always associated with the articles and used on the front end or to set parameters of the CMS in use. Front Matter allows you to integrate this information in a plain-text document written with the Markdown syntax.
Front Matter and WordPress
There is no native support for Front Matter in WordPress, but you can add this functionality with the Ultimate Markdown plugin or use external integrations like with the Postmark WP-CLI command.
Let’s see both these solutions in details in the next sections.
Create Articles From a Front Matter Enabled Markdown Document With a Dedicated WordPress Plugin
Ultimate Markdown is a plugin that allows you to upload Markdown files in WordPress.
With the Front Matter keys supported by Ultimate Markdown, you can specify the title of the post, the category, the tags, the permalink, the featured image, and more.
In the example below, you can see how to assign the title, permalink, featured image, and tag to an article.
--- title: The post title excerpt: The post excerpt status: private --- ## First Heading Paragraph Content.
The advantage of using Front Matter in this context is that you can go directly from a Markdown file to a ready-to-be-published WordPress article with no additional steps.
Advanced Usage
The complete list of Front Matter keys supported by Ultimate Markdown is available in this section of the plugin documentation. If you already have the Pro version of the plugin, you can use this list to experiment with all the keys and see the effect in the generated WordPress post.
In this example, I use all the available keys to configure many post settings.
--- title: Exploring Architectural Marvels Around the World excerpt: Embark on a global journey as we unravel the architectural wonders that defy imagination and showcase human creativity in breathtaking structures. categories: - Architecture - ravel Destinations tags: - Landmarks - Structural Design author: Emily Larson date: 2023-07-22 09:00:00 status: private slug: exploring-architectural-marvels-around-the-world thumbnail: https://example.com/taj-mahal.png thumbnail_alt: Taj Mahal thumbnail_title: Taj Mahal: A Timeless Icon of Mughal Architecture ---
Note that in this example, I also defined a featured image with the related alt and title attributes. When a valid URL for a featured image is provided, the plugin will download the image, upload it to the WordPress media library, and assign it to the post.
Send Markdown Documents With Front Matter Keys With the REST API
If your articles are managed or created with external software, you can send the Markdown documents to the WordPress website. This can be done using a dedicated Ultimate Markdown REST API endpoint.
Let’s see a practical example of a web form that sends articles to WordPress using the JavaScript Fetch API.
First, create an HTML document with the form used to create and submit the data.
<!DOCTYPE html>
<html xmlns="https://www.w3.org/1999/html">
<head>
<title>Send Markdown Document</title>
</head>
<body>
<h1>Send Document</h1>
<p>Send a Markdown document to WordPress.</p>
<div id="form">
<label for="title">Title</label>
<input type="text" id="title"/>
<label for="content">Content</label>
<textarea id="content"/></textarea>
<button id="submit-markdown">Send Document</button>
</div>
<script src="send-document.js"></script>
</body>
</html>
The form above includes the form field used by the user to add the post title and content. At the end of the form, the JavaScript script used to send the data to the WordPress REST API is added.
Next, create a JavaScript file with the code used to send the Markdown document to the REST API endpoint.
function submit() {
// Save the content of the "#title" and "#content" elements in constants
const title = document.getElementById('title').value;
const content = document.getElementById('content').value;
// Save the REST API key defined in the plugin settings in a constant
const rest_api_key = '3aff11ee37f3e83dd6b442ee349cd37c059799f5641518c6f34f4535aeeeb5031b50bdf61d528a9bec222e925bb195c49659e14dd7e9cc803fda9f387f3bc9f0775bb139346097e38b2f870411b25247ae5f06481b7aeac11f7cf825bd620730a8385fe2bc04c0f4647af60e292efde57a4d488e5114e32b01f6e01b0af42289';
const data = {
title: title,
content: content,
rest_api_key: rest_api_key,
};
// Send the data to the API endpoint
fetch(
'https://localhost/ws/wordpress-tp/wp-json/ultimate-markdown-pro/v1/import',
{
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify(data),
}).then(response => response.json()).then(result => {
// Handle the response from the API
console.log('API response:', result);
}).catch(error => {
// Handle any errors that occur during the request
console.error('Error:', error);
});
}
// Click event handler for the "#submit-markdown" button that calls the submit() function
document.getElementById('submit-markdown').addEventListener('click', submit);
This script does what follows:
- It attaches an event handler to the submit button of the form.
- It gets the title and content of the Markdown document from the input fields.
- It configures the REST API key used to authenticate the request. Note that the REST API key value should be copied from the related setting in the Ultimate Markdown options named REST API Key.
- It creates a JSON object with the Markdown document and the Front Matter keys. This object is the payload of the post request.
- It uses the fetch API to send the Markdown document to the REST API endpoint created by Ultimate Markdown.
You can verify if the script work by checking the documents listed in the Documents menu of WordPress. Note that each time you submit the form, a new record is created.
Note: Before testing this example in your WordPress environment, set the REST API Authentication (Create) option to “REST API Key”. Then paste the value of the REST API Key option to the rest_api_key JavaScript constant used at the beginning of our script.
REST API Plugin Settings
From the plugin settings, you can further customize the behavior of the REST API endpoints and set the post type used as a destination for the submitted Markdown document, the REST API key used to authenticate the request, and more.
Sync Markdown Files With WordPress With This WP-CLI Command
By utilizing the WP-CLI command named Postmark, you can generate or modify posts, pages, and various other database entities of WordPress. This command operates by accepting a Markdown file or a directory containing multiple Markdown files.
This script supports Front Matter, which is used to set all the standard WordPress page/post properties. The list of supported Front Matter keys is available in this section of the item page on GitHub.
Basic Installation and Usage
This package can be installed with this command:
wp package install dirtsimple/postmark
This script is quite complex and with many options. As a consequence, for its usage, I recommend following the official documentation on GitHub.