{"id":5322,"library":"mkdocs-include-markdown-plugin","title":"MkDocs Include Markdown Plugin","description":"The mkdocs-include-markdown-plugin enhances MkDocs by allowing users to include content from other Markdown files, or parts of files, directly into their pages. It supports various features like fragment inclusion, heading offset, and line ranges. The current version is 7.2.2, with active development and frequent minor releases.","status":"active","version":"7.2.2","language":"en","source_language":"en","source_url":"https://github.com/mondeja/mkdocs-include-markdown-plugin","tags":["mkdocs","documentation","markdown","plugin","include"],"install":[{"cmd":"pip install mkdocs-include-markdown-plugin","lang":"bash","label":"Install package"}],"dependencies":[{"reason":"Core dependency for MkDocs documentation generation.","package":"mkdocs","optional":false},{"reason":"Core dependency for Markdown parsing.","package":"markdown","optional":false},{"reason":"Optional dependency to enable auto-reloading during development with the MkDocs dev server.","package":"watchdog","optional":true},{"reason":"Optional dependency for configuring the HTTP cache directory when using 'cache_dir' global setting.","package":"platformdirs","optional":true}],"imports":[{"note":"This is the internal Python class. For common usage, you enable the plugin via your 'mkdocs.yml' file, not via direct Python import.","symbol":"IncludeMarkdownPlugin","correct":"from mkdocs_include_markdown_plugin.plugin import IncludeMarkdownPlugin"}],"quickstart":{"code":"# mkdocs.yml\nsite_name: My Docs\nplugins:\n  - include-markdown\n\n# docs/index.md\n# This is your main Markdown file\n---\n# Welcome\n\nThis is the main content of my document.\n\nHere's some content included from another file:\n\n{!include includes/snippet.md!}\n\n---\n\n# docs/includes/snippet.md\n# This is the file to be included\n---\n## Included Section\n\nThis text comes from 'includes/snippet.md'.\n\nIt can contain any Markdown.\n","lang":"yaml","description":"To use the plugin, first install it. Then, enable it in your `mkdocs.yml` file under the `plugins` section. Create a Markdown file (e.g., `docs/index.md`) and use the `{!include path/to/file.md!}` syntax to embed content from another Markdown file (e.g., `docs/includes/snippet.md`)."},"warnings":[{"fix":"Ensure `include-markdown` is listed under the `plugins` section in your `mkdocs.yml`.","message":"The plugin must be explicitly enabled in your `mkdocs.yml` file. If you forget to add `plugins: - include-markdown` (or similar for custom configuration), the `{!include ...!}` directives will not be processed and will appear as raw text in your output.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Verify the relative path from the *parent* Markdown file to the *included* Markdown file. Use `.` for current directory, `..` for parent directory.","message":"Paths specified in `{!include ...!}` directives are relative to the *current* Markdown file where the directive is used, not to the `docs` directory or the project root. Incorrect relative paths will lead to `FileNotFoundError`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always use the `{!include ...!}` syntax provided by the plugin for directives. Be mindful of potential conflicts if other plugins or themes also use similar curly bracket syntax.","message":"The plugin uses `{!include ...!}` syntax for inclusion. This is distinct from Jinja2-style `{{ include ... }}`. Mixing these or using incorrect syntax will prevent content from being included.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Carefully test `heading-offset` values. A positive offset increases heading levels (e.g., `#` becomes `##`), while a negative offset decreases them. Use `0` for no change.","message":"The `heading-offset` argument (e.g., `{!include file.md:heading-offset=1!}`) applies a numeric offset to all headings within the included content. Incorrectly specifying or misunderstanding the offset can lead to unintended heading levels in the final output. While a bug with negative values was fixed in v7.1.7, ensure offsets are logical for your document structure.","severity":"gotcha","affected_versions":"<7.1.7 for negative values, All versions for general understanding."}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}