diff options
Diffstat (limited to 'content/en/contribute')
| -rw-r--r-- | content/en/contribute/_index.md | 8 | ||||
| -rw-r--r-- | content/en/contribute/development.md | 17 | ||||
| -rw-r--r-- | content/en/contribute/documentation.md | 377 | ||||
| -rw-r--r-- | content/en/contribute/themes.md | 24 |
4 files changed, 314 insertions, 112 deletions
diff --git a/content/en/contribute/_index.md b/content/en/contribute/_index.md index 77a5cdb4d..ca7a18c36 100644 --- a/content/en/contribute/_index.md +++ b/content/en/contribute/_index.md @@ -1,8 +1,8 @@ --- title: Contribute to the Hugo project linkTitle: Overview -description: Contribute to Hugo development and documentation. -categories: [contribute] +description: Contribute to Hugo development, documentation, and themes. +categories: [] keywords: [] menu: docs: @@ -13,6 +13,4 @@ weight: 10 aliases: [/tutorials/how-to-contribute-to-hugo/,/community/contributing/] --- -Hugo relies heavily on the enthusiasm and participation of the open-source community. We need your support in both its development and documentation. - -Hugo's contribution guidelines are [detailed in a `CONTRIBUTING.md`](https://github.com/gohugoio/hugo/blob/master/CONTRIBUTING.md) in the Hugo source repository on GitHub. +Hugo relies heavily on the enthusiasm and participation of the open-source community. We need your support. diff --git a/content/en/contribute/development.md b/content/en/contribute/development.md index 7bc201288..b4de88256 100644 --- a/content/en/contribute/development.md +++ b/content/en/contribute/development.md @@ -1,9 +1,8 @@ --- -title: Contribute to development -linkTitle: Development -description: Hugo relies heavily on contributions from the open source community. +title: Development +description: Contribute to the development of Hugo. categories: [contribute] -keywords: [dev,open source] +keywords: [development] menu: docs: parent: contribute @@ -61,7 +60,7 @@ You can print the `GOPATH` with `echo $GOPATH`. You should see a non-empty strin If you are a macOS user and have [Homebrew](https://brew.sh/) installed on your machine, installing Go is as simple as the following command: -{{< code file="install-go.sh" >}} +{{< code file=install-go.sh >}} brew install go {{< /code >}} @@ -313,7 +312,7 @@ git commit --amend #### Modify multiple commits -{{% warning "Be Careful Modifying Multiple Commits"%}} +{{% note %}} Modifications such as those described in this section can have serious unintended consequences. Skip this section if you're not sure! {{% /note %}} @@ -326,7 +325,7 @@ git rebase --interactive @~6 The `6` at the end of the command represents the number of commits that should be modified. An editor should open and present a list of last six commit messages: ```txt -pick 80d02a1 tpl: Add hasPrefix to the template funcs' "smoke test" +pick 80d02a1 tpl: Add hasPrefix to template function smoke test" pick aaee038 tpl: Sort the smoke tests pick f0dbf2c tpl: Add the other test case for hasPrefix pick 911c35b Add "How to contribute to Hugo" tutorial @@ -339,7 +338,7 @@ In the case above we should merge the last two commits in the commit of this tut All operations are written before the commit message. Replace "pick" with an operation. In this case `squash` or `s` for short: ```txt -pick 80d02a1 tpl: Add hasPrefix to the template funcs' "smoke test" +pick 80d02a1 tpl: Add hasPrefix to template function smoke test" pick aaee038 tpl: Sort the smoke tests pick f0dbf2c tpl: Add the other test case for hasPrefix pick 911c35b Add "How to contribute to Hugo" tutorial @@ -352,7 +351,7 @@ We also want to rewrite the commits message of the third last commit. We forgot You should end up with a similar setup: ```txt -pick 80d02a1 tpl: Add hasPrefix to the template funcs' "smoke test" +pick 80d02a1 tpl: Add hasPrefix to template function smoke test" pick aaee038 tpl: Sort the smoke tests pick f0dbf2c tpl: Add the other test case for hasPrefix reword 911c35b Add "How to contribute to Hugo" tutorial diff --git a/content/en/contribute/documentation.md b/content/en/contribute/documentation.md index 03939f837..14df5cdee 100644 --- a/content/en/contribute/documentation.md +++ b/content/en/contribute/documentation.md @@ -1,70 +1,110 @@ --- -title: Contribute to documentation -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. +title: Documentation +description: Help us to improve the documentation by identifying issues and suggesting changes. categories: [contribute] -keywords: [docs,documentation,community, contribute] +keywords: [documentation] menu: docs: parent: contribute weight: 30 -toc: true weight: 30 +toc: true aliases: [/contribute/docs/] --- -## GitHub workflow +## Introduction -Step 1 -: Fork the [documentation repository]. +We welcome corrections and improvements to the documentation. Please note that the documentation resides in its own repository, separate from the project repository. -Step 2 -: Clone your fork. +For corrections and improvements to the current documentation, please submit issues and pull requests to the [documentation repository]. -Step 3 -: Create a new branch with a descriptive name. +For documentation related to a new feature, please include the documentation changes when you submit a pull request to the [project repository]. -```bash -git checkout -b fix/typos-site-variables -``` +## Guidelines -Step 4 -: Make changes. +### Markdown -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]. +Please follow these markdown guidelines: -```bash -git commit -m "Fix typos on site variables page +- 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 -Closes #1234 -Closes #5678" -``` +### Style -Step 5 -: Push the new branch to your fork of the documentation repository. +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. -Step 6 -: Visit the [documentation repository] and create a pull request (PR). +#### Terminology -[documentation repository]: https://github.com/gohugoio/hugoDocs/ -[issues]: https://github.com/gohugoio/hugoDocs/issues +Please link to the [glossary of terms] when necessary, and use the terms consistently throughout the documentation. Of special note: -Step 7 -: A project maintainer will review your PR, and may request changes. You may delete your branch after the maintainer merges your PR. +- 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 -## Including sample code +#### Page titles and headings -{{% note %}} -Use this syntax to include shortcodes calls within your code samples: +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 -`{{</*/* foo */*/>}}`\ -`{{%/*/* foo */*/%}}` +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 delimeters. + ### Fenced code blocks -Include the language when using a fenced code block. +Always include the language code when using a fenced code block: ````text ```go-html-template @@ -82,95 +122,254 @@ Rendered: {{ end }} ``` -### The code shortcode +### Shortcode calls -Use the `code` shortcode to include the file name and a copy-to-clipboard button. This shortcode accepts these optional parameters: +Use this syntax to include shortcodes calls within your code examples: -copy -: (`bool`) If `true`, displays a copy-to-clipboard button. Default is `true`. +```text +{{</*/* foo */*/>}} +{{%/*/* foo */*/%}} +``` -file -: (`string`) The file name to display. If you do not provide a `lang` parameter, the file extension determines the code language. +Rendered: -lang -: (`string`) The code language. Default is `text`. +```text +{{</* foo */>}} +{{%/* foo */%}} +``` -````text -{{</* code file="layouts/_default_/single.html" */>}} -{{ if eq $foo "bar" }} - {{ print "foo is bar" }} +### 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" >}} -{{ if eq $foo "bar" }} - {{ print "foo is bar" }} +{{< code file=layouts/_default/single.html >}} +{{ range .Site.RegularPages }} + <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> {{ end }} {{< /code >}} -### The code-toggle shortcode +## 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. This shortcode accepts these optional parameters: +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`) If `true`, displays a copy-to-clipboard button. Default is `true`. +: (`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 and data file examples. +: (`string`) The file name to display. Omit the file extension for site configuration examples. fm -: (`bool`) If `true`, displays the code as front matter. Default is `false`. +: (`bool`) Whether the example is front matter. Default is `false`. + +### new-in -#### Site configuration example +Use the "new-in" shortcode to indicate a new feature: ```text -{{</* code-toggle file="hugo" */>}} -baseURL = 'https://example.org' -languageCode = 'en-US' -title = "Example Site" -{{</* /code-toggle */>}} +{{</* new-in 0.120.0 */>}} ``` Rendered: -{{< code-toggle file="hugo" >}} -baseURL = 'https://example.org' -languageCode = 'en-US' -title = "Example Site" -{{< /code-toggle >}} +{{< new-in 0.120.0 >}} -#### Front matter example +### note + +Use the "note" shortcode with `{{%/* */%}}` delimiters to call attention to important content: ```text -{{</* code-toggle file="content/about.md" fm=true */>}} -title = "About" -date = 2023-04-02T12:47:24-07:00 -draft = false -{{</* /code-toggle */>}} +{{%/* note */%}} +Use the [`math.Mod`] function to control... + +[`math.Mod`]: /functions/math/mod/ +{{%/* /code */%}} ``` Rendered: -{{< code-toggle file="content/about.md" fm=true >}} -title = "About" -date = 2023-04-02T12:47:24-07:00 -draft = false +{{% note %}} +Use the [`math.Mod`] function to control... + +[`math.Mod`]: /functions/math/mod/ +{{% /code %}} + +## 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 [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 +_build: + list: never {{< /code-toggle >}} -## Admonitions +Set the `expiryDate` to one year from the date of deprecation, and add a brief front matter comment to explain the settings. -Use the `note` shortcode to draw attention to content. Use the `{{%/* */%}}` notation when calling this shortcode. +Users will be able to search for the page, but the page will not appear in any list views, including section menus. -```text -{{%/* note */%}} -This is **bold** text. -{{%/* /note */%}} -``` +## GitHub workflow {{% note %}} -This is **bold** text. +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. + +```sh +git checkout -b fix/typos-shortcode-templates +``` + +Step 4 +: Make changes. + +Step 5 +: Commit your changes with a descriptive commit message, typically 50 characters or less. Add the "Closes" keyword if your change addresses one or more open [issues]. + +```sh +git commit -m "Fix typos on the shortcode templates 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. + +[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 diff --git a/content/en/contribute/themes.md b/content/en/contribute/themes.md index 0371f7f8c..34056c35a 100644 --- a/content/en/contribute/themes.md +++ b/content/en/contribute/themes.md @@ -1,24 +1,30 @@ --- -title: Add your hugo theme to the showcase -linkTitle: Themes -description: If you've built a Hugo theme and want to contribute back to the Hugo Community, share it with us. +title: Themes +description: If you've built a Hugo theme and want to contribute back to the Hugo Community, please share it with us. categories: [contribute] -keywords: [contribute,themes,design] +keywords: [themes] menu: docs: parent: contribute weight: 40 weight: 40 aliases: [/contribute/theme/] -toc: true --- -A collection of all themes created by the Hugo community, including screenshots and demos, can be found at [themes.gohugo.io]. Every theme in this list will automatically be added to the theme site. +Visit [themes.gohugo.io] to browse a collection of themes created by the Hugo community. -Another great site for Hugo themes is [jamstackthemes.dev/](https://jamstackthemes.dev/ssg/hugo/). +To submit your theme: -### Add your theme to the repository +1. Read the [submission guidelines] +2. Open a pull request in the [themes repository] -In order to add your Hugo theme to [themes.gohugo.io] please [open a pull request in the theme repository](https://github.com/gohugoio/hugoThemesSiteBuilder). **Please make sure that you've read the theme submission guidelines in the [README](https://github.com/gohugoio/hugoThemesSiteBuilder/blob/main/README.md#hugo-themes) of the hugoThemesSiteBuilder repository.** +Other useful theme directories: +- [jamstack.club] +- [jamstackthemes.dev] + +[jamstack.club]: https://jamstack.club/#ssg=hugo +[jamstackthemes.dev]: https://jamstackthemes.dev/ssg/hugo +[submission guidelines]: https://github.com/gohugoio/hugoThemesSiteBuilder/tree/main#readme +[themes repository]: https://github.com/gohugoio/hugoThemesSiteBuilder [themes.gohugo.io]: https://themes.gohugo.io/ |