{"id":7393,"library":"markdown-include","title":"Markdown Include","description":"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.","status":"active","version":"0.8.1","language":"en","source_language":"en","source_url":"https://github.com/cmacmackin/markdown-include","tags":["markdown","extension","include","documentation","preprocessor","static-site-generation"],"install":[{"cmd":"pip install markdown-include markdown","lang":"bash","label":"Install with core Markdown library"}],"dependencies":[{"reason":"markdown-include is an extension for the Python-Markdown library and requires it to function.","package":"markdown","optional":false}],"imports":[{"symbol":"MarkdownInclude","correct":"from markdown_include.include import MarkdownInclude"},{"symbol":"markdown","correct":"import markdown"}],"quickstart":{"code":"import markdown\nfrom markdown_include.include import MarkdownInclude\nimport os\n\n# Create a dummy base directory and included file\nif not os.path.exists('docs'):\n    os.makedirs('docs')\nwith open('docs/main.md', 'w') as f:\n    f.write('# Main Document\\n\\nThis is the main content.\\n\\n{!partial.md!}\\n\\nEnd of document.')\nwith open('docs/partial.md', 'w') as f:\n    f.write('## Included Section\\n\\nThis content comes from `partial.md`.')\n\n# Configure the MarkdownInclude extension\n# base_path specifies the directory where included files are sought\nconfigs = {\n    'base_path': 'docs'\n}\n\n# Initialize Markdown with the extension\nmd_instance = markdown.Markdown(extensions=[MarkdownInclude(configs=configs)])\n\n# Read the main Markdown content\nwith open('docs/main.md', 'r') as f:\n    markdown_text = f.read()\n\n# Convert Markdown to HTML\nhtml = md_instance.convert(markdown_text)\n\nprint(html)\n\n# Expected output (simplified):\n# <h1>Main Document</h1>\n# <p>This is the main content.</p>\n# <h2>Included Section</h2>\n# <p>This content comes from <code>partial.md</code>.</p>\n# <p>End of document.</p>","lang":"python","description":"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."},"warnings":[{"fix":"Update all include statements in your Markdown files from the old `!INCLUDE \"file.md\"!` style to the new `{!file.md!}` syntax.","message":"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.","severity":"breaking","affected_versions":">=0.8.0"},{"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/'})`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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).","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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`.","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.","error":"FileNotFoundError: [Errno 2] No such file or directory: 'some_included_file.md'"},{"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.","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.","error":"Included content not rendering; `{!filename!}` appears verbatim in HTML output."},{"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.","cause":"The `markdown-include` package is not installed or there's an issue with your Python environment's path.","error":"ImportError: cannot import name 'MarkdownInclude' from 'markdown_include.include' (or similar 'No module named markdown_include')"}]}