Contribute to documentation

GitHub workflow

Step 1

Fork the documentation repository.

Step 2

Clone your fork.

Step 3

Create a new branch with a descriptive name.

git checkout -b fix/typos-site-variables

Step 4

Make changes.

Step 5

Commit your changes with a descriptive commit message, typically 50 characters or less. Included the “Closes” keyword if your change addresses one or more open issues.

git commit -m "Fix typos on site variables page

Closes #1234
Closes #5678"

Step 5

Push the new branch to your fork of the documentation repository.

Step 6

Visit the documentation repository and create a pull request (PR).

Step 7

A project maintainer will review your PR, and may request changes. You may delete your branch after the maintainer merges your PR.

Including sample code

Fenced code blocks

Include the language when using a fenced code block.

```go-html-template
{{ if eq $foo "bar" }}
  {{ print "foo is bar" }}
{{ end }}
```

Rendered:

{{ if eq $foo "bar" }}
  {{ print "foo is bar" }}
{{ end }}

The code shortcode

Use the code shortcode to include the file name and a copy-to-clipboard button. This shortcode accepts these optional parameters:

copy

(bool) If true, displays a copy-to-clipboard button. Default is true.

file

(string) The file name to display. If you do not provide a lang parameter, the file extension determines the code language.

lang

(string) The code language. Default is text.

{{< code file="layouts/_default_/single.html" >}}
{{ if eq $foo "bar" }}
  {{ print "foo is bar" }}
{{ end }}
{{< /code >}}

Rendered:

{{ if eq $foo "bar" }}
  {{ print "foo is bar" }}
{{ end }}

The code-toggle shortcode

Use the code-toggle shortcode to display examples of site configuration, front matter, or data files. This shortcode accepts these optional parameters:

copy

(bool) If true, displays a copy-to-clipboard button. Default is true.

file

(string) The file name to display. Omit the file extension for site configuration and data file examples.

fm

(bool) If true, displays the code as front matter. Default is false.

Site configuration example

{{< code-toggle file="hugo" >}}
baseURL = 'https://example.org'
languageCode = 'en-US'
title = "Example Site"
{{< /code-toggle >}}

Rendered:

baseURL: https://example.org
languageCode: en-US
title: Example Site

baseURL = 'https://example.org'
languageCode = 'en-US'
title = 'Example Site'

{
   "baseURL": "https://example.org",
   "languageCode": "en-US",
   "title": "Example Site"
}

Front matter example

{{< code-toggle file="content/about.md" fm=true >}}
title = "About"
date = 2023-04-02T12:47:24-07:00
draft = false
{{< /code-toggle >}}

Rendered:

---
date: 2023-04-02T12:47:24-07:00
draft: false
title: About
---

+++
date = 2023-04-02T12:47:24-07:00
draft = false
title = 'About'
+++

{
   "date": "2023-04-02T12:47:24-07:00",
   "draft": false,
   "title": "About"
}

Admonitions

Use the note shortcode to draw attention to content. Use the {{% %}} notation when calling this shortcode.

{{% note %}}
This is **bold** text.
{{% /note %}}