blob: b1fed4cb275f1bed7adce078365d635c7558e3db (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
|
---
title: Contribute to the Hugo Docs
linktitle: Documentation
description: Documentation is an integral part of any open source project. The Hugo documentation is as much a work in progress as the source it attempts to cover.
categories: [contribute]
keywords: [docs,documentation,community, contribute]
menu:
docs:
parent: contribute
weight: 20
toc: true
weight: 20
aliases: [/contribute/docs/]
---
## GitHub workflow
Step 1
: Fork the [documentation repository].
Step 2
: Clone your fork.
Step 3
: Create a new branch with a descriptive name.
```bash
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].
```bash
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).
[documentation repository]: https://github.com/gohugoio/hugoDocs/
[issues]: https://github.com/gohugoio/hugoDocs/issues
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
{{% note %}}
Use this syntax to include shortcodes calls within your code samples:
`{{</*/* foo */*/>}}`\
`{{%/*/* foo */*/%}}`
{{% /note %}}
### Fenced code blocks
Include the language when using a fenced code block.
````text
```go-html-template
{{ if eq $foo "bar" }}
{{ print "foo is bar" }}
{{ end }}
```
````
Rendered:
```go-html-template
{{ 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`.
````text
{{</* code file="layouts/_default_/single.html" */>}}
{{ if eq $foo "bar" }}
{{ print "foo is bar" }}
{{ end }}
{{</* /code */>}}
````
Rendered:
{{< code file="layouts/_default_/single.html" >}}
{{ if eq $foo "bar" }}
{{ print "foo is bar" }}
{{ end }}
{{< /code >}}
### 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
```text
{{</* code-toggle file="config" */>}}
baseURL = 'https://example.org'
languageCode = 'en-US'
title = "Example Site"
{{</* /code-toggle */>}}
```
Rendered:
{{< code-toggle file="config" >}}
baseURL = 'https://example.org'
languageCode = 'en-US'
title = "Example Site"
{{< /code-toggle >}}
#### Front matter example
```text
{{</* code-toggle file="content/about.md" fm=true */>}}
title = "About"
date = 2023-04-02T12:47:24-07:00
draft = false
{{</* /code-toggle */>}}
```
Rendered:
{{< code-toggle file="content/about.md" fm=true >}}
title = "About"
date = 2023-04-02T12:47:24-07:00
draft = false
{{< /code-toggle >}}
## Admonitions
Use the `note` shortcode to draw attention to content. Use the `{{%/* */%}}` notation when calling this shortcode.
```text
{{%/* note */%}}
This is **bold** text.
{{%/* /note */%}}
```
{{% note %}}
This is **bold** text.
{{% /note %}}
|
