diff options
Diffstat (limited to 'docs/content/en/contribute/documentation.md')
| -rw-r--r-- | docs/content/en/contribute/documentation.md | 476 |
1 files changed, 262 insertions, 214 deletions
diff --git a/docs/content/en/contribute/documentation.md b/docs/content/en/contribute/documentation.md index 285985b3d..1d185d21d 100644 --- a/docs/content/en/contribute/documentation.md +++ b/docs/content/en/contribute/documentation.md @@ -1,59 +1,46 @@ --- 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 +categories: [] +keywords: [] 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. +We welcome corrections and improvements to the documentation. The documentation lives in a separate repository from the main project. To contribute: -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]. +- For corrections and improvements to existing documentation, submit issues and pull requests to the [documentation repository]. +- For documentation of new features, include the documentation changes in your pull request to the [project repository]. ## Guidelines ### Style -Please adhere to Google's [developer documentation style guide]. - -[developer documentation style guide]: https://developers.google.com/style +Follow Google's [developer documentation style guide]. ### Markdown -Please follow these guidelines: +Adhere to these Markdown conventions: -- 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 or bold text -- 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 +- Use [ATX] headings (levels 2-4), not [setext] headings. +- Use [fenced code blocks], not [indented code blocks]. +- Use hyphens, not asterisks, for unordered [list items]. +- Use [callouts](#callouts) instead of bold text for emphasis. +- Do not mix [raw HTML] within Markdown. +- Do not use bold text in place of a heading or description term (`dt`). +- Remove consecutive blank lines. +- Remove trailing spaces. ### Glossary -Glossary terms are maintained on individual pages. While not directly accessible to site visitors, these pages act as a central repository for term definitions. - -Definitions must be presented in complete sentences, with the first sentence always introducing the term being defined. To enhance readability and consistency, the first occurrence of the term and any other referenced glossary terms should be italicized. +[Glossary] terms are defined on individual pages, providing a central repository for definitions, though these pages are not directly linked from the site. -To link to a term definition on the glossary page, use this custom link syntax: +Definitions must be complete sentences, with the first sentence defining the term. Italicize the first occurrence of the term and any referenced glossary terms for consistency. -```text -[term](g) -``` +Link to glossary terms using this syntax: `[term](g)` -Lookups are case-insensitive, ignore formatting, and support both singular and plural forms. For example, all of these variations will link to the same glossary term: +Term lookups are case-insensitive, ignore formatting, and support singular and plural forms. For example, all of these variations will link to the same glossary term: ```text [global resource](g) @@ -62,7 +49,7 @@ Lookups are case-insensitive, ignore formatting, and support both singular and p [`Global Resources`](g) ``` -To insert a term definition, use the [`glossary-term`] shortcode: +Use the [glossary-term shortcode](#glossary-term) to insert a term definition: ```text {{%/* glossary-term "global resource" */%}} @@ -70,29 +57,38 @@ To insert a term definition, use the [`glossary-term`] shortcode: ### Terminology -Please link to the glossary (see above) when necessary, and use the terms consistently throughout the documentation. Of special note: +Link to the [glossary] as needed and use terms consistently. Pay particular attention to: + +- "front matter" (two words, except when referring to the configuration key) +- "home page" (two words) +- "website" (one word) +- "standalone" (one word, no hyphen) +- "map" (instead of "dictionary") +- "flag" (instead of "option" for command-line flags) +- "client side" (noun), "client-side" (adjective) +- "server side" (noun), "server-side" (adjective) +- "Markdown" (capitalized) +- "open-source" (hyphenated adjective) + +### Titles and headings -- The term "front matter" is two words unless you are referring to the configuration key -- The term "home page" is two words -- The term "website" is one word -- The term "standalone" is one word, not hyphenated -- Use the word "map" instead of "dictionary" -- Use the word "flag" instead of "option" when referring to a command line flag -- Use "client side" as a noun, and "client-side" as an adjective -- Capitalize the word "Markdown" -- Hyphenate the term "open-source" when used an adjective. +- Use sentence-style capitalization. +- Avoid formatted strings. +- Keep them concise. -### Page titles and headings +### Page descriptions -Please follow these guidelines for page titles and headings: +When writing the page `description` use imperative present tense when possible. For example: -- Use sentence-style capitalization -- Avoid formatted strings in headings and page titles -- Shorter is better +{{< code-toggle file=content/en/functions/data/_index.md" fm=true >}} +title: Data functions +linkTitle: data +description: Use these functions to read local or remote data files. +{{< /code-toggle >}} -### Use active voice with present tense +### Writing style -In software documentation, passive voice is unavoidable in some cases. Please use active voice when possible. +Use active voice and present tense wherever possible. No → With Hugo you can build a static site.\ Yes → Build a static site with Hugo. @@ -100,65 +96,124 @@ 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 +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 +Minimize adverbs. 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 %}} - -### Level 6 headings - -Level 6 headings are styled as `dt` elements. This was implemented to support a [glossary] with linkable terms. +> [!note] +> "It's an adverb, Sam. It's a lazy tool of a weak mind." (Outbreak, 1995). ### Function and method descriptions -When adding a page to the [functions] or [methods] section, begin the description with the word "Returns". With functions and methods that return a boolean value, begin the description with the phrase "Reports whether". - -For example: - -- `Returns the URL aliases as defined in front matter.` -- `Reports whether the given page is in the given section.` +Start descriptions in the functions and methods sections with "Returns", of for booelan values, "Reports whether". -[functions]: /functions -[methods]: /methods +### File paths and names -### Directory names, file names, and file paths - -Enclose directory names, file names, and file paths within backticks, with the following exceptions: +Enclose directory names, file names, and file paths in backticks, except when used in: - Page titles - Section headings (h1-h6) - Definition list terms -- The description field in front matter +- The `description` field in front matter ### Miscellaneous -Other guidelines to consider: +Other best practices: + +- Introduce lists with a sentence or phrase, not directly under a heading. +- Avoid bold text; use [callouts](#callouts) for emphasis. +- Do not put description terms (`dt`) in backticks unless syntactically necessary. +- Do not use Hugo's `ref` or `relref` shortcodes. +- Prioritize current best practices over multiple options or historical information. +- Use short, focused code examples. +- Use [basic english] where possible for a global audience. + +## Front matter fields + +This site uses the front matter fields listed in the table below. + +Of the four required fields, only `title` and `description` require data. + +```text +title: The title +description: The description +categories: [] +keywords: [] +``` + +This example demonstrates the minimum required front matter fields. + +If quotation marks are required, prefer single quotes to double quotes when possible. + +Seq|Field|Description|Required +--:|:--|:--|:-- +1|`title`|The page title|:heavy_check_mark:| +2|`linkTitle`|A short version of the page title|| +3|`description`|A complete sentence describing the page|:heavy_check_mark:| +4|`categories`|An array of terms in the categories taxonomy|:heavy_check_mark: [^1]| +5|`keywords`|An array of keywords used to identify related content|:heavy_check_mark: [^1]| +6|`publishDate`|Applicable to news items: the publication date|| +7|`params.altTitle`|An alternate title: used in the "see also" panel if provided|| +8|`params.functions_and_methods.aliases`|Applicable to function and method pages: an array of alias names|| +9|`params.functions_and_methods.returnType`|Applicable to function and method pages: the data type returned|| +10|`params.functions_and_methods.signatures`|Applicable to function and method pages: an array of signatures|| +11|`params.hide_in_this_section`|Whether to hide the "in this section" panel|| +12|`params.minversion`|Applicable to the quick start page: the minimum Hugo version required|| +13|`params.permalink`|Reserved for use by the news content adapter|| +14|`params.reference (used in glossary term)`|Applicable to glossary entries: a URL for additional information|| +15|`params.show_publish_date`|Whether to show the `publishDate` when rendering the page|| +16|`weight`|The page weight|| +17|`aliases`|Previous URLs used to access this page|| +18|`expirydate`|The expiration date|| + +[^1]: The field is required, but its data is not. + +## Related content + +When available, the "See also" sidebar displays related pages using Hugo's [related content] feature, based on front matter keywords. We ensure consistent keyword usage by validating them against `data/keywords.yaml` during the build process. If a keyword is not found, you'll be alerted and must either modify the keyword or update the data file. This validation process helps to refine the related content for better results. + +If the title in the "See also" sidebar is ambiguous or the same as another page, you can define an alternate title in the front matter: + +{{< code-toggle file=hugo >}} +title = "Long descriptive title" +linkTitle = "Short title" +[params] +altTitle = "Whatever you want" +{{< /code-toggle >}} + +Use of the alternate title is limited to the "See also" sidebar. -- 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. +> [!note] +> Think carefully before setting the `altTitle`. Use it only when absolutely necessary. ## 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. +With examples of template code: + +- Indent with two spaces. +- Insert a space after an opening action delimiter. +- Insert a space before a closing action delimiter. +- Do not add white space removal syntax to action delimiters unless required. For example, inline elements like `img` and `a` require whitespace removal on both sides. + +```go-html-template +{{ if eq $foo $bar }} + {{ fmt.Printf "%s is %s" $foo $bar }} +{{ end }} +``` ### Fenced code blocks -Always include the language code when using a fenced code block: +Always specify the language. + +When providing a Mardown example, set the code language to "text" to prevent +erroneous lexing/highlighting of shortcode calls. ````text ```go-html-template @@ -168,29 +223,40 @@ Always include the language code when using a fenced code block: ``` ```` -```go-html-template +To include a filename header and copy-to-clipboard button: + +````text +```go-html-template {file="layouts/partials/foo.html" copy=true} {{ if eq $foo "bar" }} {{ print "foo is bar" }} {{ end }} ``` +```` + +To wrap the code block within an initially-opened `details` element using a non-default summary: + +````text +```go-html-template {details=true open=true summary="layouts/partials/foo.html" copy=true} +{{ if eq $foo "bar" }} + {{ print "foo is bar" }} +{{ end }} +``` +```` ### Shortcode calls -Use this syntax to include shortcodes calls within your code examples: +Use this syntax : +````text ```text {{</*/* foo */*/>}} {{%/*/* foo */*/%}} ``` - -```text -{{</* foo */>}} -{{%/* foo */%}} -``` +```` ### Site configuration -Use the [code-toggle shortcode] to include site configuration examples: +Use the [code-toggle shortcode](#code-toggle) to include site configuration examples: ```text {{</* code-toggle file=hugo */>}} @@ -200,15 +266,9 @@ title = 'My Site' {{</* /code-toggle */>}} ``` -{{< 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: +Use the [code-toggle shortcode](#code-toggle) to include front matter examples: ```text {{</* code-toggle file=content/posts/my-first-post.md fm=true */>}} @@ -218,60 +278,65 @@ draft = false {{</* /code-toggle */>}} ``` -{{< 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 >}} +## Callouts -### Other code examples +To visually emphasize important information, use callouts (admonitions). Callout types are case-insensitive. Effective March 8, 2025, we utilize only three of the five available types. -Use the [code shortcode] for other code examples that require a file name: +- note (272 instances) +- warning (2 instances) +- caution (1 instance) + +Limiting the number of callout types helps us to use them consistently. ```text -{{</* code file=layouts/_default/single.html */>}} -{{ range .Site.RegularPages }} - <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> -{{ end }} -{{</* /code */>}} +> [!note] +> Useful information that users should know, even when skimming content. ``` -{{< code file=layouts/_default/single.html >}} -{{ range .Site.RegularPages }} - <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> -{{ end }} -{{< /code >}} - -## Shortcodes +> [!note] +> Useful information that users should know, even when skimming content. -These shortcodes are commonly used throughout the documentation. Other shortcodes are available for specialized use. +```text +> [!warning] +> Urgent info that needs immediate user attention to avoid problems. +``` -### code +> [!warning] +> Urgent info that needs immediate user attention to avoid problems. -Use the `code` shortcode for other code examples that require a file name. See the [code examples] above. This shortcode takes these arguments: +```text +> [!caution] +> Advises about risks or negative outcomes of certain actions. +``` -copy -: (`bool`) Whether to display a copy-to-clipboard button. Default is `false`. +> [!caution] +> Advises about risks or negative outcomes of certain actions. -file -: (`string`) The file name to display. +```text +> [!tip] +> Helpful advice for doing things better or more easily. +``` -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`. +> [!tip] +> Helpful advice for doing things better or more easily. ```text -{{</* code file=content/something/foo.md lang=text copy=true */>}} -Some code here -{{</* /code */>}} +> [!important] +> Key information users need to know to achieve their goal. ``` -{{< code file=content/something/foo.md lang=text copy=true >}} -Some code here -{{< /code >}} +> [!important] +> Key information users need to know to achieve their goal. + + + +## Shortcodes + +These shortcodes are commonly used throughout the documentation. Other shortcodes are available for specialized use. ### 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: +Use the `code-toggle` shortcode to display examples of site configuration, front matter, or data files. This shortcode takes these arguments: config : (`string`) The section of `site.Data.docs.config` to render. @@ -279,44 +344,38 @@ config copy : (`bool`) Whether to display a copy-to-clipboard button. Default is `false`. +datakey: +: (`string`) The section of `site.Data.docs` to render. + file -: (`string`) The file name to display. Omit the file extension for site configuration examples. Default is `hugo` +: (`string`) The file name to display above the rendered code. Omit the file extension for site configuration examples. fm -: (`bool`) Whether the example is front matter. Default is `false`. +: (`bool`) Whether to render the code as front matter. Default is `false`. skipHeader -: (`bool`) Whether to omit top level key(s) when rendering a section of `site.Data.docs.config`. +: (`bool`) Whether to omit top-level key(s) when rendering a section of `site.Data.docs.config`. ```text -{{</* code-toggle */>}} -title: Example -draft: false +{{</* code-toggle file=hugo copy=true */>}} +baseURL = 'https://example.org/' +languageCode = 'en-US' +title = 'My Site' {{</* /code-toggle */>}} ``` -{{< code-toggle >}} -title: Example -draft: false -{{< /code-toggle >}} - ### deprecated-in Use the `deprecated-in` shortcode to indicate that a feature is deprecated: ```text -{{%/* deprecated-in 0.127.0 */%}} -Use [`hugo.IsServer`] instead. - -[`hugo.IsServer`]: /functions/hugo/isserver/ -{{%/* /deprecated-in */%}} -``` +{{</* deprecated-in 0.144.0 */>}} -{{% deprecated-in 0.127.0 %}} Use [`hugo.IsServer`] instead. [`hugo.IsServer`]: /functions/hugo/isserver/ -{{% /deprecated-in %}} +{{</* /deprecated-in */>}} +``` ### eturl @@ -328,10 +387,6 @@ This is a link to the [embedded alias template]. [embedded alias template]: {{%/* eturl alias */%}} ``` -This is a link to the [embedded alias template]. - -[embedded alias template]: {{% eturl alias %}} - ### glossary-term Use the `glossary-term` shortcode to insert the definition of the given glossary term. @@ -340,14 +395,12 @@ Use the `glossary-term` shortcode to insert the definition of the given glossary {{%/* glossary-term scalar */%}} ``` -{{% glossary-term scalar %}} - ### include Use the `include` shortcode to include content from another page. ```text -{{%/* include "functions/_common/glob-patterns" */%}} +{{%/* include "_common/glob-patterns.md" */%}} ``` ### new-in @@ -355,97 +408,92 @@ Use the `include` shortcode to include content from another page. Use the `new-in` shortcode to indicate a new feature: ```text -{{</* new-in 0.127.0 */>}} +{{</* new-in 0.144.0 /*/>}} ``` -{{< new-in 0.127.0 />}} - -### note - -Use the `note` shortcode with `{{%/* */%}}` delimiters to call attention to important content: +You can also include details: ```text -{{%/* note */%}} -Use the [`math.Mod`] function to control... - -[`math.Mod`]: /functions/math/mod/ -{{%/* /note */%}} +{{</* new-in 0.144.0 */>}} +This is a new feature. +{{</* /new-in */>}} ``` -{{% 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: +Use the [new-in shortcode](#new-in) to indicate a new feature: -{{< code file=content/something/foo.md lang=text >}} -{{</* new-in 0.120.0 */>}} -{{< /code >}} +```text +{{</* new-in 0.144.0 */>}} +``` 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 [details](https://github.com/gohugoio/hugoDocs/blob/master/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/new-in.html). ## Deprecated features -Use the "deprecated-in" shortcode to indicate that a feature is deprecated: +Use the [deprecated-in shorcode](#deprecated-in) shortcode to indicate that a feature is deprecated: -{{< code file=content/something/foo.md >}} -{{%/* deprecated-in 0.120.0 */%}} +```text +{{</* deprecated-in 0.144.0 */>}} Use [`hugo.IsServer`] instead. [`hugo.IsServer`]: /functions/hugo/isserver/ -{{%/* /deprecated-in */%}} -{{< /code >}} +{{</* /deprecated-in */>}} +``` When deprecating a function or method, add something like this to front matter: {{< code-toggle file=content/something/foo.md fm=true >}} -expiryDate: 2024-10-30 # deprecated 2022-10-30 in v0.123.0 +expiryDate: 2027-02-17 # deprecated 2025-02-17 in v0.144.0 {{< /code-toggle >}} Set the `expiryDate` to two years 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 %}} +> [!note] +> This section assumes that you have a working knowledge of Git and GitHub, and are comfortable working on the command line. Use this workflow to create and submit pull requests. -Step 1 -: Fork the [documentation repository]. +### Step 1 + +Fork the [documentation repository]. + +### Step 2 -Step 2 -: Clone your fork. +Clone your fork. -Step 3 -: Create a new branch with a descriptive name that includes the corresponding issue number, if any: +### 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 4 + +Make changes. + +### Step 5 + +Build the site locally to preview your changes. -Step 5 -: Build the site locally to preview your changes. +### Step 6 -Step 6 -: Commit your changes with a descriptive commit message: +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. + - Begin the summary with one of `content`, `theme`, `config`, `all`, or `misc`, followed by a colon, a space, and a brief description of the change beginning with a capital letter + - Use imperative present tense +- Optionally, provide a detailed description where each line is 72 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 +```text +git commit -m "content: Restructure the taxonomy page This restructures the taxonomy page by splitting topics into logical sections, each with one or more examples. @@ -454,29 +502,29 @@ Fixes #9999 Closes #9998" ``` -Step 7 -: Push the new branch to your fork of the documentation repository. +### Step 7 + +Push the new branch to your fork of the documentation repository. + +### Step 8 -Step 8 -: Visit the [documentation repository] and create a pull request (PR). +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. +### 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/ -[`glossary-term`]: #glossary-term [basic english]: https://simple.wikipedia.org/wiki/Basic_English -[code examples]: #code-examples -[code shortcode]: #code -[code-toggle shortcode]: #code-toggle +[basic english]: https://simple.wikipedia.org/wiki/Basic_English +[developer documentation style guide]: https://developers.google.com/style [documentation repository]: https://github.com/gohugoio/hugoDocs/ [fenced code blocks]: https://spec.commonmark.org/0.30/#fenced-code-blocks [glossary]: /quick-reference/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 +[related content]: /content-management/related-content/ [setext]: https://spec.commonmark.org/0.30/#setext-heading |