Skip to main content

This site requires you to update your browser. Your browsing experience maybe affected by not having the most up to date version.

 

Module of the Month: Exit the WYSIWYG

This ‘Module of the Month’ discusses how SilverStripe CMS can be enhanced through the use of Markdown. By replacing the normal WYSIWYG editor with Markdownfield it can simplify the user experience and better ensure that modifications will not affect the structure of the page.

Read post

Welcome to module of the month, a showcase for new modules that are being built by our community. Every month, our blog highlights a new creation that has been developed by our community of contributors.

Editing in the CMS

The SilverStripe CMS by default is pretty powerful. But it has a downside. The content editor can easily make the whole layout of the website go haywire with a simple selection of a certain style in the wrong place, accidental removal of a closing tag, etc.

For more technical documentation writing, developers often use Markdown to write. The beauty of markdown comes from it’s simplicity. It is written in plain text while it’s output is still perfectly well readable html.

Some of your product owners, content authors and testers may have encountered this way of writing already if you’ve been using Jira for your projects, where comments and descriptions use markdown as well.

Our own Head of Product, Nicole Williams, recently got deeper into markdown as well, when updating the user documentation for SilverStripe:

Markdown wasn't a huge learning curve, I'm reasonably familiar from apps that use it like Slack/Trello. I found (lack of) preview the hardest part to adjust too. When you're learning, checking things are working as expected is valuable reassurance.

The MarkdownField

Now, what has this all to do with a Module of the Month? Everything, of course! The ability to use markdown in the CMS could be a great enhancement for the more tech-savvy content editors that want to be sure that the content they write is not going to break anything on the website. And that’s where markdownfield comes in.

With markdownfield, it’s easy to replace the normal WYSIWYG editor with a markdown editor, giving you, the developer or designer, more confidence that there won’t be any breaking formatting made by content editors in the CMS.

After installation, you can replace out the HTMLTextEditorField with MarkdownEditorField. It will present you with a very basic Textarea and two buttons. Edit and Preview.

Screenshot of content preview

Preview

Screenshot of content preview close-up

And a preview-pane will also render straight away correctly, so no more trial-and-error on getting it right with submitting first, then pray for the best. Nicole her greatest annoyance with Markdown is resolved.

And yes, no worries, your preview pane will work just as you expected, so in the CMS besides just the preview, it even shows how it’ll look on the website.

Screenshot of embedded URL video and code

Screenshot from SilverStripe 4, SilverStripe 3 works the same though. The red marks are the browser not understanding it’s not normal text. Nothing to worry about!

SilverStripe 3

Now, to get your markdown correctly rendered on your website, there’s a small thing you’ll have to do. Instead of using HTMLText or Text as your Content field, you’ll need to swap it out for an Markdown Content Field, e.g. MDContent of type MarkdownField, and use this everywhere in your template instead of $Content.

private static $db = array(
'MDContent' => 'MarkdownField'
);

public function getCMSFields()
{
$fields = parent::getCMSFields();
$fields->removeByName(['Content']);
$fields->addFieldToTab('Root.Main', MarkdownEditorField::create('MDContent', 'Content'));
return $fields;
}

Now, everywhere where you put $MDContent in your template, you’ll get the rendered output

Screenshot of content preview

E.g.

  <body class="container">
<div class="content">
$MDContent
</div>
</div>

SilverStripe 4

If you are using SilverStripe 4 however, you’ll get a much fancier interface even. 

Screenshot of SilverStripe 4 interface

And to top it off, the side by side view is awesome!Screenshot of SilverStripe 4 side-by-side

Besides a dedicated Markdown editor, I have not yet seen it being implemented this smooth and useful ever before in a SilverStripe editor.

The team working on this module are busy getting everything up to speed to work with SilverStripe 4. Most hiccups I encountered were resolved within the a day since I started making issues on GitHub. (Awesome turnaround and thumbs up for the folks in Sri Lanka!)

To get the content working in SilverStripe 4, the same process can be followed as for SilverStripe 3. Or...

Replace all HTML Editor fields

To replace all HTML Editor fields in the CMS with the Markdown Editor (SilverStripe 4 only), add

SilverStripers\markdown\db\MarkdownText:
markdown_as_base: true

In your config.yml, to replace all your ‘Content’ fields in the SiteTree to MarkdownText.

Conclusion

I personally find Markdown a lot friendlier to work with than a WYSIWYG editor, as it’s cleaner and less cluttering the view.

The markdown style supported by default is the GitHub Flavoured Markdown, which extends on the standard markdown.

I’m very excited about this module and to be honest, I hope we can replace the WYSIWYG editor with Markdown in the near future. I know it won’t happen, but one can always hope, right?

As per usual, give it a try*, contribute and enjoy!

*: Better yet, let some content authors give it a try.

About the author
Simon Erkelens

Simon is a developer at SilverStripe. When not at work, he's writing other programs or focusses on one of his modules he wrote or co-wrote. Or writing new things.

As a real backend developer, he's usually staring at a dark screen with code only. Although every now and then, he can be convinced to work on some frontend things or testing.

In real life, he looks nothing like the cow in his avatar, but he does love cows (both alive and medium rare)

Post your comment

Comments

  • We have used this module on several projects now and it is great. I have to admit, in some ways I think I prefer it to the default WYSIWYG editor! It is also a much nicer alternative if working with content on objects uploaded via CSV.

    Posted by Morven Lewis-Everley, 02/11/2017 6:34am (7 years ago)

RSS feed for comments on this page | RSS feed for all comments