Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/soulless-viewer/mkdocs-video

MkDocs Video plugin
https://github.com/soulless-viewer/mkdocs-video

mkdocs mkdocs-plugin mkdocs-plugins

Last synced: about 1 month ago
JSON representation

MkDocs Video plugin

Host: GitHub
URL: https://github.com/soulless-viewer/mkdocs-video
Owner: soulless-viewer
License: mit
Archived: true
Created: 2021-06-30T13:55:40.000Z (about 3 years ago)
Default Branch: master
Last Pushed: 2024-01-04T21:17:41.000Z (8 months ago)
Last Synced: 2024-07-17T09:27:04.139Z (about 2 months ago)
Topics: mkdocs, mkdocs-plugin, mkdocs-plugins
Language: Python
Homepage:
Size: 30.3 KB
Stars: 66
Watchers: 1
Forks: 12
Open Issues: 9
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE

Awesome Lists containing this project

README

> [!WARNING]
> This project is no longer maintained. You can still use it, but there will be no more updates.

# MkDocs Video

This plugin allows you to embed videos on the documentation pages using a simple Markdown syntax.

## Contents

* [Installation](#installation)
* [Usage](#usage)
* [Configuration](#configuration)
* [Marker](#marker)
* [Style](#style)
* [Tag ``](#tag-video)
* [Video type](#video-type)
* [Video autoplay](#video-autoplay)
* [Video loop](#video-loop)
* [Video muted](#video-muted)
* [Video controls](#video-controls)
* [Embedding examples](#embedding-examples)

## Installation

Install the package with pip:

```bash
$ pip install mkdocs-video
```

Enable the plugin in the `mkdocs.yml` file:

```yaml
plugins:
- mkdocs-video
```

> See how to use [MkDocs Plugins](https://www.mkdocs.org/dev-guide/plugins/#using-plugins)

## Usage

To add a video to the final documentation page, you need to use the Markdown syntax for images with a **specific name** *(hereinafter ***marker***)*.

> See how to use [Markdown syntax](https://guides.github.com/features/mastering-markdown/)

**Example:**

*content folder structure*

```
├── content
| ├── ...
│   ├── video.md
│   └── videos
│   └── costa_rica.mp4
└── mkdocs.yml
```

*video.md*
```
# Video example

Lorem ipsum dolor sit amet

![type:video](https://www.youtube.com/embed/LXb3EKWsInQ)
```

*\/video*

![](https://user-images.githubusercontent.com/29832584/123962612-5188db00-d9ba-11eb-9e0f-1470ca57c452.png)

You can also use relative paths for videos stored together with your content
```
![type:video](./videos/costa_rica.mp4)
```

## Configuration

The following parameters can be used to change the functionality and appearance of video elements in the final HTML. Keep in mind that the plugin configuration parameters are applied globally to all relevant [marked](#marker) elements. To fine-tune each video element, you can use the [Attribute Lists](https://python-markdown.github.io/extensions/attr_list/) extension.

When using this plugin and the mentioned extension together, the following rules apply *(with an illustrative examples)*:

0. *[Let's assume we have this plugin configuration]*
```yaml
# mkdocs.yml
markdown_extensions:
- attr_list
plugins:
- mkdocs-video:
is_video: True
video_muted: True
video_controls: True
css_style:
width: "50%"
```

1. The plugin attributes are used globally by default
```markdown
![type:video](video.mp4)
```
```html

```

2. The extension attributes will override the corresponding plugin attributes, but the rest will remain by default.
```markdown
![type:video](video.mp4){: style='width: 100%'}
```
```html

```

3. The plugin attributes can be disabled for specific video element by adding `disable-global-config` attribute.
```markdown
![type:video](video.mp4){: disable-global-config style='width: 100%'}
```
```html

```

4. The extension attribute `src` will override video source... Do what you want with this info 🙃.
```markdown
![type:video](video.mp4){: src='another-video.mp4'}
```
```html

```

### Marker

By default, the string `type:video` is used as a **marker** in the Markdown syntax.

You can change this value by adding the following lines to your `mkdocs.yml`:

```yaml
plugins:
- mkdocs-video:
mark: "custom-marker"
```

Now you can use this **marker** in the Markdown syntax:

```
![custom-marker](https://www.youtube.com/embed/LXb3EKWsInQ)
```

### Style

By default, the following CSS styles are used for the `` tag that is inserted into the final page:

```css
position: relative;
width: 100%;
height: 22.172vw;
```

You can change the style by adding the following lines to your `mkdocs.yml`:

```yaml
plugins:
- mkdocs-video:
css_style:
width: "100%"
height: "22.172vw"
...
```

### Tag ``

By default, the `` tag will be used to display the video in the final page, but in some cases you may need to use `` tag instead. You can use it by adding the following lines to your `mkdocs.yml`:

```yaml
plugins:
- mkdocs-video:
is_video: True
...
```

### Video type