Formatting conventions

Tekton documentation uses Markdown to format the content. See the CommonMark tutorial to learn the basics.

Markdown formatting conventions:

• Lists

  • Capitalize the first word for each item.
  • Don’t put a period at the end of each item in lists containing only nouns or single-word items.
  • Use sentence punctuation in any other case.

• Code Format

  • Use code formatting when referencing API objects, commands, files and directories.

  • Use angle brackets for placeholders such as variables. For example:

    kubectl apply -f <pipeline-file>
    

• Markdown files

  • Hard-wrap the file lines so they are not longer than 80 characters.
  • Use reference-style links if the URL is too long. There’s no specific URL length, use your best judgment to keep markdown files readable.

Embed code samples

You can import code from external files. To do this, use the readfile shortcode with the code and lang options. For example, the following code embeds the file samples/task.yaml:

{{< readfile file="samples/task.yaml" code="true" lang="yaml" >}}

This is rendered as:

apiVersion: tekton.dev/v1beta1
kind: Task
metadata:
  name: hello
spec:
  steps:
    - name: echo
      image: alpine
      script: |
        #!/bin/sh
        echo "Hello World"        

You can also embed code samples in tabs using the tabpane shortcode. For example, the following code embeds samples/pipeline1.yaml and samples/pipeline2.yaml in different tabs:

{{< tabs >}}
{{< tab "v1beta1" >}}
{{< readfile file="samples/pipeline1.yaml" code="true" lang="yaml" >}}
{{< /tab >}}

{{< tab "v1" >}}
{{< readfile file="samples/pipeline2.yaml" code="true" lang="yaml" >}}
{{< /tab >}}
{{< /tabs >}}

Rendered as:

• v1beta1
• v1

apiVersion: tekton.dev/v1beta1
kind: TaskRun
spec:
  taskRef:
    name: example-task
    bundle: python:3-alpine

apiVersion: tekton.dev/v1
kind: TaskRun
spec:
  taskRef:
    resolver: bundles
    params:
    - name: bundle
      value: python:3-alpine
    - name: name
      value: taskName
    - name: kind
      value: Task