I spent an unreasonable amount of time trying to find the best way to use Markdown to publish within WordPress. I had a simple set of goals:
- Write posts in plain text Markdown.
- Edit posts in plain text Markdown (meaning the Markdown is preserved; there is no conversion to another format upon publishing).
- Render plain text Markdown posts as HTML for readers of the site (of course).
The frustrating quest to find a Markdown plugin that met these basic requirements led me to consider writing one from scratch, or even switching to another blogging system that prioritized Markdown usage (I would have chosen Pelican).
One option I encountered was the Jetpack plugin which, among a multitude of other free and premium features, offers Markdown support. But while I have no fundamental issues with Jetpack, I avoided it initially. It required a WordPress.com account, it noticeably slowed down the administration panel, and it seemed like overkill for such a specific purpose.
Then I discovered Offline Mode. It eliminates the external account requirement, introduces no latency that I could detect, and research indicates it is safe to use in production.
Combining the working Offline Mode with the Classic Editor plugin, I achieved my Markdown publishing goals. To do the same:
- Install the Classic Editor plugin. It is available directly or via the “Add New” link under the Plugins section of the WordPress administration panel.
- Install the Jetpack plugin. Ditto.
- Enable Jetpack’s Offline Mode by adding this line to your WordPress installation’s
wp-config.php:
define( 'JETPACK_DEV_DEBUG', true );
- The Jetpack documentation details an alternative method to enable Offline Mode through the use of a plugin (meaning, you could add a call to your theme’s
functions.phpand achieve the same outcome). I was unable to get this method to work correctly. Jetpack displayed a notification that it was in Offline Mode, but Markdown support was non-functional. I would prefer this method if it worked, but since it doesn’t, my recommendation is the debug constant above. - Navigate to
Jetpack - Settings - Writing - Composingwithin the WordPress administration panel and enable the “Write posts or pages in plain-text Markdown syntax” option.
This solution is not perfect, but it is officially supported and free of hacks.
Miscellany
- Automattic is moving WordPress away from a plain text approach with the Gutenberg editor. The project’s goals are wider than just the writing experience, and I can imagine it being useful for a certain audience. I am not a member of that audience.
- It would be nice if the Markdown functionality was extracted from Jetpack and offered as a standalone plugin. It’s technically feasible, but Automattic shut down attempts to break out functionality like this. Others that were not shut down appear abandoned. For the stronger likelihood of stability and compatibility, I prefer the above solution.
- Jetpack’s Markdown support allows for the one tweak to the original Markdown syntax that I love: using triple backticks to create fenced code blocks (similar to GitHub Flavored Markdown).
- I have not extensively tested external publishing tools, but Ulysses provides the option to send raw Markdown to WordPress. Thus, I can continue to use it as my writing tool of choice.
- Quite ironically, I discovered the Offline Mode enablement method bug while attempting to publish this post from its Markdown source. After the time spent debugging that problem, I’m once again considering moving to Pelican.