A Python-Markdown extension which provides an 'include' function
This is an extension to Python-Markdown which provides an "include" function, similar to that found in LaTeX (and also the C pre-processor and Fortran). I originally wrote it for my FORD Fortran auto-documentation generator.
This module can now be installed using pip
.
pip install markdown-include
Use the unittest module
python -m unittest discover unittests/
This module can be used in a program in the following way:
import markdown
html = 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: docs
The syntax for use within your Markdown files is {!filename!}
. This
statement will be replaced by the contents of filename
. Markdown-Include
will work recursively, so any included files within filename
will 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
setting base_path
.
You can also define specific lines or line ranges to include by specifying lines
:
{!filename!lines=1 3 8-10 2}
lines
takes 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 called filename
and include the lines
1
, 3
, 8
, 9
, 10
, 2
.
Notice that line 9
was not explicitly set. But it was still included as part of the
range 8-10
.
Also, notice that line 2
is set after the range 8-10
. This means that the
line 2
in filename
will be included after (below) the range 8-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.
The following settings can be specified when initialising the plugin.
An example of setting the base path and file encoding is given below:
import markdown
from markdown_include.include import MarkdownInclude
# Markdown Extensions
markdown_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 location
inheritHeadingDepth
, as well as receive a specific offset, headingOffset
For example, consider the files
Source 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 heading
More included file content.
End of included content.
Then running the script
import markdown
from markdown_include.include import MarkdownInclude
# Markdown Extensions
markdown_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>
Modified to work with Python-Markdown 3.4. This makes the plugin incompatible with versions < 3.0.
Bugfix for a syntax error.
Corrected some errors in documentation and merged in commits of diegobz to add support for encoding and tidy up the source code.
Fixed problem related to passing configurations to the extension.
Added support for Python 3.
Changed the API to be less likely to conflict with other syntax.
Initial release.