Bitbucket is a code hosting site with unlimited public and private repositories. We're also free for small teams!

Close

Markowik

Markowik converts Markdown to Google Code Wiki.

Flattr this

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

Installation

Markowik requires Python 2.6 or 2.7.

Run:

pip install markowik

or:

easy_install markowik

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

Usage

Command Line

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 Caveats.

Programmatic

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.

Caveats

GCW cannot express all markup possible in Markdown. This means Markdown source files should be written with the following limitations in mind.

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!

Resources

Releases and documentation:
 PyPI
Issues, source code, and test suite show case:
 Google Code
Source code mirrors:
 BitBucket and GitHub

Contributions

To contribute to Markowik, fork the project at Google Code, BitBucket, or GitHub.

Every fix or new feature should include one or more corresponding test cases (check the existing tests for how tests should look like). Please also post an issue describing your fix or enhancement.

Markowik uses Buildout to easily set up the development environment. Buildout automates the process of downloading and installing requirements to use and develop Markowik. Requirements are installed local to the project source directory, i.e. it does not clutter the system Python installation.

In a fresh source checkout, run:

$ python bootstrap.py
$ bin/buildout

When done, the following scripts can be found in the bin/ directory:

markowik
The Markowik command line tool, ready to use.
tests
Test runner script (a wrapper for nose).
fab
Fabric binary to use for the project's fabfile.
python
A Python interpreter whith acces to the local development version of the markowik module.

Changes

Version 0.2

  • 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.

Version 0.1.2

  • Explicitly require PyMD 2.0.3 (this is a temporary fix until markowik correctly works with PyMD 2.1). Note: If this conflicts with requirements of other Python packages, run markowik in its own buildout as described above.
  • Minor documentation tweaks.

Version 0.1.1

  • Improved documentation.
  • Minor fixes.

Version 0.1

  • Initial release.

Recent activity

Oben Sonne

Commits by Oben Sonne were pushed to obensonne/markowik

03667c4 - tests: adjust deflists test for PyMD 2.1 Since PyMD 2.1, multi-line descriptions in defintion lists do not need to be indented, i.e. unindented continuation lines ...
Oben Sonne

Commits by Oben Sonne were pushed to obensonne/markowik

e6dcb64 - markdown: do not use placeholders for escaped characters This patch recreates the Python Markdown 2.0.3 behavior where escaped characters are simply unescaped. Python Markdown 2.1 ...
Oben Sonne

Commits by Oben Sonne were pushed to obensonne/markowik

5bb360d - tests: adjust html-characters test to PyMD 2.1 PyMD now detects if angle brackets and ampersands should be taken literally.
Oben Sonne

Commits by Oben Sonne were pushed to obensonne/markowik

313d498 - tests: adjust nested blocks test for PyMD 2.1 PyMD now supports paragraphs in lists nested in blockquotes.
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.