Document how to add locally-stored videos not hosted on YouTube and Vimeo into your docs so you don't need to use GIF
From a conversation in Gitter, I discovered that you can include locally-hosted videos in your Antora documentation.
https://docs.antora.org/antora/2.3/asciidoc/embed-video/ excludes instructions on how to do it.
The use case for this is when you want to add a short screencast (I was using 30sec videos) instead of using GIF.
Proposed procedure
To insert a locally-hosted video into a page.
- Add the mp4 file into the /images directory.
- Use the
video::
macro to reference the file name.
NOTE: You do not need to declare the module name, just the file name.
Example:
video::filename.mp4[opts="autoplay, loop"]
IMPORTANT: You can't reference the video from another module. You have to copy it again to the module you want to use it in.
Notes
Your video may not load if you are previewing your site locally (this was the case for our implementation of the Antora local dockerized environment we use.
Discussion from Gitter
Is there a way for me to embed a short locally-stored MP4 file into an Antora file? I used video::release-notes:image$pagebuilder-reorder.mp4[]where the mp4 file is stored in the images directory of the module.
djencks @djencks 15:57
I think you'd have to write your own macro to do that.
Jared Morgan @jaredmorgs 16:24
So video doesn’t work in Antora even though it does in Asciidoctor for local files?
According to the docs it does anyhow
djencks @djencks 16:25
hmmm, my impression was that the docs only say it works for youtube and vimeo videos.
can you remind me of the doc page?
Jared Morgan @jaredmorgs 17:19
@djencks https://asciidoctor.org/docs/user-manual/#video
The Antora docs only mention YouTube and Vimeo
I have converted the short videos to GIFs because it gets the job done.
Sprychipper @Sprychipper 17:50
@jaredmorgs I use local videos in my documentation. It works. Antora is not restricted to youtube and Vimeo.
You place them in the images folder and use the video macro.
Jared Morgan @jaredmorgs 18:50
They weren’t rendering in my local builds so maybe it was something to do with that @Sprychipper . Can you provide an example of the syntax you use for the macro?
Sprychipper @Sprychipper 19:01
@jaredmorgs you don't need image folder prefix. Place them inside the images folder and use the following macro video::pagebuilder-reorder.mp4[opts="autoplay, loop"]
Jared Morgan @jaredmorgs 19:01
Thanks @Sprychipper
Sprychipper @Sprychipper 19:02
To note you cant reference the video from another module. You have to cooy it again to that module