Both block and inline image macros have built-in support for scalable vector graphics (SVGs). But there’s more than one way to include an SVG into a web page, and the strategy used can affect how the SVG behaves (or misbehaves). Therefore, these macros provide additional options to control how the SVG is included (i.e., referenced).
The viewBox attribute on the root
<svg> element is required.
The viewBox establishes the coordinate space on to which x and y values inside the SVG data are placed.
Without this information, converters cannot properly interpret the SVG data and translate it to the canvas.
We strongly recommend not using the width and height attributes on the root
You will find that SVGs that only specify a viewBox work best in a document.
That’s because the SVG data itself is infinitely scalable.
By assigning an explicit width and height, you may end up limiting how the SVG can be sized or positioned in the document.
It’s better to specify the width (or similar, such as pdfwidth) on the image macro instead, or using CSS.
You particularly want to avoid using a percentage width, such as
According to the SVG spec, this means using all available space, but without altering the aspect ratio.
As a result, you can get a large gap above and below the SVG in page-oriented media, such as PDF.
If you do specify a width and height, at least make sure the values are fixed and that they respect the aspect ratio of the data.
When the image target is an SVG, the
options attribute (often abbreviated as
opts) on the macro accepts one of the following values to control how the SVG is referenced:
The following table demonstrates the impact these options have.
Observe that the SVG does not respond to the hover event.
Observe that the color changes when hovering over the SVG.
Observe that the color changes when hovering over the SVG. The SVG also inherits CSS from the document stylesheets.
How these options values work and when each should be used is described below:
|HTML Element Used
|When To Use
Image is rasterized
Static image, no interactivity, no custom fonts
Image embedded as a live, interactive object
For using CSS animations, scripting, webfonts, or when you want to specify a fallback image
The SVG is embedded directly into the HTML itself
For using CSS animations, scripting, webfonts, when you require search engines to search the SVG content
When using the
interactive option, you can specify a fallback image using the
The fallback image is used if the browser does not support the
If the value of the fallback attribute is a relative path, it will be prefixed with the value of the
imagesdir document attribute.
When using the
interactive options, the
viewBox attribute must be defined on the root
<svg> element in order for scaling to work properly.
When using the
inline option, if you specify a width or height on the image macro in AsciiDoc, the
style attributes on the
<svg> element will be removed. Additionally, when using
inline the primary SVG elements (e.g.,
<svg>) cannot have a namespace.
If using the
interactive option, you must link to the CSS that declares the fonts in the SVG file using an XML stylesheet declaration.
As you work with SVG, you’ll become more comfortable making the decision about which method to employ given the circumstances. It’s only confusing when you first encounter the choice. To learn more about using SVG on the web, consult the online book SVG on the Web: A Practical Guide as well as these articles about SVG.