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.
65 lines
2.9 KiB
65 lines
2.9 KiB
4 years ago
|
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 effect how the SVG behaves (or misbehaves).
|
||
|
|
Therefore, these macros provide additional options to control how the SVG is included (i.e., referenced).
|
||
|
|
|
||
|
|
When the image target is an SVG, the `options` attribute on the macro accepts one of three values:
|
||
|
|
|
||
|
|
* _none_ (default)
|
||
|
|
* interactive
|
||
|
|
* inline
|
||
|
|
|
||
|
|
The following table demonstrates the impact these options have.
|
||
|
|
|
||
|
|
.Demonstration of option values for SVG images
|
||
|
|
[cols="l,a"]
|
||
|
|
|===
|
||
|
|
|image::sample.svg[Static,300]
|
||
|
|
|image::sample.svg[Static,300]
|
||
|
|
|image::sample.svg[Interactive,300,opts=interactive]
|
||
|
|
|image::sample.svg[Interactive,300,opts=interactive]
|
||
|
|
|
||
|
|
Observe that the color changes when hovering over the SVG.
|
||
|
|
|image::sample.svg[Embedded,300,opts=inline]
|
||
|
|
|image::{docdir}/../images/sample.svg[Embedded,300,opts=inline]
|
||
|
|
|
||
|
|
Observe that the color changes when hovering over the SVG.
|
||
|
|
The SVG also inherits CSS from the document stylesheets.
|
||
|
|
|===
|
||
|
|
|
||
|
|
How the options value works and when it should be used is described below:
|
||
|
|
|
||
|
|
.Option values for SVG images (HTML output)
|
||
|
|
[cols="1,1,2,2"]
|
||
|
|
|===
|
||
|
|
|Option |HTML Element Used |Effect |When To Use
|
||
|
|
|
||
|
|
|_none_ (default)
|
||
|
|
|<img>
|
||
|
|
|Image is rasterized
|
||
|
|
|Static image, no interactivity, no custom fonts
|
||
|
|
|
||
|
|
|`interactive`
|
||
|
|
|<object>
|
||
|
|
|Image embedded as a live, interactive object (aka "`content document`")
|
||
|
|
|For using CSS animations, scripting, webfonts
|
||
|
|
|
||
|
|
|`inline`
|
||
|
|
|<svg>
|
||
|
|
|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.
|
||
|
|
|
||
|
|
To allow SVG content reachable by JavaScript in the main DOM or to inherit styles from the main DOM.
|
||
|
|
|===
|
||
|
|
|
||
|
|
When using the `inline` or `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 `width`, `height` and `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.
|
||
|
|
|
||
|
|
If you're inserting an SVG using either the `inline` or `interactive` options, we strongly recommend you optimize your SVG using a tool like {uri-svgo}[svgo] or {uri-svg-editor}[SVG Editor].
|
||
|
|
|
||
|
|
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 https://svgontheweb.com/[SVG on the Web: A Practical Guide] as well as https://www.sarasoueidan.com/tags/svg/[these articles about SVG].
|