hugo/content/en/contribute/documentation.md
Bjørn Erik Pedersen 13e64d7276 Squashed 'docs/' changes from 9b494a58c..6b00298bb
6b00298bb Remove outdated "related example"
987f1e1cd Fix dead links (#601)
96287a20a Add config option "summaryLength" (#600)
ced7f2085 Adjust Over showcase
e334a6354 Add new showcase: over
10435b502 Add warning about privacy options only work with internal templates (#525)
48c6b0e4d Minor grammatical fix
684670ebc Add quote
0e9fada52 Improvements to taxonomy template examples
e06c4bf73 Add syntax highlighting; consistent 4-space indentation
c1cb3f081 Remove dead links for custom permalinks
3e3aefd04 Fix 0a671bc3751479e74a0a9d2132736c61d239707c
d65888685 fix file name in 'Add Non-content Entries to a Menu' code toggle (#547)
1a0563857 Add Solus install guide (#590)
8a0d65b0d Update Windows Installation instructions (#564)
c4348636a Fix typo
0a671bc37 Add post to menu example
af14497c6 Add notes for `os.Stat` (Hugo 0.47) (#557)
e49f65bb3 Singular to plural
cb5608dbf Update introduction.md
30b060dff Add variable re-definition example (Hugo v0.48+)
21123967e Minor edits
fac3df043 Refresh the Go Templates introduction
4a9600e92 Updating URL to how-to-guide for hosting hugo site on firebase
bfaa7779c add missing word
c2cb5d09b Tweak 'name: weight' to 'name: date' in example (#582)
5ea938ad6 Remove some Scratch
2708dcd57 Release 0.48
e375d0f05 Merge branch 'temp48'
75e36c160 releaser: Prepare repository for 0.49-DEV
a6102f253 releaser: Add release notes to /docs for release of 0.48
41fc35db4 releaser: Bump versions for release of 0.48
64b9ecc74 Spell out the npm command for installing PostCSS
19e900a17 Improved Related Content doc
fe21600e7 Merge commit '844aef544c19e9d8f529b4f8144e089d0982bb34'
844aef544 Squashed 'themes/gohugoioTheme/' changes from 66249819..68ddff44
069828db8 Update git.md
d881d1433 Make default "related" behavior more explicit
60b9160eb Add docs for displaying 404 page on CloudFront
b72ebc760 Add .gitattributes to /resources
000cf85f4 Make the pros/cons styling consistent for summaries; use desc list
ebf1da97a Add note about outputStyle compressed
e3338ee91 Triple backquote syntax fix
361962a7c Add one more Blogger to Hugo tool for Windows (.NET Framework 4.5) (#540)
066606a21 Fix wrong link about Mmark Syntax Document
faee70757 Added exitwp-for-hugo
6b4108051 Add hugo-wrapper to starter-kits
4695dfba2 Added Utterances as Comments Alternatives.
c7ba9e3e1 Correct typo
beb850d9f Release 0.47.1
1cf417c8a Merge branch 'temp471'
0843bc46c releaser: Prepare repository for 0.48-DEV
8ff5c8b70 releaser: Add release notes to /docs for release of 0.47.1
e2353434d releaser: Bump versions for release of 0.47.1
ffb1300af Update development.md
c22234ea5 netlify: Minify output
5b9191c56 Release 0.47
bfd92cf52 releaser: Prepare repository for 0.48-DEV
ac7acf730 releaser: Add release notes to /docs for release of 0.47
b0096099d releaser: Bump versions for release of 0.47
86a7ae459 docs: Regenerate CLI docs
d2c8b72bc Merge commit 'a95896878f4b4a79448b39ce93a4e0d3258b4a43'
84de7ef59 Merge commit '3a44bf182fed5f34621f450114083a6dd7e88a07'

git-subtree-dir: docs
git-subtree-split: 6b00298bb26b700281df28817b6556e7480cdd1e
2018-09-14 08:34:58 +02:00

12 KiB

title linktitle description date publishdate lastmod categories keywords menu weight sections_weight draft aliases toc
Contribute to the Hugo Docs Documentation Documentation is an integral part of any open source project. The Hugo docs are as much a work in progress as the source it attempts to cover. 2017-02-01 2017-02-01 2017-02-01
contribute
docs
documentation
community
contribute
docs
parent weight
contribute 20
20 20 false
/contribute/docs/
true

Create Your Fork

It's best to make changes to the Hugo docs on your local machine to check for consistent visual styling. Make sure you've created a fork of hugoDocs on GitHub and cloned the repository locally on your machine. For more information, you can see GitHub's documentation on "forking" or follow along with Hugo's development contribution guide.

You can then create a separate branch for your additions. Be sure to choose a descriptive branch name that best fits the type of content. The following is an example of a branch name you might use for adding a new website to the showcase:

git checkout -b jon-doe-showcase-addition

Add New Content

The Hugo docs make heavy use of Hugo's archetypes feature. All content sections in Hugo documentation have an assigned archetype.

Adding new content to the Hugo docs follows the same pattern, regardless of the content section:

hugo new <DOCS-SECTION>/<new-content-lowercase>.md

Add a New Function

Once you have cloned the Hugo repository, you can create a new function via the following command. Keep the file name lowercase.

hugo new functions/newfunction.md

The archetype for functions according to the Hugo docs is as follows:

{{< code file="archetypes/functions.md" >}} {{< readfile file="/archetypes/functions.md">}} {{< /code >}}

New Function Required Fields

Here is a review of the front matter fields automatically generated for you using hugo new functions/*:

title
this will be auto-populated in all lowercase when you use hugo new generator.
linktitle
the function's actual casing (e.g., replaceRE rather than replacere).
description
a brief description used to populate the Functions Quick Reference.
categories
currently auto-populated with 'functions` for future-proofing and portability reasons only; ignore this field.
tags
only if you think it will help end users find other related functions
signature
this is a signature/syntax definition for calling the function (e.g., apply SEQUENCE FUNCTION [PARAM...]).
workson
acceptable values include lists,taxonomies, terms, groups, and files.
hugoversion
the version of Hugo that will ship with this new function.
relatedfuncs
other [templating functions][] you feel are related to your new function to help fellow Hugo users.
{{.Content}}
an extended description of the new function; examples are not only welcomed but encouraged.

In the body of your function, expand the short description used in the front matter. Include as many examples as possible, and leverage the Hugo docs code shortcode. If you are unable to add examples but would like to solicit help from the Hugo community, add needsexample: true to your front matter.

Add Code Blocks

Code blocks are crucial for providing examples of Hugo's new features to end users of the Hugo docs. Whenever possible, create examples that you think Hugo users will be able to implement in their own projects.

Standard Syntax

Across many pages on the Hugo docs, the typical triple-back-tick markdown syntax (```) is used. If you do not want to take the extra time to implement the following code block shortcodes, please use standard GitHub-flavored markdown. The Hugo docs use a version of highlight.js with a specific set of languages.

Your options for languages are xml/html, go/golang, md/markdown/mkd, handlebars, apache, toml, yaml, json, css, asciidoc, ruby, powershell/ps, scss, sh/zsh/bash/git, http/https, and javascript/js.

```
<h1>Hello world!</h1>
```

Code Block Shortcode

The Hugo documentation comes with a very robust shortcode for adding interactive code blocks.

{{% note %}} With the code shortcodes, you must include triple back ticks and a language declaration. This was done by design so that the shortcode wrappers were easily added to legacy documentation and will be that much easier to remove if needed in future versions of the Hugo docs. {{% /note %}}

code

code is the Hugo docs shortcode you'll use most often. code requires has only one named parameter: file. Here is the pattern:

{{%/* code file="smart/file/name/with/path.html" download="download.html" copy="true" */%}}
A whole bunch of coding going on up in here!
{{%/* /code */%}}

The following are the arguments passed into code:

file
the only required argument. file is needed for styling but also plays an important role in helping users create a mental model around Hugo's directory structure. Visually, this will be displayed as text in the top left of the code block.
download
if omitted, this will have no effect on the rendered shortcode. When a value is added to download, it's used as the filename for a downloadable version of the code block.
copy
a copy button is added automatically to all code shortcodes. If you want to keep the filename and styling of code but don't want to encourage readers to copy the code (e.g., a "Do not do" snippet in a tutorial), use copy="false".

Example code Input

This example HTML code block tells Hugo users the following:

  1. This file could live in layouts/_default, as demonstrated by layouts/_default/single.html as the value for file.
  2. This snippet is complete enough to be downloaded and implemented in a Hugo project, as demonstrated by download="single.html".
{{</* code file="layouts/_default/single.html" download="single.html" */>}}
{{ define "main" }}
<main>
    <article>
        <header>
            <h1>{{.Title}}</h1>
            {{with .Params.subtitle}}
            <span>{{.}}</span>
        </header>
        <div>
            {{.Content}}
        </div>
        <aside>
            {{.TableOfContents}}
        </aside>
    </article>
</main>
{{ end }}
{{</* /code */>}}
Example 'code' Display

The output of this example will render to the Hugo docs as follows:

{{< code file="layouts/_default/single.html" download="single.html" >}} {{ define "main" }}

{{.Title}}

{{with .Params.subtitle}} {{.}}
{{.Content}}
{{ end }} {{< /code >}}

Blockquotes

Blockquotes can be added to the Hugo documentation using typical Markdown blockquote syntax:

> Without the threat of punishment, there is no joy in flight.

The preceding blockquote will render as follows in the Hugo docs:

Without the threat of punishment, there is no joy in flight.

However, you can add a quick and easy <cite> element (added on the client via JavaScript) by separating your main blockquote and the citation with a hyphen with a single space on each side:

> Without the threat of punishment, there is no joy in flight. - [Kobo Abe](https://en.wikipedia.org/wiki/Kobo_Abe)

Which will render as follows in the Hugo docs:

Without the threat of punishment, there is no joy in flight. - Kobo Abe

{{% note "Blockquotes != Admonitions" %}} Previous versions of Hugo documentation used blockquotes to draw attention to text. This is not the intended semantic use of <blockquote>. Use blockquotes when quoting. To note or warn your user of specific information, use the admonition shortcodes that follow. {{% /note %}}

Admonitions

Admonitions are common in technical documentation. The most popular is that seen in reStructuredText Directives. From the SourceForge documentation:

Admonitions are specially marked "topics" that can appear anywhere an ordinary body element can. They contain arbitrary body elements. Typically, an admonition is rendered as an offset block in a document, sometimes outlined or shaded, with a title matching the admonition type. - SourceForge

The Hugo docs contain three admonitions: note, tip, and warning.

note Admonition

Use the note shortcode when you want to draw attention to information subtly. note is intended to be less of an interruption in content than is warning.

Example note Input

{{< code file="note-with-heading.md" >}} {{%/* note /%}} Here is a piece of information I would like to draw your attention to. {{%/ /note */%}} {{< /code >}}

Example note Output

{{< output file="note-with-heading.html" >}} {{% note %}} Here is a piece of information I would like to draw your attention to. {{% /note %}} {{< /output >}}

Example note Display

{{% note %}} Here is a piece of information I would like to draw your attention to. {{% /note %}}

tip Admonition

Use the tip shortcode when you want to give the reader advice. tip, like note, is intended to be less of an interruption in content than is warning.

Example tip Input

{{< code file="using-tip.md" >}} {{%/* tip /%}} Here's a bit of advice to improve your productivity with Hugo. {{%/ /tip */%}} {{< /code >}}

Example tip Output

{{< output file="tip-output.html" >}} {{% tip %}} Here's a bit of advice to improve your productivity with Hugo. {{% /tip %}} {{< /output >}}

Example tip Display

{{% tip %}} Here's a bit of advice to improve your productivity with Hugo. {{% /tip %}}

warning Admonition

Use the warning shortcode when you want to draw the user's attention to something important. A good usage example is for articulating breaking changes in Hugo versions, known bugs, or templating "gotchas."

Example warning Input

{{< code file="warning-admonition-input.md" >}} {{%/* warning /%}} This is a warning, which should be reserved for important information like breaking changes. {{%/ /warning */%}} {{< /code >}}

Example warning Output

{{< output file="warning-admonition-output.html" >}} {{% warning %}} This is a warning, which should be reserved for important information like breaking changes. {{% /warning %}} {{< /output >}}

Example warning Display

{{% warning %}} This is a warning, which should be reserved for important information like breaking changes. {{% /warning %}}

{{% note "Pull Requests and Branches" %}} Similar to contributing to Hugo development, the Hugo team expects you to create a separate branch/fork when you make your contributions to the Hugo docs. {{% /note %}}