mkdocs-embed-external-markdown

What it is and what it does

This is a MkDocs plugin that extends your documentation build process to pull markdown content from external URLs and inject it directly into your pages. It works by parsing Jinja2 template syntax in your markdown files—you specify a URL and optionally a section header (like '## Installation'), and the plugin fetches that content and embeds it at build time. The plugin strips top-level headers from embedded content so you can use your own, and it supports extracting specific sections defined by markdown headers at any level.

The plugin depends on Jinja2 (for template rendering) and requests (for fetching URLs). It can authenticate with private GitHub repositories if you set the GH_TOKEN environment variable. A known gotcha: if your markdown contains Jinja2-like syntax (common in code examples documenting template languages, Ansible, or Django), you need to wrap those blocks in `{% raw %}` tags to prevent the plugin from trying to interpret them as macros.

Use it for:

• Keep installation or configuration instructions in a central repository and embed them in multiple documentation sites without duplication.
• Build a documentation hub that pulls README sections from different project repositories into a unified guide.
• Embed changelog or API documentation from external sources into your MkDocs site without manual copying.
• Document Ansible playbooks or Django templates by embedding code examples from live repositories while protecting them from Jinja2 interpretation.
• Maintain single-source-of-truth documentation by referencing sections from GitHub private repositories using a personal access token.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

A MkDocs plugin that fetches and embeds markdown content or specific sections from external URLs directly into your documentation pages using Jinja2 template syntax.

Yes, if you need to embed external markdown into MkDocs and can tolerate aging maintenance. The plugin is stable (no known vulnerabilities, low install friction, permissive license), but the 900-day gap since the last release means new MkDocs features or Python versions may not be supported. Install it for straightforward content embedding, but monitor the repository for compatibility issues with your MkDocs version.

Install

mkdocs-embed-external-markdown on PyPI

pip install mkdocs-embed-external-markdown

uv add mkdocs-embed-external-markdown

poetry add mkdocs-embed-external-markdown

Installing mkdocs-embed-external-markdown

Before you install

Low install friction with only two runtime dependencies (Jinja2 and requests). Maintenance status is aging—last release was 900 days ago, though the repository remains active with a recent commit on 2025-02-24. The package supports current Python versions (3.9+).

License in practice

Licensed under MIT (permissive), so you can use, modify, and distribute the package freely with minimal restrictions.

Quickstart

pip install mkdocs-embed-external-markdown

# In mkdocs.yml:
plugins:
  - external-markdown

# In your markdown:
{{ external_markdown('https://raw.githubusercontent.com/user/repo/main/README.md', '## Section Name') }}

Requires Python 3.9 or later. If fetching from private GitHub repositories, the GH_TOKEN environment variable must be set with a valid personal access token.

Verify before relying

• Whether the plugin handles rate limiting or caching of fetched external content
• Performance characteristics when embedding many sections or large markdown files
• Compatibility with recent MkDocs versions beyond what the aging maintenance status suggests

Package facts

Evidence: mkdocs_embed_external_markdown-3.0.2-py3-none-any.whl

Keywords: mkdocs, plugin, markdown, external-markdown, embed, external, markdown-section

Tags

More Documentation packages