Use Markdown format with SilverStripe

Tweet

6 May 2012 | Howard Grigg | CMS, WYSIWYG | Supports v2.4, v2.3

2 1

 Source files (16 KB)

If you are sick of fumbling with TinyMCE but still want a way to include editable HTML styled content fields in the CMS then Markdown may be the answer.

I am somewhat of a Markdown nerd - not to the extent of the John Grubers or Merlyn Manns of this world but it is certainly my preferred method of writing anything which will end up on the web (I'm writing this post in Markdown). It is pretty easy to be able to use Markdown with SilverStripe - there is a Markdown Editor Field module for SilverStripe 3.0 which is much more full featured than my quick implementation but what I am about to show you is what I tend to use for SilverStripe 2.x.

What are we working towards?

Replacing the standard TinyMCE Content field with a textarea field that we can write markdown directly into. Each time the page is saved a HTML version is exported from the markdown and saved into the normal content field. The HTML version will be the version displayed on the front end. Markdown has a number of advantages and I find it much easier to write rather than fluffing around with a WYSIWYG.

Limitations

I don't use this super simple approach with clients just because most of them have never heard of Markdown and the TinyMCE field is much more appropriate for them. We lose the ability to link to a pageID so that if an internal page is moved around and the URL changes then the link in the Markdown will no longer be correct. Also I have not included a javascript Markdown syntax helper, mainly because it's just me who uses this and I don't need one.

The approach

Let's replace the main content field of all pages with a TextareaField ready for markdown. This process could easily be used for any field that you add in the CMS, popup or even front-end forms.

First of all we need to add a Text field to our model so that we have a place to store the raw Markdown that we write. So in your Page.php file have:

public static $db = array(
	'Markdown'	=>	'Text'
);

Then we need to replace the normal TinyMCE field with a plain TextareaField, so in the Page class in your Page.php file have:

public function getCMSFields() {
	$f = parent::getCMSFields();
	$f->removeFieldFromTab("Root.Content.Main", "Content");
	$f->addFieldToTab("Root.Content.Main", new TextareaField("Markdown","Content: (in Markdown format)", 20));
	return $f;
}

This code removes the standard TinyMCE content field (line 3), then adds a new TextareaField to edit the Markdown (line 4).

Once you have run /dev/build you will have a TextareaField that will save your Markdown content. The next step is to convert that to HTML and save it into the standard Content field so it will be displayed correctly by the website.

You will need to download a php parser for Markdown. I use Micelfs version on GitHub but there are other extended versions which include support for more or different syntaxes.

Once you have downloaded that you just need to upload the single markdown.php file to your server. You can just put it in your mysite/code folder.

Now we need to create a function that will parse the Markdown and save it as HTML each time we save the page. Another approach that you could do is have it saved only as Markdown then convert it to HTML each time the page is requested but that just seems silly.

In your Page.php file inside the Page class include the code:

function onBeforeWrite(){
	if($this->Markdown){
		include_once (Director::baseFolder() . '/mysite/code/markdown.php');
		$this->Content = Markdown($this->Markdown);
	}
	parent::onBeforeWrite();
}

This checks to see if there is any text in the Markdown field (line 2). Then it includes our downloaded markdown.php parser (line 3). It then sets the standard content field (that is normally edited using the TinyMCE field) to the output of the parser (line 4).

Now once you save it it will convert your Markdown to HTML and save it in the normal Content field so you don't need to change any of your templates.

Hope this is found to be useful and it's a super simple demonstration of how to get additional php code into a SilverStripe project. Any questions, follow-up or improvements would be very welcome in the comments.