mkdocs-video

1.5.0 · active · verified Thu Apr 16

mkdocs-video is a Python plugin for MkDocs that simplifies embedding videos into documentation pages using a straightforward Markdown syntax. The current version is 1.5.0, which features a rewritten HTML parsing mechanism using `lxml.html` for more granular configuration with Python-Markdown's Attribute Lists extension. The project maintains an active, though irregular, release cadence.

Common errors

```
ERROR - Config value: 'plugins'. Error: Unrecognised plugin 'mkdocs-video'.
```
cause The `mkdocs-video` plugin is enabled in `mkdocs.yml` but has not been installed in your Python environment or is not accessible.

fix Ensure the plugin is installed using `pip install mkdocs-video` in the same Python environment where MkDocs is installed and run. If using a virtual environment, make sure it's activated.
```
Video Not Loading (video element is present but shows broken link/error)
```
cause The video file path is incorrect, the video's privacy settings (for external services) prevent embedding, or there's a browser compatibility issue.

fix Double-check the video URL or local file path for correctness. Verify privacy settings for embedded videos (e.g., YouTube's privacy-enhanced mode). Test in different web browsers and check the browser's developer console for specific errors related to video loading.
```
Relative video paths not working, or '404 not found' for local videos.
```
cause This can occur due to incorrect path resolution, especially with older MkDocs versions or specific configurations, or if the `videos` folder is not correctly included in the build.

fix Ensure `mkdocs-video` is updated to at least v1.1.0 (which fixed relative path issues for MkDocs >= 1.2). Verify that your local video files are correctly placed relative to your Markdown files and that `mkdocs` is configured to include the necessary directories.

Warnings

breaking Version 1.5.0 introduced a rewrite of the HTML parsing mechanism using `lxml.html`. While designed for more granular control with Attribute Lists, existing configurations or custom styles that relied on the previous parsing behavior might require adjustments.
Fix: Review your `mkdocs.yml` and Markdown for video embedding. Ensure compatibility with the `Attribute Lists` extension if leveraging new granular controls. Test your documentation build thoroughly after upgrading.
gotcha Plugin configuration parameters set in `mkdocs.yml` are applied globally to all relevant video elements. To fine-tune individual video elements, you must use the Python-Markdown `Attribute Lists` extension, which will override corresponding plugin attributes for that specific video.
Fix: Enable `markdown_extensions: - attr_list` in your `mkdocs.yml`. Then, in your Markdown, add attributes like `![video](path.mp4){: style='width:50%' autoplay}` to apply per-video settings.
gotcha Earlier versions of `mkdocs-video` (specifically before v1.1.0) had a 'relative paths error' when used with `mkdocs` versions `>= 1.2`. While fixed in `mkdocs-video` v1.1.0, users with older plugin versions or specific MkDocs environments might encounter issues with relative video paths.
Fix: Ensure `mkdocs-video` is updated to version 1.1.0 or newer. If you are using `mkdocs` version 1.2 or higher, this issue should be resolved by updating the plugin.
gotcha A bug in MkDocs 1.5.0 could cause `mkdocs serve` to sometimes lock up all browser tabs when navigating quickly. Although this was fixed in MkDocs 1.5.3, users running MkDocs 1.5.0 or 1.5.1 might experience this issue while developing.
Fix: Upgrade your `MkDocs` installation to version 1.5.3 or newer to mitigate this issue. `pip install --upgrade mkdocs`.

Install

pip install mkdocs-video Install latest version

Imports

mkdocs-video
```
# In mkdocs.yml
plugins:
  - mkdocs-video
```
MkDocs plugins are enabled via the `mkdocs.yml` configuration file, not directly imported in Python code.

Quickstart

To quickly get started, install the package and then enable the `mkdocs-video` plugin in your `mkdocs.yml` file under the `plugins` section. You can then embed videos in your Markdown files using a simple image-like syntax with `![type:video](path/to/video.mp4)`. For fine-grained control, especially with version 1.5.0 and newer, enable the `attr_list` Markdown extension and use attribute lists in your Markdown.

# mkdocs.yml
site_name: My Docs with Videos
plugins:
  - mkdocs-video: # Minimal configuration
      is_video: True # Optional: Forces <video> tag over <iframe>

# docs/index.md
# Embed a local video
![type:video](videos/my_local_video.mp4)

# Embed a YouTube video
![type:video](https://www.youtube.com/watch?v=VIDEO_ID)

# Embed a video with specific attributes using Attribute Lists (requires markdown_extensions:
#   - attr_list in mkdocs.yml, available since mkdocs-video v1.5.0)
![type:video](videos/another_video.mp4){: autoplay loop muted style='width: 80%;'}

view raw JSON →