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 on it.

Install

mkdocs-embed-external-markdown on PyPI

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+).

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.

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') }}

Package facts

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

Tags

More Documentation packages

See also mkdocs-macros-plugin · mkdocs-video · mkdocs-markdownextradata-plugin · mkdocs-table-reader-plugin · mkdocs-plugin-inline-svg · mkdocs-include-markdown-plugin · mkdocs-autorefs · mkdocs-mermaid2-plugin · mkdocs-meta-manager · wikitextparser