⚠️ DEPRECATION WARNING

This repository is no longer actively maintained.

An Embeddable JavaScript Markdown Editor

EpicEditor is an embeddable JavaScript Markdown editor with split fullscreen editing, live previewing, automatic draft saving, offline support, and more. For developers, it offers a robust API, can be easily themed, and allows you to swap out the bundled Markdown parser with anything you throw at it.

Why

Because, WYSIWYGs suck. Markdown is quickly becoming the replacement. GitHub, Stackoverflow, and even blogging apps like Posterous are now supporting Markdown. EpicEditor allows you to create a Markdown editor with a single line of JavaScript:

var editor = new EpicEditor().load();

Quick Start

EpicEditor is easy to implement. Add the script and assets to your page, provide a target container and call load().

Step 1: Download

Download the latest release or clone the repo:

$ git clone git@github.com:OscarGodson/EpicEditor

Step 2: Install

Copy EpicEditor/epiceditor/ onto your webserver, for example to /static/lib/epiceditor.

$ scp -r EpicEditor/epiceditor you@webserver:public_html/static/lib/

You can of course customize this step for your directory layout.

Step 3: Create your container element

<div id="epiceditor"></div>

Alternately, wrap an existing textarea to load the contents into the EpicEditor instance.

<div id="epiceditor"><textarea id="my-edit-area"></textarea></div>

Step 4: Add the epiceditor.js file

<script src="/static/lib/epiceditor/js/epiceditor.min.js"></script>

Step 5: Init EpicEditor

EpicEditor needs to know where to find its themes, so it needs to be told its install directory at init.

var editor = new EpicEditor({basePath: '/static/lib/epiceditor'}).load();

API

EpicEditor([options])

The EpicEditor constructor creates a new editor instance. Customize the instance by passing the options parameter. The example below uses all options and their defaults:

var opts = {
  container: 'epiceditor',
  textarea: null,
  basePath: 'epiceditor',
  clientSideStorage: true,
  localStorageName: 'epiceditor',
  useNativeFullscreen: true,
  parser: marked,
  file: {
    name: 'epiceditor',
    defaultContent: '',
    autoSave: 100
  },
  theme: {
    base: '/themes/base/epiceditor.css',
    preview: '/themes/preview/preview-dark.css',
    editor: '/themes/editor/epic-dark.css'
  },
  button: {
    preview: true,
    fullscreen: true,
    bar: "auto"
  },
  focusOnLoad: false,
  shortcut: {
    modifier: 18,
    fullscreen: 70,
    preview: 80
  },
  string: {
    togglePreview: 'Toggle Preview Mode',
    toggleEdit: 'Toggle Edit Mode',
    toggleFullscreen: 'Enter Fullscreen'
  },
  autogrow: false
}
var editor = new EpicEditor(opts);

Options

