{"id":6720,"library":"mkdocs-embed-external-markdown","title":"MkDocs Embed External Markdown Plugin","description":"Mkdocs-embed-external-markdown is a MkDocs plugin that allows users to inject either entire external Markdown files or specific sections from external Markdown files into their MkDocs project using a Jinja2 macro. This enables the compilation of documentation from various remote sources, such as GitHub repositories. The plugin is actively maintained, with frequent updates addressing compatibility and feature enhancements.","status":"active","version":"3.0.2","language":"en","source_language":"en","source_url":"https://github.com/fire1ce/mkdocs-embed-external-markdown","tags":["mkdocs","plugin","markdown","embed","external"],"install":[{"cmd":"pip install mkdocs-embed-external-markdown","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Required for template processing to embed external content.","package":"Jinja2","optional":false},{"reason":"Used to fetch external Markdown content from URLs.","package":"requests","optional":false},{"reason":"The plugin is designed to extend MkDocs functionality.","package":"MkDocs","optional":false}],"imports":[{"note":"This plugin is enabled in your `mkdocs.yml` configuration file, not imported as a Python symbol in code. The `external_markdown` macro is then available in your Markdown files.","symbol":"external-markdown","correct":"plugins:\n  - external-markdown"}],"quickstart":{"code":"# mkdocs.yml\nsite_name: My Docs\nplugins:\n  - external-markdown\n\n# docs/index.md\n# To be placed in docs/index.md\n#\n# # My Awesome Documentation\n#\n# This page embeds content from an external GitHub README.\n#\n# ## Features from MkDocs README\n# {{ external_markdown('https://raw.githubusercontent.com/mkdocs/mkdocs/master/README.md', '## Features') }}\n#\n# ## Quick start from MkDocs Material README\n# {{ external_markdown('https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/README.md', '## Quick start') }}\n\n# To run this example:\n# 1. Create a directory (e.g., my-docs-project)\n# 2. Inside, create mkdocs.yml and docs/index.md as shown above.\n# 3. From the project root, run:\n#    mkdocs build\n#    mkdocs serve","lang":"yaml","description":"To get started, enable the `external-markdown` plugin in your `mkdocs.yml` file. Then, use the `{{ external_markdown('url', 'section name') }}` Jinja2 macro directly within your Markdown files to embed content. The 'section name' parameter specifies the exact Markdown header (e.g., '## Installation') to embed, or an empty string ('') for the full file."},"warnings":[{"fix":"Update all `external_markdown` macro calls to include the Markdown header level, such as `{{ external_markdown('url', '## My Section') }}`.","message":"When upgrading from versions older than 2.x, the 'section name' argument for `external_markdown` now strictly requires the full Markdown header syntax (e.g., `## Section Name`) rather than just the plain text of the section.","severity":"breaking","affected_versions":"<2.0.0"},{"fix":"Escape Jinja2-like syntax in your external Markdown files using raw blocks (`{% raw %}...{% endraw %}`) if you intend for them to be rendered by a subsequent Markdown processor, or adjust the external content to avoid conflicts.","message":"Markdown content being embedded that contains Jinja2-like delimiters (e.g., `{{ variable }}` or `{% block %}`) may be prematurely interpreted by the plugin's Jinja2 engine, leading to rendering errors or unexpected output.","severity":"gotcha","affected_versions":"All"},{"fix":"Be aware of this behavior and plan your documentation structure accordingly, adding appropriate context headers in your MkDocs pages where content is embedded.","message":"The plugin automatically removes the top-level header (H1, `#`) from full embedded content and the specified section header (e.g., `##`) from embedded sections. This is by design to allow users to provide their own contextual headers in the embedding page, but it can be unexpected.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[]}