Switch uses of <figure> to {% include figure.html %} (#818)

figure.html now contains a bit of magic to substantially improve
the load time and visual appearance of pages that contain imagery.
The magic pre-allocates space on the page of the exact size needed
for the image, even though the image isn't loaded yet. The result
is that the page can be layed out once, layout doesn't need to
happen again for each image that gets loaded.

_blog/posts/2017/0.1-announcement.md

@@ -36,18 +36,19 @@ Google, IBM and Lyft joined forces to create Istio from a desire to provide a re
 
 **Fleet-wide Visibility**: Failures happen, and operators need tools to stay on top of the health of clusters and their graphs of microservices. Istio produces detailed monitoring data about application and network behaviors that is rendered using [Prometheus](https://prometheus.io/) & [Grafana](https://github.com/grafana/grafana), and can be easily extended to send metrics and logs to any collection, aggregation and querying system. Istio enables analysis of performance hotspots and diagnosis of distributed failure modes with [Zipkin](https://github.com/openzipkin/zipkin) tracing.
 
-<figure>
-    <a href="{{home}}/img/istio_grafana_dashboard-new.png">
-    <img style="max-width: 100%;" src="{{home}}/img/istio_grafana_dashboard-new.png" alt="Grafana Dashboard with Response Size" title="Grafana Dashboard with 
-    Response Size" />
-    </a>
-</figure>
+{% include figure.html width='100%' ratio='55.42%'
+    img='./img/istio_grafana_dashboard-new.png'
+    alt='Grafana Dashboard with Response Size'
+    title='Grafana Dashboard with Response Size'
+    caption='Grafana Dashboard with Response Size'
+    %}
 
-<figure>
-    <a href="{{home}}/img/istio_zipkin_dashboard.png">
-    <img style="max-width: 100%;" src="{{home}}/img/istio_zipkin_dashboard.png" alt="Zipkin Dashboard" title="Zipkin Dashboard" />
-    </a>
-</figure>
+{% include figure.html width='100%' ratio='29.91%'
+    img='./img/istio_zipkin_dashboard.png'
+    alt='Zipkin Dashboard'
+    title='Zipkin Dashboard'
+    caption='Zipkin Dashboard'
+    %}
 
 **Resiliency and efficiency**: When developing microservices, operators need to assume that the network will be unreliable. Operators can use retries, load balancing, flow-control (HTTP/2), and circuit-breaking to compensate for some of the common failure modes due to an unreliable network. Istio provides a uniform approach to configuring these features, making it easier to operate a highly resilient service mesh. 
 

_blog/posts/2017/0.1-auth.md

@@ -46,15 +46,15 @@ Istio Auth is based on industry standards like mutual TLS and X.509. Furthermore
 
 The diagram below provides an overview of the Istio Auth service authentication architecture on Kubernetes.
 
-<figure>
-    <a href="{{home}}/img/istio_auth_overview.svg">
-    <img style="max-width: 100%;" src="{{home}}/img/istio_auth_overview.svg" alt="Istio Auth Overview" title="Istio Auth Overview" />
-    </a>
-</figure>
+{% include figure.html width='100%' ratio='56.25%'
+    img='./img/istio_auth_overview.svg'
+    alt='Istio Auth Overview'
+    title='Istio Auth Overview'
+    caption='Istio Auth Overview'
+    %}
 
 The above diagram illustrates three key security features:
 
-
 ### Strong Identity
 
 Istio Auth uses [Kubernetes service accounts](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/) to identify who the service runs as. The identity is used to establish trust and define service level access policies. The identity is assigned at service deployment time and encoded in the SAN (Subject Alternative Name) field of an X.509 certificate. Using a service account as the identity has the following advantages:
@@ -83,12 +83,12 @@ Istio Auth provides a per-cluster CA (Certificate Authority) and automated key &
  
 The following diagram explains the end to end Istio Auth authentication workflow on Kubernetes:
 
-<figure>
-    <a href="{{home}}/img/istio_auth_workflow.svg">
-    <img style="max-width: 100%;" src="{{home}}/img/istio_auth_workflow.svg" alt="Istio Auth Workflow" title="Istio Auth Workflow" />
-    </a>
-</figure>
-
+{% include figure.html width='100%' ratio='56.25%'
+    img='./img/istio_auth_workflow.svg'
+    alt='Istio Auth Workflow'
+    title='Istio Auth Workflow'
+    caption='Istio Auth Workflow'
+    %}
 
 Istio Auth is part of the broader security story for containers. Red Hat, a partner on the development of Kubernetes, has identified [10 Layers](https://www.redhat.com/en/resources/container-security-openshift-cloud-devops-whitepaper) of container security. Istio and Istio Auth addresses two of these layers: "Network Isolation" and "API and Service Endpoint Management". As cluster federation evolves on Kubernetes and other platforms, our intent is for Istio to secure communications across services spanning multiple federated clusters.
 

_blog/posts/2017/0.1-using-network-policy.md

@@ -104,12 +104,13 @@ spec:
 
 Here is the service graph for the BookInfo application.
 
-<figure>
-    <a href="{{home}}/docs/guides/img/bookinfo/withistio.svg">
-    <img style="max-width: 100%;" src="{{home}}/docs/guides/img/bookinfo/withistio.svg" alt="BookInfo service graph" title="BookInfo service graph" />
-    </a>
-</figure>
-
+{% assign url = home | append: "/docs/guides/img/bookinfo/withistio.svg" %}
+{% include figure.html width='80%' ratio='59.08%'
+    img=url
+    alt='BookInfo Service Graph'
+    title='BookInfo Service Graph'
+    caption='BookInfo Service Graph'
+    %}
 
 This graph shows every connection that a correctly functioning application should be allowed to make.  All other connections, say from the Istio Ingress directly to the Rating service, are not part of the application.  Let’s lock out those extraneous connections so they cannot be used by an attacker.  Imagine, for example, that the Ingress pod is compromised by an exploit that allows an attacker to run arbitrary code.  If we only allow connections to the Product Page pods using Network Policy, the attacker has gained no more access to my application backends _even though they have compromised a member of the service mesh_.
 

_blog/posts/2017/adapter-model.md

@@ -32,8 +32,13 @@ Adapters are Go packages that are directly linked into the Mixer binary. It’s
 
 Mixer is essentially an attribute processing and routing machine. The proxy sends it [attributes]({{home}}/docs/concepts/policy-and-control/attributes.html) as part of doing precondition checks and telemetry reports, which it turns into a series of calls into adapters. The operator supplies configuration which describes how to map incoming attributes to inputs for the adapters. 
 
-<figure><img src="{{home}}/docs/concepts/policy-and-control/img/mixer-config/machine.svg" alt="Attribute Machine" title="Attribute Machine" />
-<figcaption>Attribute Machine</figcaption></figure>
+{% assign url = home | append: "/docs/concepts/policy-and-control/img/mixer-config/machine.svg" %}
+{% include figure.html width='60%' ratio='42.60%'
+    img=url
+    alt='Attribute Machine'
+    title='Attribute Machine'
+    caption='Attribute Machine'
+    %}
 
 Configuration is a complex task. In fact, evidence shows that the overwhelming majority of service outages are caused by configuration errors. To help combat this, Mixer’s configuration model enforces a number of constraints designed to avoid errors. For example, the configuration model uses strong typing to ensure that only meaningful attributes or attribute expressions are used in any given context.
 
@@ -84,4 +89,6 @@ The refreshed Mixer adapter model is designed to provide a flexible framework to
 
 Handlers provide configuration data for individual adapters, templates determine exactly what kind of data different adapters want to consume at runtime, instances let operators prepare this data, rules direct the data to one or more handlers.
 
-You can learn more about the overall Mixer architecture [here]({{home}}/docs/concepts/policy-and-control/), and learn the specifics of templates, handlers, and rules [here]({{home}}/docs/reference/config/mixer/). You can find many examples of Mixer configuration resources in the bookinfo sample [here](https://github.com/istio/istio/tree/master/samples/bookinfo/kube).
+You can learn more about Mixer's overall architecture [here]({{home}}/docs/concepts/policy-and-control/), and learn the specifics of templates, handlers,
+and rules [here]({{home}}/docs/reference/config/mixer/). You can find many examples of Mixer configuration resources in the BookInfo sample
+[here](https://github.com/istio/istio/tree/master/samples/bookinfo/kube).

_blog/posts/2017/mixer-spof-myth.md

@@ -36,8 +36,12 @@ In 2014, we started an initiative to create a replacement architecture that woul
 
 The older system was built around a centralized fleet of fairly heavy proxies into which all incoming traffic would flow, before being forwarded to the services where the real work was done. The newer architecture jettisons the shared proxy design and instead consists of a very lean and efficient distributed sidecar proxy sitting next to service instances, along with a shared fleet of sharded control plane intermediaries:
 
-<figure><img src="./img/mixer-spof-myth-1.svg" alt="Google System Topology" title="Google System Topology" />
-<figcaption>Google's API & Service Management System</figcaption></figure>
+{% include figure.html width='75%' ratio='74.79%'
+    img='./img/mixer-spof-myth-1.svg'
+    alt='Google System Topology'
+    title='Google System Topology'
+    caption="Google's API & Service Management System"
+    %}
 
 Look familiar? Of course: it’s just like Istio! Istio was conceived as a second generation of this distributed proxy architecture. We took the core lessons from this internal system, generalized many of the concepts by working with our partners, and created Istio. 
 
@@ -45,8 +49,12 @@ Look familiar? Of course: it’s just like Istio! Istio was conceived as a secon
 
 As shown in the diagram below, Mixer sits between the mesh and the infrastructure backends that support it:
 
-<figure><img src="./img/mixer-spof-myth-2.svg" alt="Istio Topology" title="Istio Topology" />
-<figcaption>Istio Topology</figcaption></figure>
+{% include figure.html width='75%' ratio='65.89%'
+    img='./img/mixer-spof-myth-2.svg'
+    alt='Istio Topology'
+    title='Istio Topology'
+    caption="Istio Topology"
+    %}
 
 The Envoy sidecar logically calls Mixer before each request to perform precondition checks, and after each request to report telemetry.
 The sidecar has local caching such that a relatively large percentage of precondition checks can be performed from cache. Additionally, the

_docs/concepts/policy-and-control/mixer-config.md

@@ -45,8 +45,12 @@ The set of attributes determines which backend Mixer calls for a given request a
 each is given. In order to hide the details of individual backends, Mixer uses modules
 known as [*adapters*](./mixer.html#adapters).
 
-<figure><img src="./img/mixer-config/machine.svg" alt="Attribute Machine" title="Attribute Machine" />
-<figcaption>Attribute Machine</figcaption></figure>
+{% include figure.html width='60%' ratio='42.60%'
+    img='./img/mixer-config/machine.svg'
+    alt='Attribute Machine'
+    title='Attribute Machine'
+    caption='Attribute Machine'
+    %}
 
 Mixer's configuration has the following central responsibilities:
 

_docs/concepts/policy-and-control/mixer.md

@@ -29,9 +29,12 @@ Mixer is designed to change the boundaries between layers in order to reduce
 systemic complexity, eliminating policy logic from service code and giving
 control to operators instead.
 
-<figure><img style="max-width:60%;" src="./img/mixer/traffic.svg" alt="Showing
-the flow of traffic through Mixer." title="Mixer Traffic Flow" />
-<figcaption>Mixer Traffic Flow</figcaption></figure>
+{% include figure.html width='60%' ratio='59%'
+    img='./img/mixer/traffic.svg'
+    alt='Showing the flow of traffic through Mixer.'
+    title='Mixer Traffic Flow'
+    caption='Mixer Traffic Flow'
+    %}
 
 Mixer provides three core features:
 
@@ -69,8 +72,12 @@ single consistent API, independent of the backends in use. The exact set of
 adapters used at runtime is determined through configuration and can easily be
 extended to target new or custom infrastructure backends.
 
-<figure><img style="max-width:35%;" src="./img/mixer/adapters.svg" alt="Showing
-Mixer with adapters." title="Mixer and its Adapters" /></figure>
+{% include figure.html width='35%' ratio='138%'
+    img='./img/mixer/adapters.svg'
+    alt='Showing Mixer with adapters.'
+    title='Mixer and its Adapters'
+    caption='Mixer and its Adapters'
+    %}
 
 ## Configuration state
 
@@ -129,9 +136,12 @@ phases:
   parameters. The Adapter Dispatching phase invokes the adapters associated with
   each aspect and passes them those parameters.
 
-<figure><img style="max-width:50%;" src="./img/mixer/phases.svg" alt="Phases of
-Mixer request processing." title="Request Phases" /> <figcaption>Request
-Phases</figcaption></figure>
+{% include figure.html width='50%' ratio='144%'
+    img='./img/mixer/phases.svg'
+    alt='Phases of Mixer request processing.'
+    title='Request Phases'
+    caption='Request Phases'
+    %}
 
 ## What's next
 

_docs/concepts/security/mutual-tls.md

@@ -29,13 +29,15 @@ Istio Auth's aim is to enhance the security of microservices and their communica
 
 The diagram below shows Istio Auth's architecture, which includes three primary components: identity, key management, and communication security. This diagram describes how Istio Auth is used to secure the service-to-service communication between service 'frontend' running as the service account 'frontend-team' and service 'backend' running as the service account 'backend-team'. Istio supports services running on both Kubernetes containers and VM/bare-metal machines.
 
-<figure><img src="./img/auth/auth.svg" alt="Components making up the Istio auth model." title="Istio Auth Architecture" />
-<figcaption>Istio Auth Architecture</figcaption></figure>
+{% include figure.html width='80%' ratio='56.25%'
+    img='./img/mutual-tls/auth.svg'
+    alt='Components making up the Istio auth model.'
+    title='Istio Auth Architecture'
+    caption='Istio Auth Architecture'
+    %}
 
 As illustrated in the diagram, Istio Auth leverages secret volume mount to deliver keys/certs from Istio CA to Kubernetes containers. For services running on VM/bare-metal machines, we introduce a node agent, which is a process running on each VM/bare-metal machine. It generates the private key and CSR (certificate signing request) locally, sends CSR to Istio CA for signing, and delivers the generated certificate together with the private key to Envoy.
 
-
-
 ## Components
 
 ### Identity

_docs/concepts/traffic-management/load-balancing.md

@@ -24,8 +24,12 @@ registry and provides a platform-agnostic service discovery
 interface. Envoy instances in the mesh perform service discovery and 
 dynamically update their load balancing pools accordingly.
 
-<figure><img src="./img/pilot/LoadBalancing.svg" alt="Discovery and Load Balancing" title="Discovery and Load Balancing" />
-<figcaption>Discovery and Load Balancing</figcaption></figure>
+{% include figure.html width='60%' ratio='74.79%'
+    img='./img/pilot/LoadBalancing.svg'
+    alt='Discovery and Load Balancing'
+    title='Discovery and Load Balancing'
+    caption='Discovery and Load Balancing'
+    %}
 
 As illustrated in the figure above, services in the mesh access each other
 using their DNS names. All HTTP traffic bound to a service is automatically

_docs/concepts/traffic-management/overview.md

@@ -43,9 +43,12 @@ of traffic for a particular service to go to a canary version irrespective
 of the size of the canary deployment, or send traffic to a particular version
 depending on the content of the request.
 
-
-<figure><img style="max-width:85%;" src="./img/pilot/TrafficManagementOverview.svg" alt="Traffic Management with Istio" title="Traffic Management with Istio" />
-<figcaption>Traffic Management with Istio</figcaption></figure>
+{% include figure.html width='85%' ratio='69.52%'
+    img='./img/pilot/TrafficManagementOverview.svg'
+    alt='Traffic Management with Istio'
+    title='Traffic Management with Istio'
+    caption='Traffic Management with Istio'
+    %}
 
 Decoupling traffic flow from infrastructure scaling like this allows Istio
 to provide a variety of traffic management features that live outside the

_docs/concepts/traffic-management/pilot.md

@@ -11,8 +11,12 @@ type: markdown
 Pilot is responsible for the lifecycle of Envoy instances deployed
 across the Istio service mesh.
 
-<figure><img src="./img/pilot/PilotAdapters.svg" alt="Pilot's overall architecture." title="Pilot Architecture" />
-<figcaption>Pilot Architecture</figcaption></figure>
+{% include figure.html width='60%' ratio='72.17%'
+    img='./img/pilot/PilotAdapters.svg'
+    alt="Pilot's overall architecture."
+    title='Pilot Architecture'
+    caption='Pilot Architecture'
+    %}
 
 As illustrated in the figure above, Pilot maintains a canonical
 representation of services in the mesh that is independent of the underlying

_docs/concepts/traffic-management/request-routing.md

@@ -32,8 +32,12 @@ additional control over traffic between services.
 
 ## Communication between services
 
-<figure><img src="./img/pilot/ServiceModel_Versions.svg" alt="Showing how service versions are handled." title="Service Versions" />
-<figcaption>Service Versions</figcaption></figure>
+{% include figure.html width='60%' ratio='100.42%'
+    img='./img/pilot/ServiceModel_Versions.svg'
+    alt='Showing how service versions are handled.'
+    title='Service Versions'
+    caption='Service Versions'
+    %}
 
 As illustrated in the figure above, clients of a service have no knowledge
 of different versions of the service. They can continue to access the
@@ -69,5 +73,10 @@ via the sidecar Envoy, operators can add failure recovery features such as
 timeouts, retries, circuit breakers, etc., and obtain detailed metrics on
 the connections to these services.
 
-<figure><img src="./img/pilot/ServiceModel_RequestFlow.svg" alt="Ingress and Egress through Envoy." title="Request Flow" />
-<figcaption>Request Flow</figcaption></figure>
+{% include figure.html width='60%' ratio='28.88%'
+    img='./img/pilot/ServiceModel_RequestFlow.svg'
+    alt='Ingress and Egress through Envoy.'
+    title='Request Flow'
+    caption='Request Flow'
+    %}
+

_docs/concepts/what-is-istio/overview.md

@@ -60,8 +60,12 @@ configuring proxies to route traffic, as well as enforcing policies at runtime.
 
 The following diagram shows the different components that make up each plane:
 
-<figure><img src="./img/architecture/arch.svg" alt="The overall architecture of an Istio-based application." title="Istio Architecture" />
-<figcaption>Istio Architecture</figcaption></figure>
+{% include figure.html width='80%' ratio='56.25%'
+    img='./img/overview/arch.svg'
+    alt='The overall architecture of an Istio-based application.'
+    title='Istio Architecture'
+    caption='Istio Architecture'
+    %}
 
 ### Envoy
 

_docs/guides/bookinfo.md

@@ -34,8 +34,12 @@ There are 3 versions of the reviews microservice:
 
 The end-to-end architecture of the application is shown below.
 
-<figure><img src="./img/bookinfo/noistio.svg" alt="BookInfo Application without Istio" title="BookInfo Application without Istio" />
-<figcaption>BookInfo Application without Istio</figcaption></figure>
+{% include figure.html width='80%' ratio='68.52%'
+    img='./img/bookinfo/noistio.svg'
+    alt='BookInfo Application without Istio'
+    title='BookInfo Application without Istio'
+    caption='BookInfo Application without Istio'
+    %}
 
 This application is polyglot, i.e., the microservices are written in different languages.
 It’s worth noting that these services have no dependencies on Istio, but make an interesting
@@ -55,8 +59,12 @@ Istio-enabled environment, with Envoy sidecars injected along side each service.
 The needed commands and configuration vary depending on the runtime environment
 although in all cases the resulting deployment will look like this:
 
-<figure><img src="./img/bookinfo/withistio.svg" alt="BookInfo Application" title="BookInfo Application" />
-<figcaption>BookInfo Application</figcaption></figure>
+{% include figure.html width='80%' ratio='59.08%'
+    img='./img/bookinfo/withistio.svg'
+    alt='BookInfo Application'
+    title='BookInfo Application'
+    caption='BookInfo Application'
+    %}
 
 All of the microservices will be packaged with an Envoy sidecar that intercepts incoming
 and outgoing calls for the services, providing the hooks needed to externally control,

_docs/guides/integrating-vms.md

@@ -18,9 +18,12 @@ this infrastructure as a single mesh.
 
 ## Overview
 
-
-<figure><img src="./img/mesh-expansion.svg" alt="BookInfo Application with Istio Mesh Expansion" title="BookInfo Application with Istio Mesh Expansion" />
-<figcaption>BookInfo Application with Istio Mesh Expansion</figcaption></figure>
+{% include figure.html width='80%' ratio='56.78%'
+    img='./img/mesh-expansion.svg'
+    alt='BookInfo Application with Istio Mesh Expansion'
+    title='BookInfo Application with Istio Mesh Expansion'
+    caption='BookInfo Application with Istio Mesh Expansion'
+    %}
 
 <!-- source of the drawing https://docs.google.com/drawings/d/1gQp1OTusiccd-JUOHktQ9RFZaqREoQbwl2Vb-P3XlRQ/edit -->
 

_docs/reference/index.md

@@ -1,7 +1,6 @@
 ---
 title: Reference
 overview: The Reference section contains detailed authoritative reference material such as command-line options, configuration options, and API calling parameters.
-index: true
 
 order: 60
 

_docs/tasks/telemetry/distributed-tracing.md

@@ -10,7 +10,7 @@ type: markdown
 {% include home.html %}
 
 This task shows you how Istio-enabled applications 
-can be configured to collect trace spans using [Zipkin](http://zipkin.io) or [Jaeger](https://uber.github.io/jaeger/). 
+can be configured to collect trace spans using [Zipkin](http://zipkin.io) or [Jaeger](https://jaeger.readthedocs.io). 
 After completing this task, you should understand all of the assumptions about your
 application and how to have it participate in tracing, regardless of what
 language/framework/platform you use to build your application.
@@ -69,19 +69,37 @@ With the BookInfo application up and running, generate trace information by acce
 
 If you now look at the dashboard, you should see something similar to the following:
 
-<figure><img style="max-width:100%" src="./img/zipkin_dashboard.png" alt="Zipkin Dashboard" title="Zipkin Dashboard" />
-<figcaption>Zipkin Dashboard</figcaption></figure>
-<figure><img style="max-width:100%" src="./img/jaeger_dashboard.png" alt="Jaeger Dashboard" title="Jaeger Dashboard" />
-<figcaption>Jaeger Dashboard</figcaption></figure>
+{% include figure.html width='100%' ratio='44.28%'
+    img='./img/zipkin_dashboard.png'
+    alt='Zipkin Dashboard'
+    title='Zipkin Dashboard'
+    caption='Zipkin Dashboard'
+    %}
+
+{% include figure.html width='100%' ratio='42.35%'
+    img='./img/jaeger_dashboard.png'
+    alt='Jaeger Dashboard'
+    title='Jaeger Dashboard'
+    caption='Jaeger Dashboard'
+    %}
 
 If you click on the top (most recent) trace, you should see the details corresponding to your
 latest refresh of the `/productpage`.
 The page should look something like this:
 
-<figure><img style="max-width:100%" src="./img/zipkin_span.png" alt="Zipkin Trace View" title="Zipkin Trace View" />
-<figcaption>Zipkin Trace View</figcaption></figure>
-<figure><img style="max-width:100%" src="./img/jaeger_trace.png" alt="Jaeger Trace View" title="Jaeger Trace View" />
-<figcaption>Jaeger Trace View</figcaption></figure>
+{% include figure.html width='100%' ratio='19.70%'
+    img='./img/zipkin_span.png'
+    alt='Zipkin Trace View'
+    title='Zipkin Trace View'
+    caption='Zipkin Trace View'
+    %}
+
+{% include figure.html width='100%' ratio='26.99%'
+    img='./img/jaeger_trace.png'
+    alt='Jaeger Trace View'
+    title='Jaeger Trace View'
+    caption='Jaeger Trace View'
+    %}
 
 As you can see, the trace is comprised of spans,
 where each span corresponds to a BookInfo service invoked during the execution of a `/productpage` request.

_docs/tasks/telemetry/querying-metrics.md

@@ -75,8 +75,12 @@ the example application throughout this task.
 
     The results will be similar to:
 
-    <figure><img style="max-width:100%" src="./img/prometheus_query_result.png" alt="Prometheus Query Result" title="Prometheus Query Result" />
-    <figcaption>Prometheus Query Result</figcaption></figure>
+{% include figure.html width='100%' ratio='39.36%'
+    img='./img/prometheus_query_result.png'
+    alt='Prometheus Query Result'
+    title='Prometheus Query Result'
+    caption='Prometheus Query Result'
+    %}
 
     Other queries to try:
 

_docs/tasks/telemetry/servicegraph.md

@@ -81,9 +81,12 @@ the example application throughout this task.
 
     The results will look similar to:
 
-<figure><img style="max-width:100%" src="./img/servicegraph-example.png"
-alt="Example Servicegraph" title="Example Servicegraph" /> <figcaption>Example
-Servicegraph</figcaption></figure>
+{% include figure.html width='100%' ratio='63.16%'
+    img='./img/servicegraph-example.png'
+    alt='Example Servicegraph'
+    title='Example Servicegraph'
+    caption='Example Servicegraph'
+    %}
 
 ### About the Servicegraph Add-on
 

_docs/tasks/telemetry/tcp-metrics.md

@@ -239,8 +239,12 @@ Mixer at both connection establishment and connection close. Additionally,
 context attributes provide the ability to distinguish between `http` and `tcp`
 protocols within policies.
 
-<figure><img style="max-width:100%;" src="./img/istio-tcp-attribute-flow.svg" alt="Attribute Generation Flow for TCP Services in an Istio Mesh." title="TCP Attribute Flow" />
-<figcaption>TCP Attribute Flow</figcaption></figure>
+{% include figure.html width='100%' ratio='192.50%'
+    img='./img/istio-tcp-attribute-flow.svg'
+    alt='Attribute Generation Flow for TCP Services in an Istio Mesh.'
+    title='TCP Attribute Flow'
+    caption='TCP Attribute Flow'
+    %}
 
 ## Cleanup
 

_docs/tasks/telemetry/using-istio-dashboard.md

@@ -66,9 +66,12 @@ the example application throughout this task.
 
     The Istio Dashboard will look similar to:
 
-<figure><img style="max-width:100%" src="./img/grafana-istio-dashboard.png"
-alt="Istio Dashboard" title="Istio Dashboard" /> <figcaption>Istio
-Dashboard</figcaption></figure>
+{% include figure.html width='100%' ratio='56.57%'
+    img='./img/grafana-istio-dashboard.png'
+    alt='Istio Dashboard'
+    title='Istio Dashboard'
+    caption='Istio Dashboard'
+    %}
 
 1. Send traffic to the mesh.
 
@@ -85,9 +88,12 @@ Dashboard</figcaption></figure>
    Look at the Istio Dashboard again. It should reflect the traffic that was
    generated. It will look similar to:
 
-<figure><img style="max-width:100%" src="./img/dashboard-with-traffic.png"
-alt="Istio Dashboard With Traffic" title="Istio Dashboard With Traffic" />
-<figcaption>Istio Dashboard With Traffic</figcaption></figure>
+{% include figure.html width='100%' ratio='56.57%'
+    img='./img/dashboard-with-traffic.png'
+    alt='Istio Dashboard With Traffic'
+    title='Istio Dashboard With Traffic'
+    caption='Istio Dashboard With Traffic'
+    %}
 
    Note: `$GATEWAY_URL` is the value set in the
    [BookInfo]({{home}}/docs/guides/bookinfo.html) guide.

_docs/welcome/contribute/writing-a-new-topic.md

@@ -136,24 +136,21 @@ SVG file in the repository even if it isn't used in the web
 site itself. This is so we can update the imagery over time 
 if needed.
 
-Within markdown, use the `figure` element to add the image:
+Within markdown, use the following sequence to add the image:
 
 ```html
-{% raw %}<figure>
-<img src="./img/myfile.svg" alt="Some description for accessibility" titla="A title displayed as a tooltip"/>
-<figcaption>A caption displayed under the image</figcaption>
-</figure>{% endraw %}
+{% raw %}
+{% include figure.html width='75%' ratio='69.52%'
+    img='./img/myfile.svg'
+    alt='Alternate text to display when the image is not available'
+    title='A tooltip displayed when hovering over the image'
+    caption='A caption displayed under the image'
+    %}
+{% endraw %}
 ```
 
-This will insert the image centered with a width of 75% and the given caption under it. You can
-adjust the width using a style element such as:
- 
-```html
-{% raw %}<figure>
-<img style="max-width: 32%;" src="./img/myfile.svg" alt="Some description for accessibility" titla="A title displayed as a tooltip"/>
-<figcaption>A caption displayed under the image</figcaption>
-</figure>{% endraw %}
-```
+You need to fill in all the values. The width represents the percentage of space used by the image
+relative to the surrounding text. The ratio is (image height / image width) * 100.
 
 ## Linking to other pages
 

_includes/figure.html

@@ -0,0 +1,28 @@
+{% comment %}
+Purpose:
+    Inserts a figure into a page. The user of this template specifies the
+    relative width of the figure in percentage, and an aspect ratio value in
+    lieu of the Y coordinate. Through CSS trickery, these two values let us
+    calculate the actual width and height of the image at render time in such
+    a way that it avoids the typical 'shifting text' problem as images are
+    loaded asynchronously.
+
+Usage:
+    {% include figure.html width='<NN>%' ratio='<NN>%'
+        img='<path to image file>'
+        alt='<text to display when the image is not available>'
+        title='<text to display when hovering over the image>'
+        caption='<text to display below the image>'
+    %}
+{% endcomment %}
+
+<div class="figure" style="width: {{include.width}};">
+    <div class="wrapper-with-intrinsic-ratio" style="padding-bottom: {{include.ratio}}">
+        <figure>
+            <a href="{{include.img}}">
+                <img class="element-to-stretch" src="{{include.img}}" alt="{{include.alt}}" title="{{include.title}}" />
+            </a>
+        </figure>
+    </div>
+    <p>{{include.caption}}</p>
+</div>

_sass/base/_override.scss

@@ -63,18 +63,3 @@ pre {
 .navbar-toggle .icon-bar {
   background-color: $inverseBrandColor;
 }
-
-figure {
-    text-align: center;
-    margin-top: 20px;
-    margin-bottom: 20px;
-
-    img {
-        max-width: 75%;
-    }
-
-    figcaption {
-        margin-top: 10px;
-        text-align: center;
-    }
-}

_sass/modules/_figure.scss

@@ -0,0 +1,27 @@
+.figure {
+    margin: 1.5rem auto;
+    display: block;
+    border: 1px solid rgba(0, 0, 0, .1);
+    border-radius: 4px;
+    padding: .5rem .5rem 0 .5rem;
+
+    p {
+        text-align: center;
+        font-size: $font-size--s;
+        font-style: italic;
+        font-weight: 300;
+    }
+
+    .wrapper-with-intrinsic-ratio {
+        position: relative;
+        height: 0;
+    }
+
+    .element-to-stretch {
+        position: absolute;
+        top: 0;
+        left: 0;
+        width: 100%;
+        height: 100%;
+    }
+}

css/all.scss

@@ -11,6 +11,7 @@
 
 @import "modules/buttons";
 @import "modules/doctab";
+@import "modules/figure";
 @import "modules/footer";
 @import "modules/nav";
 @import "modules/search-box";