Editor

A Better User Experience

MarkdownDeep includes a web-based JavaScript editor that makes it easy for your site's users to enter and manipulate Markdown content. If you've not seen it already, you can try it here.

The editor includes a toolbar for common editing commands, auto-indent capability, popup help for the Markdown syntax (both standard Markdown and Markdown Extra) and a resize bar for resizing the editor.

The editor comes in two parts:

  • MarkdownDeepEditorUI - a complete jQuery based editor UI.
  • MarkdownDeepEditor - the core editor functionality.

MarkdownDeepEditorUI

If you're already using jQuery (or you don't mind adding it), this is the easiest way to add the Markdown editor to your site.

Unlike most jQuery plugins, MarkdownDeepEditorUI is not completely decoupled from the HTML.
Because the Markdown editor has a toolbar above the text area and resize bar below, we wanted to insert this content as the page loaded - to prevent the page jumping around after it's loaded.

For this reason, MarkdownDeepEditorUI is a little different from most other jQuery plugins:

  1. Copy the supplied js, css, png and htm files to your server. Depending where you place these files on your server, you might need to update the image urls in the css file.

  2. Update your page to reference jQuery, the MarkdownDeep library and the MarkdownDeep css file (again, you might need to change the paths).

    <link rel="stylesheet" href="mdd_styles.css" 
    <script type="text/javascript" src="jQuery-1.4.2.min.js">
    <script type="text/javascript" src="MarkdownDeepLib.min.js">
    

    NB: MarkdownDeepLib.min.js is a packaged, minified version of MarkdownDeep.js, MarkdownDeepEditor.js and MarkdownDeepEditorUI.js. For debugging, you can reference these three files instead.

  3. Insert the Markdown editor into your page like this:

    <div class="mdd_toolbar"></div>
    <textarea cols=50 rows=10 class="mdd_editor"></textarea>
    <div class="mdd_resizer"></div>
    <div class="mdd_preview"></div>
    

    Note: the associated divs are all optional and if missing, the plugin will create them. However... you might experience the page jumping around during load if you do this. ie: it's recommended to explicitly include them.

  4. Called the MarkdownDeep jQuery plugin to convert the textarea to a MarkdownEditor

     $("textarea.mdd_editor").MarkdownDeep({ 
        help_location: "/Content/mdd_help.html",
        disableTabHandling:true
     });
    

That's it, but some notes:

  • To set the initial content of the editor, place it in the textarea as per normal.

  • Modify, replace or override the styles in mdd_styles.css to control the final appearance.

Options

The following options can be passed to the plugin. Most of these are described in more detail with the related component, but they're listed here for convenience.

Plugin options

  • resizebar - boolean to include the resize bar (default:true)
  • toolbar - boolean to include the toolbar (default:true)
  • help_location - URL of where the help syntax reference should be loaded from (default:"mdd_help.html")

Transform options

  • SafeMode - boolean to enable only safe markup (default:false)
  • ExtraMode - boolean to enable MarkdownExtra extensions (default:true)
  • MarkdownInHtml - boolean to allow markdown in nested html (eg: divs) (default:false)
  • AutoHeadingIDs - boolean to automatically generate IDs for headings (default:false)
  • UrlBaseLocation - string base location of document (default:null)
  • UrlRootLocation - string root location of document (default:null)
  • NewWindowForExternalLinks - boolean to add target=_blank for links to urls starting with http:// (default:true)
  • NewWindowForLocalLinks - boolean to add target=_blank for local relative links (good for preview mode) (default:true)
  • NoFollowLinks - boolean to add rel=nofollow to all external links (default:false)
  • HtmlClassFootnotes - string, html class name for footnotes div (default:nul)
  • HtmlClassTitledImages - string, html div class name to wrap single paragraph images in (default:null)

Editor options/hooks

  • disableShortCutKeys - boolean, disables Ctrl+key shortcuts (default:false)
  • disableAutoIndent - boolean, disables auto tab-indent on pressing enter (default:false)
  • disableTabHandling - boolean, disables tab key working in the editor (default:false)
  • onPreTransform=function(editor, markdown)
  • onPostTransform=function(editor, html)
  • onPostUpdateDom=function(editor)

How the associated UI components are located

  1. If toolbar option true:

    • looks for a preceeding div.mdd_toolbar and load toolbar into it
    • if can't find the div, creates it
    • it's better to include the div in your markup as it prevents jumping on page load
  2. If resizerbar option is true:

    • looks for a div.mdd_resizer bar immediately after the text area
    • creates it can't be found
    • it's better to include the div in your markup as it prevents jumping on page load
  3. Looks for, or creates a div to show the HTML preview in:

    • looks for an attribute on the text area 'data-mdd-preview'. If found, uses it as a jQuery selector to locate a the preview div.
    • if data attribute not found, uses '.mdd_preview' - ie: looks for any class with mdd_preview class
    • if no preview div found by the above selector, creates one immediately after the resize bar

MarkdownDeepEditor

MarkdownDeepEditor implements the core editor functionality - but no real user interface. It performs three main tasks:

  1. Monitors a textarea for changes, transforms the entered text from Markdown to HTML and displays the HTML in a specified div.
  2. Provides handling for command short-cut keys and special keys such as tab/shift+tab and enter.
  3. Provides an API that can execute commands such as bold, italic, insert link etc... These commands are intended to be invoked from a toolbar or other UI that you provide.

To use the editor:

  1. Add script references to the MarkdownDeepEditor.min.js file (you'll need Markdown.min.js too):

    <script type="text/javascript" src="MarkdownDeep.min.js">
    <script type="text/javascript" src="MarkdownDeepEditor.min.js">
    
  2. On page load, create an Editor object, passing a input textarea and output div

    • input textarea: the text area where the user will enter Markdown.
    • output div: the div where the resulting HTML will be displayed

    eg:

    var editor=new MarkdownDeepEditor.Editor(textarea_element, output_div)
    
  3. Optionally set options:

    editor.disableShortCutKeys=true;    // Disable Ctrl+B, Ctrl+I etc...
    editor.disableAutoIndent=true;      // Disable auto indent on enter key
    editor.disableTabHandling=true;     // Disable tab/shift+tab for indent
    
  4. Optionally install hooks:

    editor.onPreTransform=function(editor, markdown) {}
    editor.onPostTransform=function(editor, html) {}
    editor.onPostUpdateDom=function(editor) {}
    
  5. Optionally create a toolbar/UI that calls editor.InvokeCommand(cmd) where cmd is one of:

    • "undo"
    • "redo"
    • "bold"
    • "italic"
    • "heading"
    • "code"
    • "ullist"
    • "ollist"
    • "indent"
    • "outdent"
    • "link"
    • "img"
    • "hr"
    • "h0"
    • "h1"
    • "h2"
    • "h3"
    • "h4"
    • "h5"
    • "h6"
    • "tab"
    • "untab"

    eg:

    editor.InvokeCommand("heading")
    

For more detail on using the core editor API, see the supplied MarkdownDeepUI.js file.