75 lines
4.5 KiB
Markdown
75 lines
4.5 KiB
Markdown
# hugo-video
|
|
|
|
<!-- [](https://github.com/budparr/awesome-hugo) -->
|
|
|
|
## About
|
|
|
|
This [Hugo](https://gohugo.io) theme component provides a shortcode: `video` for embedding videos using the [HTML video element](https://devdocs.io/html/element/video).
|
|
|
|
It comes with english, french, german, russian, japanese, korean and polish localization. Other languages welcome! Send your pull request.
|
|
|
|
## Features
|
|
|
|
This shortcode uses Hugo [Page Resources](https://gohugo.io/content-management/page-resources/). The video to display __must be placed in the [page bundle](https://gohugo.io/content-management/page-bundles/)__.
|
|
|
|
The shortcode takes one mandatory argument: the filename of the video file to display, __without the extension__. It detects automatically if several versions of the file exists in the page bundle, and add accordingly the multiple `src` tags. When an image file with the same filename is also present in the page bundle, it is automatically used as a poster frame.
|
|
|
|
When the browser doesn't support the [HTML video element](https://devdocs.io/html/element/video), the shortcode displays a localized notice allowing the video download for local playing.
|
|
|
|
Following video formats are supported:
|
|
- MP4 (extension `.mp4` or `.m4v`)
|
|
- WebM, (extension `.webm`)
|
|
- Ogg, (extension `.ogv`)
|
|
|
|
Default values:
|
|
- Browser's default controls are displayed (`controls` attribute is always included)
|
|
- Video can be preloaded (`preload="auto"` attribute is always included)
|
|
- Video width is 100% (`width="100%"` attribute is included); this can be changed by indicating the desired width when calling the shortcode, see example below)
|
|
- Video height attribute is not set by default, but can be explicitly set by indicating the desired height in pixels (i.e. `height="640"`); credit goes to Evgeny Kuznetsov for this feature
|
|
- Following other video attributes can be set: `muted="true"`, `autoplay="true"` and `loop="true"`. Credit goes to Tom McKenzie for this feature
|
|
- Default settings are used for other video attributes
|
|
|
|
When no video file of the given name is found in the supported format (see above), the shortcode __intentionally fails__ with a `No valid video file with filename <filename> found.` error.
|
|
|
|
## Usage
|
|
|
|
1. Add the `hugo-video` as a submodule to be able to get upstream changes later
|
|
```bash
|
|
git submodule add https://github.com/martignoni/hugo-video.git themes/hugo-video
|
|
```
|
|
2. Add `hugo-video` as the left-most element of the `theme` list variable in your site's or theme's configuration file `config.yaml` or `config.toml`. Example, with `config.yaml`:
|
|
```yaml
|
|
theme: ["hugo-video", "my-theme"]
|
|
```
|
|
or, with `config.toml`,
|
|
```toml
|
|
theme = ["hugo-video", "my-theme"]
|
|
```
|
|
3. Place your video file(s) in the [page bundle](https://gohugo.io/content-management/page-bundles/) of your post.
|
|
4. In your site, use the shortcode, this way, indicating the video filename __without its extension__. If your video file is `my-beautiful-screencast.mp4`, type this:
|
|
```go
|
|
{{< video src="my-beautiful-screencast" >}}
|
|
```
|
|
or
|
|
```go
|
|
{{< video src="my-beautiful-screencast" width="600px" >}}
|
|
```
|
|
|
|
### Thanks
|
|
|
|
- To [Tom McKenzie](https://github.com/grrowl), for implementing `muted`, `autoplay` and `loop` video attributes support.
|
|
- To [Olaf Haag](https://github.com/OlafHaag), [Paul Lettington](https://github.com/plett) and [Christian Mahnke](https://github.com/cmahnke), for raising and fixing some bugs.
|
|
- To [Arsenii Lyashenko](https://github.com/ark0f), for implementing `controls` disabling option and for providing the russian localization.
|
|
- To [Evgeny Kuznetsov](https://github.com/nekr0z), for implementing `height` optional attribute.
|
|
- To [Genji Fujimori](https://github.com/ahandsel), for providing the japanese localization.
|
|
- To [Junho Park](https://github.com/cnaa97), for providing the korean localization.
|
|
- To [Dominik Palula](https://github.com/D00NIK), for providing the polish localization.
|
|
|
|
### Licence
|
|
|
|
Copyright © 2019 onwards, Nicolas Martignoni nicolas@martignoni.net.
|
|
|
|
All the source code is licensed under GPL 3 or any later version
|
|
|
|
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
|