Manual

Some usage examples of Misaka. Everything about the examples is explained here. What's possible, how it works and what you get.

Installation

Installation from PyPi:

% pip install misaka

Or get the most recent version from Github:

% git clone git://github.com/FSX/misaka.git
% cd misaka
% python setup.py install

Visual Studio's support for C is not optimal and most VS compilers are missing stdint.h, which is needed to compile Misaka. This file can be downloaded from msinttypes and put into C:\Program Files (x86)\Microsoft Visual Studio 9.0\VC\include for example.

setup.py has been extended with some extra commands:

clean          - cleanup directories created by packaging and build processes
compile_cython - compile Cython files(s) into C file(s)
update_vendor  - update Sundown files. Use `git submodule foreach git pull` to the most recent files

For example:

% python setup.py compile_cython
running cython
compiling /home/frank/Code/misaka/src/misaka.pyx

For the compile_cython command you need to have Cython installed. And Git needs to be installed to make the update_vendor command effective.

You have to manually run git submodule foreach git pull before running the update_vendor command so the most recent files are downloaded first.

To run the unit tests [HTML Tidy][] must be installed first.

pacman -S tidyhtml # on Arch Linux
sudo apt-get install tidy # on Ubuntu

And then:

cd tests
python misaka_test.py

Basic Usage

You can make it yourself really easy by using misaka.html.

import misaka as m

print m.html('A ~~complex~~ simple example.',
    extensions=m.EXT_STRIKETHROUGH)
# <p>A <del>complex</del> simple example.</p>

Add another extension has been added by using the bitwise OR operator.

print m.html('The 2^(nd) ~~complex~~ simple example.',
    extensions=m.EXT_STRIKETHROUGH | m.EXT_SUPERSCRIPT)
# <p>The 2<sup>nd</sup> <del>complex</del> simple example.</p>

Adding render flags works in the same way as adding extensions. See the API documentation for a listing of Markdown extensions and HTML render flags.

print m.html('The 3^(nd) ~~complex~~ <i>simple</i> example.',
    extensions=m.EXT_STRIKETHROUGH | m.EXT_SUPERSCRIPT,
    render_flags=m.HTML_SKIP_HTML)
# <p>The 3<sup>nd</sup> <del>complex</del> simple example.</p>

The <i>'s from <i>simple</i> are not in the output.

Custom Renderers

If you would like to influence the rendering or make a new renderer yourself, don't wait and subclass BaseRenderer and start implementing your render methods.

Here is a list of methods that can be implemented in a renderer. All method arguments are prefixed with their type. A bool is a boolean, int an integer and str a string or unicode string in Python 2. Remember that these methods are going to be implemented in a class. So the first argument is always self. The data that's returned from a render method should always be a byte or unicode string.

When an exception is raised in a render method a stacktrace will be shown in STDOUT, but the rendering process will not stop. Instead the render method just returns nothing.

Block-level:

block_code(str code, str language)
block_quote(str quote)
block_html(str raw_html)
header(str text, int level)
hrule()
list(str contents, bool is_ordered)
list_item(str text, bool is_ordered)
paragraph(str text)
table(str header, str body)
table_row(str content)
table_cell(str content, int flags)

The flags argument of the table_cell method can be compared with one of the TABLE_* render flags. For example:

# Table cell is a header?
if flags & m.TABLE_HEADER:
    print 'This is a header cell'
else:
    print 'This is not a header cell'

# Alignment of the cell?
alignment = flags & m.TABLE_ALIGNMASK

if alignment == m.TABLE_ALIGN_C:
    print 'Center'
elif alignment == m.TABLE_ALIGN_L:
    print 'Left'
elif alignment == m.TABLE_ALIGN_R:
    print 'Right'
else:
    print 'Not aligned'

Span-level:

autolink(str link, bool is_email)
codespan(str code)
double_emphasis(str text)
emphasis(str text)
image(str link, str title, str alt_text)
linebreak()
link(str link, str title, str content)
raw_html(str raw_html)
triple_emphasis(str text)
strikethrough(str text)
superscript(str text)

Low-level:

entity(str text)
normal_text(str text)

Header and footer of the document:

doc_header()
doc_footer()

Pre- and post-processing:

preprocess(str full_document)
postprocess(str full_document)

Code Highlighting

A simple code highlighting example with Pygments and Houdini.py.

import houdini as h
from pygments import highlight
from pygments.lexers import get_lexer_by_name
from pygments.formatters import HtmlFormatter

# Create a custom renderer
class BleepRenderer(HtmlRenderer, SmartyPants):
    def block_code(self, text, lang):
        if not lang:
            return '\n<pre><code>%s</code></pre>\n' % \
                h.escape_html(text.strip())
        lexer = get_lexer_by_name(lang, stripall=True)
        formatter = HtmlFormatter()
        return highlight(text, lexer, formatter)

# And use the renderer
renderer = BleepRenderer()
md = m.Markdown(renderer,
    extensions=m.EXT_FENCED_CODE | m.EXT_NO_INTRA_EMPHASIS)

print md.render('Some Markdown text.')

Pre- & Postprocessors

Pre- and postprocessors are classes that implement preprocess and/or postprocess methods. Both accept one argument. The source text is passed to preprocess and the rendered text (e.g. HTML) is passed to postprocess.

Pre- and postprocessors are intended to be used as mixins as you can see in the code highlighting example. HtmlRenderer and SmartyPants are both subclassed by BleepRenderer and SmartyPants is mixin.

Here's a useless example:

class ExamplePreprocessor(object):
    def preprocess(self, text):
        return text.replace(' ', '_')

class BleepRenderer(HtmlRenderer, ExamplePreprocessor):
    pass

But you can also add a preprocess and/or postprocess to the renderer instead of using a mixin class.

class BleepRenderer(HtmlRenderer):
    def preprocess(self, text):
        return text.replace(' ', '_')

Smartypants

Smartypants is a post-processor for (X)HTML renderers and can be used standalone or as a mixin. It adds a methode named postprocess to the renderer. It converts the charachter sequences in the left column to the sequences in the right column.

Source Result
's (s, t, m, d, re, ll, ve) 1 ’s
--
-
...
. . .
(c) ©
(r) ®
(tm)
3/4 ¾
1/2 ½
1/4 ¼
  1. A ' followed by a s, t, m, d, re, ll or ve will be turned into &rsquo;s, &rsquo;t, and so on.