For those who’ve not come across Markdown, it’s a way of using simple keyboard characters in a text file to indicate formatting. For example **this would be bold**.

WordPress uses Markdown for the README files that accompanies each plugin – this same file is used to display the plugin details on the WordPress site. Therefore, as a plugin author, I am required to produce Markdown format files.

At the moment, because I want to have my plugin details on my site as well, I copy and paste the README file to a WordPress post and re-format it. Now, you can change WordPress to use Markdown, but it requires switching off the standard editor as otherwise it will modify the results.

One of the authors of Markdown, John Gruber, provides conversion scripts in Perl, as well as instructions for modifying WordPress. What I would ideally like, though, is a way to display README files on my site, as required. There is a plugin that will already do this but it does the conversion itself and, well, not very well. The results are iffy to say the least.

To make matters worse, WordPress’ implementation of Markdown does not match the standard design.

As with many of my plugins, the need to be able to do something myself has lead me to write a solution. Michel Fortin has converted John Grubers script to work under PHP and, using this as a basis, I am creating a plugin that will display WordPress format README files in a post.

I’m still working on it, but the principle is that I read in the file and, first, convert the WordPress format to standard Markdown format. From there I can use Michel’s script to do the final conversion. So far, it’s looking good and I’m spending time now adding extra features, such as the ability to miss out README sections (for instance, the installation instuctions) – otherwise, the README is displayed as it is in the actual file. It finds WordPress username and tags and adds automatic links and I’m going to add compatibility with my Simple Content Reveal plugin, so that each section can be collapsed and revealed.

I’ve already had to speak to Michel about it after having some initial issues, and he’s been very good and helped me out.

Look out for it in the coming weeks!