UWC Mediawiki Notes

Table of Contents

What does it handle?

• some syntax
• tables (somewhat lossy)
• attachments

See the attached sample input for what syntaxes have been covered. In summary:

• Bold
• Italics
• Monospace
• No formatting
• Links
  • with aliases
  • with anchors
  • with namespaces are handled in various ways:
    • with the Image namespace, handled as an image
    • with the Category namespace, the link syntax is stripped out. (Would the appropriate equivalent be labels?)
    • with other namespaces, the syntax is essentially negated. Ex: Help:Editing becomes Help__Editing
      • Why? Several reasons: Mediawiki namespaces are not the same thing as Confluence spaces, so a namespace to space translation would not have the desired effect; the 'namespace:' syntax can also mean interwiki linking which I'm not ready to contemplate; the __ syntax will work with the mediawiki exporter module. Comments on desired use cases for this issue would be helpful for future improvements.
• Headings
• Bulleted Lists
• Numbered Lists
• <pre>, <code>, and Leading Spaces syntax
• Table of Contents, (tested with the Table of Contents macro version 1.4.7)
• Indenting colons syntax is stripped out (No Confluence equivalent)
• Images (very basic syntax)
• Very simple tables. Complex ones with rowspans, colspans, inner tables, or styles, will be converted as closely as possible, but there will be some loss.

Attachments

Point the UWC Settings Attachment Directory to the Mediawiki images directory you are using. This will probably be [Mediawiki-dir]/images

Note: It will need to be on a local filesystem. The mediawiki converter doesn't know how to access images over the net.

How do I prepare my mediawiki pages for import?

Use the exporter.
If you don't want to export your entire wiki, then you'll need to create individual text files for each page. Filename should be the page name, and file contents should be mediawiki syntax.

What about the mediawiki special page: export pages?

Mediawiki's export pages feature creates one xml file for all the desired exportable pages. We're not prepared to handle that at this time, so it's not terribly useful, unless you want to parse XML.

The exporter

Use the exporter to create a directory of data from your old wiki that can best be used by the UWC. See GUI v3 Exporter for more info on the exporter.

To use the exporter

You will first need to

1. Configure the conf/exporter.mediawiki.properties file

Configuring the exporter.mediawiki.properties file

You must configure the exporter.mediawiki.properties file, in order for the exporter to work.
It is located in the conf directory of the UWC.

The available properties are as such:

Property	Required	Example	Description
exporter.class		com.atlassian.uwc.exporters.MediaWikiExporter	Leave this alone, unless you want a different class to run the export
databaseName		myMediawikiDatabase	This is the name of the mediawiki database you are using. You can find out what this is by opening the Mediawiki LocalSettings.php file, and looking at the value of $wgDBname
dbUrl		jdbc:mysql://localhost:3306	This is the JDBC connection url. It should follow the format jdbc:databasebrand://hostname:port, or some variant.
jdbc.driver.class		com.mysql.jdbc.Driver	This is the JDBC driver class. If your Mediawiki uses a different database than MySQL, you will need to change this property to the appropriate driver class, get the associated driver JAR, and place that JAR in the lib directory. (The MySQL driver jar is provided already.)
login		mylogin	Your login for the Mediawiki database. See mediawiki LocalSettings.php $wgDBuser
password		mypassword	Your password for the Mediawiki database. See mediawiki LocalSettings.php $wgDBpassword
output		/Users/My/Desktop	This is the output directory that the export will be sent to. This needs to be a valid directory.
dbPrefix		mw_	This is the table prefix. See LocalSettings.php $wgDBprefix
Optional SQL Properties - For any of the sql properties to work, they must all be set and non-empty
db.sql.pagedata		select page_id, page_namespace, page_title, page_latest from mw_page;	This SQL will grab all the interesting pages
db.sql.textdata		select old_text from mw_text where old_id = ( select rev_text_id from mw_revision where rev_id = "db.column.textid" );	This SQL will grab the text for each result of the pagedata SQL. You can use any of the column properties as variables.
db.column.title		page_title	This is the column name for the title of a page
db.column.namespace		page_namespace	This is the column name for the namespace of a page
db.column.pageid		page_id	This is the column name for the page id
db.column.textid		page_latest	This is the column name for the revision id. It will be used to get the text.
db.column.text		old_text	This is the column name for the text.

Please note:

• Pages will be exported to the directory output/exported_mediawiki_pages where output is defined in the exporter.mediawiki.properties file.
• Pages from the namespace Special will not be exported
• Pages will be organized by the standard mediawiki namespace they belong to. (Example: Discussions, Users, Images, etc.). Exception: The "Main"/default namespace becomes the "Pages" directory.
• Pages from any of the standard Discussion namespaces will have the word Discussion appended to the page title so they do not overwrite the associated article on import.
• Pages with a non-standard namespace, will be renamed. (example, Test:Testing becomes Test__Testing)
• Pages containing 'bad' characters (like / or backslash), will be renamed (example, Bad/Character becomes Bad_Character)
• If your mediawiki is not using Mysql, you will need to provide the JDBC driver for your database. (See Configuring the exporter.mediawiki.properties file)
• If your mediawiki is not using Mysql, you may need to use the Optional SQL Properties.
• The exporter is compatible with Mediawiki 1.7.1. This should mean that it works as far back as 1.5. If you need to use it with an earlier Mediawiki, you will need to use the Optional SQL Properties.

Optional SQL Properties

If you disagree with the way the exporter pulls out the data from the database, you can customize the SQL statements that will be used.
There are seven properties that must be set if they are to be used:
db.sql.pagedata, db.sql.textdata, db.column.pageid, db.column.title, db.column.namespace, db.column.textid, db.column.text

The pagedata SQL will be used to slurp up all of the pages you are exporting.
The textdata SQL will be used to grab the text for each page that was returned as a result of pagedata. (So pagedata will be run once, and textdata will be run for every result of pagedata).

The column properties describe the name of the column that refers to a particular piece of data. These can be used in the textdata SQL. For example:

db.sql.textdata=select old_text from mw_text where old_id = ( select rev_text_id from mw_revision where rev_id = "db.column.textid" );

What if I don't agree with a particular conversion? Is it customizable?

As long as you don't mind getting your hands dirty.
So, if you want to change how the converter converts you have a couple of options.

Leave out some converters.

On the Select Converters page, the list of conversion engines that are auto-loaded based on the wiki you've chosen (from the Choose Wiki Type page) can be modified. You can remove some. You don't want the _TOC_ syntax to get changed to the Table of Contents macro? Just remove the converter with the words 'toc' in it.

Modify or even add your own converters

The mediawiki converters are defined in the file /conf/converter.mediawiki.properties

Please see the UWC Developer Documentation for more information.

Conversion notes

Headers

So, in Mediawiki, headers are defined as follows:

== Header 1==
=== Header 2===
==== Header 3====
etc.

Therefore, they are translated to:

- h1. Header 1
- h2. Header 2
- h3. Header 3

But what about

 =Header=

?

That last is discouraged syntax, but it is legal. It essentially corresponds with the style for the title of the page. So, if it's there what should we do with it? Choices include ignoring it or translating it to Confluence

 h1.

syntax.
I chose the latter. This means that both

=title=
==Header 1==

are translated to

- h1. title
- h1. Header 1

Header Conversion Customization If you don't want the =title= to be converted, edit the converter.mediawiki.properties file, and comment out the line containing the words: Mediawiki.0540-re_title.java-regex

Code, Pre and Leading Spaces

In Mediawiki there are a variety of ways to say: Just show what I typed

• <nowiki>
• <pre>
• <code>
• Leading Spaces (starting a line with a space)

<nowiki> gets translated to {noformat}
<pre> gets translated to {code}
<code> get translated to {code}
Leading spaces get translated to {panel}

Code, Pre, and Leading Spaces Conversion Customization If you want to change these, the converters you are interested in are : Mediawiki.0080-ws2panel.class Mediawiki.0090-re_pre.java-regex-tokenizer Mediawiki.0095-re_code.java-regex-tokenizer Mediawiki.0200-re_noformat.java-regex

Planned Future improvements

• more syntax handling (including definition lists, more complicated image syntax, more complicated table syntax)

Other options - Intient's MediaWiki to Confluence

MediaWiki users have another good option to explore which is
the MediaWiki to Confluence converter from Intient.