MkDocs Embed External Markdown Plugin

3.0.2 · active · verified Wed Apr 15

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.

Warnings

breaking 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.
Fix: Update all `external_markdown` macro calls to include the Markdown header level, such as `{{ external_markdown('url', '## My Section') }}`.
gotcha 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.
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.
gotcha 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.
Fix: Be aware of this behavior and plan your documentation structure accordingly, adding appropriate context headers in your MkDocs pages where content is embedded.

Install

pip install mkdocs-embed-external-markdown Install with pip

Imports

external-markdown
```
plugins:
  - external-markdown
```
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.

Quickstart

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.

# mkdocs.yml
site_name: My Docs
plugins:
  - external-markdown

# docs/index.md
# To be placed in docs/index.md
#
# # My Awesome Documentation
#
# This page embeds content from an external GitHub README.
#
# ## Features from MkDocs README
# {{ external_markdown('https://raw.githubusercontent.com/mkdocs/mkdocs/master/README.md', '## Features') }}
#
# ## Quick start from MkDocs Material README
# {{ external_markdown('https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/README.md', '## Quick start') }}

# To run this example:
# 1. Create a directory (e.g., my-docs-project)
# 2. Inside, create mkdocs.yml and docs/index.md as shown above.
# 3. From the project root, run:
#    mkdocs build
#    mkdocs serve

view raw JSON →