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, 3.6 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 build-essential
, 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.
Use the following commands to install Misaka in Termux:
apt update
apt upgrade
apt install clang python python-dev libffi libffi-dev
pip install misaka
Usage¶
Very simple example:
import misaka as m
print m.html('some other text')
Or:
from misaka import Markdown, HtmlRenderer
rndr = HtmlRenderer()
md = Markdown(rndr)
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:
lexer = get_lexer_by_name(lang, stripall=True)
except ClassNotFound:
lexer = None
if lexer:
formatter = HtmlFormatter()
return highlight(text, lexer, formatter)
# default
return '\n<pre><code>{}</code></pre>\n'.format(
h.escape_html(text.strip()))
renderer = HighlighterRenderer()
md = m.Markdown(renderer, extensions=('fenced-code',))
print(md("""
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.
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 |