Markdown and or Live Preview

I've been using StackOverflow recently which uses Markdown+WMD (for a GUI toolbar + client-side preview). The ability to see the effect of wiki markup in realtime is huge. It's much easier for me (and especially other less technically-savvy coworkers) to edit wiki pages if I can see the effect of it in realtime instead of having to wait 5 seconds for the page to refresh when I do a preview. I get immediate feedback if I haven't gotten the syntax right. If I don't get the syntax right and it takes me 3 minutes to try 10 different things, I get really frustrated and stop using the tool.

So it would be helpful to have a live preview (via the wonders of Javascript) where "live" means automatically responsive within, say, 0.5 second.

WMD gives you this. It uses Markdown; I'm not absolutely fixed on using Markdown, although I do like the syntax, and what's not acceptable is for me to have to use extra brain cells to remember 5 different Wiki markup formats, when I could be using those brain cells for other things.

–Jason

I'm absolutely with you about both the greatness of live preview and the difficulty of remembering multiple wiki markups.

This is why this wiki uses markup as close to WikiCreole as was practical. I was actually considering Markdown and Textile and a number of other options, but I think they are not really tune for wikis – especially with their awkward linking. WikiCreole is an effort to design a common markup for wikis that is optimized for them – not for plain text files or blog comments.

There is a problem with live preview: to make it useful, it would have to behave exactly the same as the server-side parser written in Python, otherwise it makes little sense. Although I know some Javascript, I'm far from being as fluent in it as I am in Python. Writing a Javascript parser and then maintaining it and keeping it in sync with the Python one would be a considerable effort – which is in my opinion better spent at getting the missing features to work (interwiki/local names, orphaned and wanted pages) and writing the unit tests to keep the whole thing from breaking apart Having said that, I do plan to at least try and add some optional Javascript goodness sooner or later, starting with basic things like editing a page on double click. Live preview is definitely high on the usability scale.

I'm also a little afraid of difficulties. Would it be fast enough to parse the whole page each time the user pauses typing? It's OK for short blog comments, but wiki pages can be several screens long. Incremental parsing is possible for line-based parts of the markup, but gets difficult with preformatted blocks and macros, etc. It's definitely a great opportunity to learn Javascript better, but it's also a bit scary – Radomir Dopieralski

BTW, I think it would be pretty simple to just replace the current parser with markdown parser and just use WMD. I just don't think Markdown is convenient for wikis. – Radomir Dopieralski

>it would have to behave exactly the same

>as the server-side parser written in Python,

>otherwise it makes little sense

You have a point there. That fails sometimes in StackOverflow. (still it works 99% of the time) I'll definitely give WikiCreole a try… (er I guess I am right now ) –Jason

(edit: either that, or don't do server-side conversion from markup -> HTML at all; use the client-side for rendering, perhaps with a fallback to HTML if there isn't javascript.)

Another option is to use AJAX and use the server-side parser for live preview too. There are lots of options, just not enough time and skill to try them – Radomir Dopieralski

How is Markdown not convenient? The idea with wikis is to write text and have it show up as html without having to remember all the tags. That is what Markdown does (IMHO) better than any other system out there. The biggest problem with most wiki markups is that they end up being as unreadable as html. How do you write/edit a page if you can't make out what you're reading?

Markdown is designed with readability in mind above all else. It makes sense for all sorts of large, structured documents. Several features are specifically designed in such a way, that they are unobtrusive when reading, at the cost of being relatively difficult to write. This includes underlined headings and links with the actual address moved far away from the link itself.

On the other hand, the goal of wiki markup is to make it easy to write and edit, often doing heavy restructuring, pages of text, with lots of links and little semantic markup. In fact, one of common operations that need to be easy, because we want to encourage them in wikis, is adding links, often by turning small phrases from existing text into links, and adding (and changing) structure of the page, by inserting or moving headings, adding or removing list bullets, etc. While Markdown is designed well enough to handle it passably, I believe that wiki markups do it better.

Another feature of Markdown that makes it unsuitable for wikis in my eyes is its ability to inline HTML. Don't get me wrong, I have nothing against HTML, it's a good and popular solution for marking up web pages, especially for people who already know it. But wikis are not general purpose web editors, too much markup not only gets in the way of actually creating content, but also makes it harder to edit by others. Wikis are about collaboration, so the advantages of Markdown: structure and extensibility with HTML, seem to be disadvantages.

This is of course only my opinion, or my accurately, the reasoning behind my design decision to use wiki-like markup in Hatta. Because Hatta is supposed to be used for documentation, I do plan to have a plugin for using ReStructured Text and other markups – possibly including Markdown. This may be a long time, though, because right now I haven't even decided how I will implement the plugin mechanism.

Sorry for ranting. – Radomir Dopieralski

Hey, just read your issues with Markdown and I have a few things to add. First, you are correct that allowing raw HTML in wiki markup is not always ideal. For this reason, most markdown implementations, including Python-Markdown, have a switch to easily turn off that feature (see the docs and scroll down to the "Safe Mode" section). So that really is a non-issue.

However, your reasons for disliking raw HTML in wiki markup seems to contradict your reasons for disliking markdown's preference for readability over writability. The fact is, if I'm going to be editing a document written by someone else, I would much prefer a format that is easier to read. I get lost in the 'easier to write but hard to read' document that someone else wrote. But we are all entitled to our own opinion, of course.

Anyway, you might be interested in taking a look at this code for a nice mechanism for implementing multiple markup engines. Although it is designed primary within the Django context, the basic principles could work anywhere.

– Waylan Limberg (Disclaimer: I'm a Python-Markdown core dev.)

Markdown link syntax is not very easy to type (though it *is* easy to read). However, WMD has a great create/change link button (& Ctrl+L shortcut) that renumbers links automatically! This makes it mostly a non-issue.

OTOH, renumbered links are going to be painful when you do merges in Mercurial

– Beni Cherniavsky-Paskin

Well, there are some beginnings of restructured text support, I see no reason why someone who needs and knows it shouldn't add markdown support, making it as sophisticated and cool as practical. The source is out there and there are some examples of extending it. I can help with it as much as I can, so go ahead. – Radomir Dopieralski (BTW, I should move it to the bugtracker probably…)

Please, take a look into MarkItUp if you're looking for a WYSIWYG editor or/and client-side previewer.

– Julien Jehannet

Issues