{"id":9119,"library":"mkdocs-video","title":"mkdocs-video","description":"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.","status":"active","version":"1.5.0","language":"en","source_language":"en","source_url":"https://github.com/soulless-viewer/mkdocs-video","tags":["mkdocs","video","documentation","plugin","markdown"],"install":[{"cmd":"pip install mkdocs-video","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"This is an MkDocs plugin and requires MkDocs to function.","package":"mkdocs"},{"reason":"Used for HTML parsing, especially since version 1.5.0.","package":"lxml"}],"imports":[{"note":"MkDocs plugins are enabled via the `mkdocs.yml` configuration file, not directly imported in Python code.","symbol":"mkdocs-video","correct":"# In mkdocs.yml\nplugins:\n  - mkdocs-video"}],"quickstart":{"code":"# mkdocs.yml\nsite_name: My Docs with Videos\nplugins:\n  - mkdocs-video: # Minimal configuration\n      is_video: True # Optional: Forces <video> tag over <iframe>\n\n# docs/index.md\n# Embed a local video\n![type:video](videos/my_local_video.mp4)\n\n# Embed a YouTube video\n![type:video](https://www.youtube.com/watch?v=VIDEO_ID)\n\n# Embed a video with specific attributes using Attribute Lists (requires markdown_extensions:\n#   - attr_list in mkdocs.yml, available since mkdocs-video v1.5.0)\n![type:video](videos/another_video.mp4){: autoplay loop muted style='width: 80%;'}","lang":"yaml","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=1.5.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<1.1.0"},{"fix":"Upgrade your `MkDocs` installation to version 1.5.3 or newer to mitigate this issue. `pip install --upgrade mkdocs`.","message":"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.","severity":"gotcha","affected_versions":"mkdocs-video (all), MkDocs (1.5.0, 1.5.1)"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","cause":"The `mkdocs-video` plugin is enabled in `mkdocs.yml` but has not been installed in your Python environment or is not accessible.","error":"ERROR - Config value: 'plugins'. Error: Unrecognised plugin 'mkdocs-video'."},{"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.","cause":"The video file path is incorrect, the video's privacy settings (for external services) prevent embedding, or there's a browser compatibility issue.","error":"Video Not Loading (video element is present but shows broken link/error)"},{"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.","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.","error":"Relative video paths not working, or '404 not found' for local videos."}]}