8.5 KiB
Misaka
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).
See the /changelog
for all changes.
Installation
Misaka has been tested on CPython 2.6, 2.7, 3.2, 3.3, 3.4, 3.5 and PyPy 2.6. CFFI 1.0 or newer is required. This means Misaka will not work on PyPy 2.5 and older versions.
If you're installing from source and are using Debian or a Debian
derivative (e.g. Ubuntu) make sure python-dev
and
libffi-dev
are installed.
Install with pip:
pip install misaka
Or grab the source from Github:
git clone https://github.com/FSX/misaka.git
cd misaka
python setup.py install
Consult the CFFI documentation if you experience problems installing CFFI.
Usage
Very simple example:
import misaka as m
print m.html('some other text')
Or:
from misaka import Markdown, HtmlRenderer
= HtmlRenderer()
rndr = Markdown(rndr)
md
print md('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, ClassNotFound
from pygments.lexers import get_lexer_by_name
class HighlighterRenderer(m.HtmlRenderer):
def blockcode(self, text, lang):
try:
= get_lexer_by_name(lang, stripall=True)
lexer except ClassNotFound:
= None
lexer
if lexer:
= HtmlFormatter()
formatter return highlight(text, lexer, formatter)
# default
return '\n<pre><code>{}</code></pre>\n'.format(
h.escape_html(text.strip()))
= HighlighterRenderer()
renderer = m.Markdown(renderer, extensions=('fenced-code',))
md
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.
Tests
tidy is needed to run the tests. tox can be used to run the tests on all supported Python versions with one command.
Run one of the following commands to install tidy:
apt-get install tidy # Debian and derivatives
pacman -S tidyhtml # Arch Linux
And run the tests with:
python setup.py test
It's also possible to include or exclude tests. -i
and
-e
accept a comma separated list of testcases:
# Only run MarkdownConformanceTest_10
python setup.py test -i MarkdownConformanceTest_10
# Or everything except MarkdownConformanceTest_10
python setup.py test -e MarkdownConformanceTest_10
# Or everything except MarkdownConformanceTest_10 and MarkdownConformanceTest_103
python setup.py test -e MarkdownConformanceTest_10,MarkdownConformanceTest_103
-l
prints a list of all testcases:
$ python setup.py test -l
[... build output ...]
MarkdownConformanceTest_10
MarkdownConformanceTest_103
BenchmarkLibraries
ArgsToIntTest
CustomRendererTest
SmartypantsTest
And -b
runs benchmarks (-i
and
-e
can also be used in combination with
-b
):
$ python setup.py test -b
[... build output ...]
>> BenchmarkLibraries
test_hoep 3270 1.00 s/t 305.91 us/op
test_markdown 20 1.23 s/t 61.44 ms/op
test_markdown2 10 3.29 s/t 329.34 ms/op
test_misaka 3580 1.00 s/t 280.01 us/op
test_misaka_classes 3190 1.00 s/t 314.00 us/op
test_mistune 70 1.04 s/t 14.91 ms/o
What you see in the above output are the name, repetitions, total amount of time (in seconds) and the time taken for an operation (one repetition). A benchmark tries to stay within one second and runs a test for a minimum of ten repetitions and tries another ten if there's time left.
API
Extensions
Name | Constant |
---|---|
tables | EXT_TABLES |
fenced-code | EXT_FENCED_CODE |
footnotes | EXT_FOOTNOTES |
autolink | EXT_AUTOLINK |
strikethrough | EXT_STRIKETHROUGH |
underline | EXT_UNDERLINE |
highlight | EXT_HIGHLIGHT |
quote | EXT_QUOTE |
superscript | EXT_SUPERSCRIPT |
math | EXT_MATH |
no-intra-emphasis | EXT_NO_INTRA_EMPHASIS |
space-headers | EXT_SPACE_HEADERS |
math-explicit | EXT_MATH_EXPLICIT |
disable-indented-code | EXT_DISABLE_INDENTED_CODE |
HTML render flags
Name | Constant |
---|---|
skip-html | HTML_SKIP_HTML |
escape | HTML_ESCAPE |
hard-wrap | HTML_HARD_WRAP |
use-xhtml | HTML_USE_XHTML |
Functions
html
smartypants
escape_html
Classes
Markdown
HtmlRenderer
SaferHtmlRenderer
HtmlTocRenderer
BaseRenderer
lang
contains the language when fenced code blocks are enabled and a language is defined in ther code block.
level
can be a humber from 1 to 6.
Depends on the tables extension.
Depends on the tables extension.
Depends on the tables extension.
Depends on the tables extension.
Depends on the tables extension.
align
can be empty,center
,left
orright
.
Depends on the footnotes extension.
Depends on the footnotes extension.
Depends on the footnotes extension.
Depends on the autolink extension.
Depends on the underline extension.
Depends on the highlight extension.
Depends on the quote extension.
Depends on the strikethrough extension.
Depends on the superscript extension.
Depends on the math extension.
displaymode
can be0
or1
. This is how :pyHtmlRenderer
handles it:if displaymode == 1: return '\\[{}\\]'.format(text) else: # displaymode == 0 return '\\({}\\)'.format(text)