Shortcodes

What follow are examples of applying shortcodes. The section headers are the name of the shortcode.

`color-listing`

This shortcode exists in case you would like to display colors in text or tables prefixed with the CSS color value that generated them. It takes one parameter which is the CSS color to display as a string. In the middle of a sentence we have #050 , which is a listing.

Listing	Raw Post
`#0000de`	`{{< color-listing "#0000de" >}}`
`rgb(9,8,7)`	`{{< color-listing "rgb(9,8,7)" >}}`

`color-patch`

This shortcode exists in case you would like to display colors in text or tables. It takes one parameter which is the CSS color to display as a string. For example this red block is produced with the following shortcode:

{{< color-patch "#f00" >}}

`excerpt-code`

This shortcode exists so that you can include sections of a file automatically in your documentation as a code sample.

The shortcode requires the following arguments:

path: The path to the file to excerpt.
lang: The language the code should be highlighted as. If you do not supply a value plain text will be the default.
start: The shortcode will ignore all file lines until it finds one that starts with exactly the prefix supplied.
end: The shortcode will include all file lines until it encounters a line that starts with exactly the prefix supplied. If start is found and end is not, then the entire file after start is matched will be excerpted.

For example, to include the configuration of markup styling from the theme’s configuration file you would invoke the shortcode as follows:

{{< excerpt-code path="themes/thoughts/config.toml" lang="toml"
    start="## Use CSS styling for code markup" end="##" >}}

Which renders the following output:

[markup]
  [markup.highlight]
    noClasses = false

`figure`

This shortcode is for displaying general images and figures. You can read more about how to use this shortcode below. It is similar to, but slightly differernt from, the default shortcode. There is a dedicated page with more examples of figures and line art.

One notable feature of this shortcode is that it will convert local images (but not SVG vector art) into the smaller WebP format. Unless different dimensions from the source image are specified, this code will preserve the original aspect ratio.

If the original image is larger than the display dimensions the shortcode will create responsive variants to improve the display on higher resolution displays.

Note: Until Hugo issue #10030 is fixed, this shortcode will not optimize GIF images.

The example below is an picture with alternative text and attribution text and a height set to at 150 pixels tall. It is generated with the following shortcode invocation:

{{< figure src="microscope.jpg" caption="Microscope."
    link="https://www.cancer.gov" height="350"
    alt="Microscope" attr="by National Cancer Institute"
    attrlink="https://unsplash.com/@nci" >}}

Microscope. by National Cancer Institute

The shortcode accepts the following arguments.

src: URL of the image to be displayed.
alt: Alternate text for the image if the image cannot be displayed. This is useful for those with disabilities and should be set on every image. A good rule of thumb to consider is to include what you might relay over the phone. See here for more detailed help on writing good alt text for images.
link: If the image is to be hyperlinked, URL of the destination.
target: Optional target attribute for the URL if link parameter is set.
rel: Optional rel attribute for the URL if link parameter is set.
caption: Image caption. Markdown within the value of caption will be rendered.
class: The class attribute of the HTML <figure> tag.
height: The height attribute of the image.
width: The width attribute of the image.
attr: Image attribution text. Markdown within the value of attr will be rendered.
attrlink: If the attribution text needs to be hyperlinked, URL of the destination.
float: Can be either left or right and will float the figure to the left or right of the main text.

The generated HTML for the above usage is:

<figure><a href="https://www.cancer.gov">
    <picture>
        <source srcset="/documentation/shortcodes/microscope_hu996f52a9ce231ee3a81fa11bb7b854d4_4737785_538x350_resize_q75_h2_box.webp 1x, /documentation/shortcodes/microscope_hu996f52a9ce231ee3a81fa11bb7b854d4_4737785_1076x700_resize_q75_h2_box.webp 2x, /documentation/shortcodes/microscope_hu996f52a9ce231ee3a81fa11bb7b854d4_4737785_1614x1050_resize_q75_h2_box.webp 3x, /documentation/shortcodes/microscope_hu996f52a9ce231ee3a81fa11bb7b854d4_4737785_2152x1400_resize_q75_h2_box.webp 4x" type="image/webp" />
        <img src="/documentation/shortcodes/microscope_hu996f52a9ce231ee3a81fa11bb7b854d4_4737785_0x350_resize_q75_box.jpg" srcset="/documentation/shortcodes/microscope_hu996f52a9ce231ee3a81fa11bb7b854d4_4737785_538x350_resize_q75_box.jpg 1x, /documentation/shortcodes/microscope_hu996f52a9ce231ee3a81fa11bb7b854d4_4737785_1076x700_resize_q75_box.jpg 2x, /documentation/shortcodes/microscope_hu996f52a9ce231ee3a81fa11bb7b854d4_4737785_1614x1050_resize_q75_box.jpg 3x, /documentation/shortcodes/microscope_hu996f52a9ce231ee3a81fa11bb7b854d4_4737785_2152x1400_resize_q75_box.jpg 4x"
         alt="Microscope" width="538" height="350"/></picture></a>
    <figcaption>Microscope.
        <a class="attrlink" href="https://unsplash.com/@nci">
        <cite>by National Cancer Institute</cite></a>
    </figcaption>
</figure>

`lineart`

This shortcode has all the same options as the figure shortcode, but it ensures that SVG line art is drawn with the text color. This makes line art drawings responsive to dark mode. There is a dedicated page with more examples of figures and line art. The following invocation produces the figure below:

{{< lineart src="glass.svg" alt="Measuring glass" width="100"
    caption="Line art measuring glass."
    alt="Measuring glass" attr="via OpenClipart"
    attrlink="https://freesvg.org/measuring-glass" >}}

Measuring glass — Line art measuring glass. via OpenClipart

The html generated is:

<figure class="lineart">
        <div style="-webkit-mask: url(glass.svg) no-repeat; mask: url(glass.svg) no-repeat;">
        <img src="glass.svg" alt="Measuring glass" width="100">
        </div>
        <figcaption>Line art measuring glass.
            <a class="attrlink" href="https://freesvg.org/measuring-glass">
            <cite>via OpenClipart</cite></a>
        </figcaption>
</figure>

`tweet`

This tweet by Balaji Srinivasan ended up being sadly prophetic regarding COVID-19. You can read more about how to use this shortcode via the Hugo tweet shortcode documentation.

Going viral

What if this coronavirus is the pandemic that public health people have been warning about for years?

It would accelerate many pre-existing trends.

- border closures
- nationalism
- social isolation
- preppers
- remote work
- face masks
- distrust in governments
— Balaji Srinivasan (@balajis) January 30, 2020

`youtube`

This YouTube video is Brett Victor talking about inventing on principle. You can read more about how to use this shortcode via the Hugo youtube shortcode documentation.

Generated HTML

<div style="position: relative; padding-bottom: 56.25%; height: 0; overflow: hidden;">
  <iframe src="https://www.youtube.com/embed/PUv66718DII"
    style="position: absolute; top: 0; left: 0; width: 100%; height: 100%; border:0;" 
    allowfullscreen="" title="YouTube Video"></iframe>
</div>

`vimeo`

Here is Adrift from Simon Christen, a beautiful video of fog rolling in across the San Francisco Bay. You can read more about how to use this shortcode via the Hugo vimeo shortcode documentation.