This page gives suggestions for upgrading an existing PmWiki 1.x installation to use PmWiki 2.0. In this page we assume that a site administrator already has a site running using PmWiki version 1.x or earlier in a somewhat standard configuration, and wants to upgrade to the 2.0 software.

As always, questions and requests for assistance can be posed to pmwiki-users. Errors or problems with the methods below can be corrected here, or posted to the PmWiki Issue Tracking System.

Method 1: Test conversion

Because of the substantial redesign of PmWiki for 2.0, converting an existing site to 2.0 is likely to cause a wiki administrator a fair amount of apprehension. The approach given here allows the administrator to install, configure, and test PmWiki 2.0 on an existing set of pages without risking an existing 1.x installation.

Step 0: It's always a very good idea to back up your existing PmWiki 1.x installation before doing anything else -- especially save the files in the local/ and wiki.d/ directories.

Step 1: Install PmWiki 2.0 into a new directory away from the existing 1.x installation.

Step 2: Briefly test the PmWiki 2.0 installation and make sure it is working properly -- i.e., edit and save a couple of pages. Then, remove the pages you created (you can just remove the files from PmWiki 2.0's wiki.d/ directory, or remove the wiki.d/ directory altogether).

Step 3: Add the following lines to the local/config.php file in the 2.0 installation, replacing "/path/to/pmwiki1/wiki.d" below with the location of your PmWiki 1.x installation's wiki.d/ directory on disk.

    
    include_once("$FarmD/scripts/compat1x.php");
    UseV1WikiD("/path/to/pmwiki1/wiki.d");
    

For example, my 2.0 test conversion uses:

    
    include_once("$FarmD/scripts/compat1x.php");
    UseV1WikiD("/home/pmichaud/pmwiki/wiki.d");
    

Step 4: After making the above change, all of your existing pages should appear in the new 2.0 installation. Furthermore, if you "edit page" on any of the existing pages, you should see that any PmWiki 1.x markups (links, etc.) have been converted to the new markup syntax.

Any pages edited/saved by the 2.0 wiki installation are kept separate from the pages in the previous installation. Thus you can safely experiment with editing and changing pages in the new site without affecting the existing 1.x site.

Step 5: Once you see that your existing pages are available in the 2.0 installation, you can then begin going through the remaining initial setup tasks for the 2.0 site to enable any local customizations you may want for your site. Many local customizations (e.g. page layout templates) remain the same between 1.x and 2.0, others such as custom markup or cookbook recipes need to be converted to 2.0 as well.

Note: WikiWord links are disabled by default since Pmwiki version 2.1 beta2. So you may either enable WikiWord links by setting $LinkWikiWords = 1; in config.php, or convert your existing WikiWord links manually to bracketed links. To find those WikiWord links easier you can highlight them by setting in config.php

       $HTMLStylesFmt['wikiword'] = "
       span.wikiword { background:yellow; }
       "; 

Step 6: Continue configuring the new installation just as if you were setting up a new PmWiki site. If you find PmWiki 1.x markups that aren't converted or convert incorrectly, be sure to enter a new PITS issue so that we can improve the conversion script.

Step 7: If you're comfortable with the conversion and want to go ahead and convert all of the 1.x pages into 2.0 format, change the UseV1WikiD(...) call in local/config.php above to ConvertV1WikiD(...) instead, as in:

    
    include_once("$FarmD/scripts/compat1x.php");
    ConvertV1WikiD("/path/to/pmwiki1/wiki.d");
    

Running the pmwiki.php script will then bring up some forms to allow you to bulk migrate some or all of your 1.x pages to 2.0 format. After you've converted pages, you can then just eliminate these two lines from the configuration and your PmWiki 2.0 site will be running standalone.

If you have local customisations that require you to specify $Compat1x['/match/'] = 'replace'; entries so they are correctly converted, make sure these are defined before the call to ConvertV1WikiD.

Note that there's nothing that requires you to convert all of the pages or get rid of the 1.x wiki.d/ directory -- PmWiki works just fine with it in place. And it's good to have a backup.

Step 8: Once you're comfortable that the PmWiki 2.0 site will meet your needs, you can then discontinue the 1.x site and just start using the 2.0 site. Or, if you decide that 2.0 isn't for you, then the 1.x site is still intact and can continue to be used.

Step 9: If your previous site had an uploads/ directory, you'll probably want to copy it or move it into the new location.