Documentation — Misaka 2.0.0 documentation

# 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) | &rsquo;s | ’s
  `"Quotes"` | &ldquo;Quotes&rdquo; | “Quotes”
  `---` | &mdash; | —
  `--` | &ndash; | –
  `...` | &hellip; | …
  `. . .` | &hellip; | …
  `(c)` | &copy; | ©
  `(r)` | &reg; | ®
  `(tm)` | &trade; | ™
  `3/4` | &frac34; | ¾
  `1/2` | &frac12; | ½
  `1/4` | &frac14; | ¼