.. 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.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 .. _Termux: https://termux.com/ .. _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, 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
{}
\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 :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 .. autofunction:: escape_html Classes ^^^^^^^ .. autoclass:: Markdown :members: .. autoclass:: HtmlRenderer :members: .. autoclass:: SaferHtmlRenderer :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)