<table cellspacing="0"> <tr> <th>Option</th> <th>Description</th> <th>Default</th> </tr> <tr> <td><code>container</code></td> <td>The ID (string) or element (object) of the target container in which you want the editor to appear.</td> <td><code>epiceditor</code></td> </tr> <tr> <td><code>textarea</code></td> <td>The ID (string) or element (object) of a textarea you would like to sync the editor's content with. On page load if there is content in the textarea, the editor will use that as its content.</td> <td></td> </tr> <tr> <td><code>basePath</code></td> <td>The base path of the directory containing the <code>/themes</code>.</td> <td><code>epiceditor</code></td> </tr> <tr> <td><code>clientSideStorage</code></td> <td>Setting this to false will disable localStorage.</td> <td><code>true</code></td> </tr> <tr> <td><code>localStorageName</code></td> <td>The name to use for the localStorage object.</td> <td><code>epiceditor</code></td> </tr> <tr> <td><code>useNativeFullscreen</code></td> <td>Set to false to always use faux fullscreen (the same as what is used for unsupported browsers).</td> <td><code>true</code></td> </tr> <tr> <td><code>parser</code></td> <td>[Marked](https://github.com/chjj/marked) is the only parser built into EpicEditor, but you can customize or toggle this by passing a parsing function to this option. For example:<br><code>parser: MyCustomParser.parse</code></td> <td><code>marked</code></td> </tr> <tr> <td><code>focusOnLoad</code></td> <td>If <code>true</code>, editor will focus on load.</td> <td><code>false</code></td> </tr> <tr> <td><code>file.name</code></td> <td>If no file exists with this name a new one will be made, otherwise the existing will be opened.</td> <td>container ID</td> </tr> <tr> <td><code>file.defaultContent</code></td> <td>The content to show if no content exists for a file. NOTE: if the <code>textarea</code> option is used, the textarea's value will take precedence over <code>defaultContent</code>.</td> <td></td> </tr> <tr> <td><code>file.autoSave</code></td> <td>How often to auto save the file in milliseconds. Set to <code>false</code> to turn it off.</td> <td><code>100</code></td> </tr> <tr> <td><code>theme.base</code></td> <td>The base styles such as the utility bar with the buttons.</td> <td><code>themes/base/epiceditor.css</code></td> </tr> <tr> <td><code>theme.editor</code></td> <td>The theme for the editor which is the area you type into.</td> <td><code>themes/editor/epic-dark.css</code></td> </tr> <tr> <td><code>theme.preview</code></td> <td>The theme for the previewer.</td> <td><code>themes/preview/github.css</code></td> </tr> <tr> <td><code>button</code></td> <td>If set to <code>false</code> will remove all buttons.</td> <td>All buttons set to <code>true</code>.</td> </tr> <tr> <td><code>button.preview</code></td> <td>If set to <code>false</code> will remove the preview button.</td> <td><code>true</code></td> </tr> <tr> <td><code>button.fullscreen</code></td> <td>If set to <code>false</code> will remove the fullscreen button.</td> <td><code>true</code></td> </tr> <tr> <td><code>button.bar</code></td> <td>If <code>true</code> or <code>"show"</code>, any defined buttons will always be visible. If <code>false</code> or <code>"hide"</code>, any defined buttons will never be visible. If <code>"auto"</code>, buttons will usually be hidden, but shown if whenever the mouse is moved.</td> <td><code>"auto"</code></td> </tr> <tr> <td><code>shortcut.modifier</code></td> <td>The key to hold while holding the other shortcut keys to trigger a key combo.</td> <td><code>18</code> (<code>alt</code> key)</td> </tr> <tr> <td><code>shortcut.fullscreen</code></td> <td>The shortcut to open fullscreen.</td> <td><code>70</code> (<code>f</code> key)</td> </tr> <tr> <td><code>shortcut.preview</code></td> <td>The shortcut to toggle the previewer.</td> <td><code>80</code> (<code>p</code> key)</td> </tr> <tr> <td><code>string.togglePreview</code></td> <td>The tooltip text that appears when hovering the preview icon.</td> <td><code>Toggle Preview Mode</code></td> </tr> <tr> <td><code>string.toggleEdit</code></td> <td>The tooltip text that appears when hovering the edit icon.</td> <td><code>Toggle Edit Mode</code></td> </tr> <tr> <td><code>string.toggleFullscreen</code></td> <td>The tooltip text that appears when hovering the fullscreen icon.</td> <td><code>Enter Fullscreen</code></td> </tr> <tr> <td><code>autogrow</code></td> <td>Whether to autogrow EpicEditor to fit its contents. If autogrow is desired one can either specify <code>true</code>, meaning to use default autogrow settings, or an object to define custom settings</td> <td><code>false</code></td> </tr> <tr> <td><code>autogrow.minHeight</code></td> <td>The minimum height (in pixels) that the editor should ever shrink to. This may also take a function that returns the desired minHeight if this is not a constant, or a falsey value if no minimum is desired</td> <td><code>80</code></td> </tr> <tr> <td><code>autogrow.maxHeight</code></td> <td>The maximum height (in pixels) that the editor should ever grow to. This may also take a function that returns the desired maxHeight if this is not a constant, or a falsey value if no maximum is desired</td> <td><code>false</code></td> </tr> <tr> <td><code>autogrow.scroll</code></td> <td>Whether the page should scroll to keep the caret in the same vertical place while autogrowing (recommended for mobile in particular)</td> <td><code>true</code></td> </tr> </table>

load([callback])

Loads the editor by inserting it into the DOM by creating an iframe. Will trigger the load event, or you can provide a callback.

editor.load(function () {
  console.log("Editor loaded.")
});

unload([callback])

Unloads the editor by removing the iframe. Keeps any options and file contents so you can easily call .load() again. Will trigger the unload event, or you can provide a callback.

editor.unload(function () {
  console.log("Editor unloaded.")
});

getElement(element)

Grabs an editor element for easy DOM manipulation. See the Themes section below for more on the layout of EpicEditor elements.

• container: The element given at setup in the options.
• wrapper: The wrapping <div> containing the 2 editor and previewer iframes.
• wrapperIframe: The iframe containing the wrapper element.
• editor: The #document of the editor iframe (i.