.. py:currentmodule:: misaka 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 :doc:`/changelog` for all changes. .. _Hoedown: https://github.com/hoedown/hoedown Installation ------------ Misaka has been tested on CPython 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. 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. .. _CFFI documentation: https://cffi.readthedocs.org/en/latest/installation.html Usage ----- Very simple example: .. code:: python import misaka as m print m.html('some other text') Or: .. code:: python 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): .. code:: python 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
{}
\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=('fenced-code',)) print(md(""" Here is some code: ```python print(123) ``` More code: print(123) """)) The above code listing subclasses :py:class:`HtmlRenderer` and implements a :py:meth:`BaseRenderer.blockcode` method. See ``tests/test_renderer.py`` for a renderer with all its methods implemented. .. _Pygments: http://pygments.org .. _houdini: https://github.com/FSX/houdini.py 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. .. _tidy: http://tidy.sourceforge.net .. _tox: https://testrun.org/tox/ 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 ^^^^^^^^^ .. autofunction:: html .. autofunction:: smartypants Classes ^^^^^^^ .. autoclass:: Markdown :members: .. autoclass:: HtmlRenderer :members: .. autoclass:: HtmlTocRenderer :members: .. autoclass:: BaseRenderer .. py:method:: blockcode(text, lang='') ``lang`` contains the language when fenced code blocks are enabled and a language is defined in ther code block. .. py:method:: blockquote(content) .. py:method:: header(content, level) ``level`` can be a humber from 1 to 6. .. py:method:: hrule() .. py:method:: list(content, is_ordered, is_block) .. py:method:: listitem(content, is_ordered, is_block) .. py:method:: paragraph(content) .. py:method:: table(content) Depends on the tables extension. .. py:method:: table_header(content) Depends on the tables extension. .. py:method:: table_body(content) Depends on the tables extension. .. py:method:: table_row(content) Depends on the tables extension. .. py:method:: table_cell(content, align, is_header) Depends on the tables extension. ``align`` can be empty, ``center``, ``left`` or ``right``. .. py:method:: footnotes(content) Depends on the footnotes extension. .. py:method:: footnote_def(content, num) Depends on the footnotes extension. .. py:method:: footnote_ref(num) Depends on the footnotes extension. .. py:method:: blockhtml(text) .. py:method:: autolink(link, is_email) Depends on the autolink extension. .. py:method:: codespan(text) .. py:method:: double_emphasis(content) .. py:method:: emphasis(content) .. py:method:: underline(content) Depends on the underline extension. .. py:method:: highlight(content) Depends on the highlight extension. .. py:method:: quote(content) Depends on the quote extension. .. py:method:: image(link, title='', alt='') .. py:method:: linebreak() .. py:method:: link(content, link, title='') .. py:method:: triple_emphasis(content) .. py:method:: strikethrough(content) Depends on the strikethrough extension. .. py:method:: superscript(content) Depends on the superscript extension. .. py:method:: math(text, displaymode) Depends on the math extension. ``displaymode`` can be ``0`` or ``1``. This is how :py:class:`HtmlRenderer` handles it: .. code:: python if displaymode == 1: return '\\[{}\\]'.format(text) else: # displaymode == 0 return '\\({}\\)'.format(text) .. py:method:: raw_html(text) .. py:method:: entity(text) .. py:method:: normal_text(text) .. py:method:: doc_header(inline_render) .. py:method:: doc_footer(inline_render)