aboutsummaryrefslogtreecommitdiffhomepage
path: root/content/en/contribute/documentation.md
blob: b0c376839f25a06a8cf908496af6ef2f0da8fe18 (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
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
---
title: Documentation
description: Help us to improve the documentation by identifying issues and suggesting changes.
categories: [contribute]
keywords: [documentation]
menu:
  docs:
    parent: contribute
    weight: 30
weight: 30
toc: true
aliases: [/contribute/docs/]
---

## Introduction

We welcome corrections and improvements to the documentation. Please note that the documentation resides in its own repository, separate from the project repository.

For corrections and improvements to the current documentation, please submit issues and pull requests to the [documentation repository].

For documentation related to a new feature, please include the documentation changes when you submit a pull request to the [project repository].

## Guidelines

### Markdown

Please follow these markdown guidelines:

- Use [ATX] headings, not [setext] headings, levels 2 through 4
- Use [fenced code blocks], not [indented code blocks]
- Use hyphens, not asterisks, with unordered [list items]
- Use the [note shortcode] instead of blockquotes
- Do not mix [raw HTML] within markdown
- Do not use bold text instead of a heading or description term (`dt`)
- Remove consecutive blank lines (maximum of two)
- Remove trailing spaces

### Style

Although we do not strictly adhere to the [Microsoft Writing Style Guide], it is an excellent resource for questions related to style, grammar, and voice.

#### Terminology

Please link to the [glossary of terms] when necessary, and use the terms consistently throughout the documentation. Of special note:

- The term "front matter" is two words unless you are referring to the configuration key
- Use the word "map" instead of "dictionary"
- Use the word "flag" instead of "option" when referring to a command line flag

#### Page titles and headings

Please follow these guidelines for page titles and headings:

- Use sentence-style capitalization
- Avoid markdown in headings and page titles
- Shorter is better

#### Use active voice with present tense

In software documentation, passive voice is unavoidable in some cases. Please use active voice when possible.

No → With Hugo you can build a static site.\
Yes → Build a static site with Hugo.

No → This will cause Hugo to generate HTML files in the public directory.\
Yes → Hugo generates HTML files in the public directory.

#### Use second person instead of third person

No → Users should exercise caution when deleting files.\
Better → You must be cautious when deleting files.\
Best → Be cautious when deleting files.

#### Avoid adverbs when possible

No → Hugo is extremely fast.\
Yes → Hugo is fast.

{{% note %}}
"It's an adverb, Sam. It's a lazy tool of a weak mind." (Outbreak, 1995).
{{% /note %}}

#### Miscellaneous

Other guidelines to consider:

- Do not place list items directly under a heading; include an introductory sentence or phrase before the list.
- Avoid use of **bold** text. Use the [note shortcode] to draw attention to important content.
- Do not place description terms (`dt`) within backticks unless required for syntactic clarity.
- Do not use Hugo's `ref` or `relref` shortcodes. We use a link render hook to resolve and validate link destinations, including fragments.
- Shorter is better. If there is more than one way to do something, describe the current best practice. For example, avoid phrases such as "you can also do..." and "in older versions you had to..."
- When including code samples, use short snippets that demonstrate the concept.
- The Hugo user community is global; use  [basic english](https://simple.wikipedia.org/wiki/Basic_English) when possible.

#### Level 6 markdown headings

Level 6 markdown headings are styled as `dt` elements. This was implemented to support a [glossary] with linkable terms.

[glossary]: /getting-started/glossary

## Code examples

Indent code by two spaces. With examples of template code, include a space after opening action delimiters, and include a space before closing action delimiters.

### Fenced code blocks

Always include the language code 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 }}
```

### Shortcode calls

Use this syntax to include shortcodes calls within your code examples:

```text
{{</*/* foo */*/>}}
{{%/*/* foo */*/%}}
```

Rendered:

```text
{{</* foo */>}}
{{%/* foo */%}}
```

### Site configuration

Use the [code-toggle shortcode] to include site configuration examples:

```text
{{</* code-toggle file=hugo */>}}
baseURL = 'https://example.org/'
languageCode = 'en-US'
title = 'My Site'
{{</* /code-toggle */>}}
```

Rendered:

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

### Front matter

Use the [code-toggle shortcode] to include front matter examples:

```text
{{</* code-toggle file=content/posts/my-first-post.md fm=true */>}}
title = 'My first post'
date = 2023-11-09T12:56:07-08:00
draft = false
{{</* /code-toggle */>}}
```

Rendered:

{{< code-toggle file=content/posts/my-first-post.md fm=true >}}
title = 'My first post'
date = 2023-11-09T12:56:07-08:00
draft = false
{{< /code-toggle >}}

### Other code examples

Use the [code shortcode] for other code examples that require a file name:

```text
{{</* code file=layouts/_default/single.html */>}}
{{ range .Site.RegularPages }}
  <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
{{ end }}
{{</* /code */>}}
```

Rendered:

{{< code file=layouts/_default/single.html >}}
{{ range .Site.RegularPages }}
  <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
{{ end }}
{{< /code >}}

## Shortcodes

These shortcodes are commonly used throughout the documentation. Other shortcodes are available for specialized use.

### deprecated-in

Use the “deprecated-in” shortcode to indicate that a feature is deprecated:

```text
{{%/* deprecated-in 0.120.0 */%}}
Use [`hugo.IsServer`] instead.

