Barking up the DOM tree. A modular, progressive, and beautiful Markdown and HTML editor
Browser support includes every sane browser and IE9+.
Try out the demo!
- Small and focused
- Progressive, enhance a raw
<textarea>
- Markdown, HTML, and WYSIWYG input modes
- Text selection persists even across input modes!
- Built in Undo and Redo
- Entirely customizable styles
- Bring your own parsers
Look and feel is meant to blend into your designs
You can get it on npm.
npm install woofmark --save
Or bower, too.
bower install woofmark --save
Returns an editor object associated with a woofmark
instance, or null
if none exists for the textarea
yet. When woofmark(textarea, options?)
is called, woofmark.find
will be used to look up an existing instance, which gets immediately returned.
Adds rich editing capabilities to a textarea
element. Returns an editor object.
A method that's called by woofmark
whenever it needs to parse Markdown into HTML. This way, editing user input is decoupled from a Markdown parser. We suggest you use megamark to parse Markdown. This parser is used whenever the editor switches from Markdown mode into HTML or WYSIWYG mode.
woofmark(textarea, {
parseMarkdown: require('megamark')
});
For optimal consistency, your parseMarkdown
method should match whatever Markdown parsing you do on the server-side.
A method that's called by woofmark
whenever it needs to parse HTML or a DOM tree into Markdown. This way, editing user input is decoupled from a DOM parser. We suggest you use domador to parse HTML and DOM. This parser is used whenever the editor switches to Markdown mode, and also when .value() is called while in the HTML or WYSIWYG modes.
woofmark(textarea, {
parseHTML: require('domador')
});
If you're implementing your own parseHTML
method, note that woofmark
will call parseHTML
with either a DOM element or a Markdown string.
While the parseHTML
method will never map HTML back to the original Markdown in 100% cases, (because you can't really know if the original source was plain HTML or Markdown), it should strive to detokenize whatever special tokens you may allow in parseMarkdown
, so that the user isn't met with inconsistent output when switching between the different editing modes.
A test of sufficiently good-citizen behavior can be found below. This is code for "Once an input Markdown string is parsed into HTML and back into Markdown, any further back-and-forth conversions should return the same output." Ensuring consistent back-and-forth is ensuring humans aren't confused when switching modes in the editor.
var parsed = parseHTML(parseMarkdown(original));
assert.equal(parseHTML(parseMarkdown(parsed)), parsed);
As an example, consider the following piece of Markdown:
Hey @bevacqua I _love_ [woofmark](https://github.com/bevacqua/woofmark)!
Without any custom Markdown hooks, it would translate to HTML similar to the following:
<p>Hey @bevacqua I <em>love</em> <a href="https://github.com/bevacqua/woofmark">woofmark</a>!</p>
However, suppose we were to add a tokenizer in our megamark
configuration, like below:
woofmark(textarea, {
parseMarkdown: function (input) {
return require('megamark')(input, {
tokenizers: [{
token: /(^|\s)@([A-z]+)\b/g,
transform: function (all, separator, id) {
return separator + '<a href="/users/' + id + '">@' + id + '</a>';
}
}]
});
},
parseHTML: require('domador')
});
Our HTML output would now look slightly different.
<p>Hey <a href="/users/bevacqua">@bevacqua</a> I <em>love</em> <a href="https://github.com/bevacqua/woofmark">woofmark</a>!</p>
The problem is that parseHTML
doesn't know about the tokenizer, so if you were to convert the HTML back into Markdown, you'd get:
Hey [@bevacqua](/users/bevacqua) I _love_ [woofmark](https://github.com/bevacqua/woofmark)!
The solution is to let parseHTML
"know" about the tokenizer, so to speak. In the example below, domador
is now aware that links that start with @
should be converted back into something like @bevacqua
.
woofmark(textarea, {
parseMarkdown: function (input) {
return require('megamark')(input, {
tokenizers: [{
token: /(^|\s)@([A-z]+)\b/g,
transform: function (all, separator, id) {
return separator + '<a href="/users/' + id + '">@' + id + '</a>';
}
}]
});
},
parseHTML: function (input) {
return require('domador')(input, {
transform: function (el) {
if (el.tagName === 'A' && el.innerHTML[0] === '@') {
return el.innerHTML;
}
}
});
}
});
This kind of nudge to the Markdown compiler is particularly useful in simpler use cases where you'd want to preserve HTML elements entirely when they have CSS classes, as well.
Note that both megamark
and domador
support a special option called markers
, needed to preserve selection across input modes. Unless your parseHTML
function supports this option, you'll lose that functionality when providing your own custom parsing functions. That's one of the reasons we strongly recommend using megamark
and domador
.
Prefers to wrap code blocks in "fences" (GitHub style) instead of indenting code blocks using four spaces. Defaults to true
.
Enables Markdown user input mode. Defaults to true
.
Enables HTML user input mode. Defaults to true
.
Enables WYSIWYG user input mode. Defaults to true
.
Sets the default mode
for the editor.
Enables this particular instance woofmark
to remember the user's preferred input mode. If enabled, the type of input mode will be persisted across browser refreshes using localStorage
. You can pass in true
if you'd like all instances to share the same localStorage
property name, but you can also pass in the property name you want to use, directly. Useful for grouping preferences as you see fit.
Note that the mode saved by storage is always preferred over the default mode.
This option can be set to a method that determines how to fill the Markdown, HTML, and WYSIWYG mode buttons. The method will be called once for each of them.
woofmark(textarea, {
render: {
modes: function (button, id) {
button.className = 'woofmark-mode-' + id;
}
}
});
Same as options.render.modes
but for command buttons. Called once on each button.
If you wish to set up file uploads, in addition to letting the user just paste a link to an image (which is always enabled), you can configure options.images
like below.
{
// http method to use, defaults to PUT
method: 'PUT',
// endpoint where the images will be uploaded to, required
url: '/uploads',
// image field key, passed to bureaucracy, which defaults to 'uploads'
fieldKey: 'uploads',
// optional additional form submission data, passed to `bureaucracy`
formData: { description: 'A new image' },
// optional options for `xhr` upload request, passed to `bureaucracy`
xhrOptions: { headers: {} },
// optional text describing the kind of files that can be uploaded
restriction: 'GIF, JPG, and PNG images',
// should return whether `e.dataTransfer.files[i]` is valid, defaults to a `true` operation
validate: function isItAnImageFile (file) {
return /^image\/(gif|png|p?jpe?g)$/i.test(file.type);
}
}
woofmark
expects a JSON response including a results
property that's an array describing the success of each file upload. Each file's entry should include an href
and a title
:
{
results: [
{ href: '/images/new.jpg', title: 'New image' }
]
}
For more information on file uploads, see bureaucracy
.
Virtually the same as images
, except an anchor <a>
tag will be used instead of an image <img>
tag.
To set the formatting of the inserted attachment link, set options.mergeHtmlAndAttachment
; the default follows this format:
function mergeHtmlAndAttachment (chunks, link) {
var linkText = chunks.selection || link.title;
return {
before: chunks.before,
selection: '<a href="' + link.href + '">' + linkText + '</a>',
after: chunks.after,
};
}
The editor
API allows you to interact with woofmark
editor instances. This is what you get back from woofmark(textarea, options)
or woofmark.find(textarea)
.
Binds a keyboard key combination such as cmd+shift+b
to a method using kanye. Please note that you should always use cmd
rather than ctrl
. In non-OSX environments it'll be properly mapped to ctrl
. When the combo is entered, fn(e, mode, chunks)
will be called.
e
is the original event objectmode
can bemarkdown
,html
, orwysiwyg
chunks
is a chunks object, describing the current state of the editor
In addition, fn
is given a this
context similar to that of Grunt tasks, where you can choose to do nothing and the command is assumed to be synchronous, or you can call this.async()
and get back a done
callback like in the example below.
editor.addCommand('cmd+j', function jump (e, mode, chunks) {
var done = this.async();
// TODO: async operation
done();
});
When the command finishes, the editor will recover focus, and whatever changes where made to the chunks
object will be applied to the editor. All commands performed by woofmark
work this way, so please take a look at the source code if you want to implement your own commands.
Adds a button to the editor using an id
and an event handler. When the button is pressed, fn(e, mode, chunks)
will be called with the same arguments as the ones passed if using editor.addCommand(combo, fn)
.
You can optionally pass in a combo
, in which case editor.addCommand(combo, fn)
will be called, in addition to creating the command button.
If you just want to run a command without setting up a keyboard shortcut or a button, you can use this method. Note that there won't be any e
event argument in this case, you'll only get chunks, mode
passed to fn
. You can still run the command asynchronously using this.async()
. Note that the argument order chunks, mode
is the reverse of that passed to addCommand (mode, chunks
).
This is the same method passed as an option.
This is the same method passed as an option.
Destroys the editor
instance, removing all event handlers. The editor is reverted to markdown
mode, and assigned the proper Markdown source code if needed. Then we go back to being a plain old and dull <textarea>
element.
If optional Markdown string text
is provided, it is used to overwrite the current editor content, parsing into HTML if necessary. Regardless of whether text
is provided, value()
returns the current Markdown value for the editor
.
If options.wysiwyg
then this will be the contentEditable
<div>
. Otherwise it'll be set to null
.
The current mode
for the editor. Can be markdown
, html
, or wysiwyg
.
Sets the current mode
of the editor.
Shows the insert link dialog as if the button to insert a link had been clicked.
Shows the insert image dialog as if the button to insert a image had been clicked.
Shows the insert attachment dialog as if the button to insert a attachment had been clicked.
Exposes a few methods to gain insight into the operation history for the editor
instance.
Undo the last operation.
Re-applies the most recently undone operation.
Returns a boolean value indicating whether there are any operations left to undo.
Returns a boolean value indicating whether there are any operations left to redo.
Please ignore undocumented functionality in the chunks
object.
Describes the current state of the editor. This is the context you get on command event handlers such as the method passed to editor.runCommand
.
Modifying the values in a chunks
object during a command will result in changes to the user input in such a way that Undo and Redo can be taken care of automatically on your behalf, basically by going back to the previous (or next) chunks state in the editor
's internal history.
The currently selected piece of text in the editor, regardless of input mode
.
The text that comes before chunks.selection
in the editor.
The text that comes after chunks.selection
in the editor.
The current scrollTop
for the element. Useful to restore later in action history navigation.
Moves whitespace on either end of chunks.selection
to chunks.before
and chunks.after
respectively. If remove
has been set to true
, the whitespace in the selection is discarded instead.
To enable localization, woofmark.strings
exposes all user-facing messages used in woofmark. Make sure not to replace woofmark.strings
with a new object, as a reference to it is cached during module load.
Usage with horsey
See banksy to integrate horsey into woofmark
.
MIT