Package: markdown-include
Markdown-IncludeThis is an extension toPython-Markdownwhich provides an "include" function, similar to that found in
LaTeX (and also the C pre-processor and Fortran). I originally wrote it for myFORDFortran auto-documentation generator.InstallationThis module can now be installed usingpip.pip install markdown-includeTestsUse the unittest modulepython-munittestdiscoverunittests/UsageThis module can be used in a program in the following way:importmarkdownhtml=markdown.markdown(source,extensions=['markdown_include.include'])Markdown-Include can also be included in MkDocs projects like below:markdown_extensions:-markdown_include.include:base_path:docsThe syntax for use within your Markdown files is{!filename!}. This
statement will be replaced by the contents offilename. Markdown-Include
will work recursively, so any included files withinfilenamewill also be
included. This replacement is done prior to any other
Markdown processing, so any Markdown syntax that you want can be used within
your included files. Note that this is a change from the previous version.
It was felt that this syntax was less likely to conflict with any code
fragments present in the Markdown.By default, all file-names are evaluated relative to the location from which
Markdown is being called. If you would like to change the directory relative to
which paths are evaluated, then this can be done by specifying the extension
settingbase_path.Line RangesYou can also define specific lines or line ranges to include by specifyinglines:{!filename!lines=1  3 8-10  2}linestakes a sequence of integers separated by spaces (one or more), or it can also
take line ranges specified with a start line and an end line separated by a dash (-).In the example above, it would read the file calledfilenameand include the lines1,3,8,9,10,2.Notice that line9was not explicitly set. But it was still included as part of the
range8-10.Also, notice that line2is setafterthe range8-10. This means that the
line2infilenamewill be includedafter(below) the range8-10.You can use this to include lines in a different order than the original file. But it
also means that if you want to preserve the original order, you have to pay attention
to the order in which you specify the lines.ConfigurationThe following settings can be specified when initialising the plugin.base_path: Default location from which to evaluate relative
paths for the include statement. (Default: the run-directory.)encoding: Encoding of the files used by the include statement. (Default: utf-8.)inheritHeadingDepth: If true, increases headings on include
file by amount of previous heading. Combiens with headingOffset
option, below. (Default: False.)headingOffset: Increases heading depth by a specific ammount, in
addition to the inheritHeadingDepth Option. (Default: 0)throwException: When true, if the extension is unable to find an
included file it will throw an exception which the user can
catch. If false (default), a warning will be printed and Markdown
will continue parsing the file.ExamplesAn example of setting the base path and file encoding is given below:importmarkdownfrommarkdown_include.includeimportMarkdownInclude# Markdown Extensionsmarkdown_include=MarkdownInclude(configs={'base_path':'/srv/content/','encoding':'iso-8859-1'})html=markdown.markdown(source,extensions=[markdown_include])Included files can inherit the heading depth of the locationinheritHeadingDepth, as well as receive a specific offset,headingOffsetFor example, consider the  filesSource file# Heading Level 1 of main file{!included_file.md!}## Heading Level 2 of main file{!included_file.md!}and included_file.md# This heading will be one level deeper from the previous headingMore included file content.
End of included content.Then running the scriptimportmarkdownfrommarkdown_include.includeimportMarkdownInclude# Markdown Extensionsmarkdown_include=MarkdownInclude(configs={'inheritHeadingDepth':True})html=markdown.markdown(source,extensions=[markdown_include])produces<p>Source file</p><h1>Heading Level 1 of main file</h1><h2>This heading will be one level deeper from the previous heading</h2><p>More included file content.</p><p>End of included content.</p><h2>Heading Level 2 of main file</h2><h3>This heading will be one level deeper from the previous heading</h3><p>More included file content.</p><p>End of included content.</p>ChangeLogVersion 0.7.0Modified to work with Python-Markdown 3.4. This makes the plugin
incompatible with versions < 3.0.Version 0.6.0Added ability ot offset headers in the included file so they fall under the header level in which the include occursAdd option to throw exception when can't find an include file (instead of printing a warning)Fixed stripping of last character in file, so only occurs if it is a new-lineSome behind-the-scenes improvement to code and documentationVersion 0.5.1Bugfix for a syntax error.Version 0.5Corrected some errors in documentation and merged in commits ofdiegobzto add support for encoding and tidy up
the source code.Version 0.4Fixed problem related to passing configurations to the extension.Version 0.3Added support for Python 3.Version 0.2Changed the API to be less likely to conflict with other syntax.Version 0.1Initial release.