>>> charlesleifer.com

Using markItUp to implement a simple browser-based reST editor

August 23, 2010 23:53 / 0 comments / javascript markitup restructuredtext

I'd like to write about an awesome jQuery-powered markup editing toolkit called markItUp. I have tinkered with tinymce and CKEditor, and while they both get the job done, there are some definite drawbacks to a browser-based wysiwyg editor:

  • they're heavy. who wants this?

tinymce bling

  • it's a blackbox - there may be hooks for altering the outputted html, but the expectation is that you turn the thing on and let it run

  • what if your target output format is not html?

markItUp takes the opposite path by providing almost no implementation, instead leaving it up to the developer to build out the features he or she wants using a handful of well-thought-out callbacks. There is no built-in wysiwyg support, you're still dealing with raw markup, what markItUp does is it makes it really easy to write formatting helpers.

Here is an example of how we're using it to generate reStructuredText on readthedocs.org, our djangodash site:

For our purposes, it was unrealistic to think about implementing the full range of reST directives/syntax - so we went with something pared-down that could be easily customized.

markItUp made this extremely easy. I started with the markdown example on the project's site, since that is the format I was most familiar with already. All that was needed was a few javascript callbacks and some css for the images, collectively called a 'markup set'. The javascript portion is simple a dictionary of buttons with callbacks, where the callbacks handle things like 'openWith' or 'replaceWith'. The h3 button would then look something like this:

{name:'Heading 3', openWith:'### ', placeHolder:'Your title here...' }

This simply takes whatever you've got highligted and prepends a few hashes to denote h3 (in markdown syntax), or alternatively drops in the placeholder text and highlights it.

To do something like indent, for a code sample perhaps, you can provide a function that takes as its args an object which gives you access to the selected text, the caret position, scroll position, etc. Our indent button operates on the selected text:

replaceWith: function(markItUp) {
    text_block = markItUp.selection || markItUp.placeHolder;
    indented = '';
    $.each(text_block.split('\n'), function(idx, text) {
        indented += '    ' + text + '\n';
    });
    return indented;
}

For our site, this stripped-down approach seems to be working pretty well. It definitely isn't a one-size-fits-all solution, but for cases where a wysiwyg editor doesn't make sense (or doesn't exist) and you want to support some format or markup, markItUp is a pretty great option.

Full source

Check out the javascript and css being used to power the above editor.

Links

Comments (0)

Commenting has been closed, but please feel free to contact me