Code Styling Guide

To optimize readability and comprehension Crossplane has developed guidelines for source code used in documentation.

Use fenced code blocks

Use Markdown fenced code blocks with three backticks (```) for all command examples and outputs.

1```
2this is a code block
3```

Only use a single backtick (`) for commands used in a sentence.

For example, the command kubectl apply is inside a sentence.

Use language hints for proper highlighting

Hugo attempts to determine the language and apply proper styling, but it’s not always optimized for readability.

For example, this YAML output isn’t automatically detected.

apiVersion: apiextensions.crossplane.io/v1
kind: CompositeResourceDefinition
metadata:
  name: xpostgresqlinstances.database.example.org

All code blocks must include a language definition on the same line as the backticks.

1```yaml
2apiVersion: apiextensions.crossplane.io/v1
3kind: CompositeResourceDefinition
4metadata:
5  name: xpostgresqlinstances.database.example.org
6```

Find a full list of supported languages in the Chroma documentation.

For example, this uses the shell language hint.

1cat test.yaml
2apiVersion: pkg.crossplane.io/v1
3kind: Provider
4metadata:
5  name: aProvider

Using the yaml language hint provides improved readability.

1cat test.yaml
2apiVersion: pkg.crossplane.io/v1
3kind: Provider
4metadata:
5  name: aProvider

Code line highlighting

Crossplane docs provide two methods of code highlighting: static and dynamic highlighting.

Static line highlighting

Static highlighting is an “always on” highlight of a line in a code box.

1apiVersion: pkg.crossplane.io/v1
2kind: Provider
3metadata:
4  name: aProvider

Apply a {hl_lines=<line number>} to a code fence.

1```yaml {hl_lines=1}
2apiVersion: pkg.crossplane.io/v1
3kind: Provider
4metadata:
5  name: aProvider
6```

To highlight continuous blocks use a range in quotes {hl_lines="1-4"}. For multiple lines, including blocks, create an array of values in square brackets. {hl_lines=[1,2,"4-6"]}.

More information on static highlighting is available in the Hugo syntax highlighting documentation.

Dynamic line highlighting

Dynamic highlighting only highlights a specific line when a read hovers over a specific word outside of the code block. This highlighting style is useful to draw attention to a line of code when explaining a command or argument.

For example hover over the word kind to highlight a line in the YAML file.

1apiVersion: pkg.crossplane.io/v1
2kind: Provider
3metadata:
4  name: aProvider

First, apply the {label=name} to the code fence.

1```yaml {label=example}
2apiVersion: pkg.crossplane.io/v1
3kind: Provider
4metadata:
5  name: aProvider
6```

Next, use the hover shortcode around the word that triggers the highlighting. Provide the matching label name and line number to highlight

1{{< hover label="example" line="2" >}}commmand{{< /hover >}}

Custom code box copy button

Code boxes automatically have a “copy to clipboard” button that copies the entire contents of the code box.

Customize the lines the button copies with a {copy-lines="<start line>-<end line>"} label on the code block.

For example, to copy lines from 2 to 5 inclusive and not copy the code fence in this example:

1```yaml {copy-lines="2-5"}
2apiVersion: pkg.crossplane.io/v1
3kind: Provider
4metadata:
5  name: aProvider
6```

Copying a single line is also supported without using the ending line number. For example to copy only line 3 use {copy-lines="3"}.

Disable the copy button with {copy-lines="none"}.

1```yaml {copy-lines="none"}
2apiVersion: pkg.crossplane.io/v1
3kind: Provider
4metadata:
5  name: aProvider
6```

Combining copying and highlighting in a single comma-separated annotation.

1```yaml {copy-lines="2-5", hl_lines="2-3"}
2apiVersion: pkg.crossplane.io/v1
3kind: Provider
4metadata:
5  name: aProvider
6```

Editable fields

The editCode shortcode makes specific lines or words editable. Editable fields allow readers to put their own inputs as part of a command and copy out the entire modified block.

For example, the following code block allows editing the key and secret fields.

1[default]
2aws_access_key_id = 
3aws_secret_access_key = 

To set a field as editable wrap a standard code block, including language highlighting hints in the {{< editCode >}} shortcode.

Wrap any editable element in dollar sign followed by a at character ($@).

1{{< editCode >}}
2```ini {copy-lines="all"}
3[default]
4aws_access_key_id = $@<aws_access_key>$@
5aws_secret_access_key = $@<aws_secret_key>$@
6```
7{{< /editCode >}}