markItUp!

Note: This documentation is for the stand-alone markItUp! module. markItUp! is also supported via Wysiwyg module. Though this stand-alone markItUp! module currently has broader capabilities than the Wysiwyg module, new users should consider the Wysiwyg module implementation as this module is likely to become deprecated in the future as the capabilities of the Wysiwyg module expand.

What the heck is markItUp!?

markItUp! (yes, the lower-case M and exclamation point are part of the official name) is a JavaScript-powered enhancement for web site forms which aids in entering formatted text, such as HTML, BBcode, or Markdown. markItUp! adds a row of buttons above a textarea in which formatted text can be entered; these buttons can insert and alter text in the field to format it. However, the textarea still contains plain text; markItUp! does not mask the formatted text with a WYSIWYG interface as projects like FCKeditor or TinyMCE. Perhaps the best way to understand what markItUp! does is to try it for yourself, or check out the official markItUp! home page for more information.

markItUp! allows you to work with various "sets," which vary the buttons added to the text field and their behavior; official sets exist for HTML, Markdown, Textile and BBcode, among others. If you are familiar with JavaScript, you can easily alter these sets or create your own. You can also choose among several "skins" which alter the appearance of the markItUp! editor, from plain to fancy.

The markItUp! module for Drupal enables markItUp! on node, comment and block editing forms. (Note that the markItUp! module and the markItUp! JavaScript files are distinct entities by different developers.)

Installing markItUp!

Notice: The following instructions are for version 2.0 of the markItUp! module. They also apply to the 1.0 version in many aspects, but if you are installing markItUp! for the first time, you really should install the 2.0 version.

markItUp! is a little difficult to install, but these directions should guide you through just fine.

First, download and install the markItUp! module as normal, but don't try to enable it yet. Note that inside the markItUp! module directory, which is named "markitup," there is another directory named "markitup." We will place the markItUp! JavaScript files, along with sets and skins, inside that empty directory. (Drupal.org project hosting rules prohibit the inclusion of third-party code in projects hosted on the site; that'd be the markItUp! JavaScript files in this case.)
Head over to the official markItUp! site and download the latest markItUp! release (1.1.5, as of this writing). You should also download any sets or skins which look useful.
Uncompress the markItUp! archive. The resultant directory will be named "latest," and inside that will be a directory named "markitup." Copy all of the files inside that "markitup" directory into the "markitup" directory inside the Drupal markItUp! module directory.
In that last step, you also copied over two directories named "sets" and "skins." If you downloaded any sets or skins from the markItUp! site, put those directories inside their respective directories.

Wow, that's kind of complicated. You'll know you'll have done it right if the directory for the markItUp! module looks something like this.

Upgrading the markItUp! module

Occasionally the markItUp! module will be updated and you'll want to upgrade to the latest version. When doing so, you should take care to copy the files and sets in the "markitup" directory of the old version of the module into the "markitup" directory of the new version. Otherwise, you may have to reinstall things.

On the other hand, there may be times when the core markItUp! JavaScript files themselves are updated, and you may possibly have to update or replace your sets and skins to go along with it. Check the front page of the markItUp! module for news and information in that regard.

Configuring markItUp!

Fortunately, after all that installation trouble, configuring markItUp! is fairly simple. The first thing to do is to go to Administer > User management > Permissions page and give the "use markitup editor" permission to the roles who you would like to be able to use markItUp!.

You can assign one set and skin combination for each input format configured on your site. (Switching between input filters while editing a node, comment or block will automatically switch sets and skins as applicable.) Go to Administer > Site configuration > markItUp! Editor. You'll be brought to a table where you can select which set and skin should be used for each input filter configured on your site. Simply click the "Save configuration" button when you're done setting things up.

In addition to selecting the skin and set for each input filter, you can also fiddle with some optional "tweaks" that will modify markItUp!'s behavior. (Developers, if you'd like to implement your own tweaks, check out the "markitup.tweaks.js" for guidelines. The rest should be self-explanatory (but here's a hint).)

Troubleshooting

With this module, markItUp! should either work perfectly, or completely fail to the point where you won't see any markItUp! controls at all. There probably won't be any problems where things just work halfway.

If you don't see markItUp controls, here's some things to check:

Is JavaScript disabled in your browser? markItUp! requires JavaScript to function.
Is markItUp! enabled for the input format you're using? Double-check the module's configuration.
Do you have the "use markitup editor" permission? Check that you are a member of a role which has this permission.
Were the markItUp! JavaScript files installed correctly? If the markItUp! module senses something may be amiss with the JavaScript files, it'll display a message on the Status Report page (Administer > Reports > Status report).
Is readme.txt / CHANGELOG.md in the right place? In recent versions of MarkItUp, readme.txt has been moved and renamed to CHANGELOG.md. This is easily fixed with a symlink:
```
$ cd sites/all/libraries/markitup/markitup
$ ln -s ../CHANGELOG.md readme.txt
```
See http://drupal.org/node/767628 for more details.