Metadata-Version: 2.1
Name: markdown-it-py
Version: 0.1.0
Summary: PYthon port of mardown-it. Markdown parser, done right.
Home-page: https://github.com/ExecutableBookProject/markdown-it-py
Author: Chris Sewell
Author-email: chrisj_sewell@hotmail.com
License: MIT
Description: # markdown-it-py
        
        ![Github-DI][github-ci]
        [![Code style: black][black-badge]][black-link]
        
        [github-ci]: https://github.com/ExecutableBookProject/markdown-it-py/workflows/Python%20package/badge.svg
        [black-badge]: https://img.shields.io/badge/code%20style-black-000000.svg
        [black-link]: https://github.com/ambv/black
        
        
        This is a Python port of [markdown-it](https://github.com/markdown-it/markdown-it),
        and some of its associated plugins.
        It is still under development, so for now should be used with caution.
        
        Details of the port can be found in `markdown_it/port.yaml` and in `port.yaml`
        within the extension folders. But the driving design philosiphy has been to change as little of the
        fundamental code structure (file names, function name, etc) as possible.
        It is very simple to write complimentary extensions for both language implementations!
        
        Basic usage:
        
        
        ```python
        from markdown_it import MarkdownIt
        from markdown_it.extensions.front_matter import front_matter_plugin
        from markdown_it.extensions.footnote import footnote_plugin
        
        md = (
            MarkdownIt()
            .use(front_matter_plugin)
            .use(footnote_plugin)
            .disable('image')
            .enable('table')
        )
        tokens = md.parse("some text")
        text = md.render("some text")
        ```
        
        Also you can use it from the command-line:
        
        ```console
        $ markdown-it
        markdown-it-py [version 0.1.0] (interactive)
        Type Ctrl-D to complete input, or Ctrl-C to exit.
        >>> > **hallo** there!
        ...
        <blockquote>
        <p><strong>hallo</strong> there!</p>
        </blockquote>
        ```
        
        ## Benchmarking
        
        markdown-it=py is the fastest _**CommonMark compliant**_ parser written in python!
        
        ```console
        $ markdown-it-bench -n 30
        Test document: spec.md
        Test iterations: 30
        Running 7 test(s) ...
        =====================
        [mistune         (0.8.4): 3.62 s]*
        markdown-it-py   (0.1.0): 9.03 s
        mistletoe        (0.10.0): 9.89 s
        commonmark-py    (0.9.1): 20.82 s
        pymarkdown       (3.2.1): 34.50 s
        pymarkdown:extra (3.2.1): 41.86 s
        panflute         (1.12.5): 35.02 s
        ```
        
        \*Note `mistune` is not CommonMark compliant, which is what allows for its
        faster parsing, at the expense of issues, for example, with nested inline parsing.
        See [mistletoes's explanation](https://github.com/miyuchina/mistletoe#performance)
        for further details.
        
        ## Original README
        
        > Markdown parser done right. Fast and easy to extend.
        
        __[Live demo](https://markdown-it.github.io)__
        
        - Follows the __[CommonMark spec](http://spec.commonmark.org/)__ + adds syntax extensions & sugar (URL autolinking, typographer).
        - Configurable syntax! You can add new rules and even replace existing ones.
        - High speed.
        - [Safe](https://github.com/markdown-it/markdown-it/tree/master/docs/security.md) by default.
        - Community-written __[plugins](https://www.npmjs.org/browse/keyword/markdown-it-plugin)__ and [other packages](https://www.npmjs.org/browse/keyword/markdown-it) on npm.
        
        __Table of content__
        
        - [markdown-it-py](#markdown-it-py)
          - [Benchmarking](#benchmarking)
          - [Original README](#original-readme)
          - [Install](#install)
          - [Usage examples](#usage-examples)
            - [Simple](#simple)
            - [Init with presets and options](#init-with-presets-and-options)
            - [Plugins load](#plugins-load)
            - [Syntax highlighting](#syntax-highlighting)
            - [Linkify](#linkify)
          - [API](#api)
          - [Syntax extensions](#syntax-extensions)
            - [Manage rules](#manage-rules)
          - [Benchmark](#benchmark)
          - [markdown-it for enterprise](#markdown-it-for-enterprise)
          - [Authors](#authors)
          - [References / Thanks](#references--thanks)
        
        ## Install
        
        **node.js** & **bower**:
        
        ```bash
        npm install markdown-it --save
        bower install markdown-it --save
        ```
        
        **browser (CDN):**
        
        - [jsDeliver CDN](http://www.jsdelivr.com/#!markdown-it "jsDelivr CDN")
        - [cdnjs.com CDN](https://cdnjs.com/libraries/markdown-it "cdnjs.com")
        
        
        ## Usage examples
        
        See also:
        
        - __[API documentation](https://markdown-it.github.io/markdown-it/)__ - for more
          info and examples.
        - [Development info](https://github.com/markdown-it/markdown-it/tree/master/docs) -
          for plugins writers.
        
        
        ### Simple
        
        ```js
        // node.js, "classic" way:
        var MarkdownIt = require('markdown-it'),
            md = new MarkdownIt();
        var result = md.render('# markdown-it rulezz!');
        
        // node.js, the same, but with sugar:
        var md = require('markdown-it')();
        var result = md.render('# markdown-it rulezz!');
        
        // browser without AMD, added to "window" on script load
        // Note, there is no dash in "markdownit".
        var md = window.markdownit();
        var result = md.render('# markdown-it rulezz!');
        ```
        
        Single line rendering, without paragraph wrap:
        
        ```js
        var md = require('markdown-it')();
        var result = md.renderInline('__markdown-it__ rulezz!');
        ```
        
        
        ### Init with presets and options
        
        (*) presets define combinations of active rules and options. Can be
        `"commonmark"`, `"zero"` or `"default"` (if skipped). See
        [API docs](https://markdown-it.github.io/markdown-it/#MarkdownIt.new) for more details.
        
        ```js
        // commonmark mode
        var md = require('markdown-it')('commonmark');
        
        // default mode
        var md = require('markdown-it')();
        
        // enable everything
        var md = require('markdown-it')({
          html: true,
          linkify: true,
          typographer: true
        });
        
        // full options list (defaults)
        var md = require('markdown-it')({
          html:         false,        // Enable HTML tags in source
          xhtmlOut:     false,        // Use '/' to close single tags (<br />).
                                      // This is only for full CommonMark compatibility.
          breaks:       false,        // Convert '\n' in paragraphs into <br>
          langPrefix:   'language-',  // CSS language prefix for fenced blocks. Can be
                                      // useful for external highlighters.
          linkify:      false,        // Autoconvert URL-like text to links
        
          // Enable some language-neutral replacement + quotes beautification
          typographer:  false,
        
          // Double + single quotes replacement pairs, when typographer enabled,
          // and smartquotes on. Could be either a String or an Array.
          //
          // For example, you can use '«»„“' for Russian, '„“‚‘' for German,
          // and ['«\xA0', '\xA0»', '‹\xA0', '\xA0›'] for French (including nbsp).
          quotes: '“”‘’',
        
          // Highlighter function. Should return escaped HTML,
          // or '' if the source string is not changed and should be escaped externally.
          // If result starts with <pre... internal wrapper is skipped.
          highlight: function (/*str, lang*/) { return ''; }
        });
        ```
        
        ### Plugins load
        
        ```js
        var md = require('markdown-it')()
                    .use(plugin1)
                    .use(plugin2, opts, ...)
                    .use(plugin3);
        ```
        
        
        ### Syntax highlighting
        
        Apply syntax highlighting to fenced code blocks with the `highlight` option:
        
        ```js
        var hljs = require('highlight.js'); // https://highlightjs.org/
        
        // Actual default values
        var md = require('markdown-it')({
          highlight: function (str, lang) {
            if (lang && hljs.getLanguage(lang)) {
              try {
                return hljs.highlight(lang, str).value;
              } catch (__) {}
            }
        
            return ''; // use external default escaping
          }
        });
        ```
        
        Or with full wrapper override (if you need assign class to `<pre>`):
        
        ```js
        var hljs = require('highlight.js'); // https://highlightjs.org/
        
        // Actual default values
        var md = require('markdown-it')({
          highlight: function (str, lang) {
            if (lang && hljs.getLanguage(lang)) {
              try {
                return '<pre class="hljs"><code>' +
                       hljs.highlight(lang, str, true).value +
                       '</code></pre>';
              } catch (__) {}
            }
        
            return '<pre class="hljs"><code>' + md.utils.escapeHtml(str) + '</code></pre>';
          }
        });
        ```
        
        ### Linkify
        
        `linkify: true` uses [linkify-it](https://github.com/markdown-it/linkify-it). To
        configure linkify-it, access the linkify instance through `md.linkify`:
        
        ```js
        md.linkify.tlds('.py', false);  // disables .py as top level domain
        ```
        
        
        ## API
        
        __[API documentation](https://markdown-it.github.io/markdown-it/)__
        
        If you are going to write plugins - take a look at
        [Development info](https://github.com/markdown-it/markdown-it/tree/master/docs).
        
        
        ## Syntax extensions
        
        Embedded (enabled by default):
        
        - [Tables](https://help.github.com/articles/organizing-information-with-tables/) (GFM)
        - [Strikethrough](https://help.github.com/articles/basic-writing-and-formatting-syntax/#styling-text) (GFM)
        
        Via plugins:
        
        - [subscript](https://github.com/markdown-it/markdown-it-sub)
        - [superscript](https://github.com/markdown-it/markdown-it-sup)
        - [footnote](https://github.com/markdown-it/markdown-it-footnote)
        - [definition list](https://github.com/markdown-it/markdown-it-deflist)
        - [abbreviation](https://github.com/markdown-it/markdown-it-abbr)
        - [emoji](https://github.com/markdown-it/markdown-it-emoji)
        - [custom container](https://github.com/markdown-it/markdown-it-container)
        - [insert](https://github.com/markdown-it/markdown-it-ins)
        - [mark](https://github.com/markdown-it/markdown-it-mark)
        - ... and [others](https://www.npmjs.org/browse/keyword/markdown-it-plugin)
        
        
        ### Manage rules
        
        By default all rules are enabled, but can be restricted by options. On plugin
        load all its rules are enabled automatically.
        
        ```js
        // Activate/deactivate rules, with curring
        var md = require('markdown-it')()
                    .disable([ 'link', 'image' ])
                    .enable([ 'link' ])
                    .enable('image');
        
        // Enable everything
        md = require('markdown-it')({
          html: true,
          linkify: true,
          typographer: true,
        });
        ```
        
        You can find all rules in sources:
        [parser_core.js](lib/parser_core.js), [parser_block](lib/parser_block.js),
        [parser_inline](lib/parser_inline.js).
        
        
        ## Benchmark
        
        Here is the result of readme parse at MB Pro Retina 2013 (2.4 GHz):
        
        ```bash
        make benchmark-deps
        benchmark/benchmark.js readme
        
        Selected samples: (1 of 28)
         > README
        
        Sample: README.md (7774 bytes)
         > commonmark-reference x 1,222 ops/sec ±0.96% (97 runs sampled)
         > current x 743 ops/sec ±0.84% (97 runs sampled)
         > current-commonmark x 1,568 ops/sec ±0.84% (98 runs sampled)
         > marked x 1,587 ops/sec ±4.31% (93 runs sampled)
        ```
        
        __Note.__ CommonMark version runs with [simplified link normalizers](https://github.com/markdown-it/markdown-it/blob/master/benchmark/implementations/current-commonmark/index.js)
        for more "honest" compare. Difference is ~ 1.5x.
        
        As you can see, `markdown-it` doesn't pay with speed for it's flexibility.
        Slowdown of "full" version caused by additional features not available in
        other implementations.
        
        
        ## markdown-it for enterprise
        
        Available as part of the Tidelift Subscription.
        
        The maintainers of `markdown-it` and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. [Learn more.](https://tidelift.com/subscription/pkg/npm-markdown-it?utm_source=npm-markdown-it&utm_medium=referral&utm_campaign=enterprise&utm_term=repo)
        
        
        ## Authors
        
        - Alex Kocharin [github/rlidwka](https://github.com/rlidwka)
        - Vitaly Puzrin [github/puzrin](https://github.com/puzrin)
        
        _markdown-it_ is the result of the decision of the authors who contributed to
        99% of the _Remarkable_ code to move to a project with the same authorship but
        new leadership (Vitaly and Alex). It's not a fork.
        
        ## References / Thanks
        
        Big thanks to [John MacFarlane](https://github.com/jgm) for his work on the
        CommonMark spec and reference implementations. His work saved us a lot of time
        during this project's development.
        
        **Related Links:**
        
        - https://github.com/jgm/CommonMark - reference CommonMark implementations in C & JS,
          also contains latest spec & online demo.
        - http://talk.commonmark.org - CommonMark forum, good place to collaborate
          developers' efforts.
        
        **Ports**
        
        - [motion-markdown-it](https://github.com/digitalmoksha/motion-markdown-it) - Ruby/RubyMotion
        
Keywords: markdown lexer parser development
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Processing :: Markup
Requires-Python: ~=3.6
Description-Content-Type: text/markdown
Provides-Extra: code_style
Provides-Extra: testing
Provides-Extra: rtd
Provides-Extra: benchmark