[`hugo.IsServer`]: /functions/hugo/isserver
{{%/* /deprecated-in */%}}
```

Rendered:

{{% deprecated-in 0.120.0 %}}
Use [`hugo.IsServer`] instead.

[`hugo.IsServer`]: /functions/hugo/isserver
{{% /deprecated-in %}}

### code

Use the "code" shortcode for other code examples that require a file name. See the [code examples] above. This shortcode takes these arguments:

copy
: (`bool`) Whether to display a copy-to-clipboard button. Default is `false`.

file
: (`string`) The file name to display.

lang
: (`string`) The code language. If you do not provide a `lang` argument, the code language is determined by the file extension. If the file extension is "html", sets the code language to `go-html-template`. Default is `text`.

### code-toggle

Use the "code-toggle" shortcode to display examples of site configuration, front matter, or data files. See the [code examples] above. This shortcode takes these arguments:

copy
: (`bool`) Whether to display a copy-to-clipboard button. Default is `false`.

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

fm
: (`bool`) Whether the example is front matter. Default is `false`.

### new-in

Use the "new-in" shortcode to indicate a new feature:

```text
{{</* new-in 0.120.0 */>}}
```

Rendered:

{{< new-in 0.120.0 >}}

### note

Use the "note" shortcode with `{{%/* */%}}` delimiters to call attention to important content:

```text
{{%/* note */%}}
Use the [`math.Mod`] function to control...

[`math.Mod`]: /functions/math/mod/
{{%/* /note */%}}
```

Rendered:

{{% note %}}
Use the [`math.Mod`] function to control...

[`math.Mod`]: /functions/math/mod/
{{% /note %}}

## New features

Use the "new-in" shortcode to indicate a new feature:

{{< code file=content/something/foo.md lang=text >}}
{{</* new-in 0.120.0 */>}}
{{< /code >}}

The "new in" label will be hidden if the specified version is older than a predefined threshold, based on differences in major and minor versions. See&nbsp;[details](https://github.com/gohugoio/hugoDocs/blob/master/layouts/shortcodes/new-in.html).

## Deprecated features

Use the "deprecated-in" shortcode to indicate that a feature is deprecated:

{{< code file=content/something/foo.md >}}
{{%/* deprecated-in 0.120.0 */%}}
Use [`hugo.IsServer`] instead.

[`hugo.IsServer`]: /functions/hugo/isserver
{{%/* /deprecated-in */%}}
{{< /code >}}

When deprecating a function or method, add this to front matter:

{{< code-toggle file=content/something/foo.md fm=true >}}
expiryDate: 2024-10-30
{{< /code-toggle >}}

Set the `expiryDate` to one year from the date of deprecation, and add a brief front matter comment to explain the setting.

## GitHub workflow

{{% note %}}
This section assumes that you have a working knowledge of Git and GitHub, and are comfortable working on the command line.
{{% /note %}}

Use this workflow to create and submit pull requests.

Step 1
: Fork the [documentation repository].

Step 2
: Clone your fork.

Step 3
: Create a new branch with a descriptive name that includes the corresponding issue number, if any:

```sh
git checkout -b restructure-foo-page-99999
```

Step 4
: Make changes.

Step 5
: Build the site locally to preview your changes.

Step 6
: Commit your changes with a descriptive commit message:

- Provide a summary on the first line, typically 50 characters or less, followed by a blank line.
- Optionally, provide a detailed description where each line is 80 characters or less, followed by a blank line.
- Optionally, add one or more "Fixes" or "Closes" keywords, each on its own line, referencing the [issues] addressed by this change.

For example:

```sh
git commit -m "Restructure the taxonomy page

This restructures the taxonomy page by splitting topics into logical
sections, each with one or more examples.

Fixes #9999
Closes #9998"
```

Step 7
: Push the new branch to your fork of the documentation repository.

Step 8
: Visit the [documentation repository] and create a pull request (PR).

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

[ATX]: https://spec.commonmark.org/0.30/#atx-headings
[Microsoft Writing Style Guide]: https://learn.microsoft.com/en-us/style-guide/welcome/
[basic english]: https://simple.wikipedia.org/wiki/Basic_English
[code examples]: #code-examples
[code shortcode]: #code
[code-toggle shortcode]: #code-toggle
[documentation repository]: https://github.com/gohugoio/hugoDocs/
[fenced code blocks]: https://spec.commonmark.org/0.30/#fenced-code-blocks
[glossary of terms]: /getting-started/glossary/
[indented code blocks]: https://spec.commonmark.org/0.30/#indented-code-blocks
[issues]: https://github.com/gohugoio/hugoDocs/issues
[list items]: https://spec.commonmark.org/0.30/#list-items
[note shortcode]: #note
[project repository]: https://github.com/gohugoio/hugo
[raw HTML]: https://spec.commonmark.org/0.30/#raw-html
[setext]: https://spec.commonmark.org/0.30/#setext-heading