Styling Content

The following is a list of Upbound documentation customizations that expand traditional Markdown. Most of these are custom Hugo Shortcodes.

Markdown

Upbound documentation uses Hugo to render Markdown to HTML. Hugo supports Commonmark and GitHub Flavored Markdown (GFM) through the Goldmark parser.

Note
Commonmark and GFM are extensions to the standard Markdown language.

The docs support standard Markdown for images, links and tables. Use the custom shortcodes provides a better user experience.

Hide long outputs

Some outputs may be verbose or relevant for a small audience. Use the expand shortcode to hide blocks of text by default.

 1apiVersion: apiextensions.crossplane.io/v1
 2kind: CompositeResourceDefinition
 3metadata:
 4  name: xpostgresqlinstances.database.example.org
 5spec:
 6  group: database.example.org
 7  names:
 8    kind: XPostgreSQLInstance
 9    plural: xpostgresqlinstances
10  claimNames:
11    kind: PostgreSQLInstance
12    plural: postgresqlinstances
13  versions:
14  - name: v1alpha1
15    served: true
16    referenceable: true
17    schema:
18      openAPIV3Schema:
19        type: object
20        properties:
21          spec:
22            type: object
23            properties:
24              parameters:
25                type: object
26                properties:
27                  storageGB:
28                    type: integer
29                required:
30                - storageGB
31            required:
32            - parameters

The expand shortcode can have a title, the default is “Expand.”

1{{< expand "A large XRD" >}}
2```yaml
3apiVersion: apiextensions.crossplane.io/v1
4kind: CompositeResourceDefinition
5metadata:
6  name: xpostgresqlinstances.database.example.org
7```
8{{< /expand >}}
Important
The expand shortcode requires opening and closing tags. Unclosed tags causes Hugo to fail.

Hints and alert boxes

Hint and alert boxes provide call-outs to important information to the reader. Upbound docs support four different hint box styles.

Note
Notes are useful for calling out optional information.
Tip
Use tips to provide context or a best practice.
Important
Important hints are for drawing extra attention to something.
Warning
Use warning boxes to alert users of things that may cause outages, lose data or are irreversible changes.

Create a hint by using a shortcode in your markdown file:

1{{< hint "note" >}}
2Your box content. This hint box is a note.
3{{< /hint >}}

Use note, tip, important, or warning as the hint value.

Important
The hint shortcode requires opening and closing tags. Unclosed tags causes Hugo to fail.

Images

Save images in the /images directory of the section using the image.

For example, save images related to contributing to the docs in /content/contribute/images.

The docs support standard Markdown image syntax but using the img shortcode is strongly recommended.

Images using the shortcode are automatically converted to webp image format, compressed and use responsive image sizing.

Note
The img shortcode doesn’t support .SVG files.

The shortcode supports the following options:

  • src - Required. The location of the image file, relative to /content.
  • alt - Required. The image alt text for screen readers.
  • align - Optional. Change the image alignment on the page with align=center or align=right. By default images align left.
  • size - Optional. Resizes the image. Useful for large images that need downscaling.
  • quality - Optional. A value between 1 and 100. Change the image quality to increase image quality or decrease image file size. The default is quality=75.
  • lightbox - Optional. Set to true to enable an image pop-out at full image size. Useful for high fidelity screenshots.

Resize images

The size can be one of:

  • xtiny - Resizes the image to 150px.
  • tiny - Resizes the image to 320px.
  • small - Resizes the image to 600px.
  • medium - Resizes the image to 1200px.
  • large - Resizes the image to 1800px.

By default the image isn’t resized.

An example of using the img shortcode:

1{{< img src="/concepts/images/WithUpbound.png" alt="Control planes with Upbound"  >}}

Which generates this responsive image (change your browser size to see it change):

Control planes with Upbound

Generate a smaller image with a size smaller than the original.

For example,

1{{< img src="/concepts/images/WithUpbound.png" size="xtiny" alt="Control planes with Upbound"  >}}

Generates this image

Control planes with Upbound

Image pop-outs

Use the lightbox=true option to create a pop-out of an image that’s full sized.

For example, render an xtiny image and click to see the full size.

1{{< img src="/concepts/images/WithUpbound.png" size="xtiny" lightbox="true" alt="Control planes with Upbound"  >}}
Control planes with Upbound

Tables

The docs support extended markdown tables but the styling isn’t optimized.

TitleA ColumnAnother Column
Contentmore contenteven more content
A Rowmore of the rowanother column in the row

Wrap a markdown table in the {{< table >}} shortcode to provide styling.

Important
The table shortcode requires a closing /table tag.
1{{< table >}}
2| Title | A Column | Another Column |
3| ---- | ---- | ---- | 
4| Content | more content | even more content | 
5| A Row | more of the row | another column in the row | 
6{{< /table >}}
TitleA ColumnAnother Column
Contentmore contenteven more content
A Rowmore of the rowanother column in the row

Bootstrap provides styling for the table shortcode. The docs support all Bootstrap table classes passed to the shortcode.

Striped tables

To create a table with striped rows:

1{{< table "table table-striped" >}}
2| Title | A Column | Another Column |
3| ---- | ---- | ---- | 
4| Content | more content | even more content | 
5| A Row | more of the row | another column in the row | 
6{{< /table >}}
TitleA ColumnAnother Column
Contentmore contenteven more content
A Rowmore of the rowanother column in the row

Compact tables

For more compact tables use table table-sm

1{{< table "table table-sm" >}}
2| Title | A Column | Another Column |
3| ---- | ---- | ---- | 
4| Content | more content | even more content | 
5| A Row | more of the row | another column in the row | 
6{{< /table >}}
TitleA ColumnAnother Column
Contentmore contenteven more content
A Rowmore of the rowanother column in the row

Tabs

Use tabs to present information about a single topic with multiple exclusive options. For example, creating a resource via command-line or GUI.

To create a tab set, first create a tabs shortcode and use multiple tab shortcodes inside for each tab.

 1{{< tabs >}}
 2
 3{{< tab "First tab title" >}}
 4An example tab. Place anything inside a tab.
 5{{< /tab >}}
 6
 7{{< tab "Second tab title" >}}
 8A second example tab. 
 9{{< /tab >}}
10
11{{< /tabs >}}

This code block renders the following tabs

An example tab. Place anything inside a tab.
A second example tab.

Both tab and tabs require opening and closing tags. Unclosed tags causes Hugo to fail.