page-assets.adoc 3.69 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26
= Adding Assets to a Page
ifndef::env-site,env-github[]
include::_attributes.adoc[]
endif::[]
// Settings
:idprefix:
:idseparator: -
// URLs
:uri-adoc-manual: http://asciidoctor.org/docs/user-manual
:uri-video-formats: https://developer.mozilla.org/en-US/docs/Web/HTML/Supported_media_formats#Browser_compatibility
:uri-hosted-video: {uri-adoc-manual}/#video
:uri-shared-video: {uri-adoc-manual}/#youtube-and-vimeo-videos
:uri-video-attrs: {uri-adoc-manual}/#supported-attributes

[#insert-attachment]
== Insert an attachment

An attachment is a resource that you want your user to download, such as a PDF or a ZIP archive of a sample project.
To insert a link to an attachment for download, use the AsciiDoc link macro (`link:[]`).

.Insert a link to an attachment
[source,asciidoc]
----
link:{attachmentsdir}/example.raml[Download the RAML example] and run it.
----

27 28 29 30 31 32
Let's break this down.
You start with the link macro prefix, `link:`.
Next is the target.
Start the target with the `{attachmentsdir}/` reference to tell Antora where to look for the file.
Then put the relative path of the attachment file after that.
Finally, end with the text of the link (as the reader will see it) between a pair of square brackets (`+[]+`).
33

34
You don't need to set the path to the [.path]_attachments/_ directory in the header of your file.
35 36
This is managed automatically by Antora.
When viewing the file in a preview tool, the path is managed by the adjacent [.path]_{blank}_attributes.adoc_ file.
37

38
A module's attachment files should be saved in its xref:modules.adoc#attachments-dir[attachments folder].
39 40 41 42

[#insert-image]
== Insert an image

43
To insert a standalone image (i.e., figure), use the AsciiDoc block image macro (`image::[]`).
44 45 46 47 48 49 50

.Insert a block image
[source,asciidoc]
----
image::file-name.ext[optional alt text]
----

51
To insert an image in the flow of text, use the AsciiDoc inline image macro (`image:[]`).
52

53 54 55 56 57 58 59 60 61
.Insert a block image
[source,asciidoc]
----
image::file-name.ext[optional alt text]
----

Let's break this down.
You start with the image macro prefix, `image::` or `+image:+`.
Next is the target.
62
Put the path of the image relative to the xref:modules.adoc#images-dir[image catalog] in that slot (no need for an attribute prefix).
63 64 65
Finally, end with a pair of square brackets (`+[]+`), optionally containing alt text for the image (which is otherwise generated).

.Block image macro example
66 67 68 69 70
[source,asciidoc]
----
image::pipeline-workflow.png[a diagram illustrating the pipeline stages]
----

71
A module's image files should be saved in its xref:modules.adoc#images-dir[images folder].
72 73 74 75 76 77 78 79 80

[#insert-video]
== Insert a video

You can embed self-hosted videos or videos shared on YouTube and Vimeo.

Video format support is dictated by the user's browser and/or system.
For a list of the web video formats each browser supports, see the {uri-video-formats}[Mozilla Developer Supported Media Formats documentation].

81
TIP: Insert animated GIFs with the <<insert-image,image macro>>.
82 83 84 85 86 87

.Insert a self-hosted video
----
video::video-file.mp4[]
----

88 89 90
Let's break this down.
You start with the video macro prefix, `video::`.
Next is the target.
91
Put the path of the video relative to the xref:modules.adoc#videos-dir[video catalog] in that slot (no need for an attribute prefix).
92
Finally, end with a pair of square brackets (`+[]+`).
93 94 95 96 97 98 99 100 101 102 103 104

=== Externally hosted videos

To embed a video hosted on Youtube or Vimeo, put the video's ID in the macro target and the name of the hosting service (`youtube`, `vimeo`) between the brackets.

.Embed a Youtube video
----
video::rPQoq7ThGAU[youtube]
----

.More AsciiDoc video help
****
105 106 107
* {uri-hosted-video}[The AsciiDoc video macro]
* {uri-shared-video}[Embed Youtube and Vimeo videos]
* {uri-video-attrs}[Video macro options and attributes]
108
****