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.
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.
Using the yaml
language hint provides improved readability.
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.
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
to highlight a line in the YAML file.
First, apply the
to the code fence.
label
name.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.
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 ($@
).