Markowik

Markowik is a Python app that converts Markdown formatted text to Google Code Wiki.

Markowik is able to convert most Markdown constructs to its Google Code Wiki (GCW) equivalents. Instead of listing all supported conversions, please have a look at Markowik's test suite and its show case.

Installation

Run:

pip install markowik

or:

easy_install markowik

You can also use Markowik without installation, as described under Contribute.

Command Line Usage

From the help output:

usage: markowik [-h] [--mx [MX [MX ...]]] [--image-baseurl URL]
 [--html-images] [--encoding ENCODING] [--quiet]
 INFILE [OUTFILE]

Convert Markdown to Google Code Wiki.

positional arguments:
 INFILE markdown file
 OUTFILE wiki file (default: stdout)

optional arguments:
 -h, --help show this help message and exit
 --mx [MX [MX ...]] markdown extensions to activate
 --image-baseurl URL base URL to prepend to relative image locations
 --html-images always use HTML for images
 --encoding ENCODING encoding of input and output (default: UTF8)
 --quiet disable info messages

Markdown extensions may be given similarly as to the Python Markdown (PyMD) command line tool, with the exception that individual extensions must be separated by a space:

markowik INPUT --mx tables def_list

The currently supported (i.e. tested) extensions are abbr, tables, and def_list. Other extensions generally should work too but might yield unexpected results in the converted wiki text.

Concerning the option --html-images, see the explanations below at Limitations.

Programmatic Usage

Markowik is implemented in Python. The markowik module provides a function named convert. Semantically it is similar to the command line interface (keyword arguments correspond to command line options). Here's a short usage example:

>>> import markowik
>>> markowik.convert("Some *markdown* text ...", mx=['tables'])
u'Some _markdown_ text ...'

Page Pragmas

GCW page pragmas can be set in Markdown source files as meta data in the format defined by the PyMD meta extension:

>>> src = """Summary: page summary
... Labels: some, labels
...
... Here starts the *page* ..
... """
>>> print markowik.convert(src, mx=['meta'])
#summary page summary
#labels some, labels
< BLANKLINE >
Here starts the _page_ ..

Note that the meta extension has to be enabled explicitly, i.e. by default Markowik does not recognize page pragmas.

What is new in this release:

• Markowik now supports (and requires) PyMD ≥ 2.1. Next to minor API changes PyMD 2.1 also had some changes and improvements in its conversion process -- for details, check how tests have been adjusted for PyMD 2.1.

What is new in version 0.1.1:

• Improved documentation.
• Minor fixes.

Requirements:

• Python

Limitations:

• GCW cannot express all markup possible in Markdown. This means Markdown source files should be written with the following limitations in mind.
• URLs in Links and Images:
• URLs used for links or image sources have to be absolute and must have a specific protocol to get recognized by GCW. In particular, any URL must start with http://, https://, or ftp://. Markowik aborts the conversion if it finds URLs not matching these requirements.
• Typefacing in Link Names:
• GCW does not support typefacing in link names. For instance GCW renders the link name in [http://foo.com _Foo_] literally, i.e. as _Foo_. However, GCW recognizes typefacing in HTML links, i.e. < a href="http://foo.com" >_Foo_< /a > is emphasized properly. For this reason Markdown links with nested typefacing like [*Foo*](http://foo.com) will be converted to HTML links. As a result, link labels with certain special characters which have to be escaped in GCW using backtick (`) markers will also result in HTML links.
• Nested Paragraphs:
• GCW does not really support multiple nested paragraphs (e.g. in lists or blockquotes). Markowik simulates multiple nested paragraphs by separating them with a < br/ > (which visually mimics paragraphs but does not break the nesting environment).
• Images:
• Markdown allows to express alternative and title texts for images. GCW's image syntax does not support this. The only way to preserve these texts is to use plain HTML < img > tags. The option --html-images enables this workaround.
• Another issue is that GCW expects image URLs to end with an image file type extension. Markowik adds artificial image extensions if necessary, for instance http://foo.bar/image is changed to http://foo.bar/image?x=x.png.
• Abbreviations:
• GCW has no markup for abbreviations nor does it support the HTML tag < abbr >. Markowik converts abbreviations to < span >-elements which kind of mimics abbreviations (in a limited fashion of course).
• HTML:
• Any plain HTML occurring in a Markdown source ends up literally in GCW (with the exception of the content of span-level tags). This means the Markdown source should only contain HTML supported by GCW. Another implication is that URLs used in plain HTML tags are not checked for GCW compatibility. In other words: when using raw HTML you are on your own!