Use Shortcodes

    This page explains the available shortcodes and how to use them for your content.

    Place image files in the same directory as the markdown file using them. To make localization easier and enhance accessibility, the preferred image format is SVG. The following example shows the shortcode with the required fields needed to add an image:

    The and caption fields are required, but the shortcode also supports optional fields, for example:

    1. {{< image width="75%" ratio="45.34%"
    2.     link="./<image.svg>"
    3.     alt="<Alternate text used by screen readers and when loading the image fails>"
    4.     title="<Text that appears on mouse-over>"
    5.     caption="<The caption displayed under the image>"
    6.     >}}

    If you don’t include the title field, Hugo uses the text set in caption. If you don’t include the alt field, Hugo uses the text in title or in caption if title is also not defined.

    The width field sets the size of the image relative to the surrounding text and has a default of 100%.

    The ratio field sets the height of the image relative to its width. Hugo calculates this value automatically for image files in the folder. However, you must calculate it manually for external images. Set the value of ratio to ([image height]/[image width]) * 100.

    Add icons

    You can embed common icons in your content with the following content:

    1. {{< warning_icon >}}
    2. {{< idea_icon >}}
    3. {{< checkmark_icon >}}
    4. {{< cancel_icon >}}
    5. {{< tip_icon >}}

    The icons are rendered within the text. For example: , Use Shortcodes - 图1, ,Use Shortcodes - 图2 and .

    Add links to other pages

    The Istio documentation supports three types of links depending on their target. Each type uses a different syntax to express the target.

    • External links. These are links to pages outside of the Istio documentation or the Istio GitHub repositories. Use the standard Markdown syntax to include the URL. Use the HTTPS protocol, when you reference files on the Internet, for example:

      1. [Descriptive text for the link](https://mysite/myfile.html)

    • Absolute links. These links target pages outside the hierarchy of the current page but within the Istio website. Start the path of absolute links with a slash /, for example:

    Regardless of type, links do not point to the index.md file with the content, but to the folder containing it.

    There are a few ways to reference content or files on GitHub:

    • {{< github_file >}} is how you reference individual files in GitHub such as yaml files. This shortcode produces a link to https://raw.githubusercontent.com/istio/istio*, for example:

      1. [liveness]({{< github_file >}}/samples/health-check/liveness-command.yaml)

    • {{< github_tree >}} is how you reference a directory tree in GitHub. This shortcode produces a link to https://github.com/istio/istio/tree*, for example:

      1. [httpbin]({{< github_tree >}}/samples/httpbin)

    • {{< github_blob >}} is how you reference a file in GitHub sources. This shortcode produces a link to https://github.com/istio/istio/blob*, for example:

      1. [RawVM MySQL]({{< github_blob >}}/samples/rawvm/README.md)

    To display the current Istio version in your content by retrieving the current version from the web site, use the following shortcodes:

    • , which renders as 1.10
    • {{< istio_full_version >}}, which renders as 1.10.0

    Glossary terms

    When you introduce a specialized Istio term in a page, the supplemental acceptance criteria for contributions require you include the term in the glossary and markup its first instance using the {{< gloss >}} shortcode. The shortcode produces a special rendering that invites readers to click on the term to get a pop-up with the definition. For example:

    1. The Istio component that programs the {{<gloss>}}Envoy{{</gloss>}} proxies, responsible for service discovery, load balancing, and routing.

    Is rendered as follows:

    The Istio component that programs the {{}}Envoy{{}} proxies, responsible for service discovery, load balancing, and routing.

    If you use a variant of the term in your text, you can still use this shortcode to include the pop up with the definition. To specify a substitution, just include the glossary entry within the shortcode. For example:

    Renders with the pop up for the envoy glossary entry as follows:

    The Istio component that programs the Envoy proxies, responsible for service discovery, load balancing, and routing.

    Callouts

    To emphasize blocks of content, you can format them as warnings, ideas, tips, or quotes. All callouts use very similar shortcodes:

    1. {{< warning >}}
    2. This is an important warning
    3. {{< /warning >}}
    5. {{< idea >}}
    6. This is a great idea
    7. {{< /idea >}}
    9. {{< tip >}}
    10. This is a useful tip from an expert
    11. {{< /tip >}}
    13. {{< quote >}}
    14. {{< /quote >}}

    The shortcodes above render as follows:

    This is an important warning

    Use Shortcodes - 图3

    This is a great idea

    This is a useful tip from an expert

    This is a quote from somewhere

    Use callouts sparingly. Each type of callout serves a specific purpose and over-using them negates their intended purposes and their efficacy. Generally, you should not include more than one callout per content file.

    To reuse content while maintaining a single source for it, use boilerplate shortcodes. To embed boilerplate text into any content file, use the boilerplate shortcode as follows:

    1. {{< boilerplate example >}}

    The shortcode above includes the following content from the example.md Markdown file in the /content/en/boilerplates/ folder:

    1. A sample nested text block in a boilerplate.

    The example shows that you need to include the filename of the Markdown file with the content you wish to insert at the current location. You can find the existing boilerplate files are located in the /content/en/boilerplates directory.

    Use tabs

    To display content that has multiple options or formats, use tab sets and tabs. For example:

    • Equivalent commands for different platforms
    • Equivalent code samples in different languages
    • Alternative configurations

    To insert tabbed content, combine the tabset and tabs shortcodes, for example:

    1. {{< tabset category-name="platform" >}}
    3. {{< tab name="One" category-value="one" >}}
    4. ONE
    5. {{< /tab >}}
    7. {{< tab name="Two" category-value="two" >}}
    9. {{< /tab >}}
    11. {{< tab name="Three" category-value="three" >}}
    12. THREE
    13. {{< /tab >}}
    15. {{< /tabset >}}

    The shortcodes above produce the following output:

    ONE

    TWO

    THREE

    The value of the name attribute of each tab contains the text displayed for the tab. Within each tab, you can have normal Markdown content, but tabs have .

    The category-name and category-value attributes are optional and make the selected tab to stick across visits to the page. For example, a visitor selects a tab and their selection is saved automatically with the given name and value. If multiple tab sets use the same category name and values, their selection is automatically synchronized across pages. This is particularly useful when there are many tab sets in the site that hold the same types of formats.

    For example, multiple tab sets could provide options for GCP, BlueMix and AWS. You can set the value of the category-name attribute to environment and the values for the category-value attributes to gcp, bluemix, and aws. Then, when a reader selects a tab in one page, their choice will carry throughout all tab sets across the website automatically.

    Tab limitations

    You can use almost any Markdown in a tab, with the following exceptions:

    • Headers. Headers in a tab appear in the table of contents but clicking on the link in the table of contents won’t automatically select the tab.

    • Nested tab sets. Don’t nest tab sets. Doing so leads to a terrible reading experience and can cause significant confusion.

    Use banners and stickers

    To advertise upcoming events, or publicize something new, you can automatically insert time-sensitive banners and stickers into the generated site in order. We’ve implemented the following shortcodes for promotions:

    • Countdown stickers: They show how much time is left before a big event For example: “37 days left until ServiceMeshCon on March 30”. Stickers have some visual impact for readers prior to the event and should be used sparingly.

    To create banners and stickers, you create Markdown files in either the events/banners or events/stickers folders. Create one Markdown file per event with dedicated front-matter fields to control their behavior. The following table explains the available options: