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.
Preview
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 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
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.
And to top it off, the side by side view is awesome!
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: trueIn 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.
Post your comment
Comments
Posted by Morven Lewis-Everley, 02/11/2017 6:34am (6 years ago)
No one has commented on this page yet.
RSS feed for comments on this page | RSS feed for all comments