mwconv

Wiki text conversions based on MediaWiki

This program parses a dialect of MediaWiki syntax and converts it to various formats (html, plain text and markdown).

This is intended for documentation written using the MediaWiki syntax instead of the Markdown syntax as is more popularly used these days; there are no wiki features such as internal links implemented.

Tables and definition lists are supported.

The markdown and text versions of this file are converted using this utility.

Options

Summary

Options:
 -h, --help show this help message and exit
 -o FILE write to this file (default stdout)
 -t TYPE, --type=TYPE select output type
 -l NUMBER, --first-level=NUMBER

The output TYPE can be one of:

text

plain text output

html

- html output

md

markdown output

md_safe

markdown output with html restricted to a 'safe' subset.

mw

mediawiki output, the output will be a normalized form of the input. It will also be affected by the _first-level_ option if given.

The first-level option sets the first heading level in the output. So if it is set to 1, the the first heading will be H1 in html regardless of what level it is in the input and all the other headings adjusted appropriately.

Compatibility

The syntax is intended to be almost identical to MediaWiki text. Lots of people try (or used to try, markdown is commonly used now) to use MediaWiki for documentation since it is/was well known.

However if your documentation contains lots of lists and code sections the syntax is not altogether convenient.

1. A list item has to be all on one line.
2. There can not be any blank lines between list items.
3. A code example can't (easily) be part of a list item.

So typically you use unordered lists and it all kind of looks ok in the browser, even though the code examples are not really in the list and break the list up into multiple lists.

This implementation has the following improvements.

1. A list item can be split onto more than one line.
2. If an indented block follows the list item, then it will be actually inside the list item.
3. There are some alternative notations.