sphinx-mdinclude
================
Sphinx extension for including or writing pages in Markdown format.
[](https://pypi.python.org/pypi/sphinx-mdinclude)
[](https://sphinx-mdinclude.readthedocs.io)
[](https://sphinx-mdinclude.omnilidb.dev/en/latest/changelog.html)
[](https://github.com/omnilib/sphinx-mdinclude/blob/main/LICENSE)
sphinx-mdinclude is a simple Sphinx extension that enables including Markdown documents
from within reStructuredText. It provides the `.. mdinclude::` directive, and
automatically converts the content of Markdown documents to reStructuredText format.
sphinx-mdinclude is a fork of [m2r](https://github.com/miyakogi/m2r) and
[m2r2](https://github.com/crossnox/m2r2), focused only on providing a Sphinx extension.
## Features
* Basic markdown and some extensions (see below)
* inline/block-level raw html
* fenced-code block
* tables
* footnotes (``[^1]``)
* Inline- and Block-level rst markups
* single- and multi-line directives (`.. directive::`)
* inline-roles (``:code:`print(1)` ...``)
* ref-link (``see `ref`_``)
* footnotes (``[#fn]_``)
* math extension inspired by [recommonmark](https://recommonmark.readthedocs.io/en/latest/index.html)
* Sphinx extension
* add markdown support for sphinx
* ``mdinclude`` directive to include markdown from md or rst files
* option to parse relative links into ref and doc directives (``md_parse_relative_links``)
## Restrictions
* In the rst's directives, markdown is not available. Please write in rst.
* Column alignment of tables is not supported. (rst does not support this feature)
* Heading with overline-and-underline is not supported.
* Heading with underline is OK
* Rst heading marks are currently hard-coded and unchangeable.
* H1: `=`, H2: `-`, H3: `^`, H4: `~`, H5: `"`, H6: `#`
## Installation
Python 3.6 or newer is required.
```
pip install sphinx-mdinclude
```
## Usage
In your Sphinx `conf.py`, add the following lines:
```python
extensions = [
...,
'sphinx_mdinclude',
]
```
Markdown files with the `.md` extension will be loaded and used by Sphinx, similar to
any other `.rst` files.
To include Markdown files within other files, use the `.. mdinclude:: <filename>`
directive. This applies the conversion from Markdown to reStructuredText format.
## License
`sphinx-mdinclude` is copyright Hiroyuki Takagi, CrossNox, and [Amethyst Reese][],
and licensed under the MIT license. I am providing code in this repository to you
under an open source license. This is my personal repository; the license you receive
to my code is from me and not from my employer. See the [LICENSE][] file for details.
[Amethyst Reese]: https://noswap.com
[LICENSE]: https://github.com/omnilib/sphinx-mdinclude/blob/main/LICENSE
Raw data
{
"_id": null,
"home_page": null,
"name": "sphinx_mdinclude",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Amethyst Reese <amy@noswap.com>",
"keywords": "Markdown, reStructuredText, sphinx-extension",
"author": null,
"author_email": "Hiroyuki Takagi <miyako.dev@gmail.com>, CrossNox <ijmermet+m2r2@gmail.com>, Amethyst Reese <amy@noswap.com>",
"download_url": "https://files.pythonhosted.org/packages/b6/a7/c9a7888bb2187fdb06955d71e75f6f266b7e179b356ac76138d160a5b7eb/sphinx_mdinclude-0.6.2.tar.gz",
"platform": null,
"description": "sphinx-mdinclude\n================\n\nSphinx extension for including or writing pages in Markdown format.\n\n[](https://pypi.python.org/pypi/sphinx-mdinclude)\n[](https://sphinx-mdinclude.readthedocs.io)\n[](https://sphinx-mdinclude.omnilidb.dev/en/latest/changelog.html)\n[](https://github.com/omnilib/sphinx-mdinclude/blob/main/LICENSE)\n\n\nsphinx-mdinclude is a simple Sphinx extension that enables including Markdown documents\nfrom within reStructuredText. It provides the `.. mdinclude::` directive, and\nautomatically converts the content of Markdown documents to reStructuredText format.\n\nsphinx-mdinclude is a fork of [m2r](https://github.com/miyakogi/m2r) and\n[m2r2](https://github.com/crossnox/m2r2), focused only on providing a Sphinx extension.\n\n## Features\n\n* Basic markdown and some extensions (see below)\n * inline/block-level raw html\n * fenced-code block\n * tables\n * footnotes (``[^1]``)\n* Inline- and Block-level rst markups\n * single- and multi-line directives (`.. directive::`)\n * inline-roles (``:code:`print(1)` ...``)\n * ref-link (``see `ref`_``)\n * footnotes (``[#fn]_``)\n * math extension inspired by [recommonmark](https://recommonmark.readthedocs.io/en/latest/index.html)\n* Sphinx extension\n * add markdown support for sphinx\n * ``mdinclude`` directive to include markdown from md or rst files\n * option to parse relative links into ref and doc directives (``md_parse_relative_links``)\n\n## Restrictions\n\n* In the rst's directives, markdown is not available. Please write in rst.\n* Column alignment of tables is not supported. (rst does not support this feature)\n* Heading with overline-and-underline is not supported.\n * Heading with underline is OK\n* Rst heading marks are currently hard-coded and unchangeable.\n * H1: `=`, H2: `-`, H3: `^`, H4: `~`, H5: `\"`, H6: `#`\n\n## Installation\n\nPython 3.6 or newer is required.\n\n```\npip install sphinx-mdinclude\n```\n\n## Usage\n\nIn your Sphinx `conf.py`, add the following lines:\n\n```python\nextensions = [\n ...,\n 'sphinx_mdinclude',\n]\n```\n\nMarkdown files with the `.md` extension will be loaded and used by Sphinx, similar to\nany other `.rst` files.\n\nTo include Markdown files within other files, use the `.. mdinclude:: <filename>`\ndirective. This applies the conversion from Markdown to reStructuredText format.\n\n## License\n\n`sphinx-mdinclude` is copyright Hiroyuki Takagi, CrossNox, and [Amethyst Reese][],\nand licensed under the MIT license. I am providing code in this repository to you\nunder an open source license. This is my personal repository; the license you receive\nto my code is from me and not from my employer. See the [LICENSE][] file for details.\n\n[Amethyst Reese]: https://noswap.com\n[LICENSE]: https://github.com/omnilib/sphinx-mdinclude/blob/main/LICENSE\n\n",
"bugtrack_url": null,
"license": null,
"summary": "Markdown extension for Sphinx",
"version": "0.6.2",
"project_urls": {
"Github": "https://github.com/omnilib/sphinx-mdinclude"
},
"split_keywords": [
"markdown",
" restructuredtext",
" sphinx-extension"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "423d6b41fe1637cd53c4b10d56e0e6f396546f837973dabf9c4b2a1de44620ac",
"md5": "c2a4aedfd5c26af2b5c78d145d2ce74c",
"sha256": "648e78edb067c0e4bffc22943278d49d54a0714494743592032fa3ad82a86984"
},
"downloads": -1,
"filename": "sphinx_mdinclude-0.6.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c2a4aedfd5c26af2b5c78d145d2ce74c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 16911,
"upload_time": "2024-08-03T19:07:30",
"upload_time_iso_8601": "2024-08-03T19:07:30.406332Z",
"url": "https://files.pythonhosted.org/packages/42/3d/6b41fe1637cd53c4b10d56e0e6f396546f837973dabf9c4b2a1de44620ac/sphinx_mdinclude-0.6.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b6a7c9a7888bb2187fdb06955d71e75f6f266b7e179b356ac76138d160a5b7eb",
"md5": "6ee1de048365f0f960f299faa183bb7f",
"sha256": "447462e82cb8be61404a2204227f920769eb923d2f57608e3325f3bb88286b4c"
},
"downloads": -1,
"filename": "sphinx_mdinclude-0.6.2.tar.gz",
"has_sig": false,
"md5_digest": "6ee1de048365f0f960f299faa183bb7f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 65257,
"upload_time": "2024-08-03T19:07:37",
"upload_time_iso_8601": "2024-08-03T19:07:37.643810Z",
"url": "https://files.pythonhosted.org/packages/b6/a7/c9a7888bb2187fdb06955d71e75f6f266b7e179b356ac76138d160a5b7eb/sphinx_mdinclude-0.6.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-03 19:07:37",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "omnilib",
"github_project": "sphinx-mdinclude",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "sphinx_mdinclude"
}
JSON
