Using code samples

Provide code examples to help with clarity, and to help the reader reproduce the subject matter.

CircleCI config should always be tested as valid before adding it to docs.

A reader should be able to copy and paste code snippets, and have them work with only minimal changes.

When using example code snippets, be mindful that people are likely to copy paste them. Always point out if any items or values need to be replaced with the reader’s own data, including whether they should replace the surrounding < > or “ “.

When a reader needs to substitute some of their own data into a snippet or command, use < > , for example, <my-data>.

When adding a code snippet supply the language to ensure correct syntax highlighting, for example:

[source,yaml]

When adding a runnable command, use the console language to ensure correct syntax highlighting, and use a dollar sign for the command, for example:

[source,console]

$ circleci version

When adding a snippet of a CircleCI config, show the full job or workflow, not just the relevant lines.

Where possible add a title to the code snippet, and call out relevant points within the snippet using comments:

version: 2.1

jobs:
  hello-job:
    docker:
      - image: cimg/node:17.2.0 # the primary container, where your job's commands are run
    steps:
      - checkout # check out the code in the project directory
      - run: echo "hello world" # run the `echo` command

workflows:
  my-workflow:
    jobs:
      - hello-job