docs/content/contribute/features.md

title	weight	description
Additional Styling Features	60	Add style and visuals to the docs

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

{{< hint "note" >}} If you're having trouble with the Hugo shortcodes, ask for help in the #documentation channel of the Crossplane Slack. {{< /hint >}}

Markdown

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

{{< hint "note" >}} Commonmark and GFM are extensions to the standard Markdown language. {{< /hint >}}

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

• [Images]({{< ref "#images">}})
• [Links]({{< ref "#links">}})
• [Tables]({{< ref "#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.

{{<expand "A large XRD" >}}

apiVersion: apiextensions.crossplane.io/v1
kind: CompositeResourceDefinition
metadata:
  name: xpostgresqlinstances.database.example.org
spec:
  group: database.example.org
  names:
    kind: XPostgreSQLInstance
    plural: xpostgresqlinstances
  claimNames:
    kind: PostgreSQLInstance
    plural: postgresqlinstances
  versions:
  - name: v1alpha1
    served: true
    referenceable: true
    schema:
      openAPIV3Schema:
        type: object
        properties:
          spec:
            type: object
            properties:
              parameters:
                type: object
                properties:
                  storageGB:
                    type: integer
                required:
                - storageGB
            required:
            - parameters

{{< /expand >}}

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

{{</* expand "A large XRD" */>}}
```yaml
apiVersion: apiextensions.crossplane.io/v1
kind: CompositeResourceDefinition
metadata:
  name: xpostgresqlinstances.database.example.org
```
{{</* /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.

{{< hint "note" >}} Notes are useful for calling out optional information. {{< /hint >}}

{{< hint "tip" >}} Use tips to provide context or a best practice. {{< /hint >}}

{{< hint "important" >}} Important hints are for drawing extra attention to something. {{< /hint >}}

{{< hint "warning" >}} Use warning boxes to alert users of things that may cause outages, lose data or are irreversible changes. {{< /hint >}}

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

{{</* hint "note" */>}}
Your box content. This hint box is a note.
{{</* /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.

{{<hint "note">}} The img shortcode doesn't support .svg files. {{< /hint >}}

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:

{{</* 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

[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,

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

{{< hint "important" >}} The table shortcode requires a closing /table tag. {{< /hint >}}

{{</* table */>}}
| Title | A Column | Another Column |
| ---- | ---- | ---- | 
| Content | more content | even more content | 
| A Row | more of the row | another column in the row | 
{{</* /table */>}}

{{< table >}}

Title	A Column	Another Column
Content	more content	even more content
A Row	more of the row	another column in the row
{{< /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:

{{</* table "table table-striped" */>}}
| Title | A Column | Another Column |
| ---- | ---- | ---- | 
| Content | more content | even more content | 
| A Row | more of the row | another column in the row | 
{{</* /table */>}}

{{< table "table table-striped">}}

Title	A Column	Another Column
Content	more content	even more content
A Row	more of the row	another column in the row
{{< /table >}}

Compact tables

For more compact tables use table table-sm

{{</* table "table table-striped" */>}}
| Title | A Column | Another Column |
| ---- | ---- | ---- | 
| Content | more content | even more content | 
| A Row | more of the row | another column in the row | 
{{</* /table */>}}

{{< table "table table-sm">}}

Title	A Column	Another Column
Content	more content	even more content
A Row	more of the row	another column in the row
{{< /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.

{{</* tabs */>}}

{{</* tab "First tab title" */>}}
An example tab. Place anything inside a tab.
{{</* /tab */>}}

{{</* tab "Second tab title" */>}}
A second example tab. 
{{</* /tab */>}}

{{</* /tabs */>}}

This code block renders the following tabs {{< tabs >}}

{{< tab "First tab title" >}} An example tab. Place anything inside a tab. {{< /tab >}}

{{< tab "Second tab title" >}} A second example tab. {{< /tab >}}

{{< /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.