Additional Styling Features

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

Markdown

Crossplane documentation uses Hugo to render Markdown to HTML. Hugo supports Commonmark and GitHub Flavored Markdown through the Goldmark parser.

The docs support standard Markdown for images, links and tables, Crossplane recommend using the custom shortcodes to provide a better experience for readers.

• Images
• Links
• Tables

Hide long outputs

Some outputs may be verbose or only 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 >}}

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. Crossplane 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.

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

Images

All images are in /content/media.
Crossplane supports 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 requires a src, an alt text and an optional size.

The src is relative to /content.

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="/media/banner.png" alt="Crossplane Popsicle Truck" size="small" >}}

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

Links

Crossplane docs support standard Markdown links but Crossplane prefers link shortcodes for links between docs pages. Using shortcodes prevents incorrect link creation and notifies which links to change after moving a page.

Between docs pages

For links between pages use a standard Markdown link in the form:

[Link text](link)

Crossplane recommends using the Hugo ref shortcode with the path of the file relative to /content for the link location.

For example, to link to the master release index page use

1[master branch documentation]({{< ref "master/_index.md" >}})

The ref value is of the markdown file, including .md extension.

If the ref value points to a page that doesn’t exist, Hugo fails to start.

Linking to external sites

Minimize linking to external sites. When linking to any page outside of crossplane.io use standard markdown link syntax without using the ref shortcode.

For example,

1[Go to Upbound](http://upbound.io)

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

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.

API documentation

The API documentation is auto generated from the Crossplane YAML files from the cluster/crds directory.

Place any updated files in the /content/<version>/api/yaml folder to update or generate new API documentation.

The logic for parsing the YAML is in /themes/geekboot/layouts/partials/crds.html.