7.6 KiB

Raw Blame History

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.0b2 (2015-08-??)

Rename Markdown.render to Markdown.__call__.

2.0.0b1 (2015-07-18)

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/run_tests.py

Usage

Very simple example:

from misaka import Markdown, HtmlRenderer

rndr = HtmlRenderer()
md = Markdown(rndr)

print md('some text')

Or:

import misaka as m
print m.html('some other 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("""
Here is some code:

```python
print(123)
```

More code:

    print(123)
"""))

The above code listing subclasses :pyHtmlRenderer and implements a :pyBaseRenderer.blockcode method. See tests/test_renderer.py for a renderer with all its methods implemented.

API

Extensions

HTML render flags

Render method flags

These constants are passed to individual render methods as flags.

Classes

BaseRenderer

lang contains the language when fenced code blocks (:pyEXT_FENCED_CODE) are enabled and a language is defined in ther code block.

level can be a humber from 1 to 6.

flags can contain the following flags:

:pyLIST_ORDERED: An ordered list.

:pyLI_BLOCK: The contents of list items contain block elements (e.g. paragraphs).

Depends on :pyEXT_TABLES.

Depends on :pyEXT_TABLES.

flags can contain the following flags:

:pyTABLE_ALIGNMASK: Alignment of the table cell.

:pyTABLE_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 = ''

Depends on :pyEXT_FOOTNOTES.

Depends on :pyEXT_AUTOLINK.

type can be :pyAUTOLINK_NORMAL or :pyAUTOLINK_EMAIL.

Depends on :pyEXT_UNDERLINE.

Depends on :pyEXT_HIGHLIGHT.

Depends on :pyEXT_QUOTE.

Depends on :pyEXT_STRIKETHROUGH.

Depends on :pyEXT_SUPERSCRIPT.

Depends on :pyEXT_MATH.

displaymode can be 0 or 1. This is how :pyHtmlRenderer handles it:
if displaymode == 1:
    return '\\[{}\\]'.format(text)
else:  # displaymode == 0
    return '\\({}\\)'.format(text)

HtmlRenderer

HtmlTocRenderer

Markdown

Functions

html

smartypants

7.6 KiB Raw Blame History