To optimize readability and comprehension Upbound 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.

```
this is a code block
```

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.

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

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

For example, this uses the shell language hint.

cat test.yaml
apiVersion: pkg.crossplane.io/v1
kind: Provider
metadata:
  name: aProvider

Using the yaml language hint provides improved readability.

cat test.yaml
apiVersion: pkg.crossplane.io/v1
kind: Provider
metadata:
  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.

apiVersion: pkg.crossplane.io/v1
kind: Provider
metadata:
  name: aProvider

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

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

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

apiVersion: pkg.crossplane.io/v1
kind: Provider
metadata:
  name: aProvider

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

```yaml {label=example}
apiVersion: pkg.crossplane.io/v1
kind: Provider
metadata:
  name: aProvider
```

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

{{< 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:

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

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

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

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

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.

[default]
aws_access_key_id = 
aws_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 a dollar-sign characters followed by an at sign ($@).

{{< editCode >}}
```ini {copy-lines="all"}
[default]
aws_access_key_id = $@<aws_access_key>$@
aws_secret_access_key = $@<aws_secret_key>$@
```
{{< /editCode >}}