Documentation¶

Misaka is a CFFI-based binding for Hoedown, a fast markdown processing library written in C. It features a fast HTML renderer and functionality to make custom renderers (e.g. man pages or LaTeX).

Changelog¶

2.0.0 (2015-07-??)

Rewrite. CFFI and Hoedown instead of Cython and Sundown.
Remove pre- and postprocessor support.
Smartypants is a normal function instead of a postprocessor.
Documentation now uses Sphinx.

See the full changelog at Changelog.

Installation¶

Misaka has been tested on CPython 2.7, 3.2, 3.3, 3.4 and PyPy 2.6. It needs CFFI 1.0 or newer, because of this it will not work on PyPy 2.5 and older.

With pip:

pip install misaka

Or the lastest development version from Github:

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

And run the tests:

python setup.py test  # or...
python tests/runner.py

Usage¶

Just HTML:

import misaka as m
print m.html('some other text')

Or:

from misaka import Markdown, HtmlRenderer

rndr = HtmlRenderer()
md = Markdown(rndr)

print md.render('some text')

Here’s a simple example that uses Pygments to highlight code (houdini is used to escape the HTML):

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

class HighlighterRenderer(m.HtmlRenderer):
    def blockcode(self, text, lang):
        if not lang:
            return '\n<pre>{}</code></pre>\n'.format(
                h.escape_html(text.strip()))

        lexer = get_lexer_by_name(lang, stripall=True)
        formatter = HtmlFormatter()

        return highlight(text, lexer, formatter)

renderer = HighlighterRenderer()
md = m.Markdown(renderer, extensions=m.EXT_FENCED_CODE)

print(md.render("""
Here is some code:

```python
print(123)
```

More code:

    print(123)
"""))

The above code listing subclasses HtmlRenderer and implements a BaseRenderer.blockcode() method. See tests/test_renderer.py for a renderer with all its methods implemented.

API¶

Extensions¶

misaka.EXT_TABLES¶

misaka.EXT_FENCED_CODE¶

misaka.EXT_FOOTNOTES¶

misaka.EXT_AUTOLINK¶

misaka.EXT_STRIKETHROUGH¶

misaka.EXT_UNDERLINE¶

misaka.EXT_HIGHLIGHT¶

misaka.EXT_QUOTE¶

misaka.EXT_SUPERSCRIPT¶

misaka.EXT_MATH¶

misaka.EXT_NO_INTRA_EMPHASIS¶

misaka.EXT_SPACE_HEADERS¶

misaka.EXT_MATH_EXPLICIT¶

misaka.EXT_DISABLE_INDENTED_CODE¶

HTML render flags¶

misaka.HTML_SKIP_HTML¶

misaka.HTML_ESCAPE¶

misaka.HTML_HARD_WRAP¶

misaka.HTML_USE_XHTML¶

Render method flags¶

These constants are passed to individual render methods as flags.

misaka.LIST_ORDERED¶

misaka.LI_BLOCK¶

misaka.TABLE_ALIGN_LEFT¶

misaka.TABLE_ALIGN_RIGHT¶

misaka.TABLE_ALIGN_CENTER¶

misaka.TABLE_ALIGNMASK¶

misaka.TABLE_HEADER¶

misaka.AUTOLINK_NORMAL¶

misaka.AUTOLINK_EMAIL¶

Classes¶

class misaka.BaseRenderer¶

blockcode(text, lang='')¶: lang contains the language when fenced code blocks (EXT_FENCED_CODE) are enabled and a language is defined in ther code block.

blockquote(content)¶

header(content, level)¶: level can be a humber from 1 to 6.

hrule()¶

list(content, flags=0)¶

flags can contain the following flags:

LIST_ORDERED: An ordered list.
LI_BLOCK: The contents of list items contain block elements (e.g. paragraphs).

listitem(content, flags=0)¶

flags can contain the following flags:

LIST_ORDERED: An ordered list.
LI_BLOCK: The contents of list items contain block elements (e.g. paragraphs).

paragraph(content)¶

table(content)¶: Depends on EXT_TABLES.

table_header(content)¶: Depends on EXT_TABLES.

table_body(content)¶: Depends on EXT_TABLES.

table_row(content)¶: Depends on EXT_TABLES.

table_cell(content, flags=0)¶

Depends on EXT_TABLES.

flags can contain the following flags:

TABLE_ALIGNMASK: Alignment of the table cell.
TABLE_HEADER: Table cell is located in the table header.

TABLE_ALIGNMASK can be used to check what the alignment of the cell is. Here’s an example:

align_bit = flags & misaka.TABLE_ALIGNMASK

if align_bit == misaka.TABLE_ALIGN_CENTER:
    align = 'center'
elif align_bit == misaka.TABLE_ALIGN_LEFT:
    align = 'left'
elif align_bit == misaka.TABLE_ALIGN_RIGHT:
    align = 'right'
else:
    align = ''

footnotes(content)¶: Depends on EXT_FOOTNOTES.

footnote_def(content, num)¶: Depends on EXT_FOOTNOTES.

footnote_ref(num)¶: Depends on EXT_FOOTNOTES.

blockhtml(text)¶

autolink(link, type)¶

Depends on EXT_AUTOLINK.

type can be AUTOLINK_NORMAL or AUTOLINK_EMAIL.

codespan(text)¶

double_emphasis(content)¶

emphasis(content)¶

underline(content)¶: Depends on EXT_UNDERLINE.

highlight(content)¶: Depends on EXT_HIGHLIGHT.

quote(content)¶: Depends on EXT_QUOTE.

image(link, title='', alt='')¶

linebreak()¶

link(content, link, title='')¶

triple_emphasis(content)¶

strikethrough(content)¶: Depends on EXT_STRIKETHROUGH.

superscript(content)¶: Depends on EXT_SUPERSCRIPT.

math(text, displaymode)¶

Depends on EXT_MATH.

displaymode can be 0 or 1. This is how HtmlRenderer handles it:

if displaymode == 1:
    return '\\[{}\\]'.format(text)
else:  # displaymode == 0
    return '\\({}\\)'.format(text)

raw_html(text)¶

entity(text)¶

normal_text(text)¶

doc_header(inline_render)¶

doc_footer(inline_render)¶

class misaka.HtmlRenderer(flags=0, nesting_level=0)¶

A wrapper for the HTML renderer that’s included in Hoedown.

nesting_level limits what’s included in the table of contents. The default value is 0, no headers.

An instance of the HtmlRenderer can not be shared with multiple Markdown instances, because it carries state that’s changed by the Markdown instance.

class misaka.HtmlTocRenderer(nesting_level=6)¶

A wrapper for the HTML table of contents renderer that’s included in Hoedown.

nesting_level limits what’s included in the table of contents. The default value is 6, all headers.

An instance of the HtmlTocRenderer can not be shared with multiple Markdown instances, because it carries state that’s changed by the Markdown instance.

class misaka.Markdown(renderer, extensions=0)¶

Parses markdown text and renders it using the given renderer.

render(text)¶: Parses and renders markdown text.

Functions¶

misaka.html(text, extensions=0, render_flags=0)¶: Convert markdown text to HTML.

misaka.smartypants(text)¶

Transforms sequences of characters into HTML entities.

Markdown	HTML	Result
`'s` (s, t, m, d, re, ll, ve)	’s	’s
`"Quotes"`	“Quotes”	“Quotes”
`---`	—	—
`--`	–	–
`...`	…	…
`. . .`	…	…
`(c)`	©	©
`(r)`	®	®
`(tm)`	™	™
`3/4`	¾	¾
`1/2`	½	½
`1/4`	¼	¼