User Tools

Site Tools


info:wikis

Wikis and Markup Languages

This is the search for the perfect wiki software, which will likely continue for a while (unless I find something better than a wiki, when I will start looking for the best one of those).

Current Status (2015)

I haven't looked around much lately. Currently I use:

  • Dokuwiki for my personal wiki (i.e. this one)
    • My biggest headache has been keeping some version of the edit sections plugin working (to move the edit button to the top of the section instead of the bottom)
  • MediaWiki for a work wiki
    • Not great, but not bad
    • Other people would really like a WYSIWYG editor
  • reStructuredText syntax for documentation within projects (README files, notes, TODO lists, etc.) which is stored in the version control system
    • This is common within the Python community
    • For project documentation, use Sphinx

Here are some to look at (possibly again):

Considerations

Syntax

The site for the Creole wiki syntax has a lot of comparisons between different wiki syntaxes.

  • List syntax (MediaWiki-like, but with embeddable pre/code blocks, preferably with nice easy syntax highlighting)
  • Code blocks / syntax highlighting (preferably optional)
  • Inline monospace syntax (I like back ticks; maybe double back ticks would be better)
    • Dokuwiki is double-single-quotes, which is okay
    • With MediaWiki you have to use html blocks (tt or code)
  • Support for complex markup within lists (code blocks, multiple paragraphs)
    • reStructuredText is the only one I know of currently that does this well
    • It's arguable that this is not a great thing to do anyway, but I like making lists
    • Dokuwiki can have code blocks in list items, but you have to put the opener on the same line, and the whole thing looks ugly.
  • Support for adding whitespace between ordered list items without breaking the numbering?

Editing

  • Smart text editor
    • Dokuwiki uses JavaScript to help with lists
  • WYSIWYG editor (depending on the use case)
  • Editing of sections to make larger pages easier
    • So far has been very helpful
    • The only Wikis I've seen so far with a good implementation are DokuWiki and MediaWiki (e.g. TWiki has a plugin to manually create sections; one other has weird stipulations like "you can't delete the header that makes the section while editing that section")
  • Keyboard shortcuts (like Dokuwiki and MediaWiki)
    • Save, preview
  • Diff view for editor
    • MediaWiki has this; DokuWiki does not
  • Saving of draft automatically
  • AJAX/in-place editing – is it available anywhere besides CMSs/TiddlyWiki/Luminotes? Also see projects page.
    • If Dokuwiki included rendering functionality in XMLRPC, then this might could be done there
  • Offline editing? Synchronization?
    • MoinMoin 1.6 has some sort of synchronization feature
    • A wiki with a version control system back-end (ikiwiki) could allow for having multiple copies running on different computer, especially if it was a distributed VCS
    • Dokuwiki now has a sync plugin.

General

  • Compatibility with mobile devices (theme, editor)
  • Table of contents (preferably without having to manually insert it on every page)
  • Indexing/search
  • History and diff-ing
  • Indentation of section headings
    • In structured documents, this can prevent confusion
    • Default behavior of DokuWiki
    • Can be added to MediaWiki with an extension
  • Numbering of section headings
    • MediaWiki has this as an option; it's off by default (can enable globally and/or per-user)
  • Page redirection (like MediaWiki)

Top Contenders, in rough order of current preference

DokuWiki

Positive

  • Runs on cheap shared (PHP) hosting like NearlyFreeSpeech.NET
  • Automatically converts some symbols (e.g. arrows, copyright, etc.)
  • Has a nice toolbar that can insert other symbols and things, in addition to acting as a quick syntax helper
  • Javascript for lists (new item after pressing Enter; indent/dedent with space/backspace)
  • It has those cool buttons to the bottom-right of the edit box that let you resize the box or toggle word-wrapping
  • Easy syntax highlighting
  • Indexing (automatic?)
  • Keyboard shortcuts are surprisingly useful
  • Section editing makes things much easier
    • Default section edit buttons are at the bottom of sections, which I find very annoying
  • Same syntax for wiki links and external links (double square brackets, with an optional bar for specifying link text).
  • I've started to like the way that successive heading levels are indented further. It's easy to turn off if you don't like it, but not easy to add to other wikis (because dokuwiki adds extra div blocks around each section corresponding to the header level).
  • Saves a draft each time you do a preview (so if you close the window without hitting cancel, then the "Edit page" link will be changed to "Edit draft")
  • Seems to handle internet disconnections gracefully enough, in the way you might expect (hit back and re-POST)
  • Interwiki links are very nice
    • (2013-04) But I can't say I've used them much in the past few years

Negative

  • Still does "smart" quotes and dashes ("typography") inside of monospace (e.g. --program-option)
  • :?: Pages are separate from their past revisions, which are separate from their metadata (MoinMoin stores them all in one folder). On the plus side, everything is in folders by namespace.
  • Fixed with Firefox 3. Going back in history seems to take you to the top of the page instead of remembering where you were
  • List support isn't as good as MoinMoin
    • Ordered lists seem to reset if you put in line breaks for easier editing (same as MediaWiki)
  • ToC is not functional in page preview
  • The layout seems to get messed up when there are images (some other times too?)
  • Missing page redirection; GOTO plugin requires Javascript and doesn't look nice like MediaWiki
  • Notification of page lock expiration while editing can get annoying
  • Will let you edit an old version of a page if that's what you were looking at, then requires you to pick one or the other of the updates, clobbering the other.
  • The edit page needs a diff function like on MediaWiki
  • Maybe not common, but I don't think the code block can properly display, for instance, HTML code that include a </code> tag. The syntax highlighter I've used with MediaWiki has the same limitation, but it might be possible to change the syntax in that case (I'm not sure).
  • No built-in syntax for definition lists, though there are some plugins that support it
  • Can't easily put multi-line code blocks in lists
    • reStructuredText can do this, but I don't think it's common in other syntaxes

Section editing

If you edit an H2 and there are H3s and H4s (i.e. other headings) under it, it will only edit the section down to the first heading.

  • The edit buttons are at the bottom of the section, so you have to go looking for the correct one!
  • Edit Section Reorganizer Plugin seems to fix both problems above
  • MediaWiki does this correctly! Look for any others that do likewise.
  • If there are multiple users, they can't edit different sections of the same page at once (apparently MediaWiki allows it)

Notes

  • "DokuWiki snapshot?" in page header
    • Make sure VERSION is there, and readable I suppose (http://forum.dokuwiki.org/post/3015); it seemed not to work until I moved it outside of htdocs/public into the nonpublic directory
  • If you see the default icon (e.g. for interwiki links) instead of the new one you added, try purging the cache (i.e. rm -rf <path-to-dokuwiki>/data/cache/*; see interwiki).
  • Plugins to maybe try:

MediaWiki

Positives

  • Good section editing
    • When you edit a section, it puts the name of the section in the edit summary
    • When you save after you edit a section, it jumps to that section (using the anchor)
  • Better list syntax (but still can't embed pre blocks without breaking the list)
  • Pages can be easily renamed, and they leave a redirect page at the former name
  • Keyboard shortcuts similar to dokuwiki (but not including, e.g., the heading shortcuts; however, headings that start with a lower number of equal signs seem to be easier to remember)
  • "Show Changes" button on the edit page (could something like that be added to dokuwiki? how easily?)
  • Ubiquitous because of WikiPedia and other wikis all over (e.g. Wikia wikis)
  • Since it's so popular, there are tons of extensions and customizations available
  • Sqlite support is being added in version 1.13.0 (i.e. must use SVN version until it is released)
  • I think I like the "Go" button (the default) in the search bar better than DokuWiki's JS search bar, especially with MediaWiki's automatic page redirection.
    • For the best of both world, the Nethack wiki has a drop-down box similar to DokuWiki (which works better, in my opinion).
  • Unlike Dokuwiki: "Handle edit conflicts (page being saved by a user while still being edited by another one, then saved again). MediaWiki will merge changes automatically if possible and otherwise require the user to do a manual merge." (http://www.mediawiki.org/wiki/Manual:MediaWiki_feature_list)

Negatives

  • No monospace syntax. It gets very annoying typing TT tags all the time.
    • Would it be possible to add the syntax (e.g. back tick or double back tick) with an extension?
  • Uses different syntax for internal and external links
  • No ACL
  • Requires a database
    • Makes management of pages more difficult? Maybe easier?
  • Takes a good bit of customization to (extensions, CSS, etc.) to get to the amount of polish on, say, a WikiMedia wiki (on the other hand, it allows a ton of customization, and it's generally not hard to do).
  • Performance may not be as good for a personal wiki, I'm not sure
  • Not as likely that personal changes would get accepted to the codebase (but could use something like git-svn, maybe, to retain customizations)
  • Geared toward WikiMedia foundation projects; the download page seems almost hostile to other uses
  • Doesn't appear to save drafts like DokuWiki, so you might lose your work if you don't manage to save it
    • Might be an extension or something on the "Editing Tools" page to mitigate this
  • Apparently no way to correctly insert <pre> blocks in lists like this:
    this is
    some text
    in a dokuwiki code block
  • Syntax highlighting is not built in; requires an extension.
  • It appears that extensions are limited in the syntax they can use. Mostly it's XML-style, which I think can be good in some cases but not in general, not only because it's annoying to type, but also because it clashes with other syntax (e.g., the syntax highlighting extension will have trouble you ever want to highlight an XML file that has a </source> tag somewhere). See Manual: MediaWiki Hooks.
  • No help pages built-in (there are some public domain help pages available for copying)

Notes

  • The FCKeditor extension seems to work fairly well, generating wikitext. There are some cases where it will mess up certain syntax (e.g. it was messing up my charinsert blocks).
  • The page title is automatically inserted as the first top-level header in the page. I don't think this is a particularly bad thing.

Ikiwiki

  • Positive
    • Can use several version control systems (Subversion, git, mercurial, bzr…)
      • Should be easy to keep a mirror on multiple computers
      • Makes for better merging
      • No locking (but I haven't had a chance to see how it handles conflicts)
    • Markdown allows for arbitrary stuff in list items, at least when using HTML (unlike DokuWiki, kind of like MoinMoin's list capabilities perhaps)
  • Negative
    • No ACL
    • No section editing (I saw something about using included pages for the same effect)
    • Default style isn't very nice
      • Doesn't have all the spans that DokuWiki uses, so it's harder to customize some things
    • Question marks for nonexistent pages (instead of differently-colored links); again, I would hope that this is customizable.
    • I have some issues with the default syntax (Markdown)
      • Code blocks are a pain compared to DokuWiki
      • Uses weird link syntax
      • Multi-level lists are also a pain
    • :?: It's written in Perl
    • Overall just missing a lot of the niceties of Dokuwiki
    • This could be a killer (from http://ikiwiki.info/wikilink/): "Note that you cannot use spaces in WikiLinks. Replace spaces with underscores. The presence of spaces is used to distinguish between a PreprocessorDirective and a WikiLink."
      • Fixed; prefix_directives option needs to be on (should default to on in the future)
    • When putting text in pre blocks (possibly html blocks of any kinds, but especially pre), it still interprets formatting like underscores (markdown, I suppose, is the culprit)
      • Try <pre>` ... `</pre> instead of <pre><code> ... </code></pre> (it seems that backtick-encapsulated text can span multiple lines)
      • See http://daringfireball.net/projects/markdown/syntax for multiple correct ways to do it (separate HTML block-level tags, indent by 8 spaces)
    • Page history is dependent on a web viewer for the VCS
      • There is no way to render old versions of a page from the interface
      • There is no way to easily get back to the wiki except the back button (e.g. if you've been browsing the history for a while)
  • Notes
    • When installing to my home directory on acme.gatech.edu, I had to edit the ikiwiki script (~/opt/perl/bin/ikiwiki) to use my local perl binary. Otherwise it would have the wrong @INC paths, and if given the correct paths with use lib, would give relocation errors.
    • When upgrading, you probably want to do a full rebuild, e.g.
      ikiwiki --setup ~/.ikiwiki/ikiwiki.setup --rebuild
    • Installing the Debian package (from sid, i.e. http://packages.debian.org/sid/ikiwiki) manually on Ubuntu seems to work.
  • Stuff that needs work
    • A little icon for external links
      • Also for shortcut links (or whatever they're called) like dokuwiki?
    • Section editing

MoinMoin

MoinMoin wiki site

  • Positive
    • Flexible list support (http://moinmoin.wikiwikiweb.de/HelpOnLists), with numbered lists with any type of numbering starting at any number
    • I mostly like the syntax for monospace (i.e. backtick, which reminds me of shell scripting), but I think the <code> syntax in DokuWiki is easier to use for syntax highlighting.
    • Seems to be actively in development (but also see negative)
      • Link syntax improving
    • Plugin for using DokuWiki syntax
    • Decent diffs; arbitrary versions
    • ToC is functional in page preview
  • Negative
    • Sub-lists still require indentation
    • No section editing
    • Slow search (can indexing be used?)
    • No namespaces; subpages are a bit weird: they're just pages with a "/" in the title (which creates weird filenames, at least in Windows)
    • Under development, including in syntax
      • Some features are flaky
    • Doesn't support (and devs don't seem to support) things like symbols, saying you should be able to type special characters directly from your keyboard
    • After using MoinMoin for a while at work for my TODO list, I'm really tired of it. I think it's because of no section editing, but remember that I am only using one big page, mostly. I might have to see what I think of (Dokuwiki/another wiki) after using it for this purpose.

TikiWiki

PmWiki

PmWiki website

  • Seems nice, lightweight
  • A lot of stuff not built in
  • Has somewhat flexible ordered lists, but syntax is not nearly as good as MoinMoin
  • Has a Section Edit plugin (haven't seen it in action yet, and it has limitations, so I don't know how it compares)

TiddlyWiki

TiddlyWiki for its awesome Javascript goodness

  • Does it have versioning?
    • "Backups"
  • What about using a regular VCS?
  • Other limitations like no seperate files

Others

  • ZWiki - support reStructuredText markup
  • Confluence (commercial/hosted)
    • Editor looks quite nice
    • No longer uses wiki markup (some functionality for inputting it, but it gets converted right away)
  • Deki Wiki could be worth looking at
    • Looks professional
    • WYSIWYG editor (only?)
  • TWiki looks like it could be powerful, with added complexity of setup
  • JAMWiki supports section editing
    • Probably best used as one Trac ↔ one development project
    • I read someone say somewhere that the Trac wiki was not so great
    • Doesn't have section editing (issue #1024, added 4 years ago)
    • Uses CamelCase links by default, which can be good or bad depending on your preferences.
    • Nice looking diffs (both for wiki text changes and for code changes in version control)
    • Appears to have no keyboard shortcuts
    • Pressing tab while in the edit box doesn't take you to the comment text area (as it does in Dokuwiki/MediaWiki)
  • Luminotes is interesting (AJAX editing, history) but seems very simplistic
  • CMS of some sort (possibly take more system resources; too structured)
    • Drupal
    • Plone
      • Linux only
      • RCS versioning for all pages
      • Offline editing of some sort
      • Wiki and other kinds of markup

Syntax Conversion

Of course, syntax conversion is always going to be imperfect, but sometimes it's helpful.

  • Pandoc supports converting between a lot of different syntaxes, and is easy to install (Windows installer, Linux packages, Mac installer)
    • Supports conversion from (at last look) markdown, reStructuredText, textile, HTML, DocBook, LaTeX, or MediaWiki markup
    • Converts to various HTML variants, various wiki formats, org-mode, Word/OpenDocument, etc.
    • DokuWiki is not a supported format; see https://github.com/jgm/pandoc/issues/386
  • HTML-WikiConverter Perl module converts from HTML to many wiki formats (including DokuWiki)
info/wikis.txt · Last modified: 2015-05-07 20:27 by sam