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.
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 >}}
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.
Create a hint by using a shortcode in your markdown file:
Use note
, tip
, important
, or warning
as the hint
value.
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.
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 withalign=center
oralign=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 isquality=75
.lightbox
- Optional. Set totrue
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.
Title | A Column | Another Column |
---|---|---|
Content | more content | even more content |
A Row | more of the row | another column in the row |
Wrap a markdown table in the {{< table >}}
shortcode to provide styling.
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 >}}
Title | A Column | Another Column |
---|---|---|
Content | more content | even more content |
A Row | more of the row | another 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 >}}
Title | A Column | Another Column |
---|---|---|
Content | more content | even more content |
A Row | more of the row | another 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 >}}
Title | A Column | Another Column |
---|---|---|
Content | more content | even more content |
A Row | more of the row | another 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
Both tab
and tabs
require opening and closing tags. Unclosed tags causes
Hugo to fail.