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.

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

• Images
• Links
• Tables

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 >}}

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.

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.

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.

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):

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

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"  >}}

Tables

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

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

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 >}}

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 >}}

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 >}}

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

• First tab title
• Second tab title

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