Markdown Include

0.8.1 · active · verified Thu Apr 16

Markdown-Include is a Python-Markdown extension that enables the inclusion of content from other Markdown files within a main document. It facilitates modular documentation by replacing a special syntax, `{!filename!}`, with the contents of the specified file. The library is currently at version 0.8.1 and is actively maintained, with its last release in February 2023.

Common errors

```
FileNotFoundError: [Errno 2] No such file or directory: 'some_included_file.md'
```
cause The `markdown-include` extension could not find the specified file. This is commonly due to an incorrect `base_path` configuration or a typo in the included filename within the Markdown source.

fix Verify that the `base_path` setting in your `MarkdownInclude` configuration points to the correct directory containing your Markdown files. Also, double-check the filename in your `{!filename!}` statement for typos and ensure it exists relative to the `base_path`.
```
Included content not rendering; `{!filename!}` appears verbatim in HTML output.
```
cause This typically means the `markdown-include` extension was not correctly loaded or configured with your `markdown.Markdown` instance, or the include syntax in the Markdown file is incorrect.

fix Ensure that `MarkdownInclude` is passed in the `extensions` list during `markdown.Markdown` initialization. For example, `markdown.Markdown(extensions=[MarkdownInclude(configs={...})])`. Also, confirm that the include syntax `{!filename!}` (with curly braces and exclamation mark) is used correctly, especially if upgrading from older versions with different syntax.
```
ImportError: cannot import name 'MarkdownInclude' from 'markdown_include.include' (or similar 'No module named markdown_include')
```
cause The `markdown-include` package is not installed or there's an issue with your Python environment's path.

fix Ensure the library is installed using `pip install markdown-include`. If it is installed in a virtual environment, ensure that environment is activated when running your script.

Warnings

breaking The include syntax changed significantly in version 0.8.x from `!INCLUDE "filename.md"!` to `{!filename!}`. This was done to reduce conflicts with other Markdown elements like code blocks.
Fix: Update all include statements in your Markdown files from the old `!INCLUDE "file.md"!` style to the new `{!file.md!}` syntax.
gotcha By default, included file paths are resolved relative to the directory from which the Python script (or `markdown.markdown` call) is executed, not relative to the Markdown file containing the include statement.
Fix: Always explicitly set the `base_path` configuration option for the `MarkdownInclude` extension to the directory where your Markdown files reside, or ensure your script execution context matches the intended base path. Example: `MarkdownInclude(configs={'base_path':'./docs/'})`.
gotcha The extension supports recursive includes, meaning an included file can itself contain include statements. While powerful, this can lead to unexpected content duplication or infinite recursion if not managed carefully (e.g., circular dependencies).
Fix: Structure your include dependencies carefully to avoid circular references. The library itself should prevent infinite loops, but logical errors in content structure might still occur. Always test your generated output.

Install

pip install markdown-include markdown Install with core Markdown library

Imports

MarkdownInclude

from markdown_include.include import MarkdownInclude

markdown
```
import markdown
```

Quickstart

This example demonstrates how to set up `markdown-include` to process a main Markdown file that includes another partial Markdown file. It creates temporary files, initializes the Markdown parser with the `MarkdownInclude` extension, and converts the content to HTML, showing how the `base_path` configuration is used to resolve included file paths.

import markdown
from markdown_include.include import MarkdownInclude
import os

# Create a dummy base directory and included file
if not os.path.exists('docs'):
    os.makedirs('docs')
with open('docs/main.md', 'w') as f:
    f.write('# Main Document\n\nThis is the main content.\n\n{!partial.md!}\n\nEnd of document.')
with open('docs/partial.md', 'w') as f:
    f.write('## Included Section\n\nThis content comes from `partial.md`.')

# Configure the MarkdownInclude extension
# base_path specifies the directory where included files are sought
configs = {
    'base_path': 'docs'
}

# Initialize Markdown with the extension
md_instance = markdown.Markdown(extensions=[MarkdownInclude(configs=configs)])

# Read the main Markdown content
with open('docs/main.md', 'r') as f:
    markdown_text = f.read()

# Convert Markdown to HTML
html = md_instance.convert(markdown_text)

print(html)

# Expected output (simplified):
# <h1>Main Document</h1>
# <p>This is the main content.</p>
# <h2>Included Section</h2>
# <p>This content comes from <code>partial.md</code>.</p>
# <p>End of document.</p>

view raw JSON →