Confluence 4.x rich editor survival guide

Recently we upgraded from Confluence 3.5 to 4.x and with that change came the loss of the wiki editor. Confluence 4.x only supports (for the best of reasons) a fancy rich editor.

Aside from the initial frustration that I had lost my most powerful writing tool I also had to do battle with some interesting features of this editor which to a novice user may seem totally illogical. Fortunately they aren’t.

In this article I will share my initial rich editor denial, discoveries and ultimately acceptance.


The day after the upgrade I had to write some documentation on confluence and to my shock the wiki editor was gone. So I naively started entering text into the rich editor, which didn’t behave as I expected. So I quickly started looking for ways to enter my text in wiki format. I found several options of which the first is in the insert menu:

The Insert Wiki Markup Dialog

This dialog allows you to enter wiki markup in a standard text-area (no fancy WYSIWYG here) for a one way conversion into the new format. It has its own short-cut (ctrl-shift-D) and is useful if you have a large piece of wiki markup to insert. For serious editing purposes its inconvenient as it lacks a preview option and after saving the wiki markup is no longer accessible as it has been converted into the new format.

Wiki Markup friendly code completion

The most commonly used tags trigger the auto completion of the editor so entering h3. will switch the current paragraph to Heading3 style. The same applies for the *bold*, _italic_ and [link] creation. You can use the pipe symbol to start a table, but not finish it if you need to have multiple rows.

Funnily enough, while this feature has been added for the benefit of hardcore wiki editor users actually it causes more confusion to me than benefit. I am used to immediately close any tags that I open, then press cursor left and start filling in the tag. When I close the tag the auto-complete kicks in and replaces that (still empty) tag with a WYSIWYG one. Oh dear..

The top secret Wiki Markup ‘Macro’

It can’t be found anywhere in the documentation (as far as I looked that is) but when migrating to 4.x sometimes a page cannot be converted to the new format (mostly a case of missing plugins in my experience). Then that page is wrapped in a special macro called Wiki Markup.

Triggering this macro in the editor is easy by entering a macro that does not exist. for example. An indented text area will appear allowing you to enter wiki markup to your hearts content. Of course you’ll need to remove your bogus macro tag :-) If you invoke the Edit menu on the macro you get the following explanation:

   Macro that identifies a block of wiki markup that could not be migrated. The body of this macro can be a candidate for subsequent attempts at migration.



There is one catch with this macro. If someone else wants to edit your document and doesn’t know wiki markup then there is trouble..


Although nice to have, the three ways of entering wiki markup into confluence all have their disadvantages. The dialog is one way, code-completion requires a certain way of entering things and the legacy support macro is not usable for non tech-savvy users. So I decided to investigate if it actually would be possible work with the rich editor. Here are my discoveries:

Don’t use Internet Explorer

Initially I was using Internet Explorer 9 for my editing but apparently in IE more quirks and bugs appear present than in other browsers. Especially the ‘wrong cursor placement after undo’ appears to happen more often than in other browsers. Also pasting formatted text in IE loses single newlines. Fortunately the ‘lose style when deleting text at end of line’ feature is consistent in all browsers I tried, but that may be just me not understanding word processors :)

Know the difference between Enter and Shift+Enter

This was an eye opener for me. The default when pressing enter is to start a new paragraph, not starting a new line. That’s Shift+Enter. Apparently starting a new paragraph is used more frequently than starting a new line. In a word processor that’s probably true. In notepad it isn’t :-)

There are real shortcuts as well

Indeed, and they are quite good. Pressing control together with a number key applies the one of the styles in the menu. For example ctrl-8 gives quote style. Strangely enough the documentation says that you should press ctrl+alt but that doesn’t do anything.

Bold and Italic use the same convenient shortcuts you know from any word processor around the world. The same applies for indenting bullets using tab and shift-tab. There are plenty more and even adding rows to a table is easy with alt-up and down. Deleting a row is actually harder, but you can do that using ctrl-shift-x (cut row).

These shortcuts work quite well (and better than the wiki markup code completion). I’d almost wish for a shortcut for all buttons in the toolbar. In fact, I do!


Using the rich editor isn’t that hard. If you know about the enter/shift-enter thing its almost like a regular word processor. The shortcuts are easy to use and cover the most important use-cases. I don’t like the wiki markup code completion because it doesn’t work the way I type. I do like the top secret Wiki Markup macro, which allows me to enter hardcore wiki tags (like special tables) if I feel like it, or paste in a wiki formatted document using the insert wiki markup dialog.

In general I am happy with the new editor, in fact, I’ve typed this whole document in it. There is only one fear I have and that is: it just might turn me slowly into a project manager..

No comments:

Post a Comment