WikiSyntax

Page last updated 20 Mar 2010, by Simon Ford. 3 replies cookbook, Forum, notebooks, syntax, wiki

Up until now, we have used an HTML WYSIWYG editor (TinyMCE) for the notebooks and forums, but a wiki syntax for our handbook and cookbook (currently frozen in favour of notebooks, but we aim to reinstate it as a central community-contributed resource).

Whilst WYSIWYG is very accessible, it has some problems. In particular (some specific to TinyMCE):

  • You often have to fight with it/re-edit to stop it putting in new lines/obscure formatting (like, every time you write something, ahhh)
  • If people paste from another application (e.g. word!), it tends to keep all the horrible markup
  • It doesn't work with iPhone
  • A text box isn't really a sensible fall back option for WYSIWYG
  • It doesn't leave us much scope for doing cool auto-magical stuff that helps make you productive e.g. link/insert projects/code - this is one of the real drivers for moving to a wiki syntax
  • It doesn't encourage consistency of presentation
  • HTML is not that compatible with version control/diff

So we are looking at moving to a site wide wiki syntax as a way of entering any type of content. If done right, when doing simple things like forum posts and comments, or simple notes, it really can just be like plain text - don't even have to think about it. But then with the power of markup to insert resources/links and structure.

When it comes down to it, everyone on the site is obviously a coder (however proficient), so using a wiki won't be foreign or inaccessible (even if there are the religious arguments!), so I'm comfortable this is the right thing to do given all the potential upsides I can see.

But what syntax?!

Guess what, there are 101 out there, ranging from wiki types (Media wiki, docu, moinmoin) to markup (ReST, markdown, textile), but I have some specific requirements in mind and the one that comes closest is a wiki-style (for auto-magical stuff), and in particular the MoinMoin syntax. There are three main reasons:

  • It is pretty much what you'd write if you were writing a text file
  • It has the simple and orthogonal concept of linking vs. inserting resources. Awesome.
  • We've used and been happy with a lot of what trac provides, which is very similar

Update: Creole is an attempt for a common wiki language and has the key parts of MoinMoin syntax I'm after, so looks like a good call.

So, here is my second attempt at a spec (modified to be based on creole, and using <<>> for the more macro-style aspects):

= heading 1st level =
== heading 2nd level ==
=== heading 3rd level ===

**bold**
''italic''
__underline__
--stroke--
^^superscript^^
,,subscript,,
##monospace##

* Unordered Item 1
 * Unordered Item 1.1
  * Unordered Item 1.1.1   
  * Unordered Item 1.1.2
  * Unordered Item 1.1.3
 * Unordered Item 1.2
* Unordered Item 2

# Ordered Item 1
 # Ordered Item 1.1
 # Ordered Item 1.1 
  # Ordered Item 1.1.1
  # Ordered Item 1.1.1
# Ordered Item 
  
http://www.google.com
user@example.com

[[]] is a resource link, {{}} is a resource to embed inline, <<>> is a block/macro
  
[[link-url]]
[[link-url|alt-text]]
[[link-url|alt-text|style-options]]

{{embed-url}}
{{embed-url|alt-text}}
{{embed-url|alt-text|style-options}}

[[link-url|{{embed-url}}]]
[[link-url|{{embed-url|alt-text}}]]
[[link-url|{{embed-url|alt-text|style-options}}]]

{{http://www.youtube.com/watch?v=Y6kECR7T4LY}} insert video
{{http://mbed.org/.../foo.cpp}} insert code

<<pre>>
pre-formated
block 
<</pre>>

<<code{ type}>>   
syntax highlighting pre-formatted block
with thinkgs like c, cpp, py, lua, txt, ...
<</code>>

<<warning>>
icon info box wrapper
with things like warning, error, info, note, tip
that can have nested other things
<</warning>>

<<quote{ user}>>
a blockquote wrapper for quoting people
that can have nested other things
maybe optional refer to user 
<</quote>>

<<comment>>
something not rendered in the output
<</comment>>

<<more>>
Make something have a link to expand it, as would be used
in an FAQ section. Could also have hide to have something visible by default
probably appends (show) link to preceding element (may need thought, but FAQ use case is important)
could be called "more"/"less" and append "(more...)"
<</more>>

forced\\linebreak

:( :) ;) :D ...

|=A|=B|=C|
|left aligned | centered | right aligned|

3 comments

Ilya I
28 Feb 2010

I don't mind wiki syntax, but will there be a WYSIWYG around?

 

Also, seems like two different constructs use the same markup:

{{monospace}}

vs.

{{embed-url}}
Simon Ford
28 Feb 2010 . Edited: 28 Feb 2010

Hi Ilya,

monospaced fixed, was meant to be {{{monospaced}}} to align with multi-line pre block. Good spot.

We'll certainly test out a WYSIWYG editor for it, but I'll chose none over a bad one. I've used enough wikis to know fighting with a wysiwyg editor is worse than not having one (one i've used has 3/4 editor views!). Another option is a wiki toolbar, and good preview. We'll put up some things to test when we get around to it, and people can have a play.

Simon

Igor Skochinsky
02 Mar 2010 . Edited: 02 Mar 2010

For me the main gripes of the current forum are:

1) non-working insert code functionality (but it seems either you fixed it or something changed in Opera 10.50 and it works now)

2) no automatic linking of URLs.

BTW, look at the implementation of MarkDown at stackoverflow.com. I think it's pretty good. The only thing I don't like there is two newlines to start a paragraph.

You need to log in to post a comment