You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
69 lines
2.6 KiB
69 lines
2.6 KiB
4 years ago
|
////
|
||
|
|
Included in:
|
||
|
|
|
||
|
|
- user-manual: Video
|
||
|
|
////
|
||
|
|
|
||
|
|
The block video macro enables you to embed videos into your documentation.
|
||
|
|
You can embed self-hosted videos or videos shared on popular video hosting sites such as YouTube and Vimeo.
|
||
|
|
|
||
|
|
The video formats Asciidoctor supports is dictated by the formats supported by the browser (and, in turn, the user's system).
|
||
|
|
While this was once a precarious ordeal, HTML5 has brought sanity to video support in the browser by adding a dedicated https://developer.mozilla.org/en-US/docs/Web/HTML/Element/video[`<video>`] element and by introducing several standard video formats.
|
||
|
|
Those formats are now widely supported across browsers and systems.
|
||
|
|
|
||
|
|
For a canonical list of supported web video formats and their interaction with modern browsers, see the https://developer.mozilla.org/en-US/docs/Web/HTML/Supported_media_formats#Browser_compatibility[Mozilla Developer Supported Media Formats] documentation.
|
||
|
|
|
||
|
|
.A recommendation for serving video to browsers
|
||
|
|
****
|
||
|
|
Where appropriate, we recommend using a video hosting service like YouTube or Vimeo to serve videos in online documentation.
|
||
|
|
These services specialize in streaming optimized video to the browser, with the lowest latency possible given hardware, software, and network capabilities of the device viewing the video.
|
||
|
|
|
||
|
|
Vimeo even offers a white label mode so users aren't made aware that the video is being served through its service.
|
||
|
|
|
||
|
|
See <<YouTube and Vimeo videos>> for details about how to serve videos from these services.
|
||
|
|
****
|
||
|
|
|
||
|
|
.Basic video file include
|
||
|
|
[source]
|
||
|
|
----
|
||
|
|
include::ex-video.adoc[tag=base]
|
||
|
|
----
|
||
|
|
|
||
|
|
You can control the video settings using additional attributes on the macro.
|
||
|
|
For instance, you can offset the start time of playback using the `start` attribute and enable autoplay using the `autoplay` option.
|
||
|
|
|
||
|
|
.Setting attributes for local video playback
|
||
|
|
[source]
|
||
|
|
----
|
||
|
|
include::ex-video.adoc[tag=attr]
|
||
|
|
----
|
||
|
|
|
||
|
|
You can include a caption on the video using the title attribute.
|
||
|
|
|
||
|
|
.Adding a caption to a video
|
||
|
|
[source]
|
||
|
|
----
|
||
|
|
include::ex-video.adoc[tag=caption]
|
||
|
|
----
|
||
|
|
|
||
|
|
=== YouTube and Vimeo videos
|
||
|
|
|
||
|
|
The video macro supports embedding videos from external video hosting services like YouTube and Vimeo.
|
||
|
|
Asciidoctor automatically generates the correct code to embed the video in the HTML output.
|
||
|
|
|
||
|
|
To use this feature, put the video ID in the macro target and the name of the hosting service in the first positional attribute.
|
||
|
|
|
||
|
|
// TODO document dynamic playlist functionality for YouTube videos
|
||
|
|
|
||
|
|
.Embedding a YouTube video
|
||
|
|
[source]
|
||
|
|
----
|
||
|
|
include::ex-video.adoc[tag=you]
|
||
|
|
----
|
||
|
|
|
||
|
|
.Embedding a Vimeo video
|
||
|
|
[source]
|
||
|
|
----
|
||
|
|
include::ex-video.adoc[tag=vim]
|
||
|
|
----
|