This page gives suggestions for upgrading an existing Pm Wiki 1.x installation to use Pm Wiki 2.0. In this page we assume that a site administrator already has a site running using Pm Wiki 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 Pm Wiki 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 Pm Wiki 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 Pm Wiki 1.x installation before doing anything else -- especially save the files in the local/ and wiki.d/ directories.

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

Step 2: Briefly test the Pm Wiki 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 Pm Wiki 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 Pm Wiki 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 Pm Wiki 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 Wiki Word links by setting $LinkWikiWords = 1; in config.php, or convert your existing Wiki Word links manually to bracketed links. To find those Wiki Word 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 Pm Wiki site. If you find Pm Wiki 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 Pm Wiki 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 Convert V 1 Wiki D?.

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

Step 8: Once you're comfortable that the Pm Wiki 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.