How to migrate pages to ikiwiki

  1. fetch the page you're going to migrate, in raw original moinmoin markup style, into the workspace, and commit it as is for reference. (adjust as needed for some other tool, like wget or curl).

    ATTENTION: The moinmoin wiki was shutdown on 2008-12-16, so this no longer works

     ftp -o ZipperMerge.moin "http://www.venge.net/mtn-wiki/ZipperMerge?action=raw"
     mtn add ZipperMerge.moin
     mtn commit
    

    Note that most pages have already been fetched en-masse; you should only need to re-fetch if there have been changes in MoinMoin you want to bring across (you can check the revision history of the page on the old wiki site).

  2. rename the file and begin the process of migrating the markup:

     sed -Ef moin2mdwn.sed <ZipperMerge.moin >ZipperMerge.mdwn
     mtn mv --bookkeep-only ZipperMerge.moin ZipperMerge.mdwn
     rm ZipperMerge.moin
    

    (use sed -rf on Linux instead)

    This will automatically add [[!tag migration-wip]] at the top of the file, tagging the page as one being worked on, but not yet finished, and convert emphasis notations.

    Note further that many of the pages fetched in bulk, above, have also had an initial conversion like this. Such pages have been tagged with [[!tag migration-auto]] instead; if you're migrating one of those pages, change the auto to wip and proceed as normal.

  3. Commit and push this rev, so others can see you're working on this file, and can pick another to start next in parallel.

  4. Translate the markup. Some of this may have been taken care of already by the sed, but please check for sanity:

    • headers are done with leading #, ## etc rather than surrounding =, == etc

    • some and more emphasis is done with * rather than lots of single-quotes

    • Links are done with [[SquareBrackets]] rather than bare <span class="createlink">CamelCaseWords</span>

    • preformatted code blocks are done with 4 more spaces (inside the current level of indentation, say when inside nested lists), rather than with {{{ and }}}

    • external web links take the form [link text](http://url) rather than [http://url link text]

      An exception: when the URL is the link text as well, it can be simplified like this: <http://url> The angle brackets are required in this case. Ikiwiki and markdown do not make any attempt to interpret URLs otherwise.

    • Lists may or may not have a blank line between entries; however, the beginning of a list must be separated from preceding material by a blank line.

    • use formatting to help, and add more notes here

    • when migrating page markup, try to minimise the number of additional unrelated formatting changes (like reflowing paragraphs) in the same commit. That can be done as a separate step.

      When flowing paragraphs, try to follow the "new sentence, new line" convention. Ikiwiki uses a blank line to break paragraphs. This tends to mean that when someone else later adjusts a few words in a paragraph, we don't get many lines of sourounding diffs that are just reflowing.

    • It seems like anchors must be coded in HTML. The recommendation is to put the <a name tag inside the markdown formatting, not around. Like this:

      `## <a name="JavaStyle">Java style</a>`
      

      Not like this:

      `<a name="JavaStyle">## Java style</a>`
      

      or markdown might interpret the whole block as HTML only, not to be processed.

      Anchors are referred to as [Java Style](#JavaStyle) instead of the moinmoin syntax [#JavaStyle Java Style].

  5. Generate, test, rinse, repeat. commit now and again if you like, because your page is still tagged as unfinished.

  6. When you're happy, change to [[!tag migration-done]], save and commit again.

  7. GOTO 1

running ikiwiki

to generate pages you can browse with a local webserver, use something like:

ikiwiki --wikiname monotone --plugin rawhtml --plugin goodstuff --plugin graphviz --plugin table --exclude 'index\.mdwn' ikiwiki/checkout/dir/ output/dir/

if you want to use them with file: protocol with no need for a local webserver, the option --no-usedirs is suggested.