Additional Styling Features
The following is a list of Crossplane documentation customizations that expand traditional Markdown. Most of these are custom Hugo Shortcodes.
#documentation
channel of the
Crossplane Slack.Markdown
Crossplane documentation uses Hugo to render Markdown to HTML. Hugo supports Commonmark and GitHub Flavored Markdown through the Goldmark parser.
GFM
are extensions to the
standard Markdown language.The docs support standard Markdown for images, links and tables, Crossplane recommend using the custom shortcodes to provide a better experience for readers.
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:
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.
img
shortcode doesn’t support .svg
files.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 Crossplane](http://crossplane.io)
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-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 |
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.
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
.