recommonmark [1]_
#################

.. note:: 本插件是让markdown文件和rst文件可以接合使用。实践感觉还行，基本能用。


* 官网 [2]_

说明::

    recommonmark is a Docutils bridge to CommonMark-py
    a Python package for parsing the CommonMark Markdown flavor

安装::

    pip install recommonmark

本教程用到的extensions::

    sphinx-ext-autosectionlabel

基础使用
========

::

    # for Sphinx-1.4 or newer
    extensions = ['recommonmark']

    # for Sphinx-1.3
    from recommonmark.parser import CommonMarkParser

    source_parsers = {
        '.md': CommonMarkParser,
    }

    source_suffix = ['.rst', '.md']

.. note:: This allows you to write both .md and .rst files inside of the same project.


Links
=====

使用::

    extensions = [
        # Auto-generate section labels.
        'sphinx.ext.autosectionlabel',
    ]

    # Prefix document path to section labels, otherwise autogenerated labels would look like 'heading'
    # rather than 'path/to/file:heading'
    autosectionlabel_prefix_document = True

实例file_1.md::

    <!-- path/to/file_1.md -->

    # Title

    ## My Subtitle

实例file_2.md::

    <!-- file_2.md -->

    [My Subtitle][]

    [My Subtitle]: <path/to/file_1:My Subtitle>

可以使用::


    .. toctree::

       link
       second


AutoStructify
=============

::

    # At top on conf.py (with other import statements)
    import recommonmark
    from recommonmark.transform import AutoStructify

    github_doc_root = 'https://github.com/rtfd/recommonmark/tree/master/doc/'

    # At the bottom of conf.py
    def setup(app):
        app.add_config_value('recommonmark_config', {
                'url_resolver': lambda url: github_doc_root + url,
                'auto_toc_tree_section': 'Contents',
                }, True)
        app.add_transform(AutoStructify)








.. [1] https://recommonmark.readthedocs.io/en/latest/index.html
.. [2] https://www.sphinx-doc.org/en/master/usage/markdown.html