{"author":"","author_email":"Chris MacMackin ","bugtrack_url":null,"classifiers":["Development Status :: 5 - Production/Stable","Intended Audience :: Developers","License :: OSI Approved :: GNU General Public License v3 (GPLv3)","Programming Language :: Python","Topic :: Internet :: WWW/HTTP :: Site Management","Topic :: Software Development :: Documentation","Topic :: Software Development :: Libraries :: Python Modules","Topic :: Text Processing :: Filters","Topic :: Text Processing :: Markup :: HTML"],"description":"# Markdown-Include\n\nThis is an extension to [Python-Markdown](https://pythonhosted.org/Markdown/)\nwhich provides an \"include\" function, similar to that found in\nLaTeX (and also the C pre-processor and Fortran). I originally wrote it for my\n[FORD](https://github.com/cmacmackin/ford) Fortran auto-documentation generator.\n\n\n## Installation\nThis module can now be installed using ``pip``.\n\n pip install markdown-include\n\n## Tests\nUse the unittest module\n```bash\npython -m unittest discover unittests/\n```\n\n## Usage\nThis module can be used in a program in the following way:\n\n```python\nimport markdown\nhtml = markdown.markdown(source, extensions=['markdown_include.include'])\n```\n\nMarkdown-Include can also be included in MkDocs projects like below:\n\n```yaml\nmarkdown_extensions:\n - markdown_include.include:\n base_path: docs\n```\n\nThe syntax for use within your Markdown files is ``{!filename!}``. This\nstatement will be replaced by the contents of ``filename``. Markdown-Include\nwill work recursively, so any included files within ``filename`` will also be\nincluded. This replacement is done prior to any other\nMarkdown processing, so any Markdown syntax that you want can be used within\nyour included files. Note that this is a change from the previous version.\nIt was felt that this syntax was less likely to conflict with any code\nfragments present in the Markdown.\n\nBy default, all file-names are evaluated relative to the location from which\nMarkdown is being called. If you would like to change the directory relative to\nwhich paths are evaluated, then this can be done by specifying the extension\nsetting ``base_path``.\n\n### Line Ranges\n\nYou can also define specific lines or line ranges to include by specifying `lines`:\n\n```Markdown\n{!filename!lines=1 3 8-10 2}\n```\n\n`lines` takes a sequence of integers separated by spaces (one or more), or it can also\ntake line ranges specified with a start line and an end line separated by a dash (`-`).\n\nIn the example above, it would read the file called `filename` and include the lines\n`1`, `3`, `8`, `9`, `10`, `2`.\n\nNotice that line `9` was not explicitly set. But it was still included as part of the\nrange `8-10`.\n\nAlso, notice that line `2` is set *after* the range `8-10`. This means that the\nline `2` in `filename` will be included *after* (below) the range `8-10`.\n\nYou can use this to include lines in a different order than the original file. But it\nalso means that if you want to preserve the original order, you have to pay attention\nto the order in which you specify the lines.\n\n## Configuration\n\nThe following settings can be specified when initialising the plugin.\n\n- __base_path__: Default location from which to evaluate relative\n paths for the include statement. (Default: the run-directory.)\n- __encoding__: Encoding of the files used by the include statement. (Default: utf-8.)\n- __inheritHeadingDepth__ : If true, increases headings on include\n file by amount of previous heading. Combiens with headingOffset\n option, below. (Default: False.)\n- __headingOffset__: Increases heading depth by a specific ammount, in\n addition to the inheritHeadingDepth Option. (Default: 0)\n- __throwException__: When true, if the extension is unable to find an\n included file it will throw an exception which the user can\n catch. If false (default), a warning will be printed and Markdown\n will continue parsing the file.\n\n## Examples\n\nAn example of setting the base path and file encoding is given below:\n```python\nimport markdown\nfrom markdown_include.include import MarkdownInclude\n\n# Markdown Extensions\nmarkdown_include = MarkdownInclude(\n configs={'base_path':'/srv/content/', 'encoding': 'iso-8859-1'}\n)\nhtml = markdown.markdown(source, extensions=[markdown_include])\n```\n\nIncluded files can inherit the heading depth of the location\n``inheritHeadingDepth``, as well as receive a specific offset, ``headingOffset``\nFor example, consider the files\n```markdown\nSource file\n# Heading Level 1 of main file\n\n{!included_file.md!}\n\n## Heading Level 2 of main file\n\n{!included_file.md!}\n```\n\nand included_file.md\n\n```markdown\n# This heading will be one level deeper from the previous heading\nMore included file content.\nEnd of included content.\n```\nThen running the script\n```python\nimport markdown\nfrom markdown_include.include import MarkdownInclude\n\n# Markdown Extensions\nmarkdown_include = MarkdownInclude(\n configs={'inheritHeadingDepth':True}\n)\nhtml = markdown.markdown(source, extensions=[markdown_include])\n```\nproduces\n```html\n

Source file

Heading Level 1 of main file

This heading will be one level deeper from the previous heading

Heading Level 2 of main file

This heading will be one level deeper from the previous heading

More included file content.

End of included content.

\n```\n\n\n## ChangeLog\n### Version 0.7.0\nModified to work with Python-Markdown 3.4. This makes the plugin\nincompatible with versions < 3.0.\n### Version 0.6.0\n- Added ability ot offset headers in the included file so they fall under the header level in which the include occurs\n- Add option to throw exception when can't find an include file (instead of printing a warning)\n- Fixed stripping of last character in file, so only occurs if it is a new-line\n- Some behind-the-scenes improvement to code and documentation\n### Version 0.5.1\nBugfix for a syntax error.\n### Version 0.5\nCorrected some errors in documentation and merged in commits of\n[diegobz](https://github.com/diegobz) to add support for encoding and tidy up\nthe source code.\n### Version 0.4\nFixed problem related to passing configurations to the extension.\n### Version 0.3\nAdded support for Python 3.\n### Version 0.2\nChanged the API to be less likely to conflict with other syntax.\n### Version 0.1\nInitial release.\n","description_content_type":"text/markdown","docs_url":null,"download_url":"","downloads":{"last_day":-1,"last_month":-1,"last_week":-1},"dynamic":null,"home_page":"","keywords":"Markdown,typesetting,include,plugin,extension","license":"GNU General Public License v3 (GPLv3)","license_expression":null,"license_files":null,"maintainer":"","maintainer_email":"","name":"markdown-include","package_url":"https://pypi.org/project/markdown-include/","platform":null,"project_url":"https://pypi.org/project/markdown-include/","project_urls":{"project":"https://github.com/cmacmackin/markdown-include"},"provides_extra":null,"release_url":"https://pypi.org/project/markdown-include/0.8.1/","requires_dist":["markdown (>=3.0)","pytest ; extra == 'tests'"],"requires_python":">=3.7","summary":"A Python-Markdown extension which provides an 'include' function","version":"0.8.1","yanked":false,"yanked_reason":null}

Dependencies of markdown-include (2).
Dependency	Optional
markdown	false
pytest	true

Package search

markdown-include

project_urls

Dependencies

All package metadata

Releases