While I will always be a developer at heart (have been more many, many years!) by day I lead an enterprise architecture team consisting of four enterprise architects and four enterprise applications developers (along with an assortment of other contractors that help out with various development and architectural "hygiene" tasks). One area I continually push my team to excel in is communication.
One of the various conduits we make use of is a WordPress-based site (hosted internally within our organization). For various reasons I won’t go into in this post, we chose WordPress over SharePoint as the repository for the various guidance documents our team produces. Along the way, several other teams have also adopted WordPress for their respective team blogs.
While WordPress is a very effective platform for creating and serving up information we have found that there is beauty to be found in the simplicity of markdown. And while there are one or two markdown plugins available for WordPress we haven’t had much luck with any of them (e.g. we’ve found that posts published via Live Writer or the built-in WordPress editor tend to end up with markdown tags embedded within them — or markdown posts end up with random HTML tags within the markdown). One markdown plugin we haven’t tried is the one provided with the Jetpack plugin for WordPress. This is because our WordPress sites are hosted internally and are not available on the "public internet" – which is something Jetpack requires.
So, to make a long story short, the idea came up of having something that could take markdown files from within Visual Studio Team Services (VSTS), convert them to HTML and publish them to a WordPress blog. Several weeks and a lot of experimentation later, I’m happy to say that the first (preview) release of the Markdown to WordPress extension has been published!
This extension provides a build task that can publish markdown files stored within a VSTS Git repo to a WordPress blog. If you’ve ever wanted to source your blog from a version control system, specifically VSTS, then this extension can help you out.
With this extension, we can author guidance pages as markdown files directly within the web-based interface for VSTS (or any number of other external tools), save the file(s) and have a continuous build kick off and publish the document to a WordPress site within seconds. It’s a win-win… we get the simplicity of markdown along with the various advantages that come along with VSTS (such as version control, history, diff capabilities, etc.). Very cool!
The Build Task
Setting up the build task is fairly straight forward. Once added, the majority of the parameters are grouped into two major categories: WordPress Settings and Team Services Settings. You can get an idea of the parameters by taking a look at the screenshot below:
Take note of the Mapping File parameter above. This is a JSON file that contains various metadata about the markdown files that have been published to WordPress. Among other bits of information, it contains the WordPress ID that maps a particular markdown file to a specific post within WordPress. This allows you to make changes to a markdown file and publish it again without creating duplicate posts.
Another parameter to note is Embed External Images. The build task does not upload image files to WordPress. Rather, it embeds the images using the Data URI Scheme. This has some distinct advantages as well as a few disadvantages. On the plus side, it greatly simplifies the process of embedding images when publishing the markdown to WordPress. On the other hand, it will increase the size of your published posts. To alleviate some of this, the Embed External Images option is set to off by default. Essentially this just means that any images sourced outside of your blog (i.e. from another site) will be linked to directly. The image will not be embedded or uploaded to WordPress.
To get more information about the remaining build task parameters, refer back to the Markdown to WordPress extension page.
While there are still some kinks to be worked out (refer to the Notes, Known Issues and Other Information section on the extension page) the build task is functional and can be used now. We will continue to make improvements and fix any issues that get reported along the way.
If this is something that might be of use to you please check it out and let us know what you think. If you have any suggestions for additional features or run into any issues, let us know in the comments section below.
Also, I am planning on publishing the source code to GitHub at some point, just not yet :-) Most likely once it comes out of "preview".
P.S. This blog post was created in markdown and published using this build task.