doc/tips/convert_mediawiki_to_ikiwiki.mdwn

   1 [[!toc levels=2]]
   2
   3 Mediawiki is a dynamically-generated wiki which stores it's data in a
   4 relational database. Pages are marked up using a proprietary markup. It is
   5 possible to import the contents of a Mediawiki site into an ikiwiki,
   6 converting some of the Mediawiki conventions into Ikiwiki ones.
   7
   8 The following instructions describe ways of obtaining the current version of
   9 the wiki. We do not yet cover importing the history of edits.
  10
  11 ## Step 1: Getting a list of pages
  12
  13 The first bit of information you require is a list of pages in the Mediawiki.
  14 There are several different ways of obtaining these.
  15
  16 ### Parsing the output of `Special:Allpages`
  17
  18 Mediawikis have a special page called `Special:Allpages` which list all the
  19 pages for a given namespace on the wiki.
  20
  21 If you fetch the output of this page to a local file with something like
  22
  23     wget -q -O tmpfile 'http://your-mediawiki/wiki/Special:Allpages'
  24
  25 You can extract the list of page names using the following python script. Note
  26 that this script is sensitive to the specific markup used on the page, so if
  27 you have tweaked your mediawiki theme a lot from the original, you will need
  28 to adjust this script too:
  29
  30     from xml.dom.minidom import parse, parseString
  31
  32     dom = parse(argv[1])
  33     tables = dom.getElementsByTagName("table")
  34     pagetable = tables[-1]
  35     anchors = pagetable.getElementsByTagName("a")
  36     for a in anchors:
  37         print a.firstChild.toxml().\
  38             replace('&amp;,'&').\
  39             replace('&lt;','<').\
  40             replace('&gt;','>')
  41
  42 Also, if you have pages with titles that need to be encoded to be represented
  43 in HTML, you may need to add further processing to the last line.
  44
  45 Note that by default, `Special:Allpages` will only list pages in the main
  46 namespace. You need to add a `&namespace=XX` argument to get pages in a
  47 different namespace. The following numbers correspond to common namespaces:
  48
  49  * 10 - templates (`Template:foo`)
  50  * 14 - categories (`Category:bar`)
  51
  52 Note that the page names obtained this way will not include any namespace
  53 specific prefix: e.g. `Category:` will be stripped off.
  54
  55 ### Querying the database
  56
  57 If you have access to the relational database in which your mediawiki data is
  58 stored, it is possible to derive a list of page names from this.
  59
  60 ## Step 2: fetching the page data
  61
  62 Once you have a list of page names, you can fetch the data for each page.
  63
  64 ### Method 1: via HTTP and `action=raw`
  65
  66 You need to create two derived strings from the page titles: the
  67 destination path for the page and the source URL. Assuming `$pagename`
  68 contains a pagename obtained above, and `$wiki` contains the URL to your
  69 mediawiki's `index.php` file:
  70
  71     src=`echo "$pagename" | tr ' ' _ | sed 's,&,&amp;,g'`
  72     dest=`"$pagename" | tr ' ' _ | sed 's,&,__38__,g'`
  73
  74     mkdir -p `dirname "$dest"`
  75     wget -q "$wiki?title=$src&action=raw" -O "$dest"
  76
  77 You may need to add more conversions here depending on the precise page titles
  78 used in your wiki.
  79
  80 If you are trying to fetch pages from a different namespace to the default,
  81 you will need to prefix the page title with the relevant prefix, e.g.
  82 `Category:` for category pages. You probably don't want to prefix it to the
  83 output page, but you may want to vary the destination path (i.e. insert an
  84 extra directory component corresponding to your ikiwiki's `tagbase`).
  85
  86 ### Method 2: via HTTP and `Special:Export`
  87
  88 Mediawiki also has a special page `Special:Export` which can be used to obtain
  89 the source of the page and other metadata such as the last contributor, or the
  90 full history, etc.
  91
  92 You need to send a `POST` request to the `Special:Export` page. See the source
  93 of the page fetched via `GET` to determine the correct arguments.
  94
  95 You will then need to write an XML parser to extract the data you need from
  96 the result.
  97
  98 ### Method 3: via the database
  99
 100 It is possible to extract the page data from the database with some
 101 well-crafted queries.
 102
 103 ## Step 3: format conversion
 104
 105 The next step is to convert Mediawiki conventions into Ikiwiki ones.
 106
 107 ### categories
 108
 109 Mediawiki uses a special page name prefix to define "Categories", which
 110 otherwise behave like ikiwiki tags. You can convert every Mediawiki category
 111 into an ikiwiki tag name using a script such as
 112
 113     import sys, re
 114     pattern =  r'\[\[Category:([^\]]+)\]\]'
 115
 116     def manglecat(mo):
 117             return '[[!tag %s]]' % mo.group(1).strip().replace(' ','_')
 118
 119     for line in sys.stdin.readlines():
 120             res = re.match(pattern, line)
 121             if res:
 122                     sys.stdout.write(re.sub(pattern, manglecat, line))
 123             else: sys.stdout.write(line)
 124
 125 ## Step 4: Mediawiki plugin
 126
 127 The [[plugins/contrib/mediawiki]] plugin can be used by ikiwiki to interpret
 128 most of the Mediawiki syntax.
 129
 130 ## External links
 131
 132 [[sabr]] used to explain how to [import MediaWiki content into
 133 git](http://u32.net/Mediawiki_Conversion/index.html?updated), including full
 134 edit history, but as of 2009/10/16 that site is not available.
 135