Images, video, audio, and downloads¶
Keep a resource near the document that explains it. Name it with a relative path,
or start the path with / to refer to the source root. Guidedog copies resources
used by the documents. A video remains a video on the web; a PDF names the recording.
Images¶
.. image:: diagrams/pipeline.png
:alt: The build pipeline
:width: 480px
.. figure:: /screenshots/search.png
Searching the site.
Pages copy images into _images; the book embeds them. PNG, JPEG, GIF, SVG, and WebP
work in both. A missing image is a warning: the page keeps the image’s alternative
text, and the book leaves the image out.
Video and audio¶
An image or figure that names a video (.mp4, .webm, .ogv, .mov,
.m4v) or an audio file (.mp3, .ogg, .oga, .m4a, .opus, .wav,
.flac, .aac) plays it, as Docutils does for video:
.. figure:: media/tour.mp4
:alt: A tour of the site
:width: 640
The two-minute tour.
.. image:: media/pronunciation.mp3
Pages show the browser’s player, with a link to the file for browsers that cannot play
it. A book cannot play media, so it names the recording in a box where the player would
be; text output writes [video: ...] or [audio: ...].
Downloads¶
The download role links to any file and copies it into _downloads:
Get :download:`the example project <examples/project.zip>`.
Theme files¶
_static holds the files the theme uses (style sheets, scripts, fonts, a logo),
copied as they are into _static in the site. html_static_path lists it, and
html_css_files, html_js_files, html_logo, and html_favicon name files
in it. Content media belongs with the documents instead, so that moving a document
with its media keeps its links working.