{"id":8312,"library":"mdx-include","title":"mdx-include","description":"mdx-include is a Python Markdown extension that enables the inclusion of local or remote files directly into Markdown documents. It provides advanced features like recursive includes, file content slicing by line/column, caching of included files, and detection of circular inclusions. The current stable version is 1.4.2, with the last update released in July 2022, indicating an irregular release cadence.","status":"active","version":"1.4.2","language":"en","source_language":"en","source_url":"https://github.com/neurobin/mdx_include","tags":["markdown","extension","include","file inclusion","documentation"],"install":[{"cmd":"pip install mdx-include","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core dependency as it's a Python Markdown extension.","package":"Markdown"}],"imports":[{"note":"mdx-include is loaded as an extension string ('mdx_include') within the `markdown` library's `extensions` list, not directly imported as a class by users.","wrong":"from mdx_include import IncludeExtension","symbol":"mdx_include","correct":"import markdown\n\nhtml = markdown.markdown(text, extensions=['mdx_include'])"}],"quickstart":{"code":"import markdown\nimport os\n\n# Create a dummy file to include\nwith open('include_me.md', 'w') as f:\n    f.write('This content is from an included file.\\n\\n- Item 1\\n- Item 2')\n\n# Markdown content that includes the dummy file\nmarkdown_content = \"\"\"\n# Main Document\n\nThis is the main content.\n\n{! include_me.md !}\n\nEnd of document.\n\"\"\"\n\nhtml = markdown.markdown(\n    markdown_content,\n    extensions=['mdx_include']\n)\n\nprint(html)\n\n# Clean up dummy file\nos.remove('include_me.md')","lang":"python","description":"This quickstart demonstrates how to use `mdx-include` to embed content from one Markdown file (`include_me.md`) into another. The extension processes the `{! file_path !}` syntax to replace it with the target file's content."},"warnings":[{"fix":"Customize the include syntax in the extension configuration. Refer to the 'Configuration' section in the documentation for details on changing the syntax pattern.","message":"The default include syntax `{! file_path_or_url !}` can conflict with other Python Markdown extensions (e.g., `markdown.extensions.attr_list`).","severity":"gotcha","affected_versions":"All versions"},{"fix":"Set `allow_circular_inclusion` to `True` in the extension configuration to allow non-recursive inclusion in such scenarios.","message":"Circular inclusions (e.g., File A includes B, B includes C, C includes A) raise a `CircularIncludeException` by default.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Choose one extension for file inclusion; do not enable both `mdx_include` and `markdown_include` in your Markdown extensions list.","message":"Do not use `mdx-include` concurrently with the `markdown-include` extension.","severity":"breaking","affected_versions":"All versions"},{"fix":"Ensure that the global `recursion` option is `None` if you intend to use the inline `recurs_state` for selective recursive inclusions.","message":"The inline `recurs_state` option (`{!+ file!}`) to force recursion is only effective if the global `recursion` configuration option is set to `None`. If `recursion` is `False`, the inline override will not work.","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":"Configure the `mdx_include` extension with `allow_circular_inclusion: True` to change this behavior, allowing the affected file to be included non-recursively. For example: `extensions=['mdx_include', {'mdx_include': {'allow_circular_inclusion': True}}]`","cause":"By default, `mdx-include` prevents infinite loops by raising an error when it detects a file including itself directly or indirectly.","error":"CircularIncludeException: Circular inclusion detected: A.md -> B.md -> C.md -> A.md"},{"fix":"Ensure you are passing configurations as a dictionary when initializing the extension, e.g., `extensions=[{'mdx_include': {'base_path': 'docs'}}]. The `configs` attribute itself is not directly exposed for external manipulation after initialization.","cause":"Attempting to access configuration with an outdated or incorrect API, or passing configuration in an incompatible format.","error":"AttributeError: 'IncludeExtension' object has no attribute 'configs'"}]}