Metadata-Version: 1.2
Name: cmarkgfm
Version: 0.5.0
Summary: Minimal bindings to GitHub's fork of cmark
Home-page: https://github.com/theacodes/cmarkgfm
Author: The Python Packaging Authority
Author-email: me@thea.codes, pypa-dev@googlegroups.com
License: UNKNOWN
Project-URL: Bug Reports, https://github.com/theacodes/cmarkgfm/issues
Project-URL: Funding, https://donate.pypi.org
Project-URL: Source, https://github.com/theacodes/cmarkgfm
Description: cmarkgfm - Python bindings to GitHub's cmark
        ============================================
        
        Minimalist Python bindings to GitHub's fork of cmark.
        
        Installation
        ------------
        
        This package is published on PyPI as `cmarkgfm <https://pypi.org/project/cmarkgfm/>`__
        and can be installed with `pip` or `pipenv`::
        
            pip install --user cmarkgfm
            pipenv install cmarkgfm
        
        Wheels are provided for macOS, Linux, and Windows for Python 2.7, 3.5, 3.6, 3.7, and 3.8.
        
        Usage
        -----
        
        High-level usage is really straightforward. To render normal CommonMark
        markdown:
        
        .. code-block:: python
        
            import cmarkgfm
        
            html = cmarkgfm.markdown_to_html(markdown_text)
        
        
        To render GitHub-flavored markdown:
        
        .. code-block:: python
        
            import cmarkgfm
        
            html = cmarkgfm.github_flavored_markdown_to_html(markdown_text)
        
        Advanced Usage
        --------------
        
        **Safe rendering**
        
        CommonMark can render potentially unsafe HTML, including raw HTML, raw Javascript, and potentially unsafe links (including links that run scripts). Although ``github_flavored_markdown_to_html`` prevents some raw HTML tags (including ``script``) from being rendered, it does not block unsafe URLs in links.
        
        Therefore it is recommend to call the rendering method with the SAFE option turned on. The safe option does not render raw HTML or potentially dangerous URLs. (Raw HTML is replaced by a placeholder comment; potentially dangerous URLs are replaced by empty strings.) Dangerous URLs are those that begin with ``javascript:``, ``vbscript:``, ``file:``, or ``data:`` (except for ``image/png``, ``image/gif``, ``image/jpeg``, or ``image/webp`` mime types) To do this, use:
        
        .. code-block:: python
        
            import cmarkgfm
            from cmarkgfm.cmark import Options as cmarkgfmOptions
        
            html = cmarkgfm.markdown_to_html(markdown_text, options=cmarkgfmOptions.CMARK_OPT_SAFE)
            # or
            html = cmarkgfm.github_flavored_markdown_to_html(markdown_text, options=cmarkgfmOptions.CMARK_OPT_SAFE)
        
        If you trust the markdown text to not include any unsafe tags and links, then you may skip this.
        
        In version 0.4.0 and earlier, the default behavior is unsafe, as described above. In later versions, the default behavior is *safe*, and to render potentially unsafe HTML pass the ``CMARK_OPT_UNSAFE`` option.
        
        **Options**
        
        Both rendering methods ``markdown_to_html`` and ``github_flavored_markdown_to_html`` have
        an optional ``options`` argument that can be used to activate `options of cmark <https://manpages.debian.org/stretch/cmark/cmark.1.en.html>`_.
        For example:
        
        .. code-block:: python
        
            import cmarkgfm
            from cmarkgfm.cmark import Options as cmarkgfmOptions
        
            html = cmarkgfm.markdown_to_html(markdown_text, options=cmarkgfmOptions.CMARK_OPT_SAFE | cmarkgfmOptions.CMARK_OPT_SMART)
        
        The options are:
        
        +---------------------------+---------------------------------------------------+
        | Option                    | Effect                                            |
        +===========================+===================================================+
        | CMARK_OPT_SAFE (≤0.4.0)   | Prevents rendering unsafe HTML and links.         |
        +---------------------------+---------------------------------------------------+
        | CMARK_OPT_UNSAFE (>0.4.0) | Allows rendering unsafe HTML and links.           |
        +---------------------------+---------------------------------------------------+
        | CMARK_OPT_SMART           | Render curly quotes, en/em-dashes, ellipses       |
        +---------------------------+---------------------------------------------------+
        | CMARK_OPT_NORMALIZE       | Consolidate adjacent text nodes.                  |
        +---------------------------+---------------------------------------------------+
        | CMARK_OPT_HARDBREAKS      | Renders line breaks within paragraphs as ``<br>`` |
        +---------------------------+---------------------------------------------------+
        | CMARK_OPT_NOBREAKS        | Render soft line breaks as spaces.                |
        +---------------------------+---------------------------------------------------+
        | CMARK_OPT_SOURCEPOS       | Adds ``data-sourcepos`` to HTML tags indicating   |
        |                           | the corresponding line/col ranges in the input    |
        +---------------------------+---------------------------------------------------+
        
        Contributing
        ------------
        
        Pull requests are welcome. :)
        
        
        License
        -------
        
        This project is under the MIT License. It includes components under differing
        copyright under the ``third_party`` directory in this source tree.
        
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Build Tools
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
