Very recently I am impressed by Markdown and in all my writing using Markdown. Thanks to Leanpub I am writing some of my books in Markdown and planning to write all my blog posts in Markdown too.
As a first step, I have installed WP-Markdown plugin for my wordpress blog and happily using that.
But I am a Joomla! guy and usually support my clients managing and building sites with Joomla!. I was searching an extension for Joomla! that can easily transform an article written in Markdown syntax to HTML. In JED, with keyword markdown nothing returned what I was searching. So I decided to develop a plugin.
Great Google helped me finding PHP Markdown, it has two files – I downloaded PHP Markdown Extra 1.2.5. This file contains a readme and license text, and the main file markdown.php. The file contains classes to transform markdown’d text into HTML using PHP. Based on this, I created a content plugin for Joomla! 2.5, and fololowing are the steps which you may use as a Tutorial.
Step 1: Create Plugin Structure
First create a plugin folder, markdown on your computer’s disk, say in Desktop. Then create a markdown.xml and markdown.php file in this folder.
If you have not download PHP Markdown Extra 1.2.5 already, download it and extract. Then rename the markdown.php file in it to markdown.class.php. Copy this markdown.class.php file to markdown folder you have already created.
That’s all we need for the files. Now we will add some codes to these files.
Step 2. Create XML manifest file
As you know, every Joomla! extension has a XML manifest file. We must have one for our plugin markdown too. Open manifest.xml file into your favorite text editor and add the following texts:
<?xml version="1.0" encoding="UTF-8"?>
<extension type="plugin" version="2.5" group="content" method="upgrade">
<name>Content - Markdown</name>
<creationDate>28-Dec-2012</creationDate>
<author>Suhreed Sarkar</author>
<authorEmail>suhreedsarkar@gmail.com</authorEmail>
<authorUrl>www.suhreedsarkar.com</authorUrl>
<copyright />
<license>http://www.gnu.org/licenses/gpl-2.0.html GNU/GPL</license>
<version>1.0</version>
<description>Shows texts in HTML that is written in Markdown syntax. Simply write your articles in Markdown using Editor - None. This plugin is developed based on <a href="http://michelf.ca/projects/php-markdown/">PHP Markdown</a> and credits goes to Michel for hist great work!</description>
<files folder="site">
<filename plugin="markdown">markdown.php</filename>
<filename>markdown.class.php</filename>
</files>
</extension>
Save the file when done adding the above code. Pretty clear. First we have added some elements to describe our plugin maekdown. In <files>…</files> block, we have mentioned tow files that are needed for this plugin. Among these two, markdown.php is the main file for markdown plugin.
Step 3. Create the main plugin file
We have already created our main plugin file markdown.php but yet not added any code to it. So, let us add few lines to it. Open markdown.php in your favorite text editor and write the following codes in this file:
<?php
/**
* @package Markdown
* @subpackage Base
* @author Suhreed Sarkar {@link www.suhreedsarkar.com}
* @author Created on 28-Dec-2012
* @license GNU/GPL
*/
//-- No direct access
defined('_JEXEC') || die('=;)');
jimport('joomla.plugin.plugin');
class plgContentMarkdown extends JPlugin
{
public function onContentPrepare($context, &$article)
{
require_once(dirname(__FILE__) . "/markdown.class.php");
$md = new MarkdownExtra_Parser;
$article->text = $md->transform($article->text);
return true;
}
}
As you see, nothing fancy here! I have just used others code. First, in the comment, added info about author – which is general practice and you may add such info when you are developing some Joomla! extension.
Next comes another standard line for Joomla! – defined('_JEXEC') || die('=;)'); which is to protect direct access. After adding this, nobody can type URL of the file directly and run it. This file must be loaded dynamically by index.php file of Joomla!.
Then we have imported Joomla! Plugin class by jimport('joomla.plugin.plugin'); line.
After all these conventional things, we started writing our class for the plugin. The class name is plgContentMarkdown which extends JPlugin object. Inside this class we have added function onContentPrepare that takes $context and $article as parameters. Actually all these are conventional and you will find in most Joomla! plugins the same way these codes are written.
Inside onContentPrepare function, we have added markdown.class.php file, and then created an instance of markdown parser by $md = new MarkdownExtra_Parser; line. By creating the instance, we got $md markdown object which has a transform method. So we have simply passed our $article->text to $md->transform() method. And that will convert the text into HTML.
That’s the main code of our plugin.
Step 4. Package it for installation
So we have created our plugin files and put it in a folder. It’s time to package it, and then install and user. Please be sure that you have 3 (three) files in markdown folder:
- markdown.xml
- markdown.php
- markdown.class.php
Once you see all these files are there and codes are added, simply compress the folder markdown by using WinZip or other compression utilty. After compressing the folder you get a zipped file named markdown.zip. That’s it! It’s your installation package for the plugin.
Step 5. Install the plugin
Login to your Joomla! Administration Panel as Super User. Then click Extensions > Extension Manager. That shows Extension Manager: Install screen.
Click on Browse button, select markdown.zip file and click Upload & Install button. That uploads and install the markdown and you see success message.
Congratulations! Your plugin is installed. Now you need to enable the plugin.
Step 6. Enable the plugin
In Joomla! aministration panel, click Extensions > Plug-in Manager. That shows Plug-in Manager: Plug-ins screen.
In the list of plug-ins, you will see our newly installed plugin Content – Markdown. Click on this plugin name and you see Plug-in Manager: Content – Markdown screen.
In Plug-in Manager: Content – Markdown screen, seelct Enabled in Status field, and then click Save & Close icon in the toolbar.
So, our plugin is now activated and it should work. But how do you know it works? Let’s add an article in Markdown syntax.
Step 7. Write an article in Markdown syntax
Our plugin is enabled and now on we will write our articles in Markdown. If you dont know markdown syntax (or forgot not using it for long time), check it at Daring Fireball.
Usually, for many Joomla! sites, WYSIWYG editors like TinyMCE or JCE are used as default editor. In Joomla! administration panel, go to Site > Global Configuration and make sure that Editor – None is selected in Default Editor field.
Once the default edito is changed, select Content > Article Manager > Add New Article. That shows Article Manager: Add New Article screen.
As you see, Article Text field shows no editor. Let us type following text in this box in Markdown synatx.
#Markdown Editor
Hello **markdown**. I am _writing_ it in markdown.
this is code example
<p>Code example</p>
You can also add incode codes like `<b>I am bold</b>` in markup.
This is a list
* item 1
* item 2
* item 3
You can get this plugin from [Joomla](http://www.joomla.org)
##Thank you all
I like Markdown very much.
This is an ordered list:
1. Item 1
2. Item 2
2. Item 3
2. Item 4 5 6
This is end of our markdown document.
Save an publish the article. Now our turn to see the result in frontend.
Step 8. View the result
Go to site’s frontend and see the result. It should look like the following screenshot.
As you see, the article is viewed as formatted HTML. We see unordered and ordered list, codes, images and links.
Now on you can write your articles in Markdown as it’s quick and easy.
Conclusion
It’s a quick demonstration of how to write a content plugin for Joomla! 2.5. The plugin we have demonstrated is very simple and used another library PHP Markdown. We have just shown how to use the method of that class and converted it to plugin for use in Joomla!. We can extend its functionalities in several ways:
- add parameters to plugin so that based on plugin configuration it can perform several tasks.
- convert the plugin is such a way so that it saves the article in converted HTML. Currently it saves the content in markdown (as is).
- create another editor plugin so that we can insert quick tags using toolbar in that editor.
Hope to write on those enhancements very soon.
You can download the plugin from this link.