Style Guide

In cases that aren't covered by the official Chainguard Style guide, Chainguard's Documentation team follows the Google developer documentation style guide in our written resources.

There are, however, a number of exceptions where we've elected to deviate from Google's style guide. Most of these cases relate to how we render code blocks in our documentation, and these are outlined in the following sections. The other pages in this wiki highlight other exceptions, as well as specific instructions and policies relating to the Chainguard Academy platform.

Code snippets in written resources

Our documentation involves many code examples throughout learning resources. While we may need to make some assumptions of readers’ knowledge at times, it is important to explain code relevant to the tasks within a given tutorial as much as possible. We do not want to encourage readers to run code that they do not understand well.

We prefer code that we expect readers to execute to be written in blocks so that it is readable. Code should be introduced before the block, and summarized after. Ideally, executed code will have a corresponding output.

For example, if we were to explain the “Hello, World!” program in Python, we may do so in a way similar to the following:

We will be creating a small “Hello, World!” program in Python. Here, we will be using the `print()` function to output a string that we pass onto our screen. We’ll be passing the string `'Hello, World!'`, which we can tell is a string by the single quotes on either side of it. If you prefer, in Python you can use double quotes (`"`) instead.

Type the following in your Python interpreter:

```sh
print('Hello, World!')
```

Once you press `ENTER` to run the program, you’ll receive the following output:

```
Hello, World!
```

At this point, the program was executed and you received the output expected from the `print()` statement. You can continue to practice by passing other strings to the function.

In this sample, the print() function is briefly explained as well as the concept of the string data type. It presents the full code snippet that the writer expects the reader to run, and also provides the expected output so that the reader can ensure that they executed the code correctly. Finally, there is a concluding sentence that explains what has happened and what the reader may like to do next given their new knowledge of this command.

Note that you should never end a section of a tutorial with a code block. There should be introductory and concluding lines in each section to ensure that the reader knows what to expect and understands whether or not they have achieved relevant goals

Additionally, before publishing or submitting a draft for review, always run through each command within the tutorial in order to ensure that everything works as written

Code Blocks and Labels

The site uses Hugo's Goldmark markdown parser with custom rendering for code blocks. Code blocks support syntax highlighting and optional labels.

Basic Syntax

Standard markdown fenced code blocks with language specification:

```python
print("This code block's label will render as 'Python' with syntax highlighting for Python.")
```

You can also leave code blocks unlabeled:

```
This code block will not render with a label.
```

Code Block Attributes

Code blocks support two optional attributes:

Title Attribute - Displays a label above the code block (e.g., filename or descriptor):

```python {title="hello.py"}
print("Hello, World!")
```

Caption Attribute - Displays explanatory text below the code block:

```yaml {caption="Example configuration for production environments"}
apiVersion: v1
kind: Service
```

Language Label Normalization

The site automatically normalizes language labels for consistent display:

• Shell variants (bash, sh, shell) → display as "Shell"
  • This is preferred to labels like Bash, as Shell is more generic and therefore more broadly applicable.
• YAML variants (yaml, yml) → display as "YAML"
• SQL variants (sql, mysql, postgresql, mariadb, postgres) → display as "SQL"
• Other languages → Capitalized (e.g., python → "Python", json → "JSON")

Automatic Features

Code blocks automatically include:

• Copy button - Appears in the top-right corner with tooltip
• Language indicator - Shows normalized language name
• Expand/collapse - Automatically added for code blocks exceeding 25 lines
• Syntax highlighting - Uses Dracula theme with Highlight.js

Accessibility

Code blocks are rendered with semantic HTML including:

• aria-labelledby attributes linking titles to code blocks
• Unique IDs generated from title attributes
• data-language and data-lang attributes for programmatic access

Supported Languages

Syntax highlighting is available for: JavaScript, JSON, Bash, Shell, TOML, INI, YAML, Markdown, PHP, Python, and Go.

Creating and editing files

We prefer our documentation to be declarative, meaning that readers can follow a given procedure or instruction by copying and pasting the given commands and keeping interaction with the command line to a minimum.

To maintain this declarative approach when a piece of technical content requires readers to create a new file, we default to using the cat command to write text to a file as in this example:

cat > sample-policy.yaml <<EOF
apiVersion: policy.sigstore.dev/v1beta1
kind: ClusterImagePolicy
metadata:
 name: sample-policy
spec:
 images:
 - glob: "ghcr.io/chainguard-dev/*/*"
 - glob: "ghcr.io/chainguard-dev/*"
 - glob: "index.docker.io/*"
 - glob: "index.docker.io/*/*"
 - glob: "cgr.dev/chainguard/**"
 authorities:
 - keyless:
     url: https://fulcio.sigstore.dev
     identities:
       - issuer: "*"
         subject: "*"
EOF

In the first line of this example, the cat command redirects all of the remaining lines into a file named sample-policy.yaml until the content reaches the string EOF. Using this approach instead of manually creating a file with a text editor like vim or nano can help our readers integrate Chainguard’s products with their existing automation systems.

With that said, if a procedure requires you to use a text editor to change an existing file, we default to using nano in examples due to its wide install base and beginner-friendly interface.

Edit the `sample-policy.yaml` file with your preferred text editor. This example uses `nano`.

```sh
nano sample-policy.yaml
```

After making your changes, save and close the file. If you used `nano` to edit the file, do so by pressing `CTRL + O` and then `CTRL + X`. 

Notice that this example doesn’t tell the reader to use nano directly. Instead, it presents the text editor as a valid option. It also provides clear instructions for how to save and close a file after editing it with nano, which is crucial information for readers who aren’t already familiar with the tool.

Placeholder values

Google's Style Guide has detailed instructions on how to format placeholder values in code examples. However, Chainguard Academy doesn't currently have a reliable means of adding the same variable highlighting that Google describes. For this reason, we have our own ways of representing placeholder values.

The default way to represent placeholder values is to precede the placeholder with a dollar sign and capitalize the entire placeholder. For example:

```shell
chainctl images ls -o table --parent $ORGANIZATION
```

This treats the placeholder as though it is an environment variable and, if they choose to do so, customers can add the appropriate environment variable and follow along with our docs by copying and pasting commands directly.

However, there are cases where a resource instructs readers to actually create environment variables to follow along. Using the environment variable-style placeholders in such cases can get confusing, so we also allow for placeholders to be represented by putting them between < and > symbles, like so:

```shell
chainctl images ls -o table --parent <organization>
```

Other important style notes

• Never use H1 headings. The largest heading that should appear on an Academy resource is an H2.