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 Another set of instructions and conversion tools (which imports the full history)
  12 can be found at <http://github.com/mithro/media2iki>
  13
  14 ## Step 1: Getting a list of pages
  15
  16 The first bit of information you require is a list of pages in the Mediawiki.
  17 There are several different ways of obtaining these.
  18
  19 ### Parsing the output of `Special:Allpages`
  20
  21 Mediawikis have a special page called `Special:Allpages` which list all the
  22 pages for a given namespace on the wiki.
  23
  24 If you fetch the output of this page to a local file with something like
  25
  26     wget -q -O tmpfile 'http://your-mediawiki/wiki/Special:Allpages'
  27
  28 You can extract the list of page names using the following python script. Note
  29 that this script is sensitive to the specific markup used on the page, so if
  30 you have tweaked your mediawiki theme a lot from the original, you will need
  31 to adjust this script too:
  32
  33     import sys
  34     from xml.dom.minidom import parse, parseString
  35
  36     dom = parse(sys.argv[1])
  37     tables = dom.getElementsByTagName("table")
  38     pagetable = tables[-1]
  39     anchors = pagetable.getElementsByTagName("a")
  40     for a in anchors:
  41         print a.firstChild.toxml().\
  42             replace('&amp;','&').\
  43             replace('&lt;','<').\
  44             replace('&gt;','>')
  45
  46 Also, if you have pages with titles that need to be encoded to be represented
  47 in HTML, you may need to add further processing to the last line.
  48
  49 Note that by default, `Special:Allpages` will only list pages in the main
  50 namespace. You need to add a `&namespace=XX` argument to get pages in a
  51 different namespace. (See below for the default list of namespaces)
  52
  53 Note that the page names obtained this way will not include any namespace
  54 specific prefix: e.g. `Category:` will be stripped off.
  55
  56 ### Querying the database
  57
  58 If you have access to the relational database in which your mediawiki data is
  59 stored, it is possible to derive a list of page names from this. With mediawiki's
  60 MySQL backend, the page table is, appropriately enough, called `table`:
  61
  62     SELECT page_namespace, page_title FROM page;
  63
  64 As with the previous method, you will need to do some filtering based on the
  65 namespace.
  66
  67 ### namespaces
  68
  69 The list of default namespaces in mediawiki is available from <http://www.mediawiki.org/wiki/Manual:Namespace#Built-in_namespaces>. Here are reproduced the ones you are most likely to encounter if you are running a small mediawiki install for your own purposes:
  70
  71 [[!table data="""
  72 Index   | Name         | Example
  73 0       | Main         | Foo
  74 1       | Talk         | Talk:Foo
  75 2       | User         | User:Jon
  76 3       | User talk    | User_talk:Jon
  77 6       | File         | File:Barack_Obama_signature.svg
  78 10      | Template     | Template:Prettytable
  79 14      | Category     | Category:Pages_needing_review
  80 """]]
  81
  82 ## Step 2: fetching the page data
  83
  84 Once you have a list of page names, you can fetch the data for each page.
  85
  86 ### Method 1: via HTTP and `action=raw`
  87
  88 You need to create two derived strings from the page titles: the
  89 destination path for the page and the source URL. Assuming `$pagename`
  90 contains a pagename obtained above, and `$wiki` contains the URL to your
  91 mediawiki's `index.php` file:
  92
  93     src=`echo "$pagename" | tr ' ' _ | sed 's,&,&amp;,g'`
  94     dest=`"$pagename" | tr ' ' _ | sed 's,&,__38__,g'`
  95
  96     mkdir -p `dirname "$dest"`
  97     wget -q "$wiki?title=$src&action=raw" -O "$dest"
  98
  99 You may need to add more conversions here depending on the precise page titles
 100 used in your wiki.
 101
 102 If you are trying to fetch pages from a different namespace to the default,
 103 you will need to prefix the page title with the relevant prefix, e.g.
 104 `Category:` for category pages. You probably don't want to prefix it to the
 105 output page, but you may want to vary the destination path (i.e. insert an
 106 extra directory component corresponding to your ikiwiki's `tagbase`).
 107
 108 ### Method 2: via HTTP and `Special:Export`
 109
 110 Mediawiki also has a special page `Special:Export` which can be used to obtain
 111 the source of the page and other metadata such as the last contributor, or the
 112 full history, etc.
 113
 114 You need to send a `POST` request to the `Special:Export` page. See the source
 115 of the page fetched via `GET` to determine the correct arguments.
 116
 117 You will then need to write an XML parser to extract the data you need from
 118 the result.
 119
 120 ### Method 3: via the database
 121
 122 It is possible to extract the page data from the database with some
 123 well-crafted queries.
 124
 125 ## Step 3: format conversion
 126
 127 The next step is to convert Mediawiki conventions into Ikiwiki ones.
 128
 129 ### categories
 130
 131 Mediawiki uses a special page name prefix to define "Categories", which
 132 otherwise behave like ikiwiki tags. You can convert every Mediawiki category
 133 into an ikiwiki tag name using a script such as
 134
 135     import sys, re
 136     pattern =  r'\[\[Category:([^\]]+)\]\]'
 137
 138     def manglecat(mo):
 139             return '\[[!tag %s]]' % mo.group(1).strip().replace(' ','_')
 140
 141     for line in sys.stdin.readlines():
 142             res = re.match(pattern, line)
 143             if res:
 144                     sys.stdout.write(re.sub(pattern, manglecat, line))
 145             else: sys.stdout.write(line)
 146
 147 ## Step 4: Mediawiki plugin
 148
 149 The [[plugins/contrib/mediawiki]] plugin can be used by ikiwiki to interpret
 150 most of the Mediawiki syntax.
 151
 152 ## External links
 153
 154 [[sabr]] used to explain how to [import MediaWiki content into
 155 git](http://u32.net/Mediawiki_Conversion/index.html?updated), including full
 156 edit history, but as of 2009/10/16 that site is not available. A copy of the
 157 information found on this website is stored at <http://github.com/mithro/media2iki>
 158
 159