github/hugo
1
0
Fork 0
mirror of https://github.com/gohugoio/hugo.git synced 2024-11-28 23:32:11 -05:00
Code Issues Projects Releases Packages Wiki Activity

Merge commit 'b9bd35d72e14932fb6588ff62b90cddef0a060fc' as 'docs'

Browse source
This commit is contained in:
Bjørn Erik Pedersen 2019-10-21 10:22:28 +02:00
commit 27aef3f1fb
735 changed files with 38220 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

20
docs/.editorconfig Normal file
View file

@ -0,0 +1,20 @@
# https://editorconfig.org
root = true
[*]
charset = utf-8
end_of_line = lf
indent_size = 2
indent_style = space
trim_trailing_whitespace = true
[*.go]
indent_size = 8
indent_style = tab
[*.js]
insert_final_newline = true
[*.md]
trim_trailing_whitespace = false

2
docs/.github/calibre/image-actions.yml vendored Normal file
View file

@ -0,0 +1,2 @@
ignorePaths:
- "resources/**"

22
docs/.github/stale.yml vendored Normal file
View file

@ -0,0 +1,22 @@
# Number of days of inactivity before an issue becomes stale
daysUntilStale: 120
# Number of days of inactivity before a stale issue is closed
daysUntilClose: 30
# Issues with these labels will never be considered stale
exemptLabels:
- Keep
- Security
- UndocumentedFeature
# Label to use when marking an issue as stale
staleLabel: Stale
# Comment to post when marking an issue as stale. Set to `false` to disable
markComment: >
This issue has been automatically marked as stale because it has not had
recent activity. The resources of the Hugo team are limited, and so we are asking for your help.
If you still think this is important, please tell us why.
This issue will automatically be closed in the near future if no further activity occurs. Thank you for all your contributions.
# Comment to post when closing a stale issue. Set to `false` to disable
closeComment: false

12
docs/.github/workflows/calibreapp-image-actions.yml vendored Normal file
View file

@ -0,0 +1,12 @@
name: Compress images
on: pull_request
jobs:
build:
name: calibreapp/image-actions
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@master
- name: calibreapp/image-actions
uses: docker://calibreapp/github-image-actions
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

5
docs/.gitignore vendored Normal file
View file

@ -0,0 +1,5 @@
/.idea
/public
nohup.out
.DS_Store
trace.out

194
docs/LICENSE.md Normal file
View file

@ -0,0 +1,194 @@
Apache License
==============
_Version 2.0, January 2004_
_&lt;<http://www.apache.org/licenses/>&gt;_
### Terms and Conditions for use, reproduction, and distribution
#### 1. Definitions
“License” shall mean the terms and conditions for use, reproduction, and
distribution as defined by Sections 1 through 9 of this document.
“Licensor” shall mean the copyright owner or entity authorized by the copyright
owner that is granting the License.
“Legal Entity” shall mean the union of the acting entity and all other entities
that control, are controlled by, or are under common control with that entity.
For the purposes of this definition, “control” means **(i)** the power, direct or
indirect, to cause the direction or management of such entity, whether by
contract or otherwise, or **(ii)** ownership of fifty percent (50%) or more of the
outstanding shares, or **(iii)** beneficial ownership of such entity.
“You” (or “Your”) shall mean an individual or Legal Entity exercising
permissions granted by this License.
“Source” form shall mean the preferred form for making modifications, including
but not limited to software source code, documentation source, and configuration
files.
“Object” form shall mean any form resulting from mechanical transformation or
translation of a Source form, including but not limited to compiled object code,
generated documentation, and conversions to other media types.
“Work” shall mean the work of authorship, whether in Source or Object form, made
available under the License, as indicated by a copyright notice that is included
in or attached to the work (an example is provided in the Appendix below).
“Derivative Works” shall mean any work, whether in Source or Object form, that
is based on (or derived from) the Work and for which the editorial revisions,
annotations, elaborations, or other modifications represent, as a whole, an
original work of authorship. For the purposes of this License, Derivative Works
shall not include works that remain separable from, or merely link (or bind by
name) to the interfaces of, the Work and Derivative Works thereof.
“Contribution” shall mean any work of authorship, including the original version
of the Work and any modifications or additions to that Work or Derivative Works
thereof, that is intentionally submitted to Licensor for inclusion in the Work
by the copyright owner or by an individual or Legal Entity authorized to submit
on behalf of the copyright owner. For the purposes of this definition,
“submitted” means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems, and
issue tracking systems that are managed by, or on behalf of, the Licensor for
the purpose of discussing and improving the Work, but excluding communication
that is conspicuously marked or otherwise designated in writing by the copyright
owner as “Not a Contribution.”
“Contributor” shall mean Licensor and any individual or Legal Entity on behalf
of whom a Contribution has been received by Licensor and subsequently
incorporated within the Work.
#### 2. Grant of Copyright License
Subject to the terms and conditions of this License, each Contributor hereby
grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free,
irrevocable copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the Work and such
Derivative Works in Source or Object form.
#### 3. Grant of Patent License
Subject to the terms and conditions of this License, each Contributor hereby
grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free,
irrevocable (except as stated in this section) patent license to make, have
made, use, offer to sell, sell, import, and otherwise transfer the Work, where
such license applies only to those patent claims licensable by such Contributor
that are necessarily infringed by their Contribution(s) alone or by combination
of their Contribution(s) with the Work to which such Contribution(s) was
submitted. If You institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work or a
Contribution incorporated within the Work constitutes direct or contributory
patent infringement, then any patent licenses granted to You under this License
for that Work shall terminate as of the date such litigation is filed.
#### 4. Redistribution
You may reproduce and distribute copies of the Work or Derivative Works thereof
in any medium, with or without modifications, and in Source or Object form,
provided that You meet the following conditions:
* **(a)** You must give any other recipients of the Work or Derivative Works a copy of
this License; and
* **(b)** You must cause any modified files to carry prominent notices stating that You
changed the files; and
* **(c)** You must retain, in the Source form of any Derivative Works that You distribute,
all copyright, patent, trademark, and attribution notices from the Source form
of the Work, excluding those notices that do not pertain to any part of the
Derivative Works; and
* **(d)** If the Work includes a “NOTICE” text file as part of its distribution, then any
Derivative Works that You distribute must include a readable copy of the
attribution notices contained within such NOTICE file, excluding those notices
that do not pertain to any part of the Derivative Works, in at least one of the
following places: within a NOTICE text file distributed as part of the
Derivative Works; within the Source form or documentation, if provided along
with the Derivative Works; or, within a display generated by the Derivative
Works, if and wherever such third-party notices normally appear. The contents of
the NOTICE file are for informational purposes only and do not modify the
License. You may add Your own attribution notices within Derivative Works that
You distribute, alongside or as an addendum to the NOTICE text from the Work,
provided that such additional attribution notices cannot be construed as
modifying the License.
You may add Your own copyright statement to Your modifications and may provide
additional or different license terms and conditions for use, reproduction, or
distribution of Your modifications, or for any such Derivative Works as a whole,
provided Your use, reproduction, and distribution of the Work otherwise complies
with the conditions stated in this License.
#### 5. Submission of Contributions
Unless You explicitly state otherwise, any Contribution intentionally submitted
for inclusion in the Work by You to the Licensor shall be under the terms and
conditions of this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify the terms of
any separate license agreement you may have executed with Licensor regarding
such Contributions.
#### 6. Trademarks
This License does not grant permission to use the trade names, trademarks,
service marks, or product names of the Licensor, except as required for
reasonable and customary use in describing the origin of the Work and
reproducing the content of the NOTICE file.
#### 7. Disclaimer of Warranty
Unless required by applicable law or agreed to in writing, Licensor provides the
Work (and each Contributor provides its Contributions) on an “AS IS” BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied,
including, without limitation, any warranties or conditions of TITLE,
NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are
solely responsible for determining the appropriateness of using or
redistributing the Work and assume any risks associated with Your exercise of
permissions under this License.
#### 8. Limitation of Liability
In no event and under no legal theory, whether in tort (including negligence),
contract, or otherwise, unless required by applicable law (such as deliberate
and grossly negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special, incidental,
or consequential damages of any character arising as a result of this License or
out of the use or inability to use the Work (including but not limited to
damages for loss of goodwill, work stoppage, computer failure or malfunction, or
any and all other commercial damages or losses), even if such Contributor has
been advised of the possibility of such damages.
#### 9. Accepting Warranty or Additional Liability
While redistributing the Work or Derivative Works thereof, You may choose to
offer, and charge a fee for, acceptance of support, warranty, indemnity, or
other liability obligations and/or rights consistent with this License. However,
in accepting such obligations, You may act only on Your own behalf and on Your
sole responsibility, not on behalf of any other Contributor, and only if You
agree to indemnify, defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason of your
accepting any such warranty or additional liability.
_END OF TERMS AND CONDITIONS_
### APPENDIX: How to apply the Apache License to your work
To apply the Apache License to your work, attach the following boilerplate
notice, with the fields enclosed by brackets `[]` replaced with your own
identifying information. (Don't include the brackets!) The text should be
enclosed in the appropriate comment syntax for the file format. We also
recommend that a file or class name and description of purpose be included on
the same “printed page” as the copyright notice for easier identification within
third-party archives.
Copyright [yyyy] [name of copyright owner]
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

48
docs/README.md Normal file
View file

@ -0,0 +1,48 @@
[![Netlify Status](https://api.netlify.com/api/v1/badges/e0dbbfc7-34f1-4393-a679-c16e80162705/deploy-status)](https://app.netlify.com/sites/gohugoio/deploys)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](https://gohugo.io/contribute/documentation/)
# Hugo Docs
Documentation site for [Hugo](https://github.com/gohugoio/hugo), the very fast and flexible static site generator built with love in Go.
## Contributing
We welcome contributions to Hugo of any kind including documentation, suggestions, bug reports, pull requests etc. Also check out our [contribution guide](https://gohugo.io/contribute/documentation/). We would love to hear from you.
Note that this repository contains solely the documentation for Hugo. For contributions that aren't documentation-related please refer to the [hugo](https://github.com/gohugoio/hugo) repository.
*Pull requests shall **only** contain changes to the actual documentation. However, changes on the code base of Hugo **and** the documentation shall be a single, atomic pull request in the [hugo](https://github.com/gohugoio/hugo) repository.*
Spelling fixes are most welcomed, and if you want to contribute longer sections to the documentation, it would be great if you had these in mind when writing:
* Short is good. People go to the library to read novels. If there is more than one way to _do a thing_ in Hugo, describe the current _best practice_ (avoid "… but you can also do …" and "… in older versions of Hugo you had to …".
* For examples, try to find short snippets that teaches people about the concept. If the example is also useful as-is (copy and paste), then great, but don't list long and similar examples just so people can use them on their sites.
* Hugo has users from all over the world, so an easy to understand and [simple English](https://simple.wikipedia.org/wiki/Basic_English) is good.
## Branches
* The `master` branch is where the site is automatically built from, and is the place to put changes relevant to the current Hugo version.
* The `next` branch is where we store changes that is related to the next Hugo release. This can be previewed here: https://next--gohugoio.netlify.com/
## Build
To view the documentation site locally, you need to clone this repository:
```bash
git clone https://github.com/gohugoio/hugoDocs.git
```
Also note that the documentation version for a given version of Hugo can also be found in the `/docs` sub-folder of the [Hugo source repository](https://github.com/gohugoio/hugo).
Then to view the docs in your browser, run Hugo and open up the link:
```bash
▶ hugo server
Started building sites ...
.
.
Serving pages from memory
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
Press Ctrl+C to stop
```

13
docs/archetypes/default.md Normal file
View file

@ -0,0 +1,13 @@
---
linktitle: ""
description: ""
godocref: ""
publishdate: ""
lastmod: ""
categories: []
tags: []
weight: 00
slug: ""
aliases: []
toc: false
---

17
docs/archetypes/functions.md Normal file
View file

@ -0,0 +1,17 @@
---
linktitle: ""
description: ""
godocref: ""
publishdate: ""
lastmod: ""
categories: [functions]
tags: []
ns: ""
signature: []
workson: []
hugoversion: ""
aliases: []
relatedfuncs: []
toc: false
deprecated: false
---

8
docs/archetypes/showcase/bio.md Normal file
View file

@ -0,0 +1,8 @@
Add some **general info** about {{ replace .Name "-" " " | title }} here.
The site is built by:
* [Person 1](https://example.com)
* [Person 1](https://example.com)

BIN
docs/archetypes/showcase/featured.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 40 KiB

37
docs/archetypes/showcase/index.md Normal file
View file

@ -0,0 +1,37 @@
---
title: {{ replace .Name "-" " " | title }}
date: {{ now.Format "2006-01-02" }}
description: "A short description of this page."
# The URL to the site on the internet.
siteURL: https://gohugo.io/
# Link to the site's Hugo source code if public and you can/want to share.
# Remove or leave blank if not needed/wanted.
siteSource: https://github.com/gohugoio/hugoDocs
# Add credit to the article author. Leave blank or remove if not needed/wanted.
byline: "[bep](https://github.com/bep), Hugo Lead"
---
To complete this showcase:
1. Write the story about your site in this file.
2. Add a summary to the `bio.md` file in this folder.
3. Replace the `featured-template.png` with a screenshot of your site. You can rename it, but it must contain the word `featured`.
4. Create a new pull request in https://github.com/gohugoio/hugoDocs/pulls
The content of this bundle explained:
index.md
: The main content file. Fill in required front matter metadata and write your story. I does not have to be a novel. It can even be self-promotional, but it should include Hugo in some form.
bio.md
: A short summary of the website. Site credits (who built it) fits nicely here.
featured.png
: A reasonably sized screenshot of your website. It can be named anything, but the name must start with "featured". The sample image is `1500x750` (2:1 aspect ratio).

118
docs/config.toml Normal file
View file

@ -0,0 +1,118 @@
baseURL = "https://gohugo.io/"
paginate = 100
defaultContentLanguage = "en"
enableEmoji = true
# Set the unicode character used for the "return" link in page footnotes.
footnotereturnlinkcontents = "↩"
languageCode = "en-us"
title = "Hugo"
googleAnalytics = "UA-7131036-4"
pluralizeListTitles = false
# We do redirects via Netlify's _redirects file, generated by Hugo (see "outputs" below).
disableAliases = true
# Highlighting config (Pygments)
# It is (currently) not in use, but you can do ```go in a content file if you want to.
pygmentsCodeFences = true
pygmentsOptions = ""
# Use the Chroma stylesheet
pygmentsUseClasses = true
pygmentsUseClassic = false
# See https://help.farbox.com/pygments.html
pygmentsStyle = "trac"
[module]
[module.hugoVersion]
min = "0.56.0"
[[module.imports]]
path = "github.com/gohugoio/gohugoioTheme"
[outputs]
home = [ "HTML", "RSS", "REDIR", "HEADERS" ]
section = [ "HTML", "RSS"]
[mediaTypes]
[mediaTypes."text/netlify"]
delimiter = ""
[outputFormats]
[outputFormats.REDIR]
mediatype = "text/netlify"
baseName = "_redirects"
isPlainText = true
notAlternative = true
[outputFormats.HEADERS]
mediatype = "text/netlify"
baseName = "_headers"
isPlainText = true
notAlternative = true
[related]
threshold = 80
includeNewer = true
toLower = false
[[related.indices]]
name = "keywords"
weight = 100
[[related.indices]]
name = "date"
weight = 10
pattern = "2006"
[social]
twitter = "GoHugoIO"
#CUSTOM PARAMS
[params]
description = "The world’s fastest framework for building websites"
## Used for views in rendered HTML (i.e., rather than using the .Hugo variable)
release = "0.55.0-DEV"
## Setting this to true will add a "noindex" to *EVERY* page on the site
removefromexternalsearch = false
## Gh repo for site footer (include trailing slash)
ghrepo = "https://github.com/gohugoio/hugoDocs/"
## GH Repo for filing a new issue
github_repo = "https://github.com/gohugoio/hugo/issues/new"
### Edit content repo (set to automatically enter "edit" mode; this is good for "improve this page" links)
ghdocsrepo = "https://github.com/gohugoio/hugoDocs/tree/master/docs"
## Gitter URL
gitter = "https://gitter.im/spf13/hugo"
## Discuss Forum URL
forum = "https://discourse.gohugo.io/"
## Google Tag Manager
gtmid = ""
# First one is picked as the Twitter card image if not set on page.
images = ["images/gohugoio-card.png"]
flex_box_interior_classes = "flex-auto w-100 w-40-l mr3 mb3 bg-white ba b--moon-gray nested-copy-line-height"
#sidebar_direction = "sidebar_left"
# MARKDOWN
## Configuration for BlackFriday markdown parser: https://github.com/russross/blackfriday
[blackfriday]
plainIDAnchors = true
# See https://github.com/gohugoio/hugo/issues/2424
hrefTargetBlank = false
angledQuotes = false
latexDashes = true
[imaging]
# See https://github.com/disintegration/imaging
# CatmullRom is a sharp bicubic filter which should fit the docs site well with its many screenshots.
# Note that you can also set this per image processing.
resampleFilter = "CatmullRom"
# Default JPEG quality setting. Default is 75.
quality = 75
anchor = "smart"

103
docs/config/_default/config.toml Normal file
View file

@ -0,0 +1,103 @@
baseURL = "https://gohugo.io/"
paginate = 100
defaultContentLanguage = "en"
enableEmoji = true
# Set the unicode character used for the "return" link in page footnotes.
footnotereturnlinkcontents = "↩"
languageCode = "en-us"
title = "Hugo"
googleAnalytics = "UA-7131036-4"
pluralizeListTitles = false
# We do redirects via Netlify's _redirects file, generated by Hugo (see "outputs" below).
disableAliases = true
# Highlighting config (Pygments)
# It is (currently) not in use, but you can do ```go in a content file if you want to.
pygmentsCodeFences = true
pygmentsOptions = ""
# Use the Chroma stylesheet
pygmentsUseClasses = true
pygmentsUseClassic = false
# See https://help.farbox.com/pygments.html
pygmentsStyle = "trac"
[outputs]
home = [ "HTML", "RSS", "REDIR", "HEADERS" ]
section = [ "HTML", "RSS"]
[mediaTypes]
[mediaTypes."text/netlify"]
delimiter = ""
[outputFormats]
[outputFormats.REDIR]
mediatype = "text/netlify"
baseName = "_redirects"
isPlainText = true
notAlternative = true
[outputFormats.HEADERS]
mediatype = "text/netlify"
baseName = "_headers"
isPlainText = true
notAlternative = true
[caches]
[caches.getjson]
dir = ":cacheDir/:project"
maxAge = -1
[caches.getcsv]
dir = ":cacheDir/:project"
maxAge = -1
[caches.images]
dir = ":resourceDir/_gen"
maxAge = -1
[caches.assets]
dir = ":resourceDir/_gen"
maxAge = -1
[related]
threshold = 80
includeNewer = true
toLower = false
[[related.indices]]
name = "keywords"
weight = 100
[[related.indices]]
name = "date"
weight = 10
pattern = "2006"
[social]
twitter = "GoHugoIO"
# MARKDOWN
## Configuration for BlackFriday markdown parser: https://github.com/russross/blackfriday
[blackfriday]
plainIDAnchors = true
# See https://github.com/gohugoio/hugo/issues/2424
hrefTargetBlank = false
angledQuotes = false
latexDashes = true
[imaging]
# See https://github.com/disintegration/imaging
# CatmullRom is a sharp bicubic filter which should fit the docs site well with its many screenshots.
# Note that you can also set this per image processing.
resampleFilter = "CatmullRom"
# Default JPEG quality setting. Default is 75.
quality = 75
anchor = "smart"
[taxonomies]
category = "categories"

10
docs/config/_default/languages.toml Normal file
View file

@ -0,0 +1,10 @@
[en]
contentDir = "content/en"
languageName = "English"
weight = 1
[zh]
contentDir = "content/zh"
languageName = "中文"
weight = 2

154
docs/config/_default/menus/menus.en.toml Normal file
View file

@ -0,0 +1,154 @@
[[docs]]
name = "About Hugo"
weight = 1
identifier = "about"
url = "/about/"
[[docs]]
name = "Getting Started"
weight = 5
identifier = "getting-started"
url = "/getting-started/"
[[docs]]
name = "Hugo Modules"
weight = 15
identifier = "modules"
post = "break"
url = "/hugo-modules/"
# Core Menus
[[docs]]
name = "Content Management"
weight = 20
identifier = "content-management"
post = "expanded"
url = "/content-management/"
[[docs]]
name = "Templates"
weight = 25
identifier = "templates"
url = "/templates/"
[[docs]]
name = "Functions"
weight = 30
identifier = "functions"
url = "/functions/"
[[docs]]
name = "Variables"
weight = 35
identifier = "variables"
url = "/variables/"
[[docs]]
name = "Hugo Pipes"
weight = 36
identifier = "pipes"
url = "/hugo-pipes/"
[[docs]]
name = "CLI"
weight = 40
post = "break"
identifier = "commands"
url = "/commands/"
# LOW LEVEL ITEMS
[[docs]]
name = "Troubleshooting"
weight = 60
identifier = "troubleshooting"
url = "/troubleshooting/"
[[docs]]
name = "Tools"
weight = 70
identifier = "tools"
url = "/tools/"
[[docs]]
name = "Hosting & Deployment"
weight = 80
identifier = "hosting-and-deployment"
url = "/hosting-and-deployment/"
[[docs]]
name = "Contribute"
weight = 100
post = "break"
identifier = "contribute"
url = "/contribute/"
#[[docs]]
# name = "Tags"
# weight = 120
# identifier = "tags"
# url = "/tags/"
# [[docs]]
# name = "Categories"
# weight = 140
# identifier = "categories"
# url = "/categories/"
######## QUICKLINKS
[[quicklinks]]
name = "Fundamentals"
weight = 1
identifier = "fundamentals"
url = "/tags/fundamentals/"
######## GLOBAL ITEMS TO BE SHARED WITH THE HUGO SITES
[[global]]
name = "News"
weight = 1
identifier = "news"
url = "/news/"
[[global]]
name = "Docs"
weight = 5
identifier = "docs"
url = "/documentation/"
[[global]]
name = "Themes"
weight = 10
identifier = "themes"
url = "https://themes.gohugo.io/"
[[global]]
name = "Showcase"
weight = 20
identifier = "showcase"
url = "/showcase/"
# Anything with a weight > 100 gets an external icon
[[global]]
name = "Community"
weight = 150
icon = true
identifier = "community"
post = "external"
url = "https://discourse.gohugo.io/"
[[global]]
name = "GitHub"
weight = 200
identifier = "github"
post = "external"
url = "https://github.com/gohugoio/hugo"

121
docs/config/_default/menus/menus.zh.toml Normal file
View file

@ -0,0 +1,121 @@
# Chinese menus
[[docs]]
name = "关于 Hugo"
weight = 1
identifier = "about"
url = "/zh/about/"
[[docs]]
name = "入门"
weight = 5
identifier = "getting-started"
url = "/zh/getting-started/"
[[docs]]
name = "主题"
weight = 15
identifier = "themes"
post = "break"
url = "/zh/themes/"
# Core languages.zh.menus
[[docs]]
name = "内容管理"
weight = 20
identifier = "content-management"
post = "expanded"
url = "/zh/content-management/"
[[docs]]
name = "模板"
weight = 25
identifier = "templates"
url = "/zh/templates/"
[[docs]]
name = "函数"
weight = 30
identifier = "functions"
url = "/zh/functions/"
[[docs]]
name = "变量"
weight = 35
identifier = "variables"
url = "/zh/variables/"
[[docs]]
name = "CLI"
weight = 40
post = "break"
identifier = "commands"
url = "/commands/"
# LOW LEVEL ITEMS
[[docs]]
name = "故障排除"
weight = 60
identifier = "troubleshooting"
url = "/zh/troubleshooting/"
[[docs]]
name = "工具"
weight = 70
identifier = "tools"
url = "/zh/tools/"
[[docs]]
name = "托管与部署"
weight = 80
identifier = "hosting-and-deployment"
url = "/zh/hosting-and-deployment/"
[[docs]]
name = "贡献"
weight = 100
post = "break"
identifier = "contribute"
url = "/zh/contribute/"
[[global]]
name = "新闻"
weight = 1
identifier = "news"
url = "/zh/news/"
[[global]]
name = "文档"
weight = 5
identifier = "docs"
url = "/zh/documentation/"
[[global]]
name = "主题"
weight = 10
identifier = "themes"
url = "https://themes.gohugo.io/"
[[global]]
name = "作品展示"
weight = 20
identifier = "showcase"
url = "/zh/showcase/"
# Anything with a weight > 100 gets an external icon
[[global]]
name = "社区"
weight = 150
icon = true
identifier = "community"
post = "external"
url = "https://discourse.gohugo.io/"
[[global]]
name = "GitHub"
weight = 200
identifier = "github"
post = "external"
url = "https://github.com/gohugoio/hugo"

25
docs/config/_default/params.toml Normal file
View file

@ -0,0 +1,25 @@
description = "The world’s fastest framework for building websites"
## Used for views in rendered HTML (i.e., rather than using the .Hugo variable)
release = "0.52"
## Setting this to true will add a "noindex" to *EVERY* page on the site..
removefromexternalsearch = false
## Gh repo for site footer (include trailing slash)
ghrepo = "https://github.com/gohugoio/hugoDocs/"
## GH Repo for filing a new issue
github_repo = "https://github.com/gohugoio/hugo/issues/new"
### Edit content repo (set to automatically enter "edit" mode; this is good for "improve this page" links)
ghdocsrepo = "https://github.com/gohugoio/hugoDocs/tree/master/docs"
## Gitter URL
gitter = "https://gitter.im/spf13/hugo"
## Discuss Forum URL
forum = "https://discourse.gohugo.io/"
## Google Tag Manager
gtmid = ""
# First one is picked as the Twitter card image if not set on page.
images = ["images/gohugoio-card.png"]
flex_box_interior_classes = "flex-auto w-100 w-40-l mr3 mb3 bg-white ba b--moon-gray nested-copy-line-height"
#sidebar_direction = "sidebar_left"

1
docs/config/development/params.toml Normal file
View file

@ -0,0 +1 @@
# Params for development (server mode)

6
docs/config/production/config.toml Normal file
View file

@ -0,0 +1,6 @@
# Config for production
# This is turned off in development as it is relatively slow.
# This is needed to get accurate lastMod and Git commit info
# on the docs pages.
enableGitInfo = true

2
docs/config/production/params.toml Normal file
View file

@ -0,0 +1,2 @@
# Params for production

49
docs/content/en/_index.md Normal file
View file

@ -0,0 +1,49 @@
---
title: "The world’s fastest framework for building websites"
date: 2017-03-02T12:00:00-05:00
features:
- heading: Blistering Speed
image_path: /images/icon-fast.svg
tagline: What's modern about waiting for your site to build?
copy: Hugo is the fastest tool of its kind. At <1 ms per page, the average site builds in less than a second.
- heading: Robust Content Management
image_path: /images/icon-content-management.svg
tagline: Flexibility rules. Hugo is a content strategist's dream.
copy: Hugo supports unlimited content types, taxonomies, menus, dynamic API-driven content, and more, all without plugins.
- heading: Shortcodes
image_path: /images/icon-shortcodes.svg
tagline: Hugo's shortcodes are Markdown's hidden superpower.
copy: We love the beautiful simplicity of markdown’s syntax, but there are times when we want more flexibility. Hugo shortcodes allow for both beauty and flexibility.
- heading: Built-in Templates
image_path: /images/icon-built-in-templates.svg
tagline: Hugo has common patterns to get your work done quickly.
copy: Hugo ships with pre-made templates to make quick work of SEO, commenting, analytics and other functions. One line of code, and you're done.
- heading: Multilingual and i18n
image_path: /images/icon-multilingual2.svg
tagline: Polyglot baked in.
copy: Hugo provides full i18n support for multi-language sites with the same straightforward development experience Hugo users love in single-language sites.
- heading: Custom Outputs
image_path: /images/icon-custom-outputs.svg
tagline: HTML not enough?
copy: Hugo allows you to output your content in multiple formats, including JSON or AMP, and makes it easy to create your own.
sections:
- heading: "300+ Themes"
cta: Check out the Hugo themes.
link: https://themes.gohugo.io/
color_classes: bg-accent-color white
image: /images/homepage-screenshot-hugo-themes.jpg
copy: "Hugo provides a robust theming system that is easy to implement but capable of producing even the most complicated websites."
- heading: "Capable Templating"
cta: Get Started.
link: templates/
color_classes: bg-primary-color-light black
image: /images/home-page-templating-example.png
copy: "Hugo's Go-based templating provides just the right amount of logic to build anything from the simple to complex. If you prefer Jade/Pug-like syntax, you can also use Amber, Ace, or any combination of the three."
---
Hugo is one of the most popular open-source static site generators. With its amazing speed and flexibility, Hugo makes building websites fun again.

20
docs/content/en/about/_index.md Normal file
View file

@ -0,0 +1,20 @@
---
title: About Hugo
linktitle: Overview
description: Hugo's features, roadmap, license, and motivation.
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
categories: []
keywords: []
menu:
docs:
parent: "about"
weight: 1
weight: 1
draft: false
aliases: [/about-hugo/,/docs/]
toc: false
---
Hugo is not your average static site generator.

43
docs/content/en/about/benefits.md Normal file
View file

@ -0,0 +1,43 @@
---
title: The Benefits of Static Site Generators
linktitle: The Benefits of Static
description: Improved performance, security and ease of use are just a few of the reasons static site generators are so appealing.
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
keywords: [ssg,static,performance,security]
menu:
docs:
parent: "about"
weight: 30
weight: 30
sections_weight: 30
draft: false
aliases: []
toc: false
---
The purpose of website generators is to render content into HTML files. Most are "dynamic site generators." That means the HTTP server---i.e., the program that sends files to the browser to be viewed---runs the generator to create a new HTML file every time an end user requests a page.
Over time, dynamic site generators were programmed to cache their HTML files to prevent unnecessary delays in delivering pages to end users. A cached page is a static version of a web page.
Hugo takes caching a step further and all HTML files are rendered on your computer. You can review the files locally before copying them to the computer hosting the HTTP server. Since the HTML files aren't generated dynamically, we say that Hugo is a *static site generator*.
This has many benefits. The most noticeable is performance. HTTP servers are *very* good at sending files---so good, in fact, that you can effectively serve the same number of pages with a fraction of the memory and CPU needed for a dynamic site.
## More on Static Site Generators
* ["An Introduction to Static Site Generators", David Walsh][]
* ["Hugo vs. Wordpress page load speed comparison: Hugo leaves WordPress in its dust", GettingThingsTech][hugovwordpress]
* ["Static Site Generators", O'Reilly][]
* [StaticGen: Top Open-Source Static Site Generators (GitHub Stars)][]
* ["Top 10 Static Website Generators", Netlify blog][]
* ["The Resurgence of Static", dotCMS][dotcms]
["An Introduction to Static Site Generators", David Walsh]: https://davidwalsh.name/introduction-static-site-generators
["Static Site Generators", O'Reilly]: https://www.oreilly.com/web-platform/free/files/static-site-generators.pdf
["Top 10 Static Website Generators", Netlify blog]: https://www.netlify.com/blog/2016/05/02/top-ten-static-website-generators/
[hugovwordpress]: https://gettingthingstech.com/hugo-vs.-wordpress-page-load-speed-comparison-hugo-leaves-wordpress-in-its-dust/
[StaticGen: Top Open-Source Static Site Generators (GitHub Stars)]: https://www.staticgen.com/
[dotcms]: https://dotcms.com/blog/post/the-resurgence-of-static

87
docs/content/en/about/features.md Normal file
View file

@ -0,0 +1,87 @@
---
title: Hugo Features
linktitle: Hugo Features
description: Hugo boasts blistering speed, robust content management, and a powerful templating language making it a great fit for all kinds of static websites.
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
menu:
docs:
parent: "about"
weight: 20
weight: 20
sections_weight: 20
draft: false
toc: true
---
## General
* [Extremely fast][] build times (&lt; 1 ms per page)
* Completely cross platform, with [easy installation][install] on macOS, Linux, Windows, and more
* Renders changes on the fly with [LiveReload][] as you develop
* [Powerful theming][]
* [Host your site anywhere][hostanywhere]
## Organization
* Straightforward [organization for your projects][], including website sections
* Customizable [URLs][]
* Support for configurable [taxonomies][], including categories and tags
* [Sort content][] as you desire through powerful template [functions][]
* Automatic [table of contents][] generation
* [Dynamic menu][] creation
* [Pretty URLs][] support
* [Permalink][] pattern support
* Redirects via [aliases][]
## Content
* Native Markdown and Emacs Org-Mode support, as well as other languages via *external helpers* (see [supported formats][])
* TOML, YAML, and JSON metadata support in [front matter][]
* Customizable [homepage][]
* Multiple [content types][]
* Automatic and user defined [content summaries][]
* [Shortcodes][] to enable rich content inside of Markdown
* ["Minutes to Read"][pagevars] functionality
* ["Wordcount"][pagevars] functionality
## Additional Features
* Integrated [Disqus][] comment support
* Integrated [Google Analytics][] support
* Automatic [RSS][] creation
* Support for [Go][], [Amber], and [Ace][] HTML templates
* [Syntax highlighting][] powered by [Chroma][] (partly compatible with Pygments)
[Ace]: /templates/alternatives/
[aliases]: /content-management/urls/#aliases
[Amber]: https://github.com/eknkc/amber
[Chroma]: https://github.com/alecthomas/chroma
[content summaries]: /content-management/summaries/
[content types]: /content-management/types/
[Disqus]: https://disqus.com/
[Dynamic menu]: /templates/menus/
[Extremely fast]: https://github.com/bep/hugo-benchmark
[front matter]: /content-management/front-matter/
[functions]: /functions/
[Go]: https://golang.org/pkg/html/template/
[Google Analytics]: https://google-analytics.com/
[homepage]: /templates/homepage/
[hostanywhere]: /hosting-and-deployment/
[install]: /getting-started/installing/
[LiveReload]: /getting-started/usage/
[organization for your projects]: /getting-started/directory-structure/
[pagevars]: /variables/page/
[Permalink]: /content-management/urls/#permalinks
[Powerful theming]: /themes/
[Pretty URLs]: /content-management/urls/
[RSS]: /templates/rss/
[Shortcodes]: /content-management/shortcodes/
[sort content]: /templates/
[supported formats]: /content-management/formats/
[Syntax highlighting]: /tools/syntax-highlighting/
[table of contents]: /content-management/toc/
[taxonomies]: /content-management/taxonomies/
[URLs]: /content-management/urls/

135
docs/content/en/about/hugo-and-gdpr.md Normal file
View file

@ -0,0 +1,135 @@
---
title: Hugo and the General Data Protection Regulation (GDPR)
linktitle: Hugo and GDPR
description: About how to configure your Hugo site to meet the new regulations.
date: 2018-05-25
layout: single
keywords: ["GDPR", "Privacy", "Data Protection"]
menu:
docs:
parent: "about"
weight: 5
weight: 5
sections_weight: 5
draft: false
aliases: [/privacy/,/gdpr/]
toc: true
---
General Data Protection Regulation ([GDPR](https://en.wikipedia.org/wiki/General_Data_Protection_Regulation)) is a regulation in EU law on data protection and privacy for all individuals within the European Union and the European Economic Area. It became enforceable on 25 May 2018.
**Hugo is a static site generator. By using Hugo you are already standing on very solid ground. Static HTML files on disk are much easier to reason about compared to server and database driven web sites.**
But even static websites can integrate with external services, so from version `0.41`, Hugo provides a **Privacy Config** that covers the relevant built-in templates.
Note that:
* These settings have their defaults setting set to _off_, i.e. how it worked before Hugo `0.41`. You must do your own evaluation of your site and apply the appropriate settings.
* These settings work with the [internal templates](/templates/internal/). Some theme may contain custom templates for embedding services like Google Analytics. In that case these options have no effect.
* We will continue this work and improve this further in future Hugo versions.
## All Privacy Settings
Below are all privacy settings and their default value. These settings need to be put in your site config (e.g. `config.toml`).
{{< code-toggle file="config">}}
[privacy]
[privacy.disqus]
disable = false
[privacy.googleAnalytics]
disable = false
respectDoNotTrack = false
anonymizeIP = false
useSessionStorage = false
[privacy.instagram]
disable = false
simple = false
[privacy.twitter]
disable = false
enableDNT = false
simple = false
[privacy.vimeo]
disable = false
simple = false
[privacy.youtube]
disable = false
privacyEnhanced = false
{{< /code-toggle >}}
## Disable All Services
An example Privacy Config that disables all the relevant services in Hugo. With this configuration, the other settings will not matter.
{{< code-toggle file="config">}}
[privacy]
[privacy.disqus]
disable = true
[privacy.googleAnalytics]
disable = true
[privacy.instagram]
disable = true
[privacy.twitter]
disable = true
[privacy.vimeo]
disable = true
[privacy.youtube]
disable = true
{{< /code-toggle >}}
## The Privacy Settings Explained
### GoogleAnalytics
anonymizeIP
: Enabling this will make it so the users' IP addresses are anonymized within Google Analytics.
respectDoNotTrack
: Enabling this will make the GA templates respect the "Do Not Track" HTTP header.
useSessionStorage
: Enabling this will disable the use of Cookies and use Session Storage to Store the GA Client ID.
### Instagram
simple
: If simple mode is enabled, a static and no-JS version of the Instagram image card will be built. Note that this only supports image cards and the image itself will be fetched from Instagram's servers.
**Note:** If you use the _simple mode_ for Instagram and a site styled with Bootstrap 4, you may want to disable the inlines styles provided by Hugo:
{{< code-toggle file="config">}}
[services]
[services.instagram]
disableInlineCSS = true
{{< /code-toggle >}}
### Twitter
enableDNT
: Enabling this for the twitter/tweet shortcode, the tweet and its embedded page on your site are not used for purposes that include personalized suggestions and personalized ads.
simple
: If simple mode is enabled, a static and no-JS version of a tweet will be built.
**Note:** If you use the _simple mode_ for Twitter, you may want to disable the inlines styles provided by Hugo:
{{< code-toggle file="config">}}
[services]
[services.twitter]
disableInlineCSS = true
{{< /code-toggle >}}
### YouTube
privacyEnhanced
: When you turn on privacy-enhanced mode, YouTube won’t store information about visitors on your website unless the user plays the embedded video.
### Vimeo
simple
: If simple mode is enabled, the video thumbnail is fetched from Vimeo's servers and it is overlayed with a play button. If the user clicks to play the video, it will open in a new tab directly on Vimeo's website.

165
docs/content/en/about/license.md Normal file
View file

@ -0,0 +1,165 @@
---
title: Apache License
linktitle: License
description: Hugo v0.15 and later are released under the Apache 2.0 license.
date: 2016-02-01
publishdate: 2016-02-01
lastmod: 2016-03-02
categories: ["about hugo"]
keywords: ["License","apache"]
menu:
docs:
parent: "about"
weight: 60
weight: 60
sections_weight: 60
aliases: [/meta/license]
toc: true
---
{{% note %}}
Hugo v0.15 and later are released under the Apache 2.0 license.
Earlier versions of Hugo were released under the [Simple Public License](https://opensource.org/licenses/Simple-2.0).
{{% /note %}}
_Version 2.0, January 2004_ <br>
<https://www.apache.org/licenses/LICENSE-2.0>
*Terms and Conditions for use, reproduction, and distribution*
## 1. Definitions
“License” shall mean the terms and conditions for use, reproduction, and
distribution as defined by Sections 1 through 9 of this document.
“Licensor” shall mean the copyright owner or entity authorized by the copyright
owner that is granting the License.
“Legal Entity” shall mean the union of the acting entity and all other entities
that control, are controlled by, or are under common control with that entity.
For the purposes of this definition, “control” means **(i)** the power, direct or
indirect, to cause the direction or management of such entity, whether by
contract or otherwise, or **(ii)** ownership of fifty percent (50%) or more of the
outstanding shares, or **(iii)** beneficial ownership of such entity.
“You” (or “Your”) shall mean an individual or Legal Entity exercising
permissions granted by this License.
“Source” form shall mean the preferred form for making modifications, including
but not limited to software source code, documentation source, and configuration
files.
“Object” form shall mean any form resulting from mechanical transformation or
translation of a Source form, including but not limited to compiled object code,
generated documentation, and conversions to other media types.
“Work” shall mean the work of authorship, whether in Source or Object form, made
available under the License, as indicated by a copyright notice that is included
in or attached to the work (an example is provided in the Appendix below).
“Derivative Works” shall mean any work, whether in Source or Object form, that
is based on (or derived from) the Work and for which the editorial revisions,
annotations, elaborations, or other modifications represent, as a whole, an
original work of authorship. For the purposes of this License, Derivative Works
shall not include works that remain separable from, or merely link (or bind by
name) to the interfaces of, the Work and Derivative Works thereof.
“Contribution” shall mean any work of authorship, including the original version
of the Work and any modifications or additions to that Work or Derivative Works
thereof, that is intentionally submitted to Licensor for inclusion in the Work
by the copyright owner or by an individual or Legal Entity authorized to submit
on behalf of the copyright owner. For the purposes of this definition,
“submitted” means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems, and
issue tracking systems that are managed by, or on behalf of, the Licensor for
the purpose of discussing and improving the Work, but excluding communication
that is conspicuously marked or otherwise designated in writing by the copyright
owner as “Not a Contribution.”
“Contributor” shall mean Licensor and any individual or Legal Entity on behalf
of whom a Contribution has been received by Licensor and subsequently
incorporated within the Work.
## 2. Grant of Copyright License
Subject to the terms and conditions of this License, each Contributor hereby
grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free,
irrevocable copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the Work and such
Derivative Works in Source or Object form.
## 3. Grant of Patent License
Subject to the terms and conditions of this License, each Contributor hereby
grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free,
irrevocable (except as stated in this section) patent license to make, have
made, use, offer to sell, sell, import, and otherwise transfer the Work, where
such license applies only to those patent claims licensable by such Contributor
that are necessarily infringed by their Contribution(s) alone or by combination
of their Contribution(s) with the Work to which such Contribution(s) was
submitted. If You institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work or a
Contribution incorporated within the Work constitutes direct or contributory
patent infringement, then any patent licenses granted to You under this License
for that Work shall terminate as of the date such litigation is filed.
## 4. Redistribution
You may reproduce and distribute copies of the Work or Derivative Works thereof
in any medium, with or without modifications, and in Source or Object form,
provided that You meet the following conditions:
* **(a)** You must give any other recipients of the Work or Derivative Works a copy of
this License; and
* **(b)** You must cause any modified files to carry prominent notices stating that You
changed the files; and
* **\(c)** You must retain, in the Source form of any Derivative Works that You distribute,
all copyright, patent, trademark, and attribution notices from the Source form
of the Work, excluding those notices that do not pertain to any part of the
Derivative Works; and
* **(d)** If the Work includes a “NOTICE” text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License.
You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.
## 5. Submission of Contributions
Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.
## 6. Trademarks
This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.
## 7. Disclaimer of Warranty
Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.
## 8. Limitation of Liability
In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages.
## 9. Accepting Warranty or Additional Liability
While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.
_END OF TERMS AND CONDITIONS_
## APPENDIX: How to apply the Apache License to your work
To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets `[]` replaced with your own identifying information. (Don't include the brackets!) The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same “printed page” as the copyright notice for easier identification within third-party archives.
{{< code file="apache-notice.txt" download="apache-notice.txt" >}}
Copyright [yyyy] [name of copyright owner]
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
https://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
{{< /code >}}

65
docs/content/en/about/what-is-hugo.md Normal file
View file

@ -0,0 +1,65 @@
---
title: What is Hugo
linktitle: What is Hugo
description: Hugo is a fast and modern static site generator written in Go, and designed to make website creation fun again.
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
layout: single
menu:
docs:
parent: "about"
weight: 10
weight: 10
sections_weight: 10
draft: false
aliases: [/overview/introduction/,/about/why-i-built-hugo/]
toc: true
---
Hugo is a general-purpose website framework. Technically speaking, Hugo is a [static site generator][]. Unlike systems that dynamically build a page with each visitor request, Hugo builds pages when you create or update your content. Since websites are viewed far more often than they are edited, Hugo is designed to provide an optimal viewing experience for your website's end users and an ideal writing experience for website authors.
Websites built with Hugo are extremely fast and secure. Hugo sites can be hosted anywhere, including [Netlify][], [Heroku][], [GoDaddy][], [DreamHost][], [GitHub Pages][], [GitLab Pages][], [Surge][], [Aerobatic][], [Firebase][], [Google Cloud Storage][], [Amazon S3][], [Rackspace][], [Azure][], and [CloudFront][] and work well with CDNs. Hugo sites run without the need for a database or dependencies on expensive runtimes like Ruby, Python, or PHP.
We think of Hugo as the ideal website creation tool with nearly instant build times, able to rebuild whenever a change is made.
## How Fast is Hugo?
{{< youtube "CdiDYZ51a2o" >}}
## What Does Hugo Do?
In technical terms, Hugo takes a source directory of files and templates and uses these as input to create a complete website.
## Who Should Use Hugo?
Hugo is for people that prefer writing in a text editor over a browser.
Hugo is for people who want to hand code their own website without worrying about setting up complicated runtimes, dependencies and databases.
Hugo is for people building a blog, a company site, a portfolio site, documentation, a single landing page, or a website with thousands of pages.
[@spf13]: https://twitter.com/@spf13
[Aerobatic]: https://www.aerobatic.com/
[Amazon S3]: https://aws.amazon.com/s3/
[Azure]: https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blob-static-website
[CloudFront]: https://aws.amazon.com/cloudfront/ "Amazon CloudFront"
[DreamHost]: https://www.dreamhost.com/
[Firebase]: https://firebase.google.com/docs/hosting/ "Firebase static hosting"
[GitHub Pages]: https://pages.github.com/
[GitLab Pages]: https://about.gitlab.com/features/pages/
[Go language]: https://golang.org/
[GoDaddy]: https://www.godaddy.com/ "Godaddy.com Hosting"
[Google Cloud Storage]: https://cloud.google.com/storage/
[Heroku]: https://www.heroku.com/
[Jekyll]: https://jekyllrb.com/
[Middleman]: https://middlemanapp.com/
[Nanoc]: https://nanoc.ws/
[Netlify]: https://netlify.com
[Rackspace]: https://www.rackspace.com/cloud/files
[Surge]: https://surge.sh
[contributing to it]: https://github.com/gohugoio/hugo
[rackspace]: https://www.rackspace.com/cloud/files
[static site generator]: /about/benefits/

82
docs/content/en/commands/hugo.md Normal file
View file

@ -0,0 +1,82 @@
---
date: 2019-07-31
title: "hugo"
slug: hugo
url: /commands/hugo/
---
## hugo
hugo builds your site
### Synopsis
hugo is the main command, used to build your Hugo site.
Hugo is a Fast and Flexible Static Site Generator
built with love by spf13 and friends in Go.
Complete documentation is available at https://gohugo.io/.
```
hugo [flags]
```
### Options
```
-b, --baseURL string hostname (and path) to the root, e.g. https://spf13.com/
-D, --buildDrafts include content marked as draft
-E, --buildExpired include expired content
-F, --buildFuture include content with publishdate in the future
--cacheDir string filesystem path to cache directory. Defaults: $TMPDIR/hugo_cache/
--cleanDestinationDir remove files from destination not found in static directories
--config string config file (default is path/config.yaml|json|toml)
--configDir string config dir (default "config")
-c, --contentDir string filesystem path to content directory
--debug debug output
-d, --destination string filesystem path to write files to
--disableKinds strings disable different kind of pages (home, RSS etc.)
--enableGitInfo add Git revision, date and author info to the pages
-e, --environment string build environment
--forceSyncStatic copy all files when static is changed.
--gc enable to run some cleanup tasks (remove unused cache files) after the build
-h, --help help for hugo
--i18n-warnings print missing translations
--ignoreCache ignores the cache directory
--ignoreVendor ignores any _vendor directory
-l, --layoutDir string filesystem path to layout directory
--log enable Logging
--logFile string log File path (if set, logging enabled automatically)
--minify minify any supported output format (HTML, XML etc.)
--noChmod don't sync permission mode of files
--noTimes don't sync modification time of files
--path-warnings print warnings on duplicate target paths etc.
--quiet build in quiet mode
--renderToMemory render to memory (only useful for benchmark testing)
-s, --source string filesystem path to read files relative from
--templateMetrics display metrics about template executions
--templateMetricsHints calculate some improvement hints when combined with --templateMetrics
-t, --theme strings themes to use (located in /themes/THEMENAME/)
--themesDir string filesystem path to themes directory
--trace file write trace to file (not useful in general)
-v, --verbose verbose output
--verboseLog verbose logging
-w, --watch watch filesystem for changes and recreate as needed
```
### SEE ALSO
* [hugo check](/commands/hugo_check/) - Contains some verification checks
* [hugo config](/commands/hugo_config/) - Print the site configuration
* [hugo convert](/commands/hugo_convert/) - Convert your content to different formats
* [hugo deploy](/commands/hugo_deploy/) - Deploy your site to a Cloud provider.
* [hugo env](/commands/hugo_env/) - Print Hugo version and environment info
* [hugo gen](/commands/hugo_gen/) - A collection of several useful generators.
* [hugo import](/commands/hugo_import/) - Import your site from others.
* [hugo list](/commands/hugo_list/) - Listing out various types of content
* [hugo mod](/commands/hugo_mod/) - Various Hugo Modules helpers.
* [hugo new](/commands/hugo_new/) - Create new content for your site
* [hugo server](/commands/hugo_server/) - A high performance webserver
* [hugo version](/commands/hugo_version/) - Print the version number of Hugo
###### Auto generated by spf13/cobra on 31-Jul-2019

43
docs/content/en/commands/hugo_check.md Normal file
View file

@ -0,0 +1,43 @@
---
date: 2019-07-31
title: "hugo check"
slug: hugo_check
url: /commands/hugo_check/
---
## hugo check
Contains some verification checks
### Synopsis
Contains some verification checks
### Options
```
-h, --help help for check
```
### Options inherited from parent commands
```
--config string config file (default is path/config.yaml|json|toml)
--configDir string config dir (default "config")
--debug debug output
-e, --environment string build environment
--ignoreVendor ignores any _vendor directory
--log enable Logging
--logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
-v, --verbose verbose output
--verboseLog verbose logging
```
### SEE ALSO
* [hugo](/commands/hugo/) - hugo builds your site
* [hugo check ulimit](/commands/hugo_check_ulimit/) - Check system ulimit settings
###### Auto generated by spf13/cobra on 31-Jul-2019

47
docs/content/en/commands/hugo_check_ulimit.md Normal file
View file

@ -0,0 +1,47 @@
---
date: 2019-07-31
title: "hugo check ulimit"
slug: hugo_check_ulimit
url: /commands/hugo_check_ulimit/
---
## hugo check ulimit
Check system ulimit settings
### Synopsis
Hugo will inspect the current ulimit settings on the system.
This is primarily to ensure that Hugo can watch enough files on some OSs
```
hugo check ulimit [flags]
```
### Options
```
-h, --help help for ulimit
```
### Options inherited from parent commands
```
--config string config file (default is path/config.yaml|json|toml)
--configDir string config dir (default "config")
--debug debug output
-e, --environment string build environment
--ignoreVendor ignores any _vendor directory
--log enable Logging
--logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
-v, --verbose verbose output
--verboseLog verbose logging
```
### SEE ALSO
* [hugo check](/commands/hugo_check/) - Contains some verification checks
###### Auto generated by spf13/cobra on 31-Jul-2019

47
docs/content/en/commands/hugo_config.md Normal file
View file

@ -0,0 +1,47 @@
---
date: 2019-07-31
title: "hugo config"
slug: hugo_config
url: /commands/hugo_config/
---
## hugo config
Print the site configuration
### Synopsis
Print the site configuration, both default and custom settings.
```
hugo config [flags]
```
### Options
```
-h, --help help for config
```
### Options inherited from parent commands
```
--config string config file (default is path/config.yaml|json|toml)
--configDir string config dir (default "config")
--debug debug output
-e, --environment string build environment
--ignoreVendor ignores any _vendor directory
--log enable Logging
--logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
-v, --verbose verbose output
--verboseLog verbose logging
```
### SEE ALSO
* [hugo](/commands/hugo/) - hugo builds your site
* [hugo config mounts](/commands/hugo_config_mounts/) - Print the configured file mounts
###### Auto generated by spf13/cobra on 31-Jul-2019

46
docs/content/en/commands/hugo_config_mounts.md Normal file
View file

@ -0,0 +1,46 @@
---
date: 2019-07-31
title: "hugo config mounts"
slug: hugo_config_mounts
url: /commands/hugo_config_mounts/
---
## hugo config mounts
Print the configured file mounts
### Synopsis
Print the configured file mounts
```
hugo config mounts [flags]
```
### Options
```
-h, --help help for mounts
```
### Options inherited from parent commands
```
--config string config file (default is path/config.yaml|json|toml)
--configDir string config dir (default "config")
--debug debug output
-e, --environment string build environment
--ignoreVendor ignores any _vendor directory
--log enable Logging
--logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
-v, --verbose verbose output
--verboseLog verbose logging
```
### SEE ALSO
* [hugo config](/commands/hugo_config/) - Print the site configuration
###### Auto generated by spf13/cobra on 31-Jul-2019

49
docs/content/en/commands/hugo_convert.md Normal file
View file

@ -0,0 +1,49 @@
---
date: 2019-07-31
title: "hugo convert"
slug: hugo_convert
url: /commands/hugo_convert/
---
## hugo convert
Convert your content to different formats
### Synopsis
Convert your content (e.g. front matter) to different formats.
See convert's subcommands toJSON, toTOML and toYAML for more information.
### Options
```
-h, --help help for convert
-o, --output string filesystem path to write files to
--unsafe enable less safe operations, please backup first
```
### Options inherited from parent commands
```
--config string config file (default is path/config.yaml|json|toml)
--configDir string config dir (default "config")
--debug debug output
-e, --environment string build environment
--ignoreVendor ignores any _vendor directory
--log enable Logging
--logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
-v, --verbose verbose output
--verboseLog verbose logging
```
### SEE ALSO
* [hugo](/commands/hugo/) - hugo builds your site
* [hugo convert toJSON](/commands/hugo_convert_tojson/) - Convert front matter to JSON
* [hugo convert toTOML](/commands/hugo_convert_totoml/) - Convert front matter to TOML
* [hugo convert toYAML](/commands/hugo_convert_toyaml/) - Convert front matter to YAML
###### Auto generated by spf13/cobra on 31-Jul-2019

49
docs/content/en/commands/hugo_convert_toJSON.md Normal file
View file

@ -0,0 +1,49 @@
---
date: 2019-07-31
title: "hugo convert toJSON"
slug: hugo_convert_toJSON
url: /commands/hugo_convert_tojson/
---
## hugo convert toJSON
Convert front matter to JSON
### Synopsis
toJSON converts all front matter in the content directory
to use JSON for the front matter.
```
hugo convert toJSON [flags]
```
### Options
```
-h, --help help for toJSON
```
### Options inherited from parent commands
```
--config string config file (default is path/config.yaml|json|toml)
--configDir string config dir (default "config")
--debug debug output
-e, --environment string build environment
--ignoreVendor ignores any _vendor directory
--log enable Logging
--logFile string log File path (if set, logging enabled automatically)
-o, --output string filesystem path to write files to
--quiet build in quiet mode
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
--unsafe enable less safe operations, please backup first
-v, --verbose verbose output
--verboseLog verbose logging
```
### SEE ALSO
* [hugo convert](/commands/hugo_convert/) - Convert your content to different formats
###### Auto generated by spf13/cobra on 31-Jul-2019

49
docs/content/en/commands/hugo_convert_toTOML.md Normal file
View file

@ -0,0 +1,49 @@
---
date: 2019-07-31
title: "hugo convert toTOML"
slug: hugo_convert_toTOML
url: /commands/hugo_convert_totoml/
---
## hugo convert toTOML
Convert front matter to TOML
### Synopsis
toTOML converts all front matter in the content directory
to use TOML for the front matter.
```
hugo convert toTOML [flags]
```
### Options
```
-h, --help help for toTOML
```
### Options inherited from parent commands
```
--config string config file (default is path/config.yaml|json|toml)
--configDir string config dir (default "config")
--debug debug output
-e, --environment string build environment
--ignoreVendor ignores any _vendor directory
--log enable Logging
--logFile string log File path (if set, logging enabled automatically)
-o, --output string filesystem path to write files to
--quiet build in quiet mode
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
--unsafe enable less safe operations, please backup first
-v, --verbose verbose output
--verboseLog verbose logging
```
### SEE ALSO
* [hugo convert](/commands/hugo_convert/) - Convert your content to different formats
###### Auto generated by spf13/cobra on 31-Jul-2019

49
docs/content/en/commands/hugo_convert_toYAML.md Normal file
View file

@ -0,0 +1,49 @@
---
date: 2019-07-31
title: "hugo convert toYAML"
slug: hugo_convert_toYAML
url: /commands/hugo_convert_toyaml/
---
## hugo convert toYAML
Convert front matter to YAML
### Synopsis
toYAML converts all front matter in the content directory
to use YAML for the front matter.
```
hugo convert toYAML [flags]
```
### Options
```
-h, --help help for toYAML
```
### Options inherited from parent commands
```
--config string config file (default is path/config.yaml|json|toml)
--configDir string config dir (default "config")
--debug debug output
-e, --environment string build environment
--ignoreVendor ignores any _vendor directory
--log enable Logging
--logFile string log File path (if set, logging enabled automatically)
-o, --output string filesystem path to write files to
--quiet build in quiet mode
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
--unsafe enable less safe operations, please backup first
-v, --verbose verbose output
--verboseLog verbose logging
```
### SEE ALSO
* [hugo convert](/commands/hugo_convert/) - Convert your content to different formats
###### Auto generated by spf13/cobra on 31-Jul-2019

56
docs/content/en/commands/hugo_deploy.md Normal file
View file

@ -0,0 +1,56 @@
---
date: 2019-07-31
title: "hugo deploy"
slug: hugo_deploy
url: /commands/hugo_deploy/
---
## hugo deploy
Deploy your site to a Cloud provider.
### Synopsis
Deploy your site to a Cloud provider.
See https://gohugo.io/hosting-and-deployment/hugo-deploy/ for detailed
documentation.
```
hugo deploy [flags]
```
### Options
```
--confirm ask for confirmation before making changes to the target
--dryRun dry run
--force force upload of all files
-h, --help help for deploy
--invalidateCDN invalidate the CDN cache via the cloudFrontDistributionID listed in the deployment target (default true)
--maxDeletes int maximum # of files to delete, or -1 to disable (default 256)
--target string target deployment from deployments section in config file; defaults to the first one
```
### Options inherited from parent commands
```
--config string config file (default is path/config.yaml|json|toml)
--configDir string config dir (default "config")
--debug debug output
-e, --environment string build environment
--ignoreVendor ignores any _vendor directory
--log enable Logging
--logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
-v, --verbose verbose output
--verboseLog verbose logging
```
### SEE ALSO
* [hugo](/commands/hugo/) - hugo builds your site
###### Auto generated by spf13/cobra on 31-Jul-2019

46
docs/content/en/commands/hugo_env.md Normal file
View file

@ -0,0 +1,46 @@
---
date: 2019-07-31
title: "hugo env"
slug: hugo_env
url: /commands/hugo_env/
---
## hugo env
Print Hugo version and environment info
### Synopsis
Print Hugo version and environment info. This is useful in Hugo bug reports.
```
hugo env [flags]
```
### Options
```
-h, --help help for env
```
### Options inherited from parent commands
```
--config string config file (default is path/config.yaml|json|toml)
--configDir string config dir (default "config")
--debug debug output
-e, --environment string build environment
--ignoreVendor ignores any _vendor directory
--log enable Logging
--logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
-v, --verbose verbose output
--verboseLog verbose logging
```
### SEE ALSO
* [hugo](/commands/hugo/) - hugo builds your site
###### Auto generated by spf13/cobra on 31-Jul-2019

46
docs/content/en/commands/hugo_gen.md Normal file
View file

@ -0,0 +1,46 @@
---
date: 2019-07-31
title: "hugo gen"
slug: hugo_gen
url: /commands/hugo_gen/
---
## hugo gen
A collection of several useful generators.
### Synopsis
A collection of several useful generators.
### Options
```
-h, --help help for gen
```
### Options inherited from parent commands
```
--config string config file (default is path/config.yaml|json|toml)
--configDir string config dir (default "config")
--debug debug output
-e, --environment string build environment
--ignoreVendor ignores any _vendor directory
--log enable Logging
--logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
-v, --verbose verbose output
--verboseLog verbose logging
```
### SEE ALSO
* [hugo](/commands/hugo/) - hugo builds your site
* [hugo gen autocomplete](/commands/hugo_gen_autocomplete/) - Generate shell autocompletion script for Hugo
* [hugo gen chromastyles](/commands/hugo_gen_chromastyles/) - Generate CSS stylesheet for the Chroma code highlighter
* [hugo gen doc](/commands/hugo_gen_doc/) - Generate Markdown documentation for the Hugo CLI.
* [hugo gen man](/commands/hugo_gen_man/) - Generate man pages for the Hugo CLI
###### Auto generated by spf13/cobra on 31-Jul-2019

64
docs/content/en/commands/hugo_gen_autocomplete.md Normal file
View file

@ -0,0 +1,64 @@
---
date: 2019-07-31
title: "hugo gen autocomplete"
slug: hugo_gen_autocomplete
url: /commands/hugo_gen_autocomplete/
---
## hugo gen autocomplete
Generate shell autocompletion script for Hugo
### Synopsis
Generates a shell autocompletion script for Hugo.
NOTE: The current version supports Bash only.
This should work for *nix systems with Bash installed.
By default, the file is written directly to /etc/bash_completion.d
for convenience, and the command may need superuser rights, e.g.:
$ sudo hugo gen autocomplete
Add `--completionfile=/path/to/file` flag to set alternative
file-path and name.
Logout and in again to reload the completion scripts,
or just source them in directly:
$ . /etc/bash_completion
```
hugo gen autocomplete [flags]
```
### Options
```
--completionfile string autocompletion file (default "/etc/bash_completion.d/hugo.sh")
-h, --help help for autocomplete
--type string autocompletion type (currently only bash supported) (default "bash")
```
### Options inherited from parent commands
```
--config string config file (default is path/config.yaml|json|toml)
--configDir string config dir (default "config")
--debug debug output
-e, --environment string build environment
--ignoreVendor ignores any _vendor directory
--log enable Logging
--logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
-v, --verbose verbose output
--verboseLog verbose logging
```
### SEE ALSO
* [hugo gen](/commands/hugo_gen/) - A collection of several useful generators.
###### Auto generated by spf13/cobra on 31-Jul-2019

51
docs/content/en/commands/hugo_gen_chromastyles.md Normal file
View file

@ -0,0 +1,51 @@
---
date: 2019-07-31
title: "hugo gen chromastyles"
slug: hugo_gen_chromastyles
url: /commands/hugo_gen_chromastyles/
---
## hugo gen chromastyles
Generate CSS stylesheet for the Chroma code highlighter
### Synopsis
Generate CSS stylesheet for the Chroma code highlighter for a given style. This stylesheet is needed if pygmentsUseClasses is enabled in config.
See https://help.farbox.com/pygments.html for preview of available styles
```
hugo gen chromastyles [flags]
```
### Options
```
-h, --help help for chromastyles
--highlightStyle string style used for highlighting lines (see https://github.com/alecthomas/chroma) (default "bg:#ffffcc")
--linesStyle string style used for line numbers (see https://github.com/alecthomas/chroma)
--style string highlighter style (see https://help.farbox.com/pygments.html) (default "friendly")
```
### Options inherited from parent commands
```
--config string config file (default is path/config.yaml|json|toml)
--configDir string config dir (default "config")
--debug debug output
-e, --environment string build environment
--ignoreVendor ignores any _vendor directory
--log enable Logging
--logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
-v, --verbose verbose output
--verboseLog verbose logging
```
### SEE ALSO
* [hugo gen](/commands/hugo_gen/) - A collection of several useful generators.
###### Auto generated by spf13/cobra on 31-Jul-2019

53
docs/content/en/commands/hugo_gen_doc.md Normal file
View file

@ -0,0 +1,53 @@
---
date: 2019-07-31
title: "hugo gen doc"
slug: hugo_gen_doc
url: /commands/hugo_gen_doc/
---
## hugo gen doc
Generate Markdown documentation for the Hugo CLI.
### Synopsis
Generate Markdown documentation for the Hugo CLI.
This command is, mostly, used to create up-to-date documentation
of Hugo's command-line interface for https://gohugo.io/.
It creates one Markdown file per command with front matter suitable
for rendering in Hugo.
```
hugo gen doc [flags]
```
### Options
```
--dir string the directory to write the doc. (default "/tmp/hugodoc/")
-h, --help help for doc
```
### Options inherited from parent commands
```
--config string config file (default is path/config.yaml|json|toml)
--configDir string config dir (default "config")
--debug debug output
-e, --environment string build environment
--ignoreVendor ignores any _vendor directory
--log enable Logging
--logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
-v, --verbose verbose output
--verboseLog verbose logging
```
### SEE ALSO
* [hugo gen](/commands/hugo_gen/) - A collection of several useful generators.
###### Auto generated by spf13/cobra on 31-Jul-2019

49
docs/content/en/commands/hugo_gen_man.md Normal file
View file

@ -0,0 +1,49 @@
---
date: 2019-07-31
title: "hugo gen man"
slug: hugo_gen_man
url: /commands/hugo_gen_man/
---
## hugo gen man
Generate man pages for the Hugo CLI
### Synopsis
This command automatically generates up-to-date man pages of Hugo's
command-line interface. By default, it creates the man page files
in the "man" directory under the current directory.
```
hugo gen man [flags]
```
### Options
```
--dir string the directory to write the man pages. (default "man/")
-h, --help help for man
```
### Options inherited from parent commands
```
--config string config file (default is path/config.yaml|json|toml)
--configDir string config dir (default "config")
--debug debug output
-e, --environment string build environment
--ignoreVendor ignores any _vendor directory
--log enable Logging
--logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
-v, --verbose verbose output
--verboseLog verbose logging
```
### SEE ALSO
* [hugo gen](/commands/hugo_gen/) - A collection of several useful generators.
###### Auto generated by spf13/cobra on 31-Jul-2019

45
docs/content/en/commands/hugo_import.md Normal file
View file

@ -0,0 +1,45 @@
---
date: 2019-07-31
title: "hugo import"
slug: hugo_import
url: /commands/hugo_import/
---
## hugo import
Import your site from others.
### Synopsis
Import your site from other web site generators like Jekyll.
Import requires a subcommand, e.g. `hugo import jekyll jekyll_root_path target_path`.
### Options
```
-h, --help help for import
```
### Options inherited from parent commands
```
--config string config file (default is path/config.yaml|json|toml)
--configDir string config dir (default "config")
--debug debug output
-e, --environment string build environment
--ignoreVendor ignores any _vendor directory
--log enable Logging
--logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
-v, --verbose verbose output
--verboseLog verbose logging
```
### SEE ALSO
* [hugo](/commands/hugo/) - hugo builds your site
* [hugo import jekyll](/commands/hugo_import_jekyll/) - hugo import from Jekyll
###### Auto generated by spf13/cobra on 31-Jul-2019

49
docs/content/en/commands/hugo_import_jekyll.md Normal file
View file

@ -0,0 +1,49 @@
---
date: 2019-07-31
title: "hugo import jekyll"
slug: hugo_import_jekyll
url: /commands/hugo_import_jekyll/
---
## hugo import jekyll
hugo import from Jekyll
### Synopsis
hugo import from Jekyll.
Import from Jekyll requires two paths, e.g. `hugo import jekyll jekyll_root_path target_path`.
```
hugo import jekyll [flags]
```
### Options
```
--force allow import into non-empty target directory
-h, --help help for jekyll
```
### Options inherited from parent commands
```
--config string config file (default is path/config.yaml|json|toml)
--configDir string config dir (default "config")
--debug debug output
-e, --environment string build environment
--ignoreVendor ignores any _vendor directory
--log enable Logging
--logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
-v, --verbose verbose output
--verboseLog verbose logging
```
### SEE ALSO
* [hugo import](/commands/hugo_import/) - Import your site from others.
###### Auto generated by spf13/cobra on 31-Jul-2019

48
docs/content/en/commands/hugo_list.md Normal file
View file

@ -0,0 +1,48 @@
---
date: 2019-07-31
title: "hugo list"
slug: hugo_list
url: /commands/hugo_list/
---
## hugo list
Listing out various types of content
### Synopsis
Listing out various types of content.
List requires a subcommand, e.g. `hugo list drafts`.
### Options
```
-h, --help help for list
```
### Options inherited from parent commands
```
--config string config file (default is path/config.yaml|json|toml)
--configDir string config dir (default "config")
--debug debug output
-e, --environment string build environment
--ignoreVendor ignores any _vendor directory
--log enable Logging
--logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
-v, --verbose verbose output
--verboseLog verbose logging
```
### SEE ALSO
* [hugo](/commands/hugo/) - hugo builds your site
* [hugo list all](/commands/hugo_list_all/) - List all posts
* [hugo list drafts](/commands/hugo_list_drafts/) - List all drafts
* [hugo list expired](/commands/hugo_list_expired/) - List all posts already expired
* [hugo list future](/commands/hugo_list_future/) - List all posts dated in the future
###### Auto generated by spf13/cobra on 31-Jul-2019

46
docs/content/en/commands/hugo_list_all.md Normal file
View file

@ -0,0 +1,46 @@
---
date: 2019-07-31
title: "hugo list all"
slug: hugo_list_all
url: /commands/hugo_list_all/
---
## hugo list all
List all posts
### Synopsis
List all of the posts in your content directory, include drafts, future and expired pages.
```
hugo list all [flags]
```
### Options
```
-h, --help help for all
```
### Options inherited from parent commands
```
--config string config file (default is path/config.yaml|json|toml)
--configDir string config dir (default "config")
--debug debug output
-e, --environment string build environment
--ignoreVendor ignores any _vendor directory
--log enable Logging
--logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
-v, --verbose verbose output
--verboseLog verbose logging
```
### SEE ALSO
* [hugo list](/commands/hugo_list/) - Listing out various types of content
###### Auto generated by spf13/cobra on 31-Jul-2019

46
docs/content/en/commands/hugo_list_drafts.md Normal file
View file

@ -0,0 +1,46 @@
---
date: 2019-07-31
title: "hugo list drafts"
slug: hugo_list_drafts
url: /commands/hugo_list_drafts/
---
## hugo list drafts
List all drafts
### Synopsis
List all of the drafts in your content directory.
```
hugo list drafts [flags]
```
### Options
```
-h, --help help for drafts
```
### Options inherited from parent commands
```
--config string config file (default is path/config.yaml|json|toml)
--configDir string config dir (default "config")
--debug debug output
-e, --environment string build environment
--ignoreVendor ignores any _vendor directory
--log enable Logging
--logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
-v, --verbose verbose output
--verboseLog verbose logging
```
### SEE ALSO
* [hugo list](/commands/hugo_list/) - Listing out various types of content
###### Auto generated by spf13/cobra on 31-Jul-2019

46
docs/content/en/commands/hugo_list_expired.md Normal file
View file

@ -0,0 +1,46 @@
---
date: 2019-07-31
title: "hugo list expired"
slug: hugo_list_expired
url: /commands/hugo_list_expired/
---
## hugo list expired
List all posts already expired
### Synopsis
List all of the posts in your content directory which has already expired.
```
hugo list expired [flags]
```
### Options
```
-h, --help help for expired
```
### Options inherited from parent commands
```
--config string config file (default is path/config.yaml|json|toml)
--configDir string config dir (default "config")
--debug debug output
-e, --environment string build environment
--ignoreVendor ignores any _vendor directory
--log enable Logging
--logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
-v, --verbose verbose output
--verboseLog verbose logging
```
### SEE ALSO
* [hugo list](/commands/hugo_list/) - Listing out various types of content
###### Auto generated by spf13/cobra on 31-Jul-2019

46
docs/content/en/commands/hugo_list_future.md Normal file
View file

@ -0,0 +1,46 @@
---
date: 2019-07-31
title: "hugo list future"
slug: hugo_list_future
url: /commands/hugo_list_future/
---
## hugo list future
List all posts dated in the future
### Synopsis
List all of the posts in your content directory which will be posted in the future.
```
hugo list future [flags]
```
### Options
```
-h, --help help for future
```
### Options inherited from parent commands
```
--config string config file (default is path/config.yaml|json|toml)
--configDir string config dir (default "config")
--debug debug output
-e, --environment string build environment
--ignoreVendor ignores any _vendor directory
--log enable Logging
--logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
-v, --verbose verbose output
--verboseLog verbose logging
```
### SEE ALSO
* [hugo list](/commands/hugo_list/) - Listing out various types of content
###### Auto generated by spf13/cobra on 31-Jul-2019

83
docs/content/en/commands/hugo_mod.md Normal file
View file

@ -0,0 +1,83 @@
---
date: 2019-07-31
title: "hugo mod"
slug: hugo_mod
url: /commands/hugo_mod/
---
## hugo mod
Various Hugo Modules helpers.
### Synopsis
Various helpers to help manage the modules in your project's dependency graph.
Most operations here requires a Go version installed on your system (>= Go 1.12) and the relevant VCS client (typically Git).
This is not needed if you only operate on modules inside /themes or if you have vendored them via "hugo mod vendor".
Note that Hugo will always start out by resolving the components defined in the site
configuration, provided by a _vendor directory (if no --ignoreVendor flag provided),
Go Modules, or a folder inside the themes directory, in that order.
See https://gohugo.io/hugo-modules/ for more information.
### Options
```
-b, --baseURL string hostname (and path) to the root, e.g. https://spf13.com/
-D, --buildDrafts include content marked as draft
-E, --buildExpired include expired content
-F, --buildFuture include content with publishdate in the future
--cacheDir string filesystem path to cache directory. Defaults: $TMPDIR/hugo_cache/
--cleanDestinationDir remove files from destination not found in static directories
-c, --contentDir string filesystem path to content directory
-d, --destination string filesystem path to write files to
--disableKinds strings disable different kind of pages (home, RSS etc.)
--enableGitInfo add Git revision, date and author info to the pages
--forceSyncStatic copy all files when static is changed.
--gc enable to run some cleanup tasks (remove unused cache files) after the build
-h, --help help for mod
--i18n-warnings print missing translations
--ignoreCache ignores the cache directory
-l, --layoutDir string filesystem path to layout directory
--minify minify any supported output format (HTML, XML etc.)
--noChmod don't sync permission mode of files
--noTimes don't sync modification time of files
--path-warnings print warnings on duplicate target paths etc.
--templateMetrics display metrics about template executions
--templateMetricsHints calculate some improvement hints when combined with --templateMetrics
-t, --theme strings themes to use (located in /themes/THEMENAME/)
--trace file write trace to file (not useful in general)
```
### Options inherited from parent commands
```
--config string config file (default is path/config.yaml|json|toml)
--configDir string config dir (default "config")
--debug debug output
-e, --environment string build environment
--ignoreVendor ignores any _vendor directory
--log enable Logging
--logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
-v, --verbose verbose output
--verboseLog verbose logging
```
### SEE ALSO
* [hugo](/commands/hugo/) - hugo builds your site
* [hugo mod clean](/commands/hugo_mod_clean/) - Delete the entire Hugo Module cache.
* [hugo mod get](/commands/hugo_mod_get/) - Resolves dependencies in your current Hugo Project.
* [hugo mod graph](/commands/hugo_mod_graph/) - Print a module dependency graph.
* [hugo mod init](/commands/hugo_mod_init/) - Initialize this project as a Hugo Module.
* [hugo mod tidy](/commands/hugo_mod_tidy/) - Remove unused entries in go.mod and go.sum.
* [hugo mod vendor](/commands/hugo_mod_vendor/) - Vendor all module dependencies into the _vendor directory.
###### Auto generated by spf13/cobra on 31-Jul-2019

52
docs/content/en/commands/hugo_mod_clean.md Normal file
View file

@ -0,0 +1,52 @@
---
date: 2019-07-31
title: "hugo mod clean"
slug: hugo_mod_clean
url: /commands/hugo_mod_clean/
---
## hugo mod clean
Delete the entire Hugo Module cache.
### Synopsis
Delete the entire Hugo Module cache.
Note that after you run this command, all of your dependencies will be re-downloaded next time you run "hugo".
Also note that if you configure a positive maxAge for the "modules" file cache, it will also be cleaned as part of "hugo --gc".
```
hugo mod clean [flags]
```
### Options
```
-h, --help help for clean
```
### Options inherited from parent commands
```
--config string config file (default is path/config.yaml|json|toml)
--configDir string config dir (default "config")
--debug debug output
-e, --environment string build environment
--ignoreVendor ignores any _vendor directory
--log enable Logging
--logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
-v, --verbose verbose output
--verboseLog verbose logging
```
### SEE ALSO
* [hugo mod](/commands/hugo_mod/) - Various Hugo Modules helpers.
###### Auto generated by spf13/cobra on 31-Jul-2019

71
docs/content/en/commands/hugo_mod_get.md Normal file
View file

@ -0,0 +1,71 @@
---
date: 2019-07-31
title: "hugo mod get"
slug: hugo_mod_get
url: /commands/hugo_mod_get/
---
## hugo mod get
Resolves dependencies in your current Hugo Project.
### Synopsis
Resolves dependencies in your current Hugo Project.
Some examples:
Install the latest version possible for a given module:
hugo mod get github.com/gohugoio/testshortcodes
Install a specific version:
hugo mod get github.com/gohugoio/testshortcodes@v0.3.0
Install the latest versions of all module dependencies:
hugo mod get -u
Run "go help get" for more information. All flags available for "go get" is also relevant here.
Note that Hugo will always start out by resolving the components defined in the site
configuration, provided by a _vendor directory (if no --ignoreVendor flag provided),
Go Modules, or a folder inside the themes directory, in that order.
See https://gohugo.io/hugo-modules/ for more information.
```
hugo mod get [flags]
```
### Options
```
-h, --help help for get
```
### Options inherited from parent commands
```
--config string config file (default is path/config.yaml|json|toml)
--configDir string config dir (default "config")
--debug debug output
-e, --environment string build environment
--ignoreVendor ignores any _vendor directory
--log enable Logging
--logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
-v, --verbose verbose output
--verboseLog verbose logging
```
### SEE ALSO
* [hugo mod](/commands/hugo_mod/) - Various Hugo Modules helpers.
###### Auto generated by spf13/cobra on 31-Jul-2019

48
docs/content/en/commands/hugo_mod_graph.md Normal file
View file

@ -0,0 +1,48 @@
---
date: 2019-07-31
title: "hugo mod graph"
slug: hugo_mod_graph
url: /commands/hugo_mod_graph/
---
## hugo mod graph
Print a module dependency graph.
### Synopsis
Print a module dependency graph with information about module status (disabled, vendored).
Note that for vendored modules, that is the version listed and not the one from go.mod.
```
hugo mod graph [flags]
```
### Options
```
-h, --help help for graph
```
### Options inherited from parent commands
```
--config string config file (default is path/config.yaml|json|toml)
--configDir string config dir (default "config")
--debug debug output
-e, --environment string build environment
--ignoreVendor ignores any _vendor directory
--log enable Logging
--logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
-v, --verbose verbose output
--verboseLog verbose logging
```
### SEE ALSO
* [hugo mod](/commands/hugo_mod/) - Various Hugo Modules helpers.
###### Auto generated by spf13/cobra on 31-Jul-2019

53
docs/content/en/commands/hugo_mod_init.md Normal file
View file

@ -0,0 +1,53 @@
---
date: 2019-07-31
title: "hugo mod init"
slug: hugo_mod_init
url: /commands/hugo_mod_init/
---
## hugo mod init
Initialize this project as a Hugo Module.
### Synopsis
Initialize this project as a Hugo Module.
It will try to guess the module path, but you may help by passing it as an argument, e.g:
hugo mod init github.com/gohugoio/testshortcodes
Note that Hugo Modules supports multi-module projects, so you can initialize a Hugo Module
inside a subfolder on GitHub, as one example.
```
hugo mod init [flags]
```
### Options
```
-h, --help help for init
```
### Options inherited from parent commands
```
--config string config file (default is path/config.yaml|json|toml)
--configDir string config dir (default "config")
--debug debug output
-e, --environment string build environment
--ignoreVendor ignores any _vendor directory
--log enable Logging
--logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
-v, --verbose verbose output
--verboseLog verbose logging
```
### SEE ALSO
* [hugo mod](/commands/hugo_mod/) - Various Hugo Modules helpers.
###### Auto generated by spf13/cobra on 31-Jul-2019

46
docs/content/en/commands/hugo_mod_tidy.md Normal file
View file

@ -0,0 +1,46 @@
---
date: 2019-07-31
title: "hugo mod tidy"
slug: hugo_mod_tidy
url: /commands/hugo_mod_tidy/
---
## hugo mod tidy
Remove unused entries in go.mod and go.sum.
### Synopsis
Remove unused entries in go.mod and go.sum.
```
hugo mod tidy [flags]
```
### Options
```
-h, --help help for tidy
```
### Options inherited from parent commands
```
--config string config file (default is path/config.yaml|json|toml)
--configDir string config dir (default "config")
--debug debug output
-e, --environment string build environment
--ignoreVendor ignores any _vendor directory
--log enable Logging
--logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
-v, --verbose verbose output
--verboseLog verbose logging
```
### SEE ALSO
* [hugo mod](/commands/hugo_mod/) - Various Hugo Modules helpers.
###### Auto generated by spf13/cobra on 31-Jul-2019

49
docs/content/en/commands/hugo_mod_vendor.md Normal file
View file

@ -0,0 +1,49 @@
---
date: 2019-07-31
title: "hugo mod vendor"
slug: hugo_mod_vendor
url: /commands/hugo_mod_vendor/
---
## hugo mod vendor
Vendor all module dependencies into the _vendor directory.
### Synopsis
Vendor all module dependencies into the _vendor directory.
If a module is vendored, that is where Hugo will look for it's dependencies.
```
hugo mod vendor [flags]
```
### Options
```
-h, --help help for vendor
```
### Options inherited from parent commands
```
--config string config file (default is path/config.yaml|json|toml)
--configDir string config dir (default "config")
--debug debug output
-e, --environment string build environment
--ignoreVendor ignores any _vendor directory
--log enable Logging
--logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
-v, --verbose verbose output
--verboseLog verbose logging
```
### SEE ALSO
* [hugo mod](/commands/hugo_mod/) - Various Hugo Modules helpers.
###### Auto generated by spf13/cobra on 31-Jul-2019

80
docs/content/en/commands/hugo_new.md Normal file
View file

@ -0,0 +1,80 @@
---
date: 2019-07-31
title: "hugo new"
slug: hugo_new
url: /commands/hugo_new/
---
## hugo new
Create new content for your site
### Synopsis
Create a new content file and automatically set the date and title.
It will guess which kind of file to create based on the path provided.
You can also specify the kind with `-k KIND`.
If archetypes are provided in your theme or site, they will be used.
Ensure you run this within the root directory of your site.
```
hugo new [path] [flags]
```
### Options
```
-b, --baseURL string hostname (and path) to the root, e.g. https://spf13.com/
-D, --buildDrafts include content marked as draft
-E, --buildExpired include expired content
-F, --buildFuture include content with publishdate in the future
--cacheDir string filesystem path to cache directory. Defaults: $TMPDIR/hugo_cache/
--cleanDestinationDir remove files from destination not found in static directories
-c, --contentDir string filesystem path to content directory
-d, --destination string filesystem path to write files to
--disableKinds strings disable different kind of pages (home, RSS etc.)
--editor string edit new content with this editor, if provided
--enableGitInfo add Git revision, date and author info to the pages
--forceSyncStatic copy all files when static is changed.
--gc enable to run some cleanup tasks (remove unused cache files) after the build
-h, --help help for new
--i18n-warnings print missing translations
--ignoreCache ignores the cache directory
-k, --kind string content type to create
-l, --layoutDir string filesystem path to layout directory
--minify minify any supported output format (HTML, XML etc.)
--noChmod don't sync permission mode of files
--noTimes don't sync modification time of files
--path-warnings print warnings on duplicate target paths etc.
--templateMetrics display metrics about template executions
--templateMetricsHints calculate some improvement hints when combined with --templateMetrics
-t, --theme strings themes to use (located in /themes/THEMENAME/)
--trace file write trace to file (not useful in general)
```
### Options inherited from parent commands
```
--config string config file (default is path/config.yaml|json|toml)
--configDir string config dir (default "config")
--debug debug output
-e, --environment string build environment
--ignoreVendor ignores any _vendor directory
--log enable Logging
--logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
-v, --verbose verbose output
--verboseLog verbose logging
```
### SEE ALSO
* [hugo](/commands/hugo/) - hugo builds your site
* [hugo new site](/commands/hugo_new_site/) - Create a new site (skeleton)
* [hugo new theme](/commands/hugo_new_theme/) - Create a new theme
###### Auto generated by spf13/cobra on 31-Jul-2019

50
docs/content/en/commands/hugo_new_site.md Normal file
View file

@ -0,0 +1,50 @@
---
date: 2019-07-31
title: "hugo new site"
slug: hugo_new_site
url: /commands/hugo_new_site/
---
## hugo new site
Create a new site (skeleton)
### Synopsis
Create a new site in the provided directory.
The new site will have the correct structure, but no content or theme yet.
Use `hugo new [contentPath]` to create new content.
```
hugo new site [path] [flags]
```
### Options
```
--force init inside non-empty directory
-f, --format string config & frontmatter format (default "toml")
-h, --help help for site
```
### Options inherited from parent commands
```
--config string config file (default is path/config.yaml|json|toml)
--configDir string config dir (default "config")
--debug debug output
-e, --environment string build environment
--ignoreVendor ignores any _vendor directory
--log enable Logging
--logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
-v, --verbose verbose output
--verboseLog verbose logging
```
### SEE ALSO
* [hugo new](/commands/hugo_new/) - Create new content for your site
###### Auto generated by spf13/cobra on 31-Jul-2019

49
docs/content/en/commands/hugo_new_theme.md Normal file
View file

@ -0,0 +1,49 @@
---
date: 2019-07-31
title: "hugo new theme"
slug: hugo_new_theme
url: /commands/hugo_new_theme/
---
## hugo new theme
Create a new theme
### Synopsis
Create a new theme (skeleton) called [name] in the current directory.
New theme is a skeleton. Please add content to the touched files. Add your
name to the copyright line in the license and adjust the theme.toml file
as you see fit.
```
hugo new theme [name] [flags]
```
### Options
```
-h, --help help for theme
```
### Options inherited from parent commands
```
--config string config file (default is path/config.yaml|json|toml)
--configDir string config dir (default "config")
--debug debug output
-e, --environment string build environment
--ignoreVendor ignores any _vendor directory
--log enable Logging
--logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
-v, --verbose verbose output
--verboseLog verbose logging
```
### SEE ALSO
* [hugo new](/commands/hugo_new/) - Create new content for your site
###### Auto generated by spf13/cobra on 31-Jul-2019

93
docs/content/en/commands/hugo_server.md Normal file
View file

@ -0,0 +1,93 @@
---
date: 2019-07-31
title: "hugo server"
slug: hugo_server
url: /commands/hugo_server/
---
## hugo server
A high performance webserver
### Synopsis
Hugo provides its own webserver which builds and serves the site.
While hugo server is high performance, it is a webserver with limited options.
Many run it in production, but the standard behavior is for people to use it
in development and use a more full featured server such as Nginx or Caddy.
'hugo server' will avoid writing the rendered and served content to disk,
preferring to store it in memory.
By default hugo will also watch your files for any changes you make and
automatically rebuild the site. It will then live reload any open browser pages
and push the latest content to them. As most Hugo sites are built in a fraction
of a second, you will be able to save and see your changes nearly instantly.
```
hugo server [flags]
```
### Options
```
--appendPort append port to baseURL (default true)
-b, --baseURL string hostname (and path) to the root, e.g. https://spf13.com/
--bind string interface to which the server will bind (default "127.0.0.1")
-D, --buildDrafts include content marked as draft
-E, --buildExpired include expired content
-F, --buildFuture include content with publishdate in the future
--cacheDir string filesystem path to cache directory. Defaults: $TMPDIR/hugo_cache/
--cleanDestinationDir remove files from destination not found in static directories
-c, --contentDir string filesystem path to content directory
-d, --destination string filesystem path to write files to
--disableBrowserError do not show build errors in the browser
--disableFastRender enables full re-renders on changes
--disableKinds strings disable different kind of pages (home, RSS etc.)
--disableLiveReload watch without enabling live browser reload on rebuild
--enableGitInfo add Git revision, date and author info to the pages
--forceSyncStatic copy all files when static is changed.
--gc enable to run some cleanup tasks (remove unused cache files) after the build
-h, --help help for server
--i18n-warnings print missing translations
--ignoreCache ignores the cache directory
-l, --layoutDir string filesystem path to layout directory
--liveReloadPort int port for live reloading (i.e. 443 in HTTPS proxy situations) (default -1)
--meminterval string interval to poll memory usage (requires --memstats), valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h". (default "100ms")
--memstats string log memory usage to this file
--minify minify any supported output format (HTML, XML etc.)
--navigateToChanged navigate to changed content file on live browser reload
--noChmod don't sync permission mode of files
--noHTTPCache prevent HTTP caching
--noTimes don't sync modification time of files
--path-warnings print warnings on duplicate target paths etc.
-p, --port int port on which the server will listen (default 1313)
--renderToDisk render to Destination path (default is render to memory & serve from there)
--templateMetrics display metrics about template executions
--templateMetricsHints calculate some improvement hints when combined with --templateMetrics
-t, --theme strings themes to use (located in /themes/THEMENAME/)
--trace file write trace to file (not useful in general)
-w, --watch watch filesystem for changes and recreate as needed (default true)
```
### Options inherited from parent commands
```
--config string config file (default is path/config.yaml|json|toml)
--configDir string config dir (default "config")
--debug debug output
-e, --environment string build environment
--ignoreVendor ignores any _vendor directory
--log enable Logging
--logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
-v, --verbose verbose output
--verboseLog verbose logging
```
### SEE ALSO
* [hugo](/commands/hugo/) - hugo builds your site
###### Auto generated by spf13/cobra on 31-Jul-2019

46
docs/content/en/commands/hugo_version.md Normal file
View file

@ -0,0 +1,46 @@
---
date: 2019-07-31
title: "hugo version"
slug: hugo_version
url: /commands/hugo_version/
---
## hugo version
Print the version number of Hugo
### Synopsis
All software has versions. This is Hugo's.
```
hugo version [flags]
```
### Options
```
-h, --help help for version
```
### Options inherited from parent commands
```
--config string config file (default is path/config.yaml|json|toml)
--configDir string config dir (default "config")
--debug debug output
-e, --environment string build environment
--ignoreVendor ignores any _vendor directory
--log enable Logging
--logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode
-s, --source string filesystem path to read files relative from
--themesDir string filesystem path to themes directory
-v, --verbose verbose output
--verboseLog verbose logging
```
### SEE ALSO
* [hugo](/commands/hugo/) - hugo builds your site
###### Auto generated by spf13/cobra on 31-Jul-2019

20
docs/content/en/content-management/_index.md Normal file
View file

@ -0,0 +1,20 @@
---
title: Content Management
linktitle: Content Management Overview
description: Hugo makes managing large static sites easy with support for archetypes, content types, menus, cross references, summaries, and more.
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
menu:
docs:
parent: "content-management"
weight: 1
keywords: [source, organization]
categories: [content management]
weight: 01 #rem
draft: false
aliases: [/content/,/content/organization]
toc: false
---
A static site generator needs to extend beyond front matter and a couple of templates to be both scalable and *manageable*. Hugo was designed with not only developers in mind, but also content managers and authors.

97
docs/content/en/content-management/archetypes.md Normal file
View file

@ -0,0 +1,97 @@
---
title: Archetypes
linktitle: Archetypes
description: Archetypes are templates used when creating new content.
date: 2017-02-01
publishdate: 2017-02-01
keywords: [archetypes,generators,metadata,front matter]
categories: ["content management"]
menu:
docs:
parent: "content-management"
weight: 70
quicklinks:
weight: 70 #rem
draft: false
aliases: [/content/archetypes/]
toc: true
---
## What are Archetypes?
**Archetypes** are content template files in the [archetypes directory][] of your project that contain preconfigured [front matter][] and possibly also a content disposition for your website's [content types][]. These will be used when you run `hugo new`.
The `hugo new` uses the `content-section` to find the most suitable archetype template in your project. If your project does not contain any archetype files, it will also look in the theme.
{{< code file="archetype-example.sh" >}}
hugo new posts/my-first-post.md
{{< /code >}}
The above will create a new content file in `content/posts/my-first-post.md` using the first archetype file found of these:
1. `archetypes/posts.md`
2. `archetypes/default.md`
3. `themes/my-theme/archetypes/posts.md`
4. `themes/my-theme/archetypes/default.md`
The last two list items are only applicable if you use a theme and it uses the `my-theme` theme name as an example.
## Create a New Archetype Template
A fictional example for the section `newsletter` and the archetype file `archetypes/newsletter.md`. Create a new file in `archetypes/newsletter.md` and open it in a text editor.
{{< code file="archetypes/newsletter.md" >}}
---
title: "{{ replace .Name "-" " " | title }}"
date: {{ .Date }}
draft: true
---
**Insert Lead paragraph here.**
## New Cool Posts
{{ range first 10 ( where .Site.RegularPages "Type" "cool" ) }}
* {{ .Title }}
{{ end }}
{{< /code >}}
When you create a new newsletter with:
```bash
hugo new newsletter/the-latest-cool.stuff.md
```
It will create a new newsletter type of content file based on the archetype template.
**Note:** the site will only be built if the `.Site` is in use in the archetype file, and this can be time consuming for big sites.
The above _newsletter type archetype_ illustrates the possibilities: The full Hugo `.Site` and all of Hugo&#39;s template funcs can be used in the archetype file.
## Directory based archetypes
Since Hugo `0.49` you can use complete directories as archetype templates. Given this archetype directory:
```bash
archetypes
├── default.md
└── post-bundle
├── bio.md
├── images
│ └── featured.jpg
└── index.md
```
```bash
hugo new --kind post-bundle posts/my-post
```
Will create a new folder in `/content/posts/my-post` with the same set of files as in the `post-bundle` archetypes folder. All content files (`index.md` etc.) can contain template logic, and will receive the correct `.Site` for the content's language.
[archetypes directory]: /getting-started/directory-structure/
[content types]: /content-management/types/
[front matter]: /content-management/front-matter/

184
docs/content/en/content-management/authors.md Normal file
View file

@ -0,0 +1,184 @@
---
title: Authors
linktitle: Authors
description:
date: 2016-08-22
publishdate: 2017-03-12
lastmod: 2017-03-12
keywords: [authors]
categories: ["content management"]
menu:
docs:
parent: "content-management"
weight: 55
weight: 55 #rem
draft: true
aliases: [/content/archetypes/]
toc: true
comments: Before this page is published, need to also update both site- and page-level variables documentation.
---
Larger sites often have multiple content authors. Hugo provides standardized author profiles to organize relationships between content and content creators for sites operating under a distributed authorship model.
## Author Profiles
You can create a profile containing metadata for each author on your website. These profiles have to be saved under `data/_authors/`. The filename of the profile will later be used as an identifier. This way Hugo can associate content with one or multiple authors. An author's profile can be defined in the JSON, YAML, or TOML format.
### Example: Author Profile
Let's suppose Alice Allison is a blogger. A simple unique identifier would be `alice`. Now, we have to create a file called `alice.toml` in the `data/_authors/` directory. The following example is the standardized template written in TOML:
{{< code file="data/_authors/alice.toml" >}}
givenName = "Alice" # or firstName as alias
familyName = "Allison" # or lastName as alias
displayName = "Alice Allison"
thumbnail = "static/authors/alice-thumb.jpg"
image = "static/authors/alice-full.jpg"
shortBio = "My name is Alice and I'm a blogger."
bio = "My name is Alice and I'm a blogger... some other stuff"
email = "alice.allison@email.com"
weight = 10
[social]
facebook = "alice.allison"
twitter = "alice"
website = "www.example.com"
[params]
random = "whatever you want"
{{< /code >}}
All variables are optional but it's advised to fill all important ones (e.g. names and biography) because themes can vary in their usage.
You can store files for the `thumbnail` and `image` attributes in the `static` folder. Then add the path to the photos relative to `static`; e.g., `/static/path/to/thumbnail.jpg`.
`weight` allows you to define the order of an author in an `.Authors` list and can be accessed on list or via the `.Site.Authors` variable.
The `social` section contains all the links to the social network accounts of an author. Hugo is able to generate the account links for the most popular social networks automatically. This way, you only have to enter your username. You can find a list of all supported social networks [here](#linking-social-network-accounts-automatically). All other variables, like `website` in the example above remain untouched.
The `params` section can contain arbitrary data much like the same-named section in the config file. What it contains is up to you.
## Associate Content Through Identifiers
Earlier it was mentioned that content can be associated with an author through their corresponding identifier. In our case, blogger Alice has the identifier `alice`. In the front matter of a content file, you can create a list of identifiers and assign it to the `authors` variable. Here are examples for `alice` using YAML and TOML, respectively.
```
---
title: Why Hugo is so Awesome
date: 2016-08-22T14:27:502:00
authors: ["alice"]
---
Nothing to read here. Move along...
```
```
+++
title = Why Hugo is so Awesome
date = "2016-08-22T14:27:502:00"
authors: ["alice"]
+++
Nothing to read here. Move along...
```
Future authors who might work on this blog post can append their identifiers to the `authors` array in the front matter as well.
## Work with Templates
After a successful setup it's time to give some credit to the authors by showing them on the website. Within the templates Hugo provides a list of the author's profiles if they are listed in the `authors` variable within the front matter.
The list is accessible via the `.Authors` template variable. Printing all authors of a the blog post is straight forward:
```
{{ range .Authors }}
{{ .DisplayName }}
{{ end }}
=> Alice Allison
```
Even if there are co-authors you may only want to show the main author. For this case you can use the `.Author` template variable **(note the singular form)**. The template variable contains the profile of the author that is first listed with his identifier in the front matter.
{{% note %}}
You can find a list of all template variables to access the profile information in [Author Variables](/variables/authors/).
{{% /note %}}
### Link Social Network Accounts
As aforementioned, Hugo is able to generate links to profiles of the most popular social networks. The following social networks with their corrersponding identifiers are supported: `github`, `facebook`, `twitter`, `pinterest`, `instagram`, `youtube` and `linkedin`.
This is can be done with the `.Social.URL` function. Its only parameter is the name of the social network as they are defined in the profile (e.g. `facebook`, `twitter`). Custom variables like `website` remain as they are.
Most articles feature a small section with information about the author at the end. Let's create one containing the author's name, a thumbnail, a (summarized) biography and links to all social networks:
{{< code file="layouts/partials/author-info.html" download="author-info.html" >}}
{{ with .Author }}
<h3>{{ .DisplayName }}</h3>
<img src="{{ .Thumbnail | absURL }}" alt="{{ .DisplayName }}">
<p>{{ .ShortBio }}</p>
<ul>
{{ range $network, $username := .Social }}
<li><a href="{{ $.Author.Social.URL $network }}">{{ $network }}</a></li>
{{ end }}
</ul>
{{ end }}
{{< /code >}}
## Who Published What?
That question can be answered with a list of all authors and another list containing all articles that they each have written. Now we have to translate this idea into templates. The [taxonomy][] feature allows us to logically group content based on information that they have in common; e.g. a tag or a category. Well, many articles share the same author, so this should sound familiar, right?
In order to let Hugo know that we want to group content based on their author, we have to create a new taxonomy called `author` (the name corresponds to the variable in the front matter). Here is the snippet in a `config.yaml` and `config.toml`, respectively:
```
taxonomies:
author: authors
```
```
[taxonomies]
author = "authors"
```
### List All Authors
In the next step we can create a template to list all authors of your website. Later, the list can be accessed at `www.example.com/authors/`. Create a new template in the `layouts/taxonomy/` directory called `authors.term.html`. This template will be exclusively used for this taxonomy.
{{< code file="layouts/taxonomy/author.term.html" download="author.term.html" >}}
<ul>
{{ range $author, $v := .Data.Terms }}
{{ $profile := $.Authors.Get $author }}
<li>
<a href="{{ printf "%s/%s/" $.Data.Plural $author | absURL }}">
{{ $profile.DisplayName }} - {{ $profile.ShortBio }}
</a>
</li>
{{ end }}
</ul>
{{< /code >}}
`.Data.Terms` contains the identifiers of all authors and we can range over it to create a list with all author names. The `$profile` variable gives us access to the profile of the current author. This allows you to generate a nice info box with a thumbnail, a biography and social media links, like at the [end of a blog post](#linking-social-network-accounts-automatically).
### List Each Author's Publications
Last but not least, we have to create the second list that contains all publications of an author. Each list will be shown in its own page and can be accessed at `www.example.com/authors/<IDENTIFIER>`. Replace `<IDENTIFIER>` with a valid author identifier like `alice`.
The layout for this page can be defined in the template `layouts/taxonomy/author.html`.
{{< code file="layouts/taxonomy/author.html" download="author.html" >}}
{{ range .Pages }}
<h2><a href="{{ .Permalink }}">{{ .Title }}</a></h2>
<span>written by {{ .Author.DisplayName }}</span>
{{ .Summary }}
{{ end }}
{{< /code >}}
The example above generates a simple list of all posts written by a single author. Inside the loop you've access to the complete set of [page variables][pagevars]. Therefore, you can add additional information about the current posts like the publishing date or the tags.
With a lot of content this list can quickly become very long. Consider to use the [pagination][] feature. It splits the list into smaller chunks and spreads them over multiple pages.
[pagevars]: /variables/page/
[pagination]: /templates/pagination/

88
docs/content/en/content-management/comments.md Normal file
View file

@ -0,0 +1,88 @@
---
title: Comments
linktitle: Comments
description: Hugo ships with an internal Disqus template, but this isn't the only commenting system that will work with your new Hugo website.
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-03-09
keywords: [sections,content,organization]
categories: [project organization, fundamentals]
menu:
docs:
parent: "content-management"
weight: 140
weight: 140 #rem
draft: false
aliases: [/extras/comments/]
toc: true
---
Hugo ships with support for [Disqus](https://disqus.com/), a third-party service that provides comment and community capabilities to websites via JavaScript.
Your theme may already support Disqus, but if not, it is easy to add to your templates via [Hugo's built-in Disqus partial][disquspartial].
## Add Disqus
Hugo comes with all the code you need to load Disqus into your templates. Before adding Disqus to your site, you'll need to [set up an account][disqussetup].
### Configure Disqus
Disqus comments require you set a single value in your [site's configuration file][configuration] like so:
{{< code-toggle copy="false" >}}
disqusShortname = "yourdiscussshortname"
{{</ code-toggle >}}
For many websites, this is enough configuration. However, you also have the option to set the following in the [front matter][] of a single content file:
* `disqus_identifier`
* `disqus_title`
* `disqus_url`
### Render Hugo's Built-in Disqus Partial Template
Disqus has its own [internal template](https://gohugo.io/templates/internal/#disqus) available, to render it add the following code where you want comments to appear:
```
{{ template "_internal/disqus.html" . }}
```
## Comments Alternatives
There are a few alternatives to commenting on static sites for those who do not want to use Disqus:
* [Static Man](https://staticman.net/)
* [Talkyard](https://www.talkyard.io/blog-comments) (Open source, & serverless hosting)
* [txtpen](https://txtpen.github.io/hn/)
* [IntenseDebate](https://intensedebate.com/)
* [Graph Comment][]
* [Muut](https://muut.com/)
* [isso](https://posativ.org/isso/) (Self-hosted, Python)
* [Tutorial on Implementing Isso with Hugo][issotutorial]
* [Utterances](https://utteranc.es/) (Open source, Github comments widget built on Github issues)
* [Remark](https://github.com/umputun/remark) (Open source, Golang, Easy to run docker)
* [Commento](https://commento.io/) (Open Source, available as a service, local install, or docker image)
* [JustComments](https://just-comments.com) (Open Source, available as a service, can be self-hosted)
<!-- I don't think this is worth including in the documentation since it seems that Steve is no longer supporting or developing this project. rdwatters - 2017-02-29.-->
<!-- * [Kaiju](https://github.com/spf13/kaiju) -->
<!-- ## Kaiju
[Kaiju](https://github.com/spf13/kaiju) is an open-source project started by [spf13](https://spf13.com/) (Hugo’s author) to bring easy and fast real time discussions to the web.
Written using Go, Socket.io, and [MongoDB][], Kaiju is very fast and easy to deploy.
It is in early development but shows promise. If you have interest, please help by contributing via pull request, [opening an issue in the Kaiju GitHub repository][kaijuissue], or [Tweeting about it][tweet]. Every bit helps. -->
[configuration]: /getting-started/configuration/
[disquspartial]: /templates/partials/#disqus
[disqussetup]: https://disqus.com/profile/signup/
[forum]: https://discourse.gohugo.io
[front matter]: /content-management/front-matter/
[Graph Comment]: https://graphcomment.com/
[kaijuissue]: https://github.com/spf13/kaiju/issues/new
[issotutorial]: https://stiobhart.net/2017-02-24-isso-comments/
[partials]: /templates/partials/
[MongoDB]: https://www.mongodb.com/
[tweet]: https://twitter.com/spf13

100
docs/content/en/content-management/cross-references.md Normal file
View file

@ -0,0 +1,100 @@
---
title: Links and Cross References
description: Shortcodes for creating links to documents.
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-03-31
categories: [content management]
keywords: ["cross references","references", "anchors", "urls"]
menu:
docs:
parent: "content-management"
weight: 100
weight: 100 #rem
aliases: [/extras/crossreferences/]
toc: true
---
The `ref` and `relref` shortcode resolves the absolute or relative permalink given a path to a document.
## Use `ref` and `relref`
```go-html-template
{{</* ref "document.md" */>}}
{{</* ref "#anchor" */>}}
{{</* ref "document.md#anchor" */>}}
{{</* ref "/blog/my-post" */>}}
{{</* ref "/blog/my-post.md" */>}}
{{</* relref "document.md" */>}}
{{</* relref "#anchor" */>}}
{{</* relref "document.md#anchor" */>}}
```
The single parameter to `ref` is a string with a content `documentname` (e.g., `about.md`) with or without an appended in-document `anchor` (`#who`) without spaces. Hugo is flexible in how we search for documents, so the file suffix may be omitted.
**Paths without a leading `/` will first be tried resolved relative to the current page.**
You will get an error if your document could not be uniquely resolved. The error behaviour can be configured, see below.
### Link to another language version
Link to another language version of a document, you need to use this syntax:
```go-html-template
{{</* relref path="document.md" lang="ja" */>}}
```
### Get another Output Format
To link to a given Output Format of a document, you can use this syntax:
```go-html-template
{{</* relref path="document.md" outputFormat="rss" */>}}
```
### Anchors
When an `anchor` is provided by itself, the current page’s unique identifier will be appended; when an `anchor` is provided appended to `documentname`, the found page's unique identifier will be appended:
```go-html-template
{{</* relref "#anchors" */>}} => #anchors:9decaf7
```
The above examples render as follows for this very page as well as a reference to the "Content" heading in the Hugo docs features pageyoursite
```go-html-template
{{</* relref "#who" */>}} => #who:9decaf7
{{</* relref "/blog/post.md#who" */>}} => /blog/post/#who:badcafe
```
More information about document unique identifiers and headings can be found [below]({{< ref "#hugo-heading-anchors" >}}).
## Hugo Heading Anchors
When using Markdown document types, Hugo generates heading anchors automatically. The generated anchor for this section is `hugo-heading-anchors`. Because the heading anchors are generated automatically, Hugo takes some effort to ensure that heading anchors are unique both inside a document and across the entire site.
Ensuring heading uniqueness across the site is accomplished with a unique identifier for each document based on its path. Unless a document is renamed or moved between sections *in the filesystem*, the unique identifier for the document will not change: `blog/post.md` will always have a unique identifier of `81df004c333b392d34a49fd3a91ba720`.
`ref` and `relref` were added so you can make these reference links without having to know the document’s unique identifier. (The links in document tables of contents are automatically up-to-date with this value.)
```
{{</* relref "content-management/cross-references.md#hugo-heading-anchors" */>}}
/content-management/cross-references/#hugo-heading-anchors:77cd9ea530577debf4ce0f28c8dca242
```
## Ref and RelRef Configuration
The behaviour can, since Hugo 0.45, be configured in `config.toml`:
refLinksErrorLevel ("ERROR")
: When using `ref` or `relref` to resolve page links and a link cannot resolved, it will be logged with this log level. Valid values are `ERROR` (default) or `WARNING`. Any `ERROR` will fail the build (`exit -1`).
refLinksNotFoundURL
: URL to be used as a placeholder when a page reference cannot be found in `ref` or `relref`. Is used as-is.
[lists]: /templates/lists/
[output formats]: /templates/output-formats/
[shortcode]: /content-management/shortcodes/
[bfext]: /content-management/formats/#blackfriday-extensions

248
docs/content/en/content-management/formats.md Normal file
View file

@ -0,0 +1,248 @@
---
title: Supported Content Formats
linktitle: Supported Content Formats
description: Both HTML and Markdown are supported content formats.
date: 2017-01-10
publishdate: 2017-01-10
lastmod: 2017-04-06
categories: [content management]
keywords: [markdown,asciidoc,mmark,pandoc,content format]
menu:
docs:
parent: "content-management"
weight: 20
weight: 20 #rem
draft: false
aliases: [/content/markdown-extras/,/content/supported-formats/,/doc/supported-formats/,/tutorials/mathjax/]
toc: true
---
**Markdown is the main content format** and comes in two flavours: The excellent [Blackfriday project][blackfriday] (name your files `*.md` or set `markup = "markdown"` in front matter) or its fork [Mmark][mmark] (name your files `*.mmark` or set `markup = "mmark"` in front matter), both very fast markdown engines written in Go.
For Emacs users, [go-org](https://github.com/niklasfasching/go-org) provides built-in native support for Org-mode (name your files `*.org` or set `markup = "org"` in front matter)
But in many situations, plain HTML is what you want. Just name your files with `.html` or `.htm` extension inside your content folder. Note that if you want your HTML files to have a layout, they need front matter. It can be empty, but it has to be there:
```html
---
title: "This is a content file in HTML"
---
<div>
<h1>Hello, Hugo!</h1>
</div>
```
{{% note "Deeply Nested Lists" %}}
Before you begin writing your content in markdown, Blackfriday has a known issue [(#329)](https://github.com/russross/blackfriday/issues/329) with handling deeply nested lists. Luckily, there is an easy workaround. Use 4-spaces (i.e., <kbd>tab</kbd>) rather than 2-space indentations.
{{% /note %}}
## Configure BlackFriday Markdown Rendering
You can configure multiple aspects of Blackfriday as shown in the following list. See the docs on [Configuration][config] for the full list of explicit directions you can give to Hugo when rendering your site.
{{< readfile file="/content/en/readfiles/bfconfig.md" markdown="true" >}}
## Extend Markdown
Hugo provides some convenient methods for extending markdown.
### Task Lists
Hugo supports [GitHub-styled task lists (i.e., TODO lists)][gfmtasks] for the Blackfriday markdown renderer. If you do not want to use this feature, you can disable it in your configuration.
#### Example Task List Input
{{< code file="content/my-to-do-list.md" >}}
- [ ] a task list item
- [ ] list syntax required
- [ ] incomplete
- [x] completed
{{< /code >}}
#### Example Task List Output
The preceding markdown produces the following HTML in your rendered website:
```
<ul class="task-list">
<li><input type="checkbox" disabled="" class="task-list-item"> a task list item</li>
<li><input type="checkbox" disabled="" class="task-list-item"> list syntax required</li>
<li><input type="checkbox" disabled="" class="task-list-item"> incomplete</li>
<li><input type="checkbox" checked="" disabled="" class="task-list-item"> completed</li>
</ul>
```
#### Example Task List Display
The following shows how the example task list will look to the end users of your website. Note that visual styling of lists is up to you. This list has been styled according to [the Hugo Docs stylesheet][hugocss].
- [ ] a task list item
- [ ] list syntax required
- [ ] incomplete
- [x] completed
### Emojis
To add emojis directly to content, set `enableEmoji` to `true` in your [site configuration][config]. To use emojis in templates or shortcodes, see [`emojify` function][].
For a full list of emojis, see the [Emoji cheat sheet][emojis].
### Shortcodes
If you write in Markdown and find yourself frequently embedding your content with raw HTML, Hugo provides built-in shortcodes functionality. This is one of the most powerful features in Hugo and allows you to create your own Markdown extensions very quickly.
See [Shortcodes][sc] for usage, particularly for the built-in shortcodes that ship with Hugo, and [Shortcode Templating][sct] to learn how to build your own.
### Code Blocks
Hugo supports GitHub-flavored markdown's use of triple back ticks, as well as provides a special [`highlight` shortcode][hlsc], and syntax highlights those code blocks natively using *Chroma*. Users also have an option to use *Pygments* instead. See the [Syntax Highlighting][hl] section for details.
## Mmark
Mmark is a [fork of BlackFriday][mmark] and markdown superset that is well suited for writing [IETF documentation][ietf]. You can see examples of the syntax in the [Mmark GitHub repository][mmark] or the full syntax on [Miek Gieben's website][].
### Use Mmark
As Hugo ships with Mmark, using the syntax is as easy as changing the extension of your content files from `.md` to `.mmark`.
In the event that you want to only use Mmark in specific files, you can also define the Mmark syntax in your content's front matter:
```
---
title: My Post
date: 2017-04-01
markup: mmark
---
```
{{% warning %}}
Thare are some features not available in Mmark; one example being that shortcodes are not translated when used in an included `.mmark` file ([#3131](https://github.com/gohugoio/hugo/issues/3137)), and `EXTENSION_ABBREVIATION` ([#1970](https://github.com/gohugoio/hugo/issues/1970)) and the aforementioned GFM todo lists ([#2270](https://github.com/gohugoio/hugo/issues/2270)) are not fully supported. Contributions are welcome.
{{% /warning %}}
## MathJax with Hugo
[MathJax](https://www.mathjax.org/) is a JavaScript library that allows the display of mathematical expressions described via a LaTeX-style syntax in the HTML (or Markdown) source of a web page. As it is a pure a JavaScript library, getting it to work within Hugo is fairly straightforward, but does have some oddities that will be discussed here.
This is not an introduction into actually using MathJax to render typeset mathematics on your website. Instead, this page is a collection of tips and hints for one way to get MathJax working on a website built with Hugo.
### Enable MathJax
The first step is to enable MathJax on pages that you would like to have typeset math. There are multiple ways to do this (adventurous readers can consult the [Loading and Configuring](https://docs.mathjax.org/en/latest/web/configuration.html) section of the MathJax documentation for additional methods of including MathJax), but the easiest way is to use the secure MathJax CDN by include a `<script>` tag for the officially recommended secure CDN ([cdn.js.com](https://cdnjs.com)):
{{< code file="add-mathjax-to-page.html" >}}
<script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>
{{< /code >}}
One way to ensure that this code is included in all pages is to put it in one of the templates that live in the `layouts/partials/` directory. For example, I have included this in the bottom of my template `footer.html` because I know that the footer will be included in every page of my website.
### Options and Features
MathJax is a stable open-source library with many features. I encourage the interested reader to view the [MathJax Documentation](https://docs.mathjax.org/en/latest/index.html), specifically the sections on [Basic Usage](http://docs.mathjax.org/en/latest/index.html#basic-usage) and [MathJax Configuration Options](http://docs.mathjax.org/en/latest/index.html#mathjax-configuration-options).
### Issues with Markdown
{{% note %}}
The following issues with Markdown assume you are using `.md` for content and BlackFriday for parsing. Using [Mmark](#mmark) as your content format will obviate the need for the following workarounds.
When using Mmark with MathJax, use `displayMath: [['$$','$$'], ['\\[','\\]']]`. See the [Mmark `README.md`](https://github.com/miekg/mmark/wiki/Syntax#math-blocks) for more information. In addition to MathJax, Mmark has been shown to work well with [KaTeX](https://github.com/Khan/KaTeX). See this [related blog post from a Hugo user](http://nosubstance.me/post/a-great-toolset-for-static-blogging/).
{{% /note %}}
After enabling MathJax, any math entered between proper markers (see the [MathJax documentation][mathjaxdocs]) will be processed and typeset in the web page. One issue that comes up, however, with Markdown is that the underscore character (`_`) is interpreted by Markdown as a way to wrap text in `emph` blocks while LaTeX (MathJax) interprets the underscore as a way to create a subscript. This "double speak" of the underscore can result in some unexpected and unwanted behavior.
### Solution
There are multiple ways to remedy this problem. One solution is to simply escape each underscore in your math code by entering `\_` instead of `_`. This can become quite tedious if the equations you are entering are full of subscripts.
Another option is to tell Markdown to treat the MathJax code as verbatim code and not process it. One way to do this is to wrap the math expression inside a `<div>` `</div>` block. Markdown would ignore these sections and they would get passed directly on to MathJax and processed correctly. This works great for display style mathematics, but for inline math expressions the line break induced by the `<div>` is not acceptable. The syntax for instructing Markdown to treat inline text as verbatim is by wrapping it in backticks (`` ` ``). You might have noticed, however, that the text included in between backticks is rendered differently than standard text (on this site these are items highlighted in red). To get around this problem, we could create a new CSS entry that would apply standard styling to all inline verbatim text that includes MathJax code. Below I will show the HTML and CSS source that would accomplish this (note this solution was adapted from [this blog post](http://doswa.com/2011/07/20/mathjax-in-markdown.html)---all credit goes to the original author).
{{< code file="mathjax-markdown-solution.html" >}}
<script type="text/x-mathjax-config">
MathJax.Hub.Config({
tex2jax: {
inlineMath: [['$','$'], ['\\(','\\)']],
displayMath: [['$$','$$'], ['\[','\]']],
processEscapes: true,
processEnvironments: true,
skipTags: ['script', 'noscript', 'style', 'textarea', 'pre'],
TeX: { equationNumbers: { autoNumber: "AMS" },
extensions: ["AMSmath.js", "AMSsymbols.js"] }
}
});
</script>
{{< /code >}}
As before, this content should be included in the HTML source of each page that will be using MathJax. The next code snippet contains the CSS that is used to have verbatim MathJax blocks render with the same font style as the body of the page.
{{< code file="mathjax-style.css" >}}
code.has-jax {
font: inherit;
font-size: 100%;
background: inherit;
border: inherit;
color: #515151;
}
{{< /code >}}
In the CSS snippet, notice the line `color: #515151;`. `#515151` is the value assigned to the `color` attribute of the `body` class in my CSS. In order for the equations to fit in with the body of a web page, this value should be the same as the color of the body.
### Usage
With this setup, everything is in place for a natural usage of MathJax on pages generated using Hugo. In order to include inline mathematics, just put LaTeX code in between `` `$ TeX Code $` `` or `` `\( TeX Code \)` ``. To include display style mathematics, just put LaTeX code in between `<div>$$TeX Code$$</div>`. All the math will be properly typeset and displayed within your Hugo generated web page!
## Additional Formats Through External Helpers
Hugo has a new concept called _external helpers_. It means that you can write your content using [Asciidoc][ascii], [reStructuredText][rest], or [pandoc]. If you have files with associated extensions, Hugo will call external commands to generate the content. ([See the Hugo source code for external helpers][helperssource].)
For example, for Asciidoc files, Hugo will try to call the `asciidoctor` or `asciidoc` command. This means that you will have to install the associated tool on your machine to be able to use these formats. ([See the Asciidoctor docs for installation instructions](https://asciidoctor.org/docs/install-toolchain/)).
To use these formats, just use the standard extension and the front matter exactly as you would do with natively supported `.md` files.
Hugo passes reasonable default arguments to these external helpers by default:
- `asciidoc`: `--no-header-footer --safe -`
- `asciidoctor`: `--no-header-footer --safe --trace -`
- `rst2html`: `--leave-comments --initial-header-level=2`
- `pandoc`: `--mathjax`
{{% warning "Performance of External Helpers" %}}
Because additional formats are external commands generation performance will rely heavily on the performance of the external tool you are using. As this feature is still in its infancy, feedback is welcome.
{{% /warning %}}
## Learn Markdown
Markdown syntax is simple enough to learn in a single sitting. The following are excellent resources to get you up and running:
* [Daring Fireball: Markdown, John Gruber (Creator of Markdown)][fireball]
* [Markdown Cheatsheet, Adam Pritchard][mdcheatsheet]
* [Markdown Tutorial (Interactive), Garen Torikian][mdtutorial]
* [The Markdown Guide, Matt Cone][mdguide]
[`emojify` function]: /functions/emojify/
[ascii]: https://asciidoctor.org/
[bfconfig]: /getting-started/configuration/#configuring-blackfriday-rendering
[blackfriday]: https://github.com/russross/blackfriday
[mmark]: https://github.com/miekg/mmark
[config]: /getting-started/configuration/
[developer tools]: /tools/
[emojis]: https://www.webpagefx.com/tools/emoji-cheat-sheet/
[fireball]: https://daringfireball.net/projects/markdown/
[gfmtasks]: https://guides.github.com/features/mastering-markdown/#syntax
[helperssource]: https://github.com/gohugoio/hugo/blob/77c60a3440806067109347d04eb5368b65ea0fe8/helpers/general.go#L65
[hl]: /content-management/syntax-highlighting/
[hlsc]: /content-management/shortcodes/#highlight
[hugocss]: /css/style.css
[ietf]: https://tools.ietf.org/html/
[mathjaxdocs]: https://docs.mathjax.org/en/latest/
[mdcheatsheet]: https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet
[mdguide]: https://www.markdownguide.org/
[mdtutorial]: https://www.markdowntutorial.com/
[Miek Gieben's website]: https://miek.nl/2016/march/05/mmark-syntax-document/
[mmark]: https://github.com/mmarkdown/mmark
[org]: https://orgmode.org/
[pandoc]: https://www.pandoc.org/
[Pygments]: http://pygments.org/
[rest]: http://docutils.sourceforge.net/rst.html
[sc]: /content-management/shortcodes/
[sct]: /templates/shortcode-templates/

210
docs/content/en/content-management/front-matter.md Normal file
View file

@ -0,0 +1,210 @@
---
title: Front Matter
linktitle:
description: Hugo allows you to add front matter in yaml, toml, or json to your content files.
date: 2017-01-09
publishdate: 2017-01-09
lastmod: 2017-02-24
categories: [content management]
keywords: ["front matter", "yaml", "toml", "json", "metadata", "archetypes"]
menu:
docs:
parent: "content-management"
weight: 30
weight: 30 #rem
draft: false
aliases: [/content/front-matter/]
toc: true
---
**Front matter** allows you to keep metadata attached to an instance of a [content type][]---i.e., embedded inside a content file---and is one of the many features that gives Hugo its strength.
{{< youtube Yh2xKRJGff4 >}}
## Front Matter Formats
Hugo supports four formats for front matter, each with their own identifying tokens.
TOML
: identified by opening and closing `+++`.
YAML
: identified by opening and closing `---`.
JSON
: a single JSON object surrounded by '`{`' and '`}`', followed by a new line.
ORG
: a group of Org mode keywords in the format '`#+KEY: VALUE`'. Any line that does not start with `#+` ends the front matter section.
Keyword values can be either strings (`#+KEY: VALUE`) or a whitespace separated list of strings (`#+KEY[]: VALUE_1 VALUE_2`).
### Example
{{< code-toggle >}}
title = "spf13-vim 3.0 release and new website"
description = "spf13-vim is a cross platform distribution of vim plugins and resources for Vim."
tags = [ ".vimrc", "plugins", "spf13-vim", "vim" ]
date = "2012-04-06"
categories = [
"Development",
"VIM"
]
slug = "spf13-vim-3-0-release-and-new-website"
{{< /code-toggle >}}
## Front Matter Variables
### Predefined
There are a few predefined variables that Hugo is aware of. See [Page Variables][pagevars] for how to call many of these predefined variables in your templates.
aliases
: an array of one or more aliases (e.g., old published paths of renamed content) that will be created in the output directory structure . See [Aliases][aliases] for details.
audio
: an array of paths to audio files related to the page; used by the `opengraph` [internal template](/templates/internal) to populate `og:audio`.
cascade
: a map of Front Matter keys whose values are passed down to the page's descendents unless overwritten by self or a closer ancestor's cascade. See [Front Matter Cascade](#front-matter-cascade) for details.
date
: the datetime assigned to this page. This is usually fetched from the `date` field in front matter, but this behaviour is configurable.
description
: the description for the content.
draft
: if `true`, the content will not be rendered unless the `--buildDrafts` flag is passed to the `hugo` command.
expiryDate
: the datetime at which the content should no longer be published by Hugo; expired content will not be rendered unless the `--buildExpired` flag is passed to the `hugo` command.
headless
: if `true`, sets a leaf bundle to be [headless][headless-bundle].
images
: an array of paths to images related to the page; used by [internal templates](/templates/internal) such as `_internal/twitter_cards.html`.
isCJKLanguage
: if `true`, Hugo will explicitly treat the content as a CJK language; both `.Summary` and `.WordCount` work properly in CJK languages.
keywords
: the meta keywords for the content.
layout
: the layout Hugo should select from the [lookup order][lookup] when rendering the content. If a `type` is not specified in the front matter, Hugo will look for the layout of the same name in the layout directory that corresponds with a content's section. See ["Defining a Content Type"][definetype]
lastmod
: the datetime at which the content was last modified.
linkTitle
: used for creating links to content; if set, Hugo defaults to using the `linktitle` before the `title`. Hugo can also [order lists of content by `linktitle`][bylinktitle].
markup
: **experimental**; specify `"rst"` for reStructuredText (requires`rst2html`) or `"md"` (default) for Markdown.
outputs
: allows you to specify output formats specific to the content. See [output formats][outputs].
publishDate
: if in the future, content will not be rendered unless the `--buildFuture` flag is passed to `hugo`.
resources
: used for configuring page bundle resources. See [Page Resources][page-resources].
series
: an array of series this page belongs to, as a subset of the `series` [taxonomy](/content-management/taxonomies/); used by the `opengraph` [internal template](/templates/internal) to populate `og:see_also`.
slug
: appears as the tail of the output URL. A value specified in front matter will override the segment of the URL based on the filename.
summary
: text used when providing a summary of the article in the `.Summary` page variable; details available in the [content-summaries](/content-management/summaries/) section.
title
: the title for the content.
type
: the type of the content; this value will be automatically derived from the directory (i.e., the [section][]) if not specified in front matter.
url
: the full path to the content from the web root. It makes no assumptions about the path of the content file. It also ignores any language prefixes of
the multilingual feature.
videos
: an array of paths to videos related to the page; used by the `opengraph` [internal template](/templates/internal) to populate `og:video`.
weight
: used for [ordering your content in lists][ordering]. Lower weight gets higher precedence. So content with lower weight will come first.
\<taxonomies\>
: field name of the *plural* form of the index. See `tags` and `categories` in the above front matter examples. _Note that the plural form of user-defined taxonomies cannot be the same as any of the predefined front matter variables._
{{% note "Hugo's Default URL Destinations" %}}
If neither `slug` nor `url` is present and [permalinks are not configured otherwise in your site `config` file](/content-management/urls/#permalinks), Hugo will use the filename of your content to create the output URL. See [Content Organization](/content-management/organization) for an explanation of paths in Hugo and [URL Management](/content-management/urls/) for ways to customize Hugo's default behaviors.
{{% /note %}}
### User-Defined
You can add fields to your front matter arbitrarily to meet your needs. These user-defined key-values are placed into a single `.Params` variable for use in your templates.
The following fields can be accessed via `.Params.include_toc` and `.Params.show_comments`, respectively. The [Variables][] section provides more information on using Hugo's page- and site-level variables in your templates.
{{< code-toggle copy="false" >}}
include_toc: true
show_comments: false
{{</ code-toggle >}}
## Front Matter Cascade
Any node or section can pass down to descendents a set of Front Matter values as long as defined underneath the reserved `cascade` Front Matter key.
### Example
```yaml
# content/blog/_index.md
title: Blog
cascade:
banner: images/typewriter.jpg
```
With the above example the Blog section page and its descendents will return `images/typewriter.jpg` when `.Params.banner` is invoked unless:
- Said descendent has its own `banner` value set
- Or a closer ancestor node has its own `cascade.banner` value set.
## Order Content Through Front Matter
You can assign content-specific `weight` in the front matter of your content. These values are especially useful for [ordering][ordering] in list views. You can use `weight` for ordering of content and the convention of [`<TAXONOMY>_weight`][taxweight] for ordering content within a taxonomy. See [Ordering and Grouping Hugo Lists][lists] to see how `weight` can be used to organize your content in list views.
## Override Global Markdown Configuration
It's possible to set some options for Markdown rendering in a content's front matter as an override to the [BlackFriday rendering options set in your project configuration][config].
## Front Matter Format Specs
* [TOML Spec][toml]
* [YAML Spec][yaml]
* [JSON Spec][json]
[variables]: /variables/
[aliases]: /content-management/urls/#aliases
[archetype]: /content-management/archetypes/
[bylinktitle]: /templates/lists/#by-link-title
[config]: /getting-started/configuration/ "Hugo documentation for site configuration"
[content type]: /content-management/types/
[contentorg]: /content-management/organization/
[definetype]: /content-management/types/#defining-a-content-type "Learn how to specify a type and a layout in a content's front matter"
[headless-bundle]: /content-management/page-bundles/#headless-bundle
[json]: https://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf "Specification for JSON, JavaScript Object Notation"
[lists]: /templates/lists/#ordering-content "See how to order content in list pages; for example, templates that look to specific _index.md for content and front matter."
[lookup]: /templates/lookup-order/ "Hugo traverses your templates in a specific order when rendering content to allow for DRYer templating."
[ordering]: /templates/lists/ "Hugo provides multiple ways to sort and order your content in list templates"
[outputs]: /templates/output-formats/ "With the release of v22, you can output your content to any text format using Hugo's familiar templating"
[page-resources]: /content-management/page-resources/
[pagevars]: /variables/page/
[section]: /content-management/sections/
[taxweight]: /content-management/taxonomies/
[toml]: https://github.com/toml-lang/toml "Specification for TOML, Tom's Obvious Minimal Language"
[urls]: /content-management/urls/
[variables]: /variables/
[yaml]: https://yaml.org/spec/ "Specification for YAML, YAML Ain't Markup Language"

292
docs/content/en/content-management/image-processing/index.md Normal file
View file

@ -0,0 +1,292 @@
---
title: "Image Processing"
description: "Image Page resources can be resized and cropped."
date: 2018-01-24T13:10:00-05:00
linktitle: "Image Processing"
categories: ["content management"]
keywords: [resources,images]
weight: 4004
draft: false
toc: true
menu:
docs:
parent: "content-management"
weight: 32
---
## The Image Page Resource
The `image` is a [Page Resource]({{< relref "/content-management/page-resources" >}}), and the processing methods listed below does not work on images inside your `/static` folder.
To get all images in a [Page Bundle]({{< relref "/content-management/organization#page-bundles" >}}):
```go-html-template
{{ with .Resources.ByType "image" }}
{{ end }}
```
## Image Processing Methods
The `image` resource implements the methods `Resize`, `Fit` and `Fill`, each returning the transformed image using the specified dimensions and processing options. The `image` resource also, since Hugo 0.58, implements the method `Exif` and `Filter`.
### Resize
Resizes the image to the specified width and height.
```go
// Resize to a width of 600px and preserve ratio
{{ $image := $resource.Resize "600x" }}
// Resize to a height of 400px and preserve ratio
{{ $image := $resource.Resize "x400" }}
// Resize to a width 600px and a height of 400px
{{ $image := $resource.Resize "600x400" }}
```
### Fit
Scale down the image to fit the given dimensions while maintaining aspect ratio. Both height and width are required.
```go
{{ $image := $resource.Fit "600x400" }}
```
### Fill
Resize and crop the image to match the given dimensions. Both height and width are required.
```go
{{ $image := $resource.Fill "600x400" }}
```
### Filter
Apply one or more filters to your image. See [Image Filters](/functions/images/#image-filters) for a full list.
```go-html-template
{{ $img = $img.Filter (images.GaussianBlur 6) (images.Pixelate 8) }}
```
The above can also be written in a more functional style using pipes:
```go-html-template
{{ $img = $img | images.Filter (images.GaussianBlur 6) (images.Pixelate 8) }}
```
The filters will be applied in the given order.
Sometimes it can be useful to create the filter chain once and then reuse it:
```go-html-template
{{ $filters := slice (images.GaussianBlur 6) (images.Pixelate 8) }}
{{ $img1 = $img1.Filter $filters }}
{{ $img2 = $img2.Filter $filters }}
```
### Exif
Provides an [Exif](https://en.wikipedia.org/wiki/Exif) object with metadata about the image.
Note that this is only suported for JPG and TIFF images, so it's recommended to wrap the access with a `with`, e.g.:
```go-html-template
{{ with $img.Exif }}
Date: {{ .Date }}
Lat/Long: {{ .Lat}}/{{ .Long }}
Tags:
{{ range $k, $v := .Tags }}
TAG: {{ $k }}: {{ $v }}
{{ end }}
```
#### Exif fields
Data
: "photo taken" date/time
Lat
: "photo taken where", GPS latitude
Long
: "photo taken where", GPS longitude
See [Image Processing Config](#image-processing-config) for how to configure what gets included in Exif.
## Image Processing Options
In addition to the dimensions (e.g. `600x400`), Hugo supports a set of additional image options.
### Background Color
The background color to fill into the transparency layer. This is mostly useful when converting to a format that does not support transparency, e.g. `JPEG`.
You can set the background color to use with a 3 or 6 digit hex code starting with `#`.
```go
{{ $image.Resize "600x jpg #b31280" }}
```
For color codes, see https://www.google.com/search?q=color+picker
### JPEG Quality
Only relevant for JPEG images, values 1 to 100 inclusive, higher is better. Default is 75.
```go
{{ $image.Resize "600x q50" }}
```
### Rotate
Rotates an image by the given angle counter-clockwise. The rotation will be performed first to get the dimensions correct. The main use of this is to be able to manually correct for [EXIF orientation](https://github.com/golang/go/issues/4341) of JPEG images.
```go
{{ $image.Resize "600x r90" }}
```
### Anchor
Only relevant for the `Fill` method. This is useful for thumbnail generation where the main motive is located in, say, the left corner.
Valid are `Center`, `TopLeft`, `Top`, `TopRight`, `Left`, `Right`, `BottomLeft`, `Bottom`, `BottomRight`.
```go
{{ $image.Fill "300x200 BottomLeft" }}
```
### Resample Filter
Filter used in resizing. Default is `Box`, a simple and fast resampling filter appropriate for downscaling.
Examples are: `Box`, `NearestNeighbor`, `Linear`, `Gaussian`.
See https://github.com/disintegration/imaging for more. If you want to trade quality for faster processing, this may be a option to test.
```go
{{ $image.Resize "600x400 Gaussian" }}
```
### Target Format
By default the images is encoded in the source format, but you can set the target format as an option.
Valid values are `jpg`, `png`, `tif`, `bmp`, and `gif`.
```go
{{ $image.Resize "600x jpg" }}
```
## Image Processing Examples
_The photo of the sunset used in the examples below is Copyright [Bjørn Erik Pedersen](https://commons.wikimedia.org/wiki/User:Bep) (Creative Commons Attribution-Share Alike 4.0 International license)_
{{< imgproc sunset Resize "300x" />}}
{{< imgproc sunset Fill "90x120 left" />}}
{{< imgproc sunset Fill "90x120 right" />}}
{{< imgproc sunset Fit "90x90" />}}
{{< imgproc sunset Resize "300x q10" />}}
This is the shortcode used in the examples above:
{{< code file="layouts/shortcodes/imgproc.html" >}}
{{< readfile file="layouts/shortcodes/imgproc.html" >}}
{{< /code >}}
And it is used like this:
```go-html-template
{{</* imgproc sunset Resize "300x" /*/>}}
```
{{% note %}}
**Tip:** Note the self-closing shortcode syntax above. The `imgproc` shortcode can be called both with and without **inner content**.
{{% /note %}}
## Image Processing Config
You can configure an `imaging` section in `config.toml` with default image processing options:
```toml
[imaging]
# Default resample filter used for resizing. Default is Box,
# a simple and fast averaging filter appropriate for downscaling.
# See https://github.com/disintegration/imaging
resampleFilter = "box"
# Default JPEG quality setting. Default is 75.
quality = 75
# Anchor used when cropping pictures.
# Default is "smart" which does Smart Cropping, using https://github.com/muesli/smartcrop
# Smart Cropping is content aware and tries to find the best crop for each image.
# Valid values are Smart, Center, TopLeft, Top, TopRight, Left, Right, BottomLeft, Bottom, BottomRight
anchor = "smart"
# Default background color.
# Hugo will preserve transparency for target formats that supports it,
# but will fall back to this color for JPEG.
# Expects a standard HEX color string with 3 or 6 digits.
# See https://www.google.com/search?q=color+picker
bgColor = "#ffffff"
[imaging.exif]
# Regexp matching the fields you want to Exclude from the (massive) set of Exif info
# available. As we cache this info to disk, this is for performance and
# disk space reasons more than anything.
# If you want it all, put ".*" in this config setting.
# Note that if neither this or ExcludeFields is set, Hugo will return a small
# default set.
includeFields = ""
# Regexp matching the Exif fields you want to exclude. This may be easier to use
# than IncludeFields above, depending on what you want.
excludeFields = ""
# Hugo extracts the "photo taken" date/time into .Date by default.
# Set this to true to turn it off.
disableDate = false
# Hugo extracts the "photo taken where" (GPS latitude and longitude) into
# .Long and .Lat. Set this to true to turn it off.
disableLatLong = false
```
## Smart Cropping of Images
By default, Hugo will use the [Smartcrop](https://github.com/muesli/smartcrop), a library created by [muesli](https://github.com/muesli), when cropping images with `.Fill`. You can set the anchor point manually, but in most cases the smart option will make a good choice. And we will work with the library author to improve this in the future.
An example using the sunset image from above:
{{< imgproc sunset Fill "200x200 smart" />}}
## Image Processing Performance Consideration
Processed images are stored below `<project-dir>/resources` (can be set with `resourceDir` config setting). This folder is deliberately placed in the project, as it is recommended to check these into source control as part of the project. These images are not "Hugo fast" to generate, but once generated they can be reused.
If you change your image settings (e.g. size), remove or rename images etc., you will end up with unused images taking up space and cluttering your project.
To clean up, run:
```bash
hugo --gc
```
{{% note %}}
**GC** is short for **Garbage Collection**.
{{% /note %}}

BIN
docs/content/en/content-management/image-processing/sunset.jpg Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 88 KiB

123
docs/content/en/content-management/menus.md Normal file
View file

@ -0,0 +1,123 @@
---
title: Menus
linktitle: Menus
description: Hugo has a simple yet powerful menu system.
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-03-31
categories: [content management]
keywords: [menus]
draft: false
menu:
docs:
parent: "content-management"
weight: 120
weight: 120 #rem
aliases: [/extras/menus/]
toc: true
---
{{% note "Lazy Blogger"%}}
If all you want is a simple menu for your sections, see the ["Section Menu for Lazy Bloggers" in Menu Templates](/templates/menu-templates/#section-menu-for-lazy-bloggers).
{{% /note %}}
You can do this:
* Place content in one or many menus
* Handle nested menus with unlimited depth
* Create menu entries without being attached to any content
* Distinguish active element (and active branch)
## What is a Menu in Hugo?
A **menu** is a named array of menu entries accessible by name via the [`.Site.Menus` site variable][sitevars]. For example, you can access your site's `main` menu via `.Site.Menus.main`.
{{% note "Menus on Multilingual Sites" %}}
If you make use of the [multilingual feature](/content-management/multilingual/), you can define language-independent menus.
{{% /note %}}
See the [Menu Entry Properties][me-props] for all the variables and functions related to a menu entry.
## Add content to menus
Hugo allows you to add content to a menu via the content's [front matter](/content-management/front-matter/).
### Simple
If all you need to do is add an entry to a menu, the simple form works well.
#### A Single Menu
```
---
menu: "main"
---
```
#### Multiple Menus
```
---
menu: ["main", "footer"]
---
```
#### Advanced
```
---
menu:
docs:
parent: 'extras'
weight: 20
---
```
## Add Non-content Entries to a Menu
You can also add entries to menus that aren’t attached to a piece of content. This takes place in your Hugo project's [`config` file][config].
Here’s an example snippet pulled from a configuration file:
{{< code-toggle file="config" >}}
[[menu.main]]
name = "about hugo"
pre = "<i class='fa fa-heart'></i>"
weight = -110
identifier = "about"
url = "/about/"
[[menu.main]]
name = "getting started"
pre = "<i class='fa fa-road'></i>"
post = "<span class='alert'>New!</span>"
weight = -100
url = "/getting-started/"
{{< /code-toggle >}}
{{% note %}}
The URLs must be relative to the context root. If the `baseURL` is `https://example.com/mysite/`, then the URLs in the menu must not include the context root `mysite`. Using an absolute URL will override the baseURL. If the value used for `URL` in the above example is `https://subdomain.example.com/`, the output will be `https://subdomain.example.com`.
{{% /note %}}
## Nesting
All nesting of content is done via the `parent` field.
The parent of an entry should be the identifier of another entry. The identifier should be unique (within a menu).
The following order is used to determine an Identifier:
`.Name > .LinkTitle > .Title`
This means that `.Title` will be used unless `.LinkTitle` is present, etc. In practice, `.Name` and `.Identifier` are only used to structure relationships and therefore never displayed.
In this example, the top level of the menu is defined in your [site `config` file][config]. All content entries are attached to one of these entries via the `.Parent` field.
## Render Menus
See [Menu Templates](/templates/menu-templates/) for information on how to render your site menus within your templates.
[config]: /getting-started/configuration/
[multilingual]: /content-management/multilingual/
[sitevars]: /variables/
[me-props]: /variables/menus/

460
docs/content/en/content-management/multilingual.md Normal file
View file

@ -0,0 +1,460 @@
---
title: Multilingual Mode
linktitle: Multilingual and i18n
description: Hugo supports the creation of websites with multiple languages side by side.
date: 2017-01-10
publishdate: 2017-01-10
lastmod: 2017-01-10
categories: [content management]
keywords: [multilingual,i18n, internationalization]
menu:
docs:
parent: "content-management"
weight: 150
weight: 150 #rem
draft: false
aliases: [/content/multilingual/,/tutorials/create-a-multilingual-site/]
toc: true
---
You should define the available languages in a `languages` section in your site configuration.
> Also See [Hugo Multilingual Part 1: Content translation](https://regisphilibert.com/blog/2018/08/hugo-multilingual-part-1-managing-content-translation/)
## Configure Languages
The following is an example of a site configuration for a multilingual Hugo project:
{{< code-toggle file="config" >}}
DefaultContentLanguage = "en"
copyright = "Everything is mine"
[params]
[params.navigation]
help = "Help"
[languages]
[languages.en]
title = "My blog"
weight = 1
[languages.en.params]
linkedin = "https://linkedin.com/whoever"
[languages.fr]
title = "Mon blogue"
weight = 2
[languages.fr.params]
linkedin = "https://linkedin.com/fr/whoever"
[languages.fr.params.navigation]
help = "Aide"
{{< /code-toggle >}}
Anything not defined in a `languages` block will fall back to the global value for that key (e.g., `copyright` for the English `en` language). This also works for `params`, as demonstrated with `help` above: You will get the value `Aide` in French and `Help` in all the languages without this parameter set.
With the configuration above, all content, sitemap, RSS feeds, paginations,
and taxonomy pages will be rendered below `/` in English (your default content language) and then below `/fr` in French.
When working with front matter `Params` in [single page templates][singles], omit the `params` in the key for the translation.
`defaultContentLanguage` sets the project's default language. If not set, the default language will be `en`.
If the default language needs to be rendererd below its own language code (`/en`) like the others, set `defaultContentLanguageInSubdir: true`.
Only the obvious non-global options can be overridden per language. Examples of global options are `baseURL`, `buildDrafts`, etc.
### Disable a Language
You can disable one or more languages. This can be useful when working on a new translation.
```toml
disableLanguages = ["fr", "ja"]
```
Note that you cannot disable the default content language.
We kept this as a standalone setting to make it easier to set via [OS environment](/getting-started/configuration/#configure-with-environment-variables):
```bash
HUGO_DISABLELANGUAGES="fr ja" hugo
```
If you have already a list of disabled languages in `config.toml`, you can enable them in development like this:
```bash
HUGO_DISABLELANGUAGES=" " hugo server
```
### Configure Multilingual Multihost
From **Hugo 0.31** we support multiple languages in a multihost configuration. See [this issue](https://github.com/gohugoio/hugo/issues/4027) for details.
This means that you can now configure a `baseURL` per `language`:
> If a `baseURL` is set on the `language` level, then all languages must have one and they must all be different.
Example:
{{< code-toggle file="config" >}}
[languages]
[languages.fr]
baseURL = "https://example.fr"
languageName = "Français"
weight = 1
title = "En Français"
[languages.en]
baseURL = "https://example.com"
languageName = "English"
weight = 2
title = "In English"
{{</ code-toggle >}}
With the above, the two sites will be generated into `public` with their own root:
```bash
public
├── en
└── fr
```
**All URLs (i.e `.Permalink` etc.) will be generated from that root. So the English home page above will have its `.Permalink` set to `https://example.com/`.**
When you run `hugo server` we will start multiple HTTP servers. You will typlically see something like this in the console:
```bash
Web Server is available at 127.0.0.1:1313 (bind address 127.0.0.1)
Web Server is available at 127.0.0.1:1314 (bind address 127.0.0.1)
Press Ctrl+C to stop
```
Live reload and `--navigateToChanged` between the servers work as expected.
### Taxonomies and Blackfriday
Taxonomies and [Blackfriday configuration][config] can also be set per language:
{{< code-toggle file="config" >}}
[Taxonomies]
tag = "tags"
[blackfriday]
angledQuotes = true
hrefTargetBlank = true
[languages]
[languages.en]
weight = 1
title = "English"
[languages.en.blackfriday]
angledQuotes = false
[languages.fr]
weight = 2
title = "Français"
[languages.fr.Taxonomies]
plaque = "plaques"
{{</ code-toggle >}}
## Translate Your Content
There are two ways to manage your content translations. Both ensure each page is assigned a language and is linked to its counterpart translations.
### Translation by filename
Considering the following example:
1. `/content/about.en.md`
2. `/content/about.fr.md`
The first file is assigned the English language and is linked to the second.
The second file is assigned the French language and is linked to the first.
Their language is __assigned__ according to the language code added as a __suffix to the filename__.
By having the same **path and base filename**, the content pieces are __linked__ together as translated pages.
{{< note >}}
If a file has no language code, it will be assigned the default language.
{{</ note >}}
### Translation by content directory
This system uses different content directories for each of the languages. Each language's content directory is set using the `contentDir` param.
{{< code-toggle file="config" >}}
languages:
en:
weight: 10
languageName: "English"
contentDir: "content/english"
fr:
weight: 20
languageName: "Français"
contentDir: "content/french"
{{< /code-toggle >}}
The value of `contentDir` can be any valid path -- even absolute path references. The only restriction is that the content directories cannot overlap.
Considering the following example in conjunction with the configuration above:
1. `/content/english/about.md`
2. `/content/french/about.md`
The first file is assigned the English language and is linked to the second.
The second file is assigned the French language and is linked to the first.
Their language is __assigned__ according to the content directory they are __placed__ in.
By having the same **path and basename** (relative to their language content directory), the content pieces are __linked__ together as translated pages.
### Bypassing default linking.
Any pages sharing the same `translationKey` set in front matter will be linked as translated pages regardless of basename or location.
Considering the following example:
1. `/content/about-us.en.md`
2. `/content/om.nn.md`
3. `/content/presentation/a-propos.fr.md`
```yaml
# set in all three pages
translationKey: "about"
```
By setting the `translationKey` front matter param to `about` in all three pages, they will be __linked__ as translated pages.
### Localizing permalinks
Because paths and filenames are used to handle linking, all translated pages will share the same URL (apart from the language subdirectory).
To localize the URLs, the [`slug`]({{< ref "/content-management/organization/index.md#slug" >}}) or [`url`]({{< ref "/content-management/organization/index.md#url" >}}) front matter param can be set in any of the non-default language file.
For example, a French translation (`content/about.fr.md`) can have its own localized slug.
{{< code-toggle >}}
Title: A Propos
slug: "a-propos"
{{< /code-toggle >}}
At render, Hugo will build both `/about/` and `/fr/a-propos/` while maintaining their translation linking.
{{% note %}}
If using `url`, remember to include the language part as well: `/fr/compagnie/a-propos/`.
{{%/ note %}}
### Page Bundles
To avoid the burden of having to duplicate files, each Page Bundle inherits the resources of its linked translated pages' bundles except for the content files (markdown files, html files etc...).
Therefore, from within a template, the page will have access to the files from all linked pages' bundles.
If, across the linked bundles, two or more files share the same basename, only one will be included and chosen as follows:
* File from current language bundle, if present.
* First file found across bundles by order of language `Weight`.
{{% note %}}
Page Bundle resources follow the same language assignment logic as content files, both by filename (`image.jpg`, `image.fr.jpg`) and by directory (`english/about/header.jpg`, `french/about/header.jpg`).
{{%/ note %}}
## Reference the Translated Content
To create a list of links to translated content, use a template similar to the following:
{{< code file="layouts/partials/i18nlist.html" >}}
{{ if .IsTranslated }}
<h4>{{ i18n "translations" }}</h4>
<ul>
{{ range .Translations }}
<li>
<a href="{{ .Permalink }}">{{ .Lang }}: {{ .Title }}{{ if .IsPage }} ({{ i18n "wordCount" . }}){{ end }}</a>
</li>
{{ end }}
</ul>
{{ end }}
{{< /code >}}
The above can be put in a `partial` (i.e., inside `layouts/partials/`) and included in any template, whether a [single content page][contenttemplate] or the [homepage][]. It will not print anything if there are no translations for a given page.
The above also uses the [`i18n` function][i18func] described in the next section.
### List All Available Languages
`.AllTranslations` on a `Page` can be used to list all translations, including the page itself. On the home page it can be used to build a language navigator:
{{< code file="layouts/partials/allLanguages.html" >}}
<ul>
{{ range $.Site.Home.AllTranslations }}
<li><a href="{{ .Permalink }}">{{ .Language.LanguageName }}</a></li>
{{ end }}
</ul>
{{< /code >}}
## Translation of Strings
Hugo uses [go-i18n][] to support string translations. [See the project's source repository][go-i18n-source] to find tools that will help you manage your translation workflows.
Translations are collected from the `themes/<THEME>/i18n/` folder (built into the theme), as well as translations present in `i18n/` at the root of your project. In the `i18n`, the translations will be merged and take precedence over what is in the theme folder. Language files should be named according to [RFC 5646][] with names such as `en-US.toml`, `fr.toml`, etc.
{{% note %}}
From **Hugo 0.31** you no longer need to use a valid language code. It can be anything.
See https://github.com/gohugoio/hugo/issues/3564
{{% /note %}}
From within your templates, use the `i18n` function like this:
```
{{ i18n "home" }}
```
This uses a definition like this one in `i18n/en-US.toml`:
```
[home]
other = "Home"
```
Often you will want to use to the page variables in the translations strings. To do that, pass on the "." context when calling `i18n`:
```
{{ i18n "wordCount" . }}
```
This uses a definition like this one in `i18n/en-US.toml`:
```
[wordCount]
other = "This article has {{ .WordCount }} words."
```
An example of singular and plural form:
```
[readingTime]
one = "One minute to read"
other = "{{.Count}} minutes to read"
```
And then in the template:
```
{{ i18n "readingTime" .ReadingTime }}
```
## Customize Dates
At the time of this writing, Go does not yet have support for internationalized locales for dates, but if you do some work, you can simulate it. For example, if you want to use French month names, you can add a data file like ``data/mois.yaml`` with this content:
~~~yaml
1: "janvier"
2: "février"
3: "mars"
4: "avril"
5: "mai"
6: "juin"
7: "juillet"
8: "août"
9: "septembre"
10: "octobre"
11: "novembre"
12: "décembre"
~~~
...then index the non-English date names in your templates like so:
~~~html
<time class="post-date" datetime="{{ .Date.Format '2006-01-02T15:04:05Z07:00' | safeHTML }}">
Article publié le {{ .Date.Day }} {{ index $.Site.Data.mois (printf "%d" .Date.Month) }} {{ .Date.Year }} (dernière modification le {{ .Lastmod.Day }} {{ index $.Site.Data.mois (printf "%d" .Lastmod.Month) }} {{ .Lastmod.Year }})
</time>
~~~
This technique extracts the day, month and year by specifying ``.Date.Day``, ``.Date.Month``, and ``.Date.Year``, and uses the month number as a key, when indexing the month name data file.
## Menus
You can define your menus for each language independently. Creating multilingual menus works just like [creating regular menus][menus], except they're defined in language-specific blocks in the configuration file:
```
defaultContentLanguage = "en"
[languages.en]
weight = 0
languageName = "English"
[[languages.en.menu.main]]
url = "/"
name = "Home"
weight = 0
[languages.de]
weight = 10
languageName = "Deutsch"
[[languages.de.menu.main]]
url = "/"
name = "Startseite"
weight = 0
```
The rendering of the main navigation works as usual. `.Site.Menus` will just contain the menu in the current language. Note that `absLangURL` below will link to the correct locale of your website. Without it, menu entries in all languages would link to the English version, since it's the default content language that resides in the root directory.
```
<ul>
{{- $currentPage := . -}}
{{ range .Site.Menus.main -}}
<li class="{{ if $currentPage.IsMenuCurrent "main" . }}active{{ end }}">
<a href="{{ .URL | absLangURL }}">{{ .Name }}</a>
</li>
{{- end }}
</ul>
```
## Missing Translations
If a string does not have a translation for the current language, Hugo will use the value from the default language. If no default value is set, an empty string will be shown.
While translating a Hugo website, it can be handy to have a visual indicator of missing translations. The [`enableMissingTranslationPlaceholders` configuration option][config] will flag all untranslated strings with the placeholder `[i18n] identifier`, where `identifier` is the id of the missing translation.
{{% note %}}
Hugo will generate your website with these missing translation placeholders. It might not be suitable for production environments.
{{% /note %}}
For merging of content from other languages (i.e. missing content translations), see [lang.Merge](/functions/lang.merge/).
To track down missing translation strings, run Hugo with the `--i18n-warnings` flag:
```
hugo --i18n-warnings | grep i18n
i18n|MISSING_TRANSLATION|en|wordCount
```
## Multilingual Themes support
To support Multilingual mode in your themes, some considerations must be taken for the URLs in the templates. If there is more than one language, URLs must meet the following criteria:
* Come from the built-in `.Permalink` or `.RelPermalink`
* Be constructed with the [`relLangURL` template function][rellangurl] or the [`absLangURL` template function][abslangurl] **OR** be prefixed with `{{ .LanguagePrefix }}`
If there is more than one language defined, the `LanguagePrefix` variable will equal `/en` (or whatever your `CurrentLanguage` is). If not enabled, it will be an empty string (and is therefore harmless for single-language Hugo websites).
[abslangurl]: /functions/abslangurl
[config]: /getting-started/configuration/
[contenttemplate]: /templates/single-page-templates/
[go-i18n-source]: https://github.com/nicksnyder/go-i18n
[go-i18n]: https://github.com/nicksnyder/go-i18n
[homepage]: /templates/homepage/
[i18func]: /functions/i18n/
[menus]: /content-management/menus/
[rellangurl]: /functions/rellangurl
[RFC 5646]: https://tools.ietf.org/html/rfc5646
[singles]: /templates/single-page-templates/

BIN
docs/content/en/content-management/organization/1-featured-content-bundles.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 62 KiB

240
docs/content/en/content-management/organization/index.md Normal file
View file

@ -0,0 +1,240 @@
---
title: Content Organization
linktitle: Organization
description: Hugo assumes that the same structure that works to organize your source content is used to organize the rendered site.
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
categories: [content management,fundamentals]
keywords: [sections,content,organization,bundle,resources]
menu:
docs:
parent: "content-management"
weight: 10
weight: 10 #rem
draft: false
aliases: [/content/sections/]
toc: true
---
## Page Bundles
Hugo `0.32` announced page-relative images and other resources packaged into `Page Bundles`.
These terms are connected, and you also need to read about [Page Resources]({{< relref "/content-management/page-resources" >}}) and [Image Processing]({{< relref "/content-management/image-processing" >}}) to get the full picture.
{{% imgproc 1-featured Resize "300x" %}}
The illustration shows 3 bundles. Note that the home page bundle cannot contain other content pages, but other files (images etc.) are fine.
{{% /imgproc %}}
{{% note %}}
The bundle documentation is **work in progress**. We will publish more comprehensive docs about this soon.
{{% /note %}}
# Organization of Content Source
In Hugo, your content should be organized in a manner that reflects the rendered website.
While Hugo supports content nested at any level, the top levels (i.e. `content/<DIRECTORIES>`) are special in Hugo and are considered the content type used to determine layouts etc. To read more about sections, including how to nest them, see [sections][].
Without any additional configuration, the following will just work:
```
.
└── content
└── about
| └── index.md // <- https://example.com/about/
├── posts
| ├── firstpost.md // <- https://example.com/posts/firstpost/
| ├── happy
| | └── ness.md // <- https://example.com/posts/happy/ness/
| └── secondpost.md // <- https://example.com/posts/secondpost/
└── quote
├── first.md // <- https://example.com/quote/first/
└── second.md // <- https://example.com/quote/second/
```
## Path Breakdown in Hugo
The following demonstrates the relationships between your content organization and the output URL structure for your Hugo website when it renders. These examples assume you are [using pretty URLs][pretty], which is the default behavior for Hugo. The examples also assume a key-value of `baseURL = "https://example.com"` in your [site's configuration file][config].
### Index Pages: `_index.md`
`_index.md` has a special role in Hugo. It allows you to add front matter and content to your [list templates][lists]. These templates include those for [section templates][], [taxonomy templates][], [taxonomy terms templates][], and your [homepage template][].
{{% note %}}
**Tip:** You can get a reference to the content and metadata in `_index.md` using the [`.Site.GetPage` function](/functions/getpage/).
{{% /note %}}
You can keep one `_index.md` for your homepage and one in each of your content sections, taxonomies, and taxonomy terms. The following shows typical placement of an `_index.md` that would contain content and front matter for a `posts` section list page on a Hugo website:
```
. url
. ⊢--^-⊣
. path slug
. ⊢--^-⊣⊢---^---⊣
. filepath
. ⊢------^------⊣
content/posts/_index.md
```
At build, this will output to the following destination with the associated values:
```
url ("/posts/")
⊢-^-⊣
baseurl section ("posts")
⊢--------^---------⊣⊢-^-⊣
permalink
⊢----------^-------------⊣
https://example.com/posts/index.html
```
The [sections][] can be nested as deeply as you need. The important part to understand is, that to make the section tree fully navigational, at least the lower-most section needs a content file. (i.e. `_index.md`).
### Single Pages in Sections
Single content files in each of your sections are going to be rendered as [single page templates][singles]. Here is an example of a single `post` within `posts`:
```
path ("posts/my-first-hugo-post.md")
. ⊢-----------^------------⊣
. section slug
. ⊢-^-⊣⊢--------^----------⊣
content/posts/my-first-hugo-post.md
```
At the time Hugo builds your site, the content will be output to the following destination:
```
url ("/posts/my-first-hugo-post/")
⊢------------^----------⊣
baseurl section slug
⊢--------^--------⊣⊢-^--⊣⊢-------^---------⊣
permalink
⊢--------------------^---------------------⊣
https://example.com/posts/my-first-hugo-post/index.html
```
## Paths Explained
The following concepts will provide more insight into the relationship between your project's organization and the default behaviors of Hugo when building the output website.
### `section`
A default content type is determined by a piece of content's section. `section` is determined by the location within the project's `content` directory. `section` *cannot* be specified or overridden in front matter.
### `slug`
A content's `slug` is either `name.extension` or `name/`. The value for `slug` is determined by
* the name of the content file (e.g., `lollapalooza.md`) OR
* front matter overrides
### `path`
A content's `path` is determined by the section's path to the file. The file `path`
* is based on the path to the content's location AND
* does not include the slug
### `url`
The `url` is the relative URL for the piece of content. The `url`
* is based on the content's location within the directory structure OR
* is defined in front matter and *overrides all the above*
## Override Destination Paths via Front Matter
Hugo believes that you organize your content with a purpose. The same structure that works to organize your source content is used to organize the rendered site. As displayed above, the organization of the source content will be mirrored in the destination.
There are times where you may need more control over your content. In these cases, there are fields that can be specified in the front matter to determine the destination of a specific piece of content.
The following items are defined in this order for a specific reason: items explained further down in the list will override earlier items, and not all of these items can be defined in front matter:
### `filename`
This isn't in the front matter, but is the actual name of the file minus the extension. This will be the name of the file in the destination (e.g., `content/posts/my-post.md` becomes `example.com/posts/my-post/`).
### `slug`
When defined in the front matter, the `slug` can take the place of the filename for the destination.
{{< code file="content/posts/old-post.md" >}}
---
title: New Post
slug: "new-post"
---
{{< /code >}}
This will render to the following destination according to Hugo's default behavior:
```
example.com/posts/new-post/
```
### `section`
`section` is determined by a content's location on disk and *cannot* be specified in the front matter. See [sections][] for more information.
### `type`
A content's `type` is also determined by its location on disk but, unlike `section`, it *can* be specified in the front matter. See [types][]. This can come in especially handy when you want a piece of content to render using a different layout. In the following example, you can create a layout at `layouts/new/mylayout.html` that Hugo will use to render this piece of content, even in the midst of many other posts.
{{< code file="content/posts/my-post.md" >}}
---
title: My Post
type: new
layout: mylayout
---
{{< /code >}}
<!-- See https://discourse.gohugo.io/t/path-not-works/6387 -->
<!-- ### `path`-->
<!--`path` can be provided in the front matter. This will replace the actual path to the file on disk. Destination will create the destination with the same path, including the section. -->
### `url`
A complete URL can be provided. This will override all the above as it pertains to the end destination. This must be the path from the baseURL (starting with a `/`). `url` will be used exactly as it provided in the front matter and will ignore the `--uglyURLs` setting in your site configuration:
{{< code file="content/posts/old-url.md" >}}
---
title: Old URL
url: /blog/new-url/
---
{{< /code >}}
Assuming your `baseURL` is [configured][config] to `https://example.com`, the addition of `url` to the front matter will make `old-url.md` render to the following destination:
```
https://example.com/blog/new-url/
```
You can see more information on how to control output paths in [URL Management][urls].
[config]: /getting-started/configuration/
[formats]: /content-management/formats/
[front matter]: /content-management/front-matter/
[getpage]: /functions/getpage/
[homepage template]: /templates/homepage/
[homepage]: /templates/homepage/
[lists]: /templates/lists/
[pretty]: /content-management/urls/#pretty-urls
[section templates]: /templates/section-templates/
[sections]: /content-management/sections/
[singles]: /templates/single-page-templates/
[taxonomy templates]: /templates/taxonomy-templates/
[taxonomy terms templates]: /templates/taxonomy-templates/
[types]: /content-management/types/
[urls]: /content-management/urls/

185
docs/content/en/content-management/page-bundles.md Normal file
View file

@ -0,0 +1,185 @@
---
title : "Page Bundles"
description : "Content organization using Page Bundles"
date : 2018-01-24T13:09:00-05:00
lastmod : 2018-01-28T22:26:40-05:00
linktitle : "Page Bundles"
keywords : ["page", "bundle", "leaf", "branch"]
categories : ["content management"]
toc : true
menu :
docs:
identifier : "page-bundles"
parent : "content-management"
weight : 11
---
Page Bundles are a way to group [Page Resources](/content-management/page-resources/).
A Page Bundle can be one of:
- Leaf Bundle (leaf means it has no children)
- Branch Bundle (home page, section, taxonomy terms, taxonomy list)
| | Leaf Bundle | Branch Bundle |
|-------------------------------------|----------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Usage | Collection of content and attachments for single pages | Collection of attachments for section pages (home page, section, taxonomy terms, taxonomy list) |
| Index file name | `index.md` [^fn:1] | `_index.md` [^fn:1] |
| Allowed Resources | Page and non-page (like images, pdf, etc.) types | Only non-page (like images, pdf, etc.) types |
| Where can the Resources live? | At any directory level within the leaf bundle directory. | Only in the directory level **of** the branch bundle directory i.e. the directory containing the `_index.md` ([ref](https://discourse.gohugo.io/t/question-about-content-folder-structure/11822/4?u=kaushalmodi)). |
| Layout type | `single` | `list` |
| Nesting | Does not allow nesting of more bundles under it | Allows nesting of leaf or branch bundles under it |
| Example | `content/posts/my-post/index.md` | `content/posts/_index.md` |
| Content from non-index page files... | Accessed only as page resources | Accessed only as regular pages |
## Leaf Bundles {#leaf-bundles}
A _Leaf Bundle_ is a directory at any hierarchy within the `content/`
directory, that contains an **`index.md`** file.
### Examples of Leaf Bundle organization {#examples-of-leaf-bundle-organization}
```text
content/
├── about
│ ├── index.md
├── posts
│ ├── my-post
│ │ ├── content1.md
│ │ ├── content2.md
│ │ ├── image1.jpg
│ │ ├── image2.png
│ │ └── index.md
│ └── my-other-post
│    └── index.md
│
└── another-section
├── ..
   └── not-a-leaf-bundle
├── ..
   └── another-leaf-bundle
   └── index.md
```
In the above example `content/` directory, there are four leaf
bundles:
about
: This leaf bundle is at the root level (directly under
`content` directory) and has only the `index.md`.
my-post
: This leaf bundle has the `index.md`, two other content
Markdown files and two image files.
my-other-post
: This leaf bundle has only the `index.md`.
another-leaf-bundle
: This leaf bundle is nested under couple of
directories. This bundle also has only the `index.md`.
{{% note %}}
The hierarchy depth at which a leaf bundle is created does not matter,
as long as it is not inside another **leaf** bundle.
{{% /note %}}
### Headless Bundle {#headless-bundle}
A headless bundle is a bundle that is configured to not get published
anywhere:
- It will have no `Permalink` and no rendered HTML in `public/`.
- It will not be part of `.Site.RegularPages`, etc.
But you can get it by `.Site.GetPage`. Here is an example:
```go-html-template
{{ $headless := .Site.GetPage "/some-headless-bundle" }}
{{ $reusablePages := $headless.Resources.Match "author*" }}
<h2>Authors</h2>
{{ range $reusablePages }}
<h3>{{ .Title }}</h3>
{{ .Content }}
{{ end }}
```
_In this example, we are assuming the `some-headless-bundle` to be a headless
bundle containing one or more **page** resources whose `.Name` matches
`"author*"`._
Explanation of the above example:
1. Get the `some-headless-bundle` Page "object".
2. Collect a *slice* of resources in this *Page Bundle* that matches
`"author*"` using `.Resources.Match`.
3. Loop through that *slice* of nested pages, and output their `.Title` and
`.Content`.
---
A leaf bundle can be made headless by adding below in the Front Matter
(in the `index.md`):
```toml
headless = true
```
{{% note %}}
Only leaf bundles can be made headless.
{{% /note %}}
There are many use cases of such headless page bundles:
- Shared media galleries
- Reusable page content "snippets"
## Branch Bundles {#branch-bundles}
A _Branch Bundle_ is any directory at any hierarchy within the
`content/` directory, that contains at least an **`_index.md`** file.
This `_index.md` can also be directly under the `content/` directory.
{{% note %}}
Here `md` (markdown) is used just as an example. You can use any file
type as a content resource as long as it is a content type recognized by Hugo.
{{% /note %}}
### Examples of Branch Bundle organization {#examples-of-branch-bundle-organization}
```text
content/
├── branch-bundle-1
│   ├── branch-content1.md
│   ├── branch-content2.md
│   ├── image1.jpg
│   ├── image2.png
│   └── _index.md
└── branch-bundle-2
├── _index.md
└── a-leaf-bundle
└── index.md
```
In the above example `content/` directory, there are two branch
bundles (and a leaf bundle):
`branch-bundle-1`
: This branch bundle has the `_index.md`, two
other content Markdown files and two image files.
`branch-bundle-2`
: This branch bundle has the `_index.md` and a
nested leaf bundle.
{{% note %}}
The hierarchy depth at which a branch bundle is created does not
matter.
{{% /note %}}
[^fn:1]: The `.md` extension is just an example. The extension can be `.html`, `.json` or any of any valid MIME type.

165
docs/content/en/content-management/page-resources.md Normal file
View file

@ -0,0 +1,165 @@
---
title : "Page Resources"
description : "Page Resources -- images, other pages, documents etc. -- have page-relative URLs and their own metadata."
date: 2018-01-24
categories: ["content management"]
keywords: [bundle,content,resources]
weight: 4003
draft: false
toc: true
linktitle: "Page Resources"
menu:
docs:
parent: "content-management"
weight: 31
---
## Properties
ResourceType
: The main type of the resource. For example, a file of MIME type `image/jpg` has the ResourceType `image`.
Name
: Default value is the filename (relative to the owning page). Can be set in front matter.
Title
: Default value is the same as `.Name`. Can be set in front matter.
Permalink
: The absolute URL to the resource. Resources of type `page` will have no value.
RelPermalink
: The relative URL to the resource. Resources of type `page` will have no value.
Content
: The content of the resource itself. For most resources, this returns a string with the contents of the file. This can be used to inline some resources, such as `<script>{{ (.Resources.GetMatch "myscript.js").Content | safeJS }}</script>` or `<img src="{{ (.Resources.GetMatch "mylogo.png").Content | base64Encode }}">`.
MediaType
: The MIME type of the resource, such as `image/jpg`.
MediaType.MainType
: The main type of the resource's MIME type. For example, a file of MIME type `application/pdf` has for MainType `application`.
MediaType.SubType
: The subtype of the resource's MIME type. For example, a file of MIME type `application/pdf` has for SubType `pdf`. Note that this is not the same as the file extension - PowerPoint files have a subtype of `vnd.mspowerpoint`.
MediaType.Suffixes
: A slice of possible suffixes for the resource's MIME type.
## Methods
ByType
: Returns the page resources of the given type.
```go
{{ .Resources.ByType "image" }}
```
Match
: Returns all the page resources (as a slice) whose `Name` matches the given Glob pattern ([examples](https://github.com/gobwas/glob/blob/master/readme.md)). The matching is case-insensitive.
```go
{{ .Resources.Match "images/*" }}
```
GetMatch
: Same as `Match` but will return the first match.
### Pattern Matching
```go
// Using Match/GetMatch to find this images/sunset.jpg ?
.Resources.Match "images/sun*" ✅
.Resources.Match "**/Sunset.jpg" ✅
.Resources.Match "images/*.jpg" ✅
.Resources.Match "**.jpg" ✅
.Resources.Match "*" 🚫
.Resources.Match "sunset.jpg" 🚫
.Resources.Match "*sunset.jpg" 🚫
```
## Page Resources Metadata
Page Resources' metadata is managed from their page's front matter with an array/table parameter named `resources`. You can batch assign values using a [wildcards](http://tldp.org/LDP/GNU-Linux-Tools-Summary/html/x11655.htm).
{{% note %}}
Resources of type `page` get `Title` etc. from their own front matter.
{{% /note %}}
name
: Sets the value returned in `Name`.
{{% warning %}}
The methods `Match` and `GetMatch` use `Name` to match the resources.
{{%/ warning %}}
title
: Sets the value returned in `Title`
params
: A map of custom key/values.
### Resources metadata example
{{< code-toggle copy="false">}}
title: Application
date : 2018-01-25
resources :
- src : "images/sunset.jpg"
name : "header"
- src : "documents/photo_specs.pdf"
title : "Photo Specifications"
params:
icon : "photo"
- src : "documents/guide.pdf"
title : "Instruction Guide"
- src : "documents/checklist.pdf"
title : "Document Checklist"
- src : "documents/payment.docx"
title : "Proof of Payment"
- src : "**.pdf"
name : "pdf-file-:counter"
params :
icon : "pdf"
- src : "**.docx"
params :
icon : "word"
{{</ code-toggle >}}
From the example above:
- `sunset.jpg` will receive a new `Name` and can now be found with `.GetMatch "header"`.
- `documents/photo_specs.pdf` will get the `photo` icon.
- `documents/checklist.pdf`, `documents/guide.pdf` and `documents/payment.docx` will get `Title` as set by `title`.
- Every `PDF` in the bundle except `documents/photo_specs.pdf` will get the `pdf` icon.
- All `PDF` files will get a new `Name`. The `name` parameter contains a special placeholder [`:counter`](#the-counter-placeholder-in-name-and-title), so the `Name` will be `pdf-file-1`, `pdf-file-2`, `pdf-file-3`.
- Every docx in the bundle will receive the `word` icon.
{{% warning %}}
The __order matters__ --- Only the **first set** values of the `title`, `name` and `params`-**keys** will be used. Consecutive parameters will be set only for the ones not already set. For example, in the above example, `.Params.icon` is already first set to `"photo"` in `src = "documents/photo_specs.pdf"`. So that would not get overridden to `"pdf"` by the later set `src = "**.pdf"` rule.
{{%/ warning %}}
### The `:counter` placeholder in `name` and `title`
The `:counter` is a special placeholder recognized in `name` and `title` parameters `resources`.
The counter starts at 1 the first time they are used in either `name` or `title`.
For example, if a bundle has the resources `photo_specs.pdf`, `other_specs.pdf`, `guide.pdf` and `checklist.pdf`, and the front matter has specified the `resources` as:
{{< code-toggle copy="false">}}
[[resources]]
src = "*specs.pdf"
title = "Specification #:counter"
[[resources]]
src = "**.pdf"
name = "pdf-file-:counter"
{{</ code-toggle >}}
the `Name` and `Title` will be assigned to the resource files as follows:
| Resource file | `Name` | `Title` |
|-------------------|-------------------|-----------------------|
| checklist.pdf | `"pdf-file-1.pdf` | `"checklist.pdf"` |
| guide.pdf | `"pdf-file-2.pdf` | `"guide.pdf"` |
| other\_specs.pdf | `"pdf-file-3.pdf` | `"Specification #1"` |
| photo\_specs.pdf | `"pdf-file-4.pdf` | `"Specification #2"` |

135
docs/content/en/content-management/related.md Normal file
View file

@ -0,0 +1,135 @@
---
title: Related Content
description: List related content in "See Also" sections.
date: 2017-09-05
categories: [content management]
keywords: [content]
menu:
docs:
parent: "content-management"
weight: 40
weight: 30
draft: false
aliases: [/content/related/,/related/]
toc: true
---
Hugo uses a set of factors to identify a page's related content based on Front Matter parameters. This can be tuned to the desired set of indices and parameters or left to Hugo's default [Related Content configuration](#configure-related-content).
## List Related Content
To list up to 5 related pages (which share the same _date_ or _keyword_ parameters) is as simple as including something similar to this partial in your single page template:
{{< code file="layouts/partials/related.html" >}}
{{ $related := .Site.RegularPages.Related . | first 5 }}
{{ with $related }}
<h3>See Also</h3>
<ul>
{{ range . }}
<li><a href="{{ .RelPermalink }}">{{ .Title }}</a></li>
{{ end }}
</ul>
{{ end }}
{{< /code >}}
### Methods
Here is the list of "Related" methods available on a page collection such `.RegularPages`.
#### .Related PAGE
Returns a collection of pages related the given one.
```
{{ $related := .Site.RegularPages.Related . }}
```
#### .RelatedIndices PAGE INDICE1 [INDICE2 ...]
Returns a collection of pages related to a given one restricted to a list of indices.
```
{{ $related := .Site.RegularPages.RelatedIndices . "tags" "date" }}
```
#### .RelatedTo KEYVALS [KEYVALS2 ...]
Returns a collection of pages related together by a set of indices and their match.
In order to build those set and pass them as argument, one must use the `keyVals` function where the first argument would be the `indice` and the consective ones its potential `matches`.
```
{{ $related := .Site.RegularPages.RelatedTo ( keyVals "tags" "hugo" "rocks") ( keyVals "date" .Date ) }}
```
{{% note %}}
Read [this blog article](https://regisphilibert.com/blog/2018/04/hugo-optmized-relashionships-with-related-content/) for a great explanation of more advanced usage of this feature.
{{% /note %}}
## Configure Related Content
Hugo provides a sensible default configuration of Related Content, but you can fine-tune this in your configuration, on the global or language level if needed.
### Default configuration
Without any `related` configuration set on the project, Hugo's Related Content methods will use the following.
```yaml
related:
threshold: 80
includeNewer: false
toLower: false
indices:
- name: keywords
weight: 100
- name: date
weight: 10
```
Custom configuration should be set using the same syntax.
{{% note %}}
If you add a `related` config section, you need to add a complete configuration. It is not possible to just set, say, `includeNewer` and use the rest from the Hugo defaults.
{{% /note %}}
### Top Level Config Options
threshold
: A value between 0-100. Lower value will give more, but maybe not so relevant, matches.
includeNewer
: Set to true to include **pages newer than the current page** in the related content listing. This will mean that the output for older posts may change as new related content gets added.
toLower
: Set to true to lower case keywords in both the indexes and the queries. This may give more accurate results at a slight performance penalty. Note that this can also be set per index.
### Config Options per Index
name
: The index name. This value maps directly to a page param. Hugo supports string values (`author` in the example) and lists (`tags`, `keywords` etc.) and time and date objects.
weight
: An integer weight that indicates _how important_ this parameter is relative to the other parameters. It can be 0, which has the effect of turning this index off, or even negative. Test with different values to see what fits your content best.
pattern
: This is currently only relevant for dates. When listing related content, we may want to list content that is also close in time. Setting "2006" (default value for date indexes) as the pattern for a date index will add weight to pages published in the same year. For busier blogs, "200601" (year and month) may be a better default.
toLower
: See above.
## Performance Considerations
**Fast is Hugo's middle name** and we would not have released this feature had it not been blistering fast.
This feature has been in the back log and requested by many for a long time. The development got this recent kick start from this Twitter thread:
{{< tweet 898398437527363585 >}}
Scott S. Lowe removed the "Related Content" section built using the `intersect` template function on tags, and the build time dropped from 30 seconds to less than 2 seconds on his 1700 content page sized blog.
He should now be able to add an improved version of that "Related Content" section without giving up the fast live-reloads. But it's worth noting that:
* If you don't use any of the `Related` methods, you will not use the Relate Content feature, and performance will be the same as before.
* Calling `.RegularPages.Related` etc. will create one inverted index, also sometimes named posting list, that will be reused for any lookups in that same page collection. Doing that in addition to, as an example, calling `.Pages.Related` will work as expected, but will create one additional inverted index. This should still be very fast, but worth having in mind, especially for bigger sites.
{{% note %}}
We currently do not index **Page content**. We thought we would release something that will make most people happy before we start solving [Sherlock's last case](https://github.com/joearms/sherlock).
{{% /note %}}

98
docs/content/en/content-management/sections.md Normal file
View file

@ -0,0 +1,98 @@
---
title: Content Sections
linktitle: Sections
description: "Hugo generates a **section tree** that matches your content."
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
categories: [content management]
keywords: [lists,sections,content types,organization]
menu:
docs:
parent: "content-management"
weight: 50
weight: 50 #rem
draft: false
aliases: [/content/sections/]
toc: true
---
A **Section** is a collection of pages that gets defined based on the
organization structure under the `content/` directory.
By default, all the **first-level** directories under `content/` form their own
sections (**root sections**).
If a user needs to define a section `foo` at a deeper level, they need to create
a directory named `foo` with an `_index.md` file (see [Branch Bundles][branch bundles]
for more information).
{{% note %}}
A **section** cannot be defined or overridden by a front matter parameter -- it
is strictly derived from the content organization structure.
{{% /note %}}
## Nested Sections
The sections can be nested as deeply as you need.
```bash
content
└── blog <-- Section, because first-level dir under content/
├── funny-cats
│   ├── mypost.md
│   └── kittens <-- Section, because contains _index.md
│   └── _index.md
└── tech <-- Section, because contains _index.md
└── _index.md
```
**The important part to understand is, that to make the section tree fully navigational, at least the lower-most section needs a content file. (e.g. `_index.md`).**
{{% note %}}
When we talk about a **section** in correlation with template selection, it is
currently always the *root section* only (`/blog/funny-cats/mypost/ => blog`).
If you need a specific template for a sub-section, you need to adjust either the `type` or `layout` in front matter.
{{% /note %}}
## Example: Breadcrumb Navigation
With the available [section variables and methods](#section-page-variables-and-methods) you can build powerful navigation. One common example would be a partial to show Breadcrumb navigation:
{{< code file="layouts/partials/breadcrumb.html" download="breadcrumb.html" >}}
<ol class="nav navbar-nav">
{{ template "breadcrumbnav" (dict "p1" . "p2" .) }}
</ol>
{{ define "breadcrumbnav" }}
{{ if .p1.Parent }}
{{ template "breadcrumbnav" (dict "p1" .p1.Parent "p2" .p2 ) }}
{{ else if not .p1.IsHome }}
{{ template "breadcrumbnav" (dict "p1" .p1.Site.Home "p2" .p2 ) }}
{{ end }}
<li{{ if eq .p1 .p2 }} class="active"{{ end }}>
<a href="{{ .p1.Permalink }}">{{ .p1.Title }}</a>
</li>
{{ end }}
{{< /code >}}
## Section Page Variables and Methods
Also see [Page Variables](/variables/page/).
{{< readfile file="/content/en/readfiles/sectionvars.md" markdown="true" >}}
## Content Section Lists
Hugo will automatically create pages for each *root section* that list all of the content in that section. See the documentation on [section templates][] for details on customizing the way these pages are rendered.
## Content *Section* vs Content *Type*
By default, everything created within a section will use the [content `type`][content type] that matches the *root section* name. For example, Hugo will assume that `posts/post-1.md` has a `posts` content `type`. If you are using an [archetype][] for your `posts` section, Hugo will generate front matter according to what it finds in `archetypes/posts.md`.
[archetype]: /content-management/archetypes/
[content type]: /content-management/types/
[directory structure]: /getting-started/directory-structure/
[section templates]: /templates/section-templates/
[branch bundles]: /content-management/page-bundles/#branch-bundles

422
docs/content/en/content-management/shortcodes.md Normal file
View file

@ -0,0 +1,422 @@
---
title: Shortcodes
linktitle:
description: Shortcodes are simple snippets inside your content files calling built-in or custom templates.
godocref:
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-03-31
menu:
docs:
parent: "content-management"
weight: 35
weight: 35 #rem
categories: [content management]
keywords: [markdown,content,shortcodes]
draft: false
aliases: [/extras/shortcodes/]
testparam: "Hugo Rocks!"
toc: true
---
## What a Shortcode is
Hugo loves Markdown because of its simple content format, but there are times when Markdown falls short. Often, content authors are forced to add raw HTML (e.g., video `<iframes>`) to Markdown content. We think this contradicts the beautiful simplicity of Markdown's syntax.
Hugo created **shortcodes** to circumvent these limitations.
A shortcode is a simple snippet inside a content file that Hugo will render using a predefined template. Note that shortcodes will not work in template files. If you need the type of drop-in functionality that shortcodes provide but in a template, you most likely want a [partial template][partials] instead.
In addition to cleaner Markdown, shortcodes can be updated any time to reflect new classes, techniques, or standards. At the point of site generation, Hugo shortcodes will easily merge in your changes. You avoid a possibly complicated search and replace operation.
## Use Shortcodes
{{< youtube 2xkNJL4gJ9E >}}
In your content files, a shortcode can be called by calling `{{%/* shortcodename parameters */%}}`. Shortcode parameters are space delimited, and parameters with internal spaces can be quoted.
The first word in the shortcode declaration is always the name of the shortcode. Parameters follow the name. Depending upon how the shortcode is defined, the parameters may be named, positional, or both, although you can't mix parameter types in a single call. The format for named parameters models that of HTML with the format `name="value"`.
Some shortcodes use or require closing shortcodes. Again like HTML, the opening and closing shortcodes match (name only) with the closing declaration, which is prepended with a slash.
Here are two examples of paired shortcodes:
```
{{%/* mdshortcode */%}}Stuff to `process` in the *center*.{{%/* /mdshortcode */%}}
```
```
{{</* highlight go */>}} A bunch of code here {{</* /highlight */>}}
```
The examples above use two different delimiters, the difference being the `%` character in the first and the `<>` characters in the second.
### Shortcodes with Markdown
In Hugo `0.55` we changed how the `%` delimiter works. Shortcodes using the `%` as the outer-most delimiter will now be fully rendered when sent to the content renderer (e.g. Blackfriday for Markdown), meaning they can be part of the generated table of contents, footnotes, etc.
If you want the old behavior, you can put the following line in the start of your shortcode template:
```
{{ $_hugo_config := `{ "version": 1 }` }}
```
### Shortcodes Without Markdown
The `<` character indicates that the shortcode's inner content does *not* need further rendering. Often shortcodes without markdown include internal HTML:
```
{{</* myshortcode */>}}<p>Hello <strong>World!</strong></p>{{</* /myshortcode */>}}
```
### Nested Shortcodes
You can call shortcodes within other shortcodes by creating your own templates that leverage the `.Parent` variable. `.Parent` allows you to check the context in which the shortcode is being called. See [Shortcode templates][sctemps].
## Use Hugo's Built-in Shortcodes
Hugo ships with a set of predefined shortcodes that represent very common usage. These shortcodes are provided for author convenience and to keep your markdown content clean.
### `figure`
`figure` is an extension of the image syntax in markdown, which does not provide a shorthand for the more semantic [HTML5 `<figure>` element][figureelement].
The `figure` shortcode can use the following named parameters:
src
: URL of the image to be displayed.
link
: If the image needs to be hyperlinked, URL of the destination.
target
: Optional `target` attribute for the URL if `link` parameter is set.
rel
: Optional `rel` attribute for the URL if `link` parameter is set.
alt
: Alternate text for the image if the image cannot be displayed.
title
: Image title.
caption
: Image caption.
class
: `class` attribute of the HTML `figure` tag.
height
: `height` attribute of the image.
width
: `width` attribute of the image.
attr
: Image attribution text.
attrlink
: If the attribution text needs to be hyperlinked, URL of the destination.
#### Example `figure` Input
{{< code file="figure-input-example.md" >}}
{{</* figure src="/media/spf13.jpg" title="Steve Francia" */>}}
{{< /code >}}
#### Example `figure` Output
{{< output file="figure-output-example.html" >}}
<figure>
<img src="/media/spf13.jpg" />
<figcaption>
<h4>Steve Francia</h4>
</figcaption>
</figure>
{{< /output >}}
### `gist`
Bloggers often want to include GitHub gists when writing posts. Let's suppose we want to use the [gist at the following url][examplegist]:
```
https://gist.github.com/spf13/7896402
```
We can embed the gist in our content via username and gist ID pulled from the URL:
```
{{</* gist spf13 7896402 */>}}
```
#### Example `gist` Input
If the gist contains several files and you want to quote just one of them, you can pass the filename (quoted) as an optional third argument:
{{< code file="gist-input.md" >}}
{{</* gist spf13 7896402 "img.html" */>}}
{{< /code >}}
#### Example `gist` Output
{{< output file="gist-output.html" >}}
{{< gist spf13 7896402 >}}
{{< /output >}}
#### Example `gist` Display
To demonstrate the remarkably efficiency of Hugo's shortcode feature, we have embedded the `spf13` `gist` example in this page. The following simulates the experience for visitors to your website. Naturally, the final display will be contingent on your stylesheets and surrounding markup.
{{< gist spf13 7896402 >}}
### `highlight`
This shortcode will convert the source code provided into syntax-highlighted HTML. Read more on [highlighting](/tools/syntax-highlighting/). `highlight` takes exactly one required `language` parameter and requires a closing shortcode.
#### Example `highlight` Input
{{< code file="content/tutorials/learn-html.md" >}}
{{</* highlight html */>}}
<section id="main">
<div>
<h1 id="title">{{ .Title }}</h1>
{{ range .Pages }}
{{ .Render "summary"}}
{{ end }}
</div>
</section>
{{</* /highlight */>}}
{{< /code >}}
#### Example `highlight` Output
The `highlight` shortcode example above would produce the following HTML when the site is rendered:
{{< output file="tutorials/learn-html/index.html" >}}
<span style="color: #f92672">&lt;section</span> <span style="color: #a6e22e">id=</span><span style="color: #e6db74">&quot;main&quot;</span><span style="color: #f92672">&gt;</span>
<span style="color: #f92672">&lt;div&gt;</span>
<span style="color: #f92672">&lt;h1</span> <span style="color: #a6e22e">id=</span><span style="color: #e6db74">&quot;title&quot;</span><span style="color: #f92672">&gt;</span>{{ .Title }}<span style="color: #f92672">&lt;/h1&gt;</span>
{{ range .Pages }}
{{ .Render &quot;summary&quot;}}
{{ end }}
<span style="color: #f92672">&lt;/div&gt;</span>
<span style="color: #f92672">&lt;/section&gt;</span>
{{< /output >}}
{{% note "More on Syntax Highlighting" %}}
To see even more options for adding syntax-highlighted code blocks to your website, see [Syntax Highlighting in Developer Tools](/tools/syntax-highlighting/).
{{% /note %}}
### `instagram`
If you'd like to embed a photo from [Instagram][], you only need the photo's ID. You can discern an Instagram photo ID from the URL:
```
https://www.instagram.com/p/BWNjjyYFxVx/
```
#### Example `instagram` Input
{{< code file="instagram-input.md" >}}
{{</* instagram BWNjjyYFxVx */>}}
{{< /code >}}
You also have the option to hide the caption:
{{< code file="instagram-input-hide-caption.md" >}}
{{</* instagram BWNjjyYFxVx hidecaption */>}}
{{< /code >}}
#### Example `instagram` Output
By adding the preceding `hidecaption` example, the following HTML will be added to your rendered website's markup:
{{< output file="instagram-hide-caption-output.html" >}}
{{< instagram BWNjjyYFxVx hidecaption >}}
{{< /output >}}
#### Example `instagram` Display
Using the preceding `instagram` with `hidecaption` example above, the following simulates the displayed experience for visitors to your website. Naturally, the final display will be contingent on your stylesheets and surrounding markup.
{{< instagram BWNjjyYFxVx hidecaption >}}
### `param`
Gets a value from the current `Page's` params set in front matter, with a fall back to the site param value. It will log an `ERROR` if the param with the given key could not be found in either.
```bash
{{</* param testparam */>}}
```
Since `testparam` is a param defined in front matter of this page with the value `Hugo Rocks!`, the above will print:
{{< param testparam >}}
To access deeply nested params, use "dot syntax", e.g:
```bash
{{</* param "my.nested.param" */>}}
```
### `ref` and `relref`
These shortcodes will look up the pages by their relative path (e.g., `blog/post.md`) or their logical name (`post.md`) and return the permalink (`ref`) or relative permalink (`relref`) for the found page.
`ref` and `relref` also make it possible to make fragmentary links that work for the header links generated by Hugo.
{{% note "More on Cross References" %}}
Read a more extensive description of `ref` and `relref` in the [cross references](/content-management/cross-references/) documentation.
{{% /note %}}
`ref` and `relref` take exactly one required parameter of _reference_, quoted and in position `0`.
#### Example `ref` and `relref` Input
```
[Neat]({{</* ref "blog/neat.md" */>}})
[Who]({{</* relref "about.md#who" */>}})
```
#### Example `ref` and `relref` Output
Assuming that standard Hugo pretty URLs are turned on.
```
<a href="/blog/neat">Neat</a>
<a href="/about/#who:c28654c202e73453784cfd2c5ab356c0">Who</a>
```
### `tweet`
You want to include a single tweet into your blog post? Everything you need is the URL of the tweet:
```
https://twitter.com/spf13/status/877500564405444608
```
#### Example `tweet` Input
Pass the tweet's ID from the URL as a parameter to the `tweet` shortcode:
{{< code file="example-tweet-input.md" >}}
{{</* tweet 877500564405444608 */>}}
{{< /code >}}
#### Example `tweet` Output
Using the preceding `tweet` example, the following HTML will be added to your rendered website's markup:
{{< output file="example-tweet-output.html" >}}
{{< tweet 877500564405444608 >}}
{{< /output >}}
#### Example `tweet` Display
Using the preceding `tweet` example, the following simulates the displayed experience for visitors to your website. Naturally, the final display will be contingent on your stylesheets and surrounding markup.
{{< tweet 877500564405444608 >}}
### `vimeo`
Adding a video from [Vimeo][] is equivalent to the YouTube shortcode above.
```
https://vimeo.com/channels/staffpicks/146022717
```
#### Example `vimeo` Input
Extract the ID from the video's URL and pass it to the `vimeo` shortcode:
{{< code file="example-vimeo-input.md" >}}
{{</* vimeo 146022717 */>}}
{{< /code >}}
#### Example `vimeo` Output
Using the preceding `vimeo` example, the following HTML will be added to your rendered website's markup:
{{< output file="example-vimeo-output.html" >}}
{{< vimeo 146022717 >}}
{{< /output >}}
{{% tip %}}
If you want to further customize the visual styling of the YouTube or Vimeo output, add a `class` named parameter when calling the shortcode. The new `class` will be added to the `<div>` that wraps the `<iframe>` *and* will remove the inline styles. Note that you will need to call the `id` as a named parameter as well. You can also give the vimeo video a descriptive title with `title`.
```
{{</* vimeo id="146022717" class="my-vimeo-wrapper-class" title="My vimeo video" */>}}
```
{{% /tip %}}
#### Example `vimeo` Display
Using the preceding `vimeo` example, the following simulates the displayed experience for visitors to your website. Naturally, the final display will be contingent on your stylesheets and surrounding markup.
{{< vimeo 146022717 >}}
### `youtube`
The `youtube` shortcode embeds a responsive video player for [YouTube videos][]. Only the ID of the video is required, e.g.:
```
https://www.youtube.com/watch?v=w7Ft2ymGmfc
```
#### Example `youtube` Input
Copy the YouTube video ID that follows `v=` in the video's URL and pass it to the `youtube` shortcode:
{{< code file="example-youtube-input.md" >}}
{{</* youtube w7Ft2ymGmfc */>}}
{{< /code >}}
Furthermore, you can automatically start playback of the embedded video by setting the `autoplay` parameter to `true`. Remember that you can't mix named and unnamed parameters, so you'll need to assign the yet unnamed video id to the parameter `id`:
{{< code file="example-youtube-input-with-autoplay.md" >}}
{{</* youtube id="w7Ft2ymGmfc" autoplay="true" */>}}
{{< /code >}}
#### Example `youtube` Output
Using the preceding `youtube` example, the following HTML will be added to your rendered website's markup:
{{< code file="example-youtube-output.html" >}}
{{< youtube id="w7Ft2ymGmfc" autoplay="true" >}}
{{< /code >}}
#### Example `youtube` Display
Using the preceding `youtube` example (without `autoplay="true"`), the following simulates the displayed experience for visitors to your website. Naturally, the final display will be contingent on your stylesheets and surrounding markup. The video is also include in the [Quick Start of the Hugo documentation][quickstart].
{{< youtube w7Ft2ymGmfc >}}
## Privacy Config
To learn how to configure your Hugo site to meet the new EU privacy regulation, see [Hugo and the GDPR][].
## Create Custom Shortcodes
To learn more about creating custom shortcodes, see the [shortcode template documentation][].
[`figure` shortcode]: #figure
[contentmanagementsection]: /content-management/formats/
[examplegist]: https://gist.github.com/spf13/7896402
[figureelement]: http://html5doctor.com/the-figure-figcaption-elements/ "An article from HTML5 doctor discussing the fig and figcaption elements."
[Hugo and the GDPR]: /about/hugo-and-gdpr/
[Instagram]: https://www.instagram.com/
[pagevariables]: /variables/page/
[partials]: /templates/partials/
[Pygments]: http://pygments.org/
[quickstart]: /getting-started/quick-start/
[sctemps]: /templates/shortcode-templates/
[scvars]: /variables/shortcodes/
[shortcode template documentation]: /templates/shortcode-templates/
[templatessection]: /templates/
[Vimeo]: https://vimeo.com/
[YouTube Videos]: https://www.youtube.com/

70
docs/content/en/content-management/static-files.md Normal file
View file

@ -0,0 +1,70 @@
---
title: Static Files
description: "Files that get served **statically** (as-is, no modification) on the site root."
date: 2017-11-18
categories: [content management]
keywords: [source, directories]
menu:
docs:
parent: "content-management"
weight: 130
weight: 130 #rem
aliases: [/static-files]
toc: true
---
By default, the `static/` directory in the site project is used for
all **static files** (e.g. stylesheets, JavaScript, images). The static files are served on the site root path (eg. if you have the file `static/image.png` you can access it using `http://{server-url}/image.png`, to include it in a document you can use `![Example image](/image.png) )`.
Hugo can be configured to look into a different directory, or even
**multiple directories** for such static files by configuring the
`staticDir` parameter in the [site config][]. All the files in all the
static directories will form a union filesystem.
This union filesystem will be served from your site root. So a file
`<SITE PROJECT>/static/me.png` will be accessible as
`<MY_BASEURL>/me.png`.
Here's an example of setting `staticDir` and `staticDir2` for a
multi-language site:
{{< code-toggle copy="false" file="config" >}}
staticDir = ["static1", "static2"]
[languages]
[languages.en]
staticDir2 = "static_en"
baseURL = "https://example.com"
languageName = "English"
weight = 2
title = "In English"
[languages.no]
staticDir = ["staticDir_override", "static_no"]
baseURL = "https://example.no"
languageName = "Norsk"
weight = 1
title = "På norsk"
{{</ code-toggle >}}
In the above, with no theme used:
- The English site will get its static files as a union of "static1",
"static2" and "static_en". On file duplicates, the right-most
version will win.
- The Norwegian site will get its static files as a union of
"staticDir_override" and "static_no".
Note 1
: The **2** (can be a number between 0 and 10) in `staticDir2` is
added to tell Hugo that you want to **add** this directory to the
global set of static directories defined using `staticDir`. Using
`staticDir` on the language level would replace the global value (as
can be seen in the Norwegian site case).
Note 2
: The example above is a [multihost setup][]. In a regular setup, all
the static directories will be available to all sites.
[site config]: /getting-started/configuration/#all-configuration-settings
[multihost setup]: /content-management/multilingual/#configure-multilingual-multihost

112
docs/content/en/content-management/summaries.md Normal file
View file

@ -0,0 +1,112 @@
---
title: Content Summaries
linktitle: Summaries
description: Hugo generates summaries of your content.
date: 2017-01-10
publishdate: 2017-01-10
lastmod: 2017-01-10
categories: [content management]
keywords: [summaries,abstracts,read more]
menu:
docs:
parent: "content-management"
weight: 90
weight: 90 #rem
draft: false
aliases: [/content/summaries/,/content-management/content-summaries/]
toc: true
---
With the use of the `.Summary` [page variable][pagevariables], Hugo generates summaries of content to use as a short version in summary views.
## Summary Splitting Options
* Automatic Summary Split
* Manual Summary Split
* Front Matter Summary
It is natural to accompany the summary with links to the original content, and a common design pattern is to see this link in the form of a "Read More ..." button. See the `.RelPermalink`, `.Permalink`, and `.Truncated` [page variables][pagevariables].
### Automatic Summary Splitting
By default, Hugo automatically takes the first 70 words of your content as its summary and stores it into the `.Summary` page variable for use in your templates. You may customize the summary length by setting `summaryLength` in your [site configuration](/getting-started/configuration/).
{{% note %}}
You can customize how HTML tags in the summary are loaded using functions such as `plainify` and `safeHTML`.
{{% /note %}}
{{% note %}}
The Hugo-defined summaries are set to use word count calculated by splitting the text by one or more consecutive whitespace characters. If you are creating content in a `CJK` language and want to use Hugo's automatic summary splitting, set `hasCJKLanguage` to `true` in your [site configuration](/getting-started/configuration/).
{{% /note %}}
### Manual Summary Splitting
Alternatively, you may add the <code>&#60;&#33;&#45;&#45;more&#45;&#45;&#62;</code> summary divider where you want to split the article.
For [Org mode content][org], use `# more` where you want to split the article.
Content that comes before the summary divider will be used as that content's summary and stored in the `.Summary` page variable with all HTML formatting intact.
{{% note "Summary Divider"%}}
The concept of a *summary divider* is not unique to Hugo. It is also called the "more tag" or "excerpt separator" in other literature.
{{% /note %}}
Pros
: Freedom, precision, and improved rendering. All HTML tags and formatting are preserved.
Cons
: Extra work for content authors, since they need to remember to type <code>&#60;&#33;&#45;&#45;more&#45;&#45;&#62;</code> (or `# more` for [org content][org]) in each content file. This can be automated by adding the summary divider below the front matter of an [archetype](/content-management/archetypes/).
{{% warning "Be Precise with the Summary Divider" %}}
Be careful to enter <code>&#60;&#33;&#45;&#45;more&#45;&#45;&#62;</code> exactly; i.e., all lowercase and with no whitespace.
{{% /warning %}}
### Front Matter Summary
You might want your summary to be something other than the text that starts the article. In this case you can provide a separate summary in the `summary` variable of the article front matter.
Pros
: Complete freedom of text independent of the content of the article. Markup can be used within the summary.
Cons
: Extra work for content authors as they need to write an entirely separate piece of text as the summary of the article.
## Summary Selection Order
Because there are multiple ways in which a summary can be specified it is useful to understand the order of selection Hugo follows when deciding on the text to be returned by `.Summary`. It is as follows:
1. If there is a <code>&#60;&#33;&#45;&#45;more&#45;&#45;&#62;</code> summary divider present in the article the text up to the divider will be provided as per the manual summary split method
2. If there is a `summary` variable in the article front matter the value of the variable will be provided as per the front matter summary method
3. The text at the start of the article will be provided as per the automatic summary split method
{{% warning "Competing selections" %}}
Hugo uses the _first_ of the above steps that returns text. So if, for example, your article has both `summary` variable in its front matter and a <code>&#60;&#33;&#45;&#45;more&#45;&#45;&#62;</code> summary divider Hugo will use the manual summary split method.
{{% /warning %}}
## Example: First 10 Articles with Summaries
You can show content summaries with the following code. You could use the following snippet, for example, in a [section template][].
{{< code file="page-list-with-summaries.html" >}}
{{ range first 10 .Pages }}
<article>
<!-- this <div> includes the title summary -->
<div>
<h2><a href="{{ .RelPermalink }}">{{ .Title }}</a></h2>
{{ .Summary }}
</div>
{{ if .Truncated }}
<!-- This <div> includes a read more link, but only if the summary is truncated... -->
<div>
<a href="{{ .RelPermalink }}">Read More…</a>
</div>
{{ end }}
</article>
{{ end }}
{{< /code >}}
Note how the `.Truncated` boolean variable value may be used to hide the "Read More..." link when the content is not truncated; i.e., when the summary contains the entire article.
[org]: /content-management/formats/
[pagevariables]: /variables/page/
[section template]: /templates/section-templates/

199
docs/content/en/content-management/syntax-highlighting.md Normal file
View file

@ -0,0 +1,199 @@
---
title: Syntax Highlighting
description: Hugo comes with really fast syntax highlighting from Chroma.
date: 2017-02-01
publishdate: 2017-02-01
keywords: [highlighting,pygments,chroma,code blocks,syntax]
categories: [content management]
menu:
docs:
parent: "content-management"
weight: 300
weight: 20
sections_weight: 20
draft: false
aliases: [/extras/highlighting/,/extras/highlight/,/tools/syntax-highlighting/]
toc: true
---
From Hugo 0.28, the default syntax highlighter in Hugo is [Chroma](https://github.com/alecthomas/chroma); it is built in Go and is really, really fast -- and for the most important parts compatible with Pygments.
If you want to continue to use Pygments (see below), set `pygmentsUseClassic=true` in your site config.
The example below shows a simple code snippet from the Hugo source highlighted with the `highlight` shortcode. Note that the gohugo.io site is generated with `pygmentsUseClasses=true` (see [Generate Syntax Highlighter CSS](#generate-syntax-highlighter-css)).
* `linenos=inline` or `linenos=table` (`table` will give copy-and-paste friendly code blocks) turns on line numbers.
* `hl_lines` lists a set of line numbers or line number ranges to be highlighted. Note that the hyphen range syntax is only supported for Chroma.
* `linenostart=199` starts the line number count from 199.
With that, this:
```
{{</* highlight go "linenos=table,hl_lines=8 15-17,linenostart=199" */>}}
// ... code
{{</* / highlight */>}}
```
Gives this:
{{< highlight go "linenos=table,hl_lines=8 15-17,linenostart=199" >}}
// GetTitleFunc returns a func that can be used to transform a string to
// title case.
//
// The supported styles are
//
// - "Go" (strings.Title)
// - "AP" (see https://www.apstylebook.com/)
// - "Chicago" (see https://www.chicagomanualofstyle.org/home.html)
//
// If an unknown or empty style is provided, AP style is what you get.
func GetTitleFunc(style string) func(s string) string {
switch strings.ToLower(style) {
case "go":
return strings.Title
case "chicago":
tc := transform.NewTitleConverter(transform.ChicagoStyle)
return tc.Title
default:
tc := transform.NewTitleConverter(transform.APStyle)
return tc.Title
}
}
{{< / highlight >}}
## Configure Syntax Highlighter
To make the transition from Pygments to Chroma seamless, they share a common set of configuration options:
pygmentsOptions
: A comma separated list of options. See below for a full list.
pygmentsCodeFences
: Set to true to enable syntax highlighting in code fences with a language tag in markdown (see below for an example).
pygmentsStyle
: The style of code highlighting. Note that this option is not
relevant when `pygmentsUseClasses` is set.
Syntax highlighting galleries:
**Chroma** ([short snippets](https://xyproto.github.io/splash/docs/all.html),
[long snippets](https://xyproto.github.io/splash/docs/longer/all.html)),
[Pygments](https://help.farbox.com/pygments.html)
pygmentsUseClasses
: Set to `true` to use CSS classes to format your highlighted code. See [Generate Syntax Highlighter CSS](#generate-syntax-highlighter-css).
pygmentsCodeFencesGuessSyntax
: Set to `true` to try to do syntax highlighting on code fenced blocks in markdown without a language tag.
pygmentsUseClassic
: Set to true to use Pygments instead of the much faster Chroma.
### Options
`pygmentsOptions` can be set either in site config or overridden per code block in the Highlight shortcode or template func.
noclasses
: Use inline style.
linenos
: For Chroma, any value in this setting will print line numbers. Pygments has some more fine grained control.
linenostart
: Start the line numbers from this value (default is 1).
hl_lines
: Highlight a space separated list of line numbers. For Chroma, you can provide a list of ranges, i.e. "3-8 10-20".
The full set of supported options for Pygments is: `encoding`, `outencoding`, `nowrap`, `full`, `title`, `style`, `noclasses`, `classprefix`, `cssclass`, `cssstyles`, `prestyles`, `linenos`, `hl_lines`, `linenostart`, `linenostep`, `linenospecial`, `nobackground`, `lineseparator`, `lineanchors`, `linespans`, `anchorlinenos`, `startinline`. See the [Pygments HTML Formatter Documentation](http://pygments.org/docs/formatters/#HtmlFormatter) for details.
## Generate Syntax Highlighter CSS
If you run with `pygmentsUseClasses=true` in your site config, you need a style sheet.
You can generate one with Hugo:
```bash
hugo gen chromastyles --style=monokai > syntax.css
```
Run `hugo gen chromastyles -h` for more options. See https://xyproto.github.io/splash/docs/ for a gallery of available styles.
## Highlight Shortcode
Highlighting is carried out via the [built-in shortcode](/content-management/shortcodes/) `highlight`. `highlight` takes exactly one required parameter for the programming language to be highlighted and requires a closing shortcode. Note that `highlight` is *not* used for client-side javascript highlighting.
### Example `highlight` Shortcode
{{< code file="example-highlight-shortcode-input.md" >}}
{{</* highlight html */>}}
<section id="main">
<div>
<h1 id="title">{{ .Title }}</h1>
{{ range .Pages }}
{{ .Render "summary"}}
{{ end }}
</div>
</section>
{{</* /highlight */>}}
{{< /code >}}
## Highlight Template Func
See [Highlight](/functions/highlight/).
## Highlight in Code Fences
It is also possible to add syntax highlighting with GitHub flavored code fences. To enable this, set the `pygmentsCodeFences` to `true` in Hugo's [configuration file](/getting-started/configuration/);
````
```go-html-template
<section id="main">
<div>
<h1 id="title">{{ .Title }}</h1>
{{ range .Pages }}
{{ .Render "summary"}}
{{ end }}
</div>
</section>
```
````
## List of Chroma Highlighting Languages
The full list of Chroma lexers and their aliases (which is the identifier used in the `highlight` template func or when doing highlighting in code fences):
{{< chroma-lexers >}}
## Highlight with Pygments Classic
If you for some reason don't want to use the built-in Chroma highlighter, you can set `pygmentsUseClassic=true` in your config and add Pygments to your path.
{{% note "Disclaimers on Pygments" %}}
* Pygments is relatively slow and _causes a performance hit when building your site_, but Hugo has been designed to cache the results to disk.
* The caching can be turned off by setting the `--ignoreCache` flag to `true`.
* The languages available for highlighting depend on your Pygments installation.
{{% /note %}}
If you have never worked with Pygments before, here is a brief primer:
+ Install Python from [python.org](https://www.python.org/downloads/). Version 2.7.x is already sufficient.
+ Run `pip install Pygments` in order to install Pygments. Once installed, Pygments gives you a command `pygmentize`. Make sure it sits in your PATH; otherwise, Hugo will not be able to find and use it.
On Debian and Ubuntu systems, you may also install Pygments by running `sudo apt-get install python3-pygments`.
[Prism]: https://prismjs.com
[prismdownload]: https://prismjs.com/download.html
[Highlight.js]: https://highlightjs.org/
[Rainbow]: https://craig.is/making/rainbows
[Syntax Highlighter]: https://alexgorbatchev.com/SyntaxHighlighter/
[Google Prettify]: https://github.com/google/code-prettify
[Yandex]: https://yandex.ru/

214
docs/content/en/content-management/taxonomies.md Normal file
View file

@ -0,0 +1,214 @@
---
title: Taxonomies
linktitle:
description: Hugo includes support for user-defined taxonomies to help you demonstrate logical relationships between content for the end users of your website.
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
keywords: [taxonomies,metadata,front matter,terms]
categories: [content management]
menu:
docs:
parent: "content-management"
weight: 80
weight: 80 #rem
draft: false
aliases: [/taxonomies/overview/,/taxonomies/usage/,/indexes/overview/,/doc/indexes/,/extras/indexes]
toc: true
---
## What is a Taxonomy?
Hugo includes support for user-defined groupings of content called **taxonomies**. Taxonomies are classifications of logical relationships between content.
### Definitions
Taxonomy
: a categorization that can be used to classify content
Term
: a key within the taxonomy
Value
: a piece of content assigned to a term
{{< youtube pCPCQgqC8RA >}}
## Example Taxonomy: Movie Website
Let's assume you are making a website about movies. You may want to include the following taxonomies:
* Actors
* Directors
* Studios
* Genre
* Year
* Awards
Then, in each of the movies, you would specify terms for each of these taxonomies (i.e., in the [front matter][] of each of your movie content files). From these terms, Hugo would automatically create pages for each Actor, Director, Studio, Genre, Year, and Award, with each listing all of the Movies that matched that specific Actor, Director, Studio, Genre, Year, and Award.
### Movie Taxonomy Organization
To continue with the example of a movie site, the following demonstrates content relationships from the perspective of the taxonomy:
```
Actor <- Taxonomy
Bruce Willis <- Term
The Sixth Sense <- Value
Unbreakable <- Value
Moonrise Kingdom <- Value
Samuel L. Jackson <- Term
Unbreakable <- Value
The Avengers <- Value
xXx <- Value
```
From the perspective of the content, the relationships would appear differently, although the data and labels used are the same:
```
Unbreakable <- Value
Actors <- Taxonomy
Bruce Willis <- Term
Samuel L. Jackson <- Term
Director <- Taxonomy
M. Night Shyamalan <- Term
...
Moonrise Kingdom <- Value
Actors <- Taxonomy
Bruce Willis <- Term
Bill Murray <- Term
Director <- Taxonomy
Wes Anderson <- Term
...
```
## Hugo Taxonomy Defaults {#default-taxonomies}
Hugo natively supports taxonomies.
Without adding a single line to your [site config][config] file, Hugo will automatically create taxonomies for `tags` and `categories`. That would be the same as manually [configuring your taxonomies](#configuring-taxonomies) as below:
{{< code-toggle copy="false" >}}
[taxonomies]
tag = "tags"
category = "categories"
{{</ code-toggle >}}
If you do not want Hugo to create any taxonomies, set `disableKinds` in your [site config][config] to the following:
{{< code-toggle copy="false" >}}
disableKinds = ["taxonomy","taxonomyTerm"]
{{</ code-toggle >}}
### Default Destinations
When taxonomies are used---and [taxonomy templates][] are provided---Hugo will automatically create both a page listing all the taxonomy's terms and individual pages with lists of content associated with each term. For example, a `categories` taxonomy declared in your configuration and used in your content front matter will create the following pages:
* A single page at `example.com/categories/` that lists all the [terms within the taxonomy][]
* [Individual taxonomy list pages][taxonomy templates] (e.g., `/categories/development/`) for each of the terms that shows a listing of all pages marked as part of that taxonomy within any content file's [front matter][]
## Configure Taxonomies {#configuring-taxonomies}
Custom taxonomies other than the [defaults](#default-taxonomies) must be defined in your [site config][config] before they can be used throughout the site. You need to provide both the plural and singular labels for each taxonomy. For example, `singular key = "plural value"` for TOML and `singular key: "plural value"` for YAML.
### Example: Adding a custom taxonomy named "series"
{{% note %}}
While adding custom taxonomies, you need to put in the default taxonomies too, _if you want to keep them_.
{{% /note %}}
{{< code-toggle copy="false" >}}
[taxonomies]
tag = "tags"
category = "categories"
series = "series"
{{</ code-toggle >}}
### Example: Removing default taxonomies
If you want to have just the default `tags` taxonomy, and remove the `categories` taxonomy for your site, you can do so by modifying the `taxonomies` value in your [site config][config].
{{< code-toggle copy="false" >}}
[taxonomies]
tag = "tags"
{{</ code-toggle >}}
If you want to disable all taxonomies altogether, see the use of `disableKinds` in [Hugo Taxonomy Defaults](#default-taxonomies).
{{% note %}}
You can add content and front matter to your taxonomy list and taxonomy terms pages. See [Content Organization](/content-management/organization/) for more information on how to add an `_index.md` for this purpose.
Much like regular pages, taxonomy list [permalinks](/content-management/urls/) are configurable, but taxonomy term page permalinks are not.
{{% /note %}}
{{% warning %}}
The configuration option `preserveTaxonomyNames` was removed in Hugo 0.55.
You can now use `.Page.Title` on the relevant taxonomy node to get the original value.
{{% /warning %}}
## Add Taxonomies to Content
Once a taxonomy is defined at the site level, any piece of content can be assigned to it, regardless of [content type][] or [content section][].
Assigning content to a taxonomy is done in the [front matter][]. Simply create a variable with the *plural* name of the taxonomy and assign all terms you want to apply to the instance of the content type.
{{% note %}}
If you would like the ability to quickly generate content files with preconfigured taxonomies or terms, read the docs on [Hugo archetypes](/content-management/archetypes/).
{{% /note %}}
### Example: Front Matter with Taxonomies
{{< code-toggle copy="false">}}
title = "Hugo: A fast and flexible static site generator"
tags = [ "Development", "Go", "fast", "Blogging" ]
categories = [ "Development" ]
series = [ "Go Web Dev" ]
slug = "hugo"
project_url = "https://github.com/gohugoio/hugo"
{{</ code-toggle >}}
## Order Taxonomies
A content file can assign weight for each of its associate taxonomies. Taxonomic weight can be used for sorting or ordering content in [taxonomy list templates][] and is declared in a content file's [front matter][]. The convention for declaring taxonomic weight is `taxonomyname_weight`.
The following TOML and YAML examples show a piece of content that has a weight of 22, which can be used for ordering purposes when rendering the pages assigned to the "a", "b" and "c" values of the `tags` taxonomy. It has also been assigned the weight of 44 when rendering the "d" category page.
### Example: Taxonomic `weight`
{{< code-toggle copy="false" >}}
title = "foo"
tags = [ "a", "b", "c" ]
tags_weight = 22
categories = ["d"]
categories_weight = 44
{{</ code-toggle >}}
By using taxonomic weight, the same piece of content can appear in different positions in different taxonomies.
{{% note "Limits to Ordering Taxonomies" %}}
Currently taxonomies only support the [default `weight => date` ordering of list content](/templates/lists/#default-weight-date). For more information, see the documentation on [taxonomy templates](/templates/taxonomy-templates/).
{{% /note %}}
## Add custom metadata to a Taxonomy Term
If you need to add custom metadata to your taxonomy terms, you will need to create a page for that term at `/content/<TAXONOMY>/<TERM>/_index.md` and add your metadata in it's front matter. Continuing with our 'Actors' example, let's say you want to add a wikipedia page link to each actor. Your terms pages would be something like this:
{{< code file="/content/actors/bruce-willis/_index.md" >}}
---
title: "Bruce Willis"
wikipedia: "https://en.wikipedia.org/wiki/Bruce_Willis"
---
{{< /code >}}
You can later use your custom metadata as shown in the [Taxonomy Terms Templates documentation](/templates/taxonomy-templates/#displaying-custom-metadata-in-taxonomy-terms-templates).
[`urlize` template function]: /functions/urlize/
[content section]: /content-management/sections/
[content type]: /content-management/types/
[documentation on archetypes]: /content-management/archetypes/
[front matter]: /content-management/front-matter/
[taxonomy list templates]: /templates/taxonomy-templates/#taxonomy-page-templates
[taxonomy templates]: /templates/taxonomy-templates/
[terms within the taxonomy]: /templates/taxonomy-templates/#taxonomy-terms-templates "See how to order terms associated with a taxonomy"
[config]: /getting-started/configuration/

95
docs/content/en/content-management/toc.md Normal file
View file

@ -0,0 +1,95 @@
---
title: Table of Contents
linktitle:
description: Hugo can automatically parse Markdown content and create a Table of Contents you can use in your templates.
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
categories: [content management]
keywords: [table of contents, toc]
menu:
docs:
parent: "content-management"
weight: 130
weight: 130 #rem
draft: false
aliases: [/extras/toc/]
toc: true
---
{{% note "TOC Heading Levels are Fixed" %}}
Currently, the `{{.TableOfContents}}` [page variable](/variables/page/) does not allow you to specify which heading levels you want the TOC to render. [See the related GitHub discussion (#1778)](https://github.com/gohugoio/hugo/issues/1778). As such, the resulting `<nav id="TableOfContents"><ul></ul></nav>` is going to start at `<h1>` when pulling from `{{.Content}}`.
{{% /note %}}
## Usage
Create your markdown the way you normally would with the appropriate headings. Here is some example content:
```
<!-- Your front matter up here -->
## Introduction
One morning, when Gregor Samsa woke from troubled dreams, he found himself transformed in his bed into a horrible vermin.
## My Heading
He lay on his armour-like back, and if he lifted his head a little he could see his brown belly, slightly domed and divided by arches into stiff sections. The bedding was hardly able to cover it and seemed ready to slide off any moment.
### My Subheading
A collection of textile samples lay spread out on the table - Samsa was a travelling salesman - and above it there hung a picture that he had recently cut out of an illustrated magazine and housed in a nice, gilded frame. It showed a lady fitted out with a fur hat and fur boa who sat upright, raising a heavy fur muff that covered the whole of her lower arm towards the viewer. Gregor then turned to look out the window at the dull weather. Drops
```
Hugo will take this Markdown and create a table of contents from `## Introduction`, `## My Heading`, and `### My Subheading` and then store it in the [page variable][pagevars]`.TableOfContents`.
The built-in `.TableOfContents` variables outputs a `<nav id="TableOfContents">` element with a child `<ul>`, whose child `<li>` elements begin with any `<h1>`'s (i.e., `#` in markdown) inside your content.'
{{% note "Table of contents not available for MMark" %}}
Hugo documents created in the [MMark](/content-management/formats/#mmark) Markdown dialect do not currently display TOCs. TOCs are, however, compatible with all other supported Markdown formats.
{{% /note %}}
## Template Example: Basic TOC
The following is an example of a very basic [single page template][]:
{{< code file="layout/_default/single.html" download="single.html" >}}
{{ define "main" }}
<main>
<article>
<header>
<h1>{{ .Title }}</h1>
</header>
{{ .Content }}
</article>
<aside>
{{ .TableOfContents }}
</aside>
</main>
{{ end }}
{{< /code >}}
## Template Example: TOC Partial
The following is a [partial template][partials] that adds slightly more logic for page-level control over your table of contents. It assumes you are using a `toc` field in your content's [front matter][] that, unless specifically set to `false`, will add a TOC to any page with a `.WordCount` (see [Page Variables][pagevars]) greater than 400. This example also demonstrates how to use [conditionals][] in your templating:
{{< code file="layouts/partials/toc.html" download="toc.html" >}}
{{ if and (gt .WordCount 400 ) (.Params.toc) }}
<aside>
<header>
<h2>{{.Title}}</h2>
</header>
{{.TableOfContents}}
</aside>
{{ end }}
{{< /code >}}
{{% note %}}
With the preceding example, even pages with > 400 words *and* `toc` not set to `false` will not render a table of contents if there are no headings in the page for the `{{.TableOfContents}}` variable to pull from.
{{% /note %}}
[conditionals]: /templates/introduction/#conditionals
[front matter]: /content-management/front-matter/
[pagevars]: /variables/page/
[partials]: /templates/partials/
[single page template]: /templates/single-page-templates/

99
docs/content/en/content-management/types.md Normal file
View file

@ -0,0 +1,99 @@
---
title: Content Types
linktitle: Types
description: Hugo supports sites with multiple content types and assumes your site will be organized into sections, where each section represents the corresponding type.
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
categories: [content management]
keywords: [lists,sections,content types,types,organization]
menu:
docs:
parent: "content-management"
weight: 60
weight: 60 #rem
draft: false
aliases: [/content/types]
toc: true
---
A **content type** can have a unique set of metadata (i.e., [front matter][]) or customized [template][] and can be created by the `hugo new` command via [archetypes][].
## What is a Content Type
[Tumblr][] is a good example of a website with multiple content types. A piece of "content" could be a photo, quote, or a post, each with different sets of metadata and different visual rendering.
## Assign a Content Type
Hugo assumes that your site will be organized into [sections][] and each section represents a corresponding type. This is to reduce the amount of configuration necessary for new Hugo projects.
If you are taking advantage of this default behavior, each new piece of content you place into a section will automatically inherit the type. Therefore a new file created at `content/posts/new-post.md` will automatically be assigned the type `posts`. Alternatively, you can set the content type in a content file's [front matter][] in the field "`type`".
## Create New Content of a Specific Type
You can manually add files to your content directories, but Hugo can create and populate a new content file with preconfigured front matter via [archetypes][].
## Define a Content Type
Creating a new content type is easy. You simply define the templates and archetype unique to your new content type, or Hugo will use defaults.
{{% note "Declaring Content Types" %}}
Remember, all of the following are *optional*. If you do not specifically declare content types in your front matter or develop specific layouts for content types, Hugo is smart enough to assume the content type from the file path and section. (See [Content Sections](/content-management/sections/) for more information.)
{{% /note %}}
The following examples take you stepwise through creating a new type layout for a content file that contains the following front matter:
{{< code file="content/events/my-first-event.md" copy="false" >}}
+++
title = My First Event
date = "2016-06-24T19:20:04-07:00"
description = "Today is my 36th birthday. How time flies."
type = "event"
layout = "birthday"
+++
{{< /code >}}
By default, Hugo assumes `*.md` under `events` is of the `events` content type. However, we have specified that this particular file at `content/events/my-first-event.md` is of type `event` and should render using the `birthday` layout.
### Create a Type Layout Directory
Create a directory with the name of the type in `/layouts`. For creating these custom layouts, **type is always singular**; e.g., `events => event` and `posts => post`.
For this example, you need to create `layouts/event/birthday.html`.
{{% note %}}
If you have multiple content files in your `events` directory that are of the `special` type and you don't want to define the `layout` specifically for each piece of content, you can create a layout at `layouts/special/single.html` to observe the [single page template lookup order](/templates/single-page-templates/).
{{% /note %}}
{{% warning %}}
With the "everything is a page" data model introduced in v0.18 (see [Content Organization](/content-management/organization/)), you can use `_index.md` in content directories to add both content and front matter to [list pages](/templates/lists/).
{{% /warning %}}
### Create Views
Many sites support rendering content in a few different ways; e.g., a single page view and a summary view to be used when displaying a [list of section contents][sectiontemplates].
Hugo limits assumptions about how you want to display your content to an intuitive set of sane defaults and will support as many different views of a content type as your site requires. All that is required for these additional views is that a template exists in each `/layouts/<TYPE>` directory with the same name.
### Custom Content Type Template Lookup Order
The lookup order for the `content/events/my-first-event.md` templates would be as follows:
* `layouts/event/birthday.html`
* `layouts/event/single.html`
* `layouts/events/single.html`
* `layouts/_default/single.html`
### Create a Corresponding Archetype
We can then create a custom archetype with preconfigured front matter at `event.md` in the `/archetypes` directory; i.e. `archetypes/event.md`.
Read [Archetypes][archetypes] for more information on archetype usage with `hugo new`.
[archetypes]: /content-management/archetypes/
[front matter]: /content-management/front-matter/
[sectiontemplates]: /templates/section-templates/
[sections]: /content-management/sections/
[template]: /templates/
[Tumblr]: https://www.tumblr.com/

297
docs/content/en/content-management/urls.md Normal file
View file

@ -0,0 +1,297 @@
---
title: URL Management
linktitle: URL Management
description: Hugo supports permalinks, aliases, link canonicalization, and multiple options for handling relative vs absolute URLs.
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-03-09
keywords: [aliases,redirects,permalinks,urls]
categories: [content management]
menu:
docs:
parent: "content-management"
weight: 110
weight: 110 #rem
draft: false
aliases: [/extras/permalinks/,/extras/aliases/,/extras/urls/,/doc/redirects/,/doc/alias/,/doc/aliases/]
toc: true
---
## Permalinks
The default Hugo target directory for your built website is `public/`. However, you can change this value by specifying a different `publishDir` in your [site configuration][config]. The directories created at build time for a section reflect the position of the content's directory within the `content` folder and namespace matching its layout within the `contentdir` hierarchy.
The `permalinks` option in your [site configuration][config] allows you to adjust the directory paths (i.e., the URLs) on a per-section basis. This will change where the files are written to and will change the page's internal "canonical" location, such that template references to `.RelPermalink` will honor the adjustments made as a result of the mappings in this option.
{{% note "Default Publish and Content Folders" %}}
These examples use the default values for `publishDir` and `contentDir`; i.e., `public` and `content`, respectively. You can override the default values in your [site's `config` file](/getting-started/configuration/).
{{% /note %}}
For example, if one of your [sections][] is called `posts` and you want to adjust the canonical path to be hierarchical based on the year, month, and post title, you could set up the following configurations in YAML and TOML, respectively.
### Permalinks Configuration Example
{{< code-toggle file="config" copy="false" >}}
permalinks:
posts: /:year/:month/:title/
{{< /code-toggle >}}
Only the content under `posts/` will have the new URL structure. For example, the file `content/posts/sample-entry.md` with `date: 2017-02-27T19:20:00-05:00` in its front matter will render to `public/2017/02/sample-entry/index.html` at build time and therefore be reachable at `https://example.com/2017/02/sample-entry/`.
You can also configure permalinks of taxonomies with the same syntax, by using the plural form of the taxonomy instead of the section. You will probably only want to use the configuration values `:slug` or `:title`.
### Permalink Configuration Values
The following is a list of values that can be used in a `permalink` definition in your site `config` file. All references to time are dependent on the content's date.
`:year`
: the 4-digit year
`:month`
: the 2-digit month
`:monthname`
: the name of the month
`:day`
: the 2-digit day
`:weekday`
: the 1-digit day of the week (Sunday = 0)
`:weekdayname`
: the name of the day of the week
`:yearday`
: the 1- to 3-digit day of the year
`:section`
: the content's section
`:sections`
: the content's sections hierarchy
`:title`
: the content's title
`:slug`
: the content's slug (or title if no slug is provided in the front matter)
`:filename`
: the content's filename (without extension)
## Aliases
Aliases can be used to create redirects to your page from other URLs.
Aliases comes in two forms:
1. Starting with a `/` meaning they are relative to the `BaseURL`, e.g. `/posts/my-blogpost/`
2. They are relative to the `Page` they're defined in, e.g. `my-blogpost` or even something like `../blog/my-blogpost` (new in Hugo 0.55).
### Example: Aliases
Let's assume you create a new piece of content at `content/posts/my-awesome-blog-post.md`. The content is a revision of your previous post at `content/posts/my-original-url.md`. You can create an `aliases` field in the front matter of your new `my-awesome-blog-post.md` where you can add previous paths. The following examples show how to create this field in TOML and YAML front matter, respectively.
#### TOML Front Matter
{{< code file="content/posts/my-awesome-post.md" copy="false" >}}
+++
aliases = [
"/posts/my-original-url/",
"/2010/01/01/even-earlier-url.html"
]
+++
{{< /code >}}
#### YAML Front Matter
{{< code file="content/posts/my-awesome-post.md" copy="false" >}}
---
aliases:
- /posts/my-original-url/
- /2010/01/01/even-earlier-url.html
---
{{< /code >}}
Now when you visit any of the locations specified in aliases---i.e., *assuming the same site domain*---you'll be redirected to the page they are specified on. For example, a visitor to `example.com/posts/my-original-url/` will be immediately redirected to `example.com/posts/my-awesome-post/`.
### Example: Aliases in Multilingual
On [multilingual sites][multilingual], each translation of a post can have unique aliases. To use the same alias across multiple languages, prefix it with the language code.
In `/posts/my-new-post.es.md`:
```
---
aliases:
- /es/posts/my-original-post/
---
```
From Hugo 0.55 you can also have page-relative aliases, so ` /es/posts/my-original-post/` can be simplified to the more portable `my-original-post/`
### How Hugo Aliases Work
When aliases are specified, Hugo creates a directory to match the alias entry. Inside the directory, Hugo creates an `.html` file specifying the canonical URL for the page and the new redirect target.
For example, a content file at `posts/my-intended-url.md` with the following in the front matter:
```
---
title: My New post
aliases: [/posts/my-old-url/]
---
```
Assuming a `baseURL` of `example.com`, the contents of the auto-generated alias `.html` found at `https://example.com/posts/my-old-url/` will contain the following:
```
<!DOCTYPE html>
<html>
<head>
<title>https://example.com/posts/my-intended-url</title>
<link rel="canonical" href="https://example.com/posts/my-intended-url"/>
<meta name="robots" content="noindex">
<meta http-equiv="content-type" content="text/html; charset=utf-8"/>
<meta http-equiv="refresh" content="0; url=https://example.com/posts/my-intended-url"/>
</head>
</html>
```
The `http-equiv="refresh"` line is what performs the redirect, in 0 seconds in this case. If an end user of your website goes to `https://example.com/posts/my-old-url`, they will now be automatically redirected to the newer, correct URL. The addition of `<meta name="robots" content="noindex">` lets search engine bots know that they should not crawl and index your new alias page.
### Customize
You may customize this alias page by creating an `alias.html` template in the
layouts folder of your site (i.e., `layouts/alias.html`). In this case, the data passed to the template is
`Permalink`
: the link to the page being aliased
`Page`
: the Page data for the page being aliased
### Important Behaviors of Aliases
1. Hugo makes no assumptions about aliases. They also do not change based
on your UglyURLs setting. You need to provide absolute paths to your web root
and the complete filename or directory.
2. Aliases are rendered *before* any content are rendered and therefore will be overwritten by any content with the same location.
## Pretty URLs
Hugo's default behavior is to render your content with "pretty" URLs. No non-standard server-side configuration is required for these pretty URLs to work.
The following demonstrates the concept:
```
content/posts/_index.md
=> example.com/posts/index.html
content/posts/post-1.md
=> example.com/posts/post-1/
```
## Ugly URLs
If you would like to have what are often referred to as "ugly URLs" (e.g., example.com/urls.html), set `uglyurls = true` or `uglyurls: true` in your site's `config.toml` or `config.yaml`, respectively. You can also use the `--uglyURLs=true` [flag from the command line][usage] with `hugo` or `hugo server`.
If you want a specific piece of content to have an exact URL, you can specify this in the [front matter][] under the `url` key. The following are examples of the same content directory and what the eventual URL structure will be when Hugo runs with its default behavior.
See [Content Organization][contentorg] for more details on paths.
```
.
└── content
└── about
| └── _index.md // <- https://example.com/about/
├── posts
| ├── firstpost.md // <- https://example.com/posts/firstpost/
| ├── happy
| | └── ness.md // <- https://example.com/posts/happy/ness/
| └── secondpost.md // <- https://example.com/posts/secondpost/
└── quote
├── first.md // <- https://example.com/quote/first/
└── second.md // <- https://example.com/quote/second/
```
Here's the same organization run with `hugo --uglyURLs`:
```
.
└── content
└── about
| └── _index.md // <- https://example.com/about.html
├── posts
| ├── firstpost.md // <- https://example.com/posts/firstpost.html
| ├── happy
| | └── ness.md // <- https://example.com/posts/happy/ness.html
| └── secondpost.md // <- https://example.com/posts/secondpost.html
└── quote
├── first.md // <- https://example.com/quote/first.html
└── second.md // <- https://example.com/quote/second.html
```
## Canonicalization
By default, all relative URLs encountered in the input are left unmodified, e.g. `/css/foo.css` would stay as `/css/foo.css`. The `canonifyURLs` field in your site `config` has a default value of `false`.
By setting `canonifyURLs` to `true`, all relative URLs would instead be *canonicalized* using `baseURL`. For example, assuming you have `baseURL = https://example.com/`, the relative URL `/css/foo.css` would be turned into the absolute URL `https://example.com/css/foo.css`.
Benefits of canonicalization include fixing all URLs to be absolute, which may aid with some parsing tasks. Note, however, that all modern browsers handle this on the client without issue.
Benefits of non-canonicalization include being able to have scheme-relative resource inclusion; e.g., so that `http` vs `https` can be decided according to how the page was retrieved.
{{% note "`canonifyURLs` default change" %}}
In the May 2014 release of Hugo v0.11, the default value of `canonifyURLs` was switched from `true` to `false`, which we think is the better default and should continue to be the case going forward. Please verify and adjust your website accordingly if you are upgrading from v0.10 or older versions.
{{% /note %}}
To find out the current value of `canonifyURLs` for your website, you may use the handy `hugo config` command added in v0.13.
```
hugo config | grep -i canon
```
Or, if you are on Windows and do not have `grep` installed:
```
hugo config | FINDSTR /I canon
```
## Set URL in Front Matter
In addition to specifying permalink values in your site configuration for different content sections, Hugo provides even more granular control for individual pieces of content.
Both `slug` and `url` can be defined in individual front matter. For more information on content destinations at build time, see [Content Organization][contentorg].
From Hugo 0.55, you can use URLs relative to the current site context (the language), which makes it simpler to maintain. For a Japanese translation, both of the following examples would get the same URL:
```markdown
---
title: "Custom URL!"
url: "/jp/custom/foo"
---
```
```markdown
---
title: "Custom URL!"
url: "custom/foo"
---
```
## Relative URLs
By default, all relative URLs are left unchanged by Hugo, which can be problematic when you want to make your site browsable from a local file system.
Setting `relativeURLs` to `true` in your [site configuration][config] will cause Hugo to rewrite all relative URLs to be relative to the current content.
For example, if your `/posts/first/` page contains a link to `/about/`, Hugo will rewrite the URL to `../../about/`.
[config]: /getting-started/configuration/
[contentorg]: /content-management/organization/
[front matter]: /content-management/front-matter/
[multilingual]: /content-management/multilingual/
[sections]: /content-management/sections/
[usage]: /getting-started/usage/

23
docs/content/en/contribute/_index.md Normal file
View file

@ -0,0 +1,23 @@
---
title: Contribute to the Hugo Project
linktitle: Contribute to Hugo
description: Contribute to Hugo development and documentation.
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
categories: [contribute]
keywords: []
menu:
docs:
parent: "contribute"
weight: 01
weight: 01 #rem
draft: false
slug:
aliases: [/tutorials/how-to-contribute-to-hugo/,/community/contributing/]
toc: false
---
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.

442
docs/content/en/contribute/development.md Normal file
View file

@ -0,0 +1,442 @@
---
title: Contribute to Hugo Development
linktitle: Development
description: Hugo relies heavily on contributions from the open source community.
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
categories: [contribute]
keywords: [dev,open source]
authors: [digitalcraftsman]
menu:
docs:
parent: "contribute"
weight: 10
weight: 10
sections_weight: 10
draft: false
toc: true
---
## Introduction
Hugo is an open-source project and lives by the work of its [contributors][]. There are plenty of [open issues][issues], and we need your help to make Hugo even more awesome. You don't need to be a Go guru to contribute to the project's development.
## Assumptions
This contribution guide takes a step-by-step approach in hopes of helping newcomers. Therefore, we only assume the following:
* You are new to Git or open-source projects in general
* You are a fan of Hugo and enthusiastic about contributing to the project
{{% note "Additional Questions?" %}}
If you're struggling at any point in this contribution guide, reach out to the Hugo community in [Hugo's Discussion forum](https://discourse.gohugo.io).
{{% /note %}}
## Install Go
The installation of Go should take only a few minutes. You have more than one option to get Go up and running on your machine.
If you are having trouble following the installation guides for Go, check out [Go Bootcamp, which contains setups for every platform][gobootcamp] or reach out to the Hugo community in the [Hugo Discussion Forums][forums].
### Install Go From Source
[Download the latest stable version of Go][godl] and follow the official [Go installation guide][goinstall].
Once you're finished installing Go, let's confirm everything is working correctly. Open a terminal---or command line under Windows--and type the following:
```
go version
```
You should see something similar to the following written to the console. Note that the version here reflects the most recent version of Go as of the last update for this page:
```
go version go1.12 darwin/amd64
```
Next, make sure that you set up your `GOPATH` [as described in the installation guide][setupgopath].
You can print the `GOPATH` with `echo $GOPATH`. You should see a non-empty string containing a valid path to your Go workspace; for example:
```
/Users/<yourusername>/Code/go
```
### Install Go with Homebrew
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" >}}
brew install go
{{< /code >}}
### Install Go via GVM
More experienced users can use the [Go Version Manager][gvm] (GVM). GVM allows you to switch between different Go versions *on the same machine*. If you're a beginner, you probably don't need this feature. However, GVM makes it easy to upgrade to a new released Go version with just a few commands.
GVM comes in especially handy if you follow the development of Hugo over a longer period of time. Future versions of Hugo will usually be compiled with the latest version of Go. Sooner or later, you will have to upgrade if you want to keep up.
## Create a GitHub Account
If you're going to contribute code, you'll need to have an account on GitHub. Go to [www.github.com/join](https://github.com/join) and set up a personal account.
## Install Git on Your System
You will need to have Git installed on your computer to contribute to Hugo development. Teaching Git is outside the scope of the Hugo docs, but if you're looking for an excellent reference to learn the basics of Git, we recommend the [Git book][gitbook] if you are not sure where to begin. We will include short explanations of the Git commands in this document.
Git is a [version control system](https://en.wikipedia.org/wiki/Version_control) to track the changes of source code. Hugo depends on smaller third-party packages that are used to extend the functionality. We use them because we don't want to reinvent the wheel.
Go ships with a sub-command called `get` that will download these packages for us when we setup our working environment. The source code of the packages is tracked with Git. `get` will interact with the Git servers of the package hosters in order to fetch all dependencies.
Move back to the terminal and check if Git is already installed. Type in `git version` and press enter. You can skip the rest of this section if the command returned a version number. Otherwise [download](https://git-scm.com/downloads) the latest version of Git and follow this [installation guide](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git).
Finally, check again with `git version` if Git was installed successfully.
### Git Graphical Front Ends
There are several [GUI clients](https://git-scm.com/downloads/guis) that help you to operate Git. Not all are available for all operating systems and maybe differ in their usage. Because of this we will document how to use the command line, since the commands are the same everywhere.
### Install Hub on Your System (Optional)
Hub is a great tool for working with GitHub. The main site for it is [hub.github.com](https://hub.github.com/). Feel free to install this little Git wrapper.
On a Mac, you can install [Hub](https://github.com/github/hub) using [Homebrew](https://brew.sh):
```
brew install hub
```
Now we'll create an [alias in Bash](http://tldp.org/LDP/abs/html/aliases.html) so that typing `git` actually runs `Hub`:
```
echo "alias git='hub'" >> ~/.bash_profile
```
Confirm the installation:
```
git version 2.21.0
hub version 2.10.0
```
## Set up your working copy
You set up the working copy of the repository locally on your computer. Your local copy of the files is what you'll edit, compile, and end up pushing back to GitHub. The main steps are cloning the repository and creating your fork as a remote.
### Clone the repository
We assume that you've set up your `GOPATH` (see the section above if you're unsure about this). You should now copy the Hugo repository down to your computer. You'll hear this called "clone the repo". GitHub's [help pages](https://help.github.com/articles/cloning-a-repository/) give us a short explanation:
> When you create a repository on GitHub, it exists as a remote repository. You can create a local clone of your repository on your computer and sync between the two locations.
We're going to clone the [master Hugo repository](https://github.com/gohugoio/hugo). That seems counter-intuitive, since you won't have commit rights on it. But it's required for the Go workflow. You'll work on a copy of the master and push your changes to your own repository on GitHub.
So, let's make a new directory and clone that master repository:
```
mkdir $HOME/src
cd $HOME/src
git clone https://github.com/gohugoio/hugo.git
```
> Since Hugo 0.48, Hugo uses the Go Modules support built into Go 1.11 to build.
> The easiest is to clone Hugo in a directory outside of GOPATH
And then, install dependencies of Hugo by running the following in the cloned directory:
```
cd $HOME/src/hugo
go install
```
Hugo relies on [mage](github.com/magefile/mage) for some convenient build and test targets. If you don't already have it, get it:
```
go get github.com/magefile/mage
```
### Fork the repository
If you're not familiar with this term, GitHub's [help pages](https://help.github.com/articles/fork-a-repo/) provide again a simple explanation:
> A fork is a copy of a repository. Forking a repository allows you to freely experiment with changes without affecting the original project.
#### Fork by hand
Open the [Hugo repository](https://github.com/gohugoio/hugo) on GitHub and click on the "Fork" button in the top right.
![Fork button](/images/contribute/development/forking-a-repository.png)
Now open your fork repository on GitHub and copy the remote url of your fork. You can choose between HTTPS and SSH as protocol that Git should use for the following operations. HTTPS works always [if you're not sure](https://help.github.com/articles/which-remote-url-should-i-use/).
![Copy remote url](/images/contribute/development/copy-remote-url.png)
Switch back to the terminal and move into the directory of the cloned master repository from the last step.
```
cd $HOME/src/hugo
```
Now Git needs to know that our fork exists by adding the copied remote url:
```
git remote add <YOUR-GITHUB-USERNAME> <COPIED REMOTE-URL>
```
#### Fork with Hub
Alternatively, you can use the Git wrapper Hub. Hub makes forking a repository easy:
```
git fork
```
That command will log in to GitHub using your account, create a fork of the repository that you're currently working in, and add it as a remote to your working copy.
#### Trust, but verify
Let's check if everything went right by listing all known remotes:
```
git remote -v
```
The output should look similar:
```
digitalcraftsman git@github.com:digitalcraftsman/hugo.git (fetch)
digitalcraftsman git@github.com:digitalcraftsman/hugo.git (push)
origin https://github.com/gohugoio/hugo (fetch)
origin https://github.com/gohugoio/hugo (push)
```
## The Hugo Git Contribution Workflow
### Create a new branch
You should never develop against the "master" branch. The development team will not accept a pull request against that branch. Instead, create a descriptive named branch and work on it.
First, you should always pull the latest changes from the master repository:
```
git checkout master
git pull
```
Now we can create a new branch for your additions:
```
git checkout -b <BRANCH-NAME>
```
You can check on which branch you are with `git branch`. You should see a list of all local branches. The current branch is indicated with a little asterisk.
### Contribute to Documentation
Perhaps you want to start contributing to the Hugo docs. If so, you can ignore most of the following steps and focus on the `/docs` directory within your newly cloned repository. You can change directories into the Hugo docs using `cd docs`.
You can start Hugo's built-in server via `hugo server`. Browse the documentation by entering [http://localhost:1313](http://localhost:1313) in the address bar of your browser. The server automatically updates the page whenever you change content.
We have developed a [separate Hugo documentation contribution guide][docscontrib] for more information on how the Hugo docs are built, organized, and improved by the generosity of people like you.
### Build Hugo
While making changes in the codebase it's a good idea to build the binary to test them:
```
mage hugo
```
This command generates the binary file at the root of the repository.
If you want to install the binary in `$GOPATH/bin`, run
```
mage install
```
### Test
Sometimes changes on the codebase can cause unintended side effects. Or they don't work as expected. Most functions have their own test cases. You can find them in files ending with `_test.go`.
Make sure the commands
```
mage -v check
```
passes.
### Formatting
The Go code styleguide maybe is opinionated but it ensures that the codebase looks the same, regardless who wrote the code. Go comes with its own formatting tool. Let's apply the styleguide to our additions:
```
mage fmt
```
Once you made your additions commit your changes. Make sure that you follow our [code contribution guidelines](https://github.com/gohugoio/hugo/blob/master/CONTRIBUTING.md):
```
# Add all changed files
git add --all
git commit --message "YOUR COMMIT MESSAGE"
```
The commit message should describe what the commit does (e.g. add feature XYZ), not how it is done.
### Modify commits
You noticed some commit messages don't fulfill the code contribution guidelines or you just forget something to add some files? No problem. Git provides the necessary tools to fix such problems. The next two methods cover all common cases.
If you are unsure what a command does leave the commit as it is. We can fix your commits later in the pull request.
#### Modify the last commit
Let's say you want to modify the last commit message. Run the following command and replace the current message:
```
git commit --amend -m"YOUR NEW COMMIT MESSAGE"
```
Take a look at the commit log to see the change:
```
git log
# Exit with q
```
After making the last commit you may have forgot something. There is no need to create a new commit. Just add the latest changes and merge them into the intended commit:
```
git add --all
git commit --amend
```
#### Modify multiple commits
{{% warning "Be Careful Modifying Multiple Commits"%}}
Modifications such as those described in this section can have serious unintended consequences. Skip this section if you're not sure!
{{% /warning %}}
This is a bit more advanced. Git allows you to [rebase](https://git-scm.com/docs/git-rebase) commits interactively. In other words: it allows you to rewrite the commit history.
```
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:
```
pick 80d02a1 tpl: Add hasPrefix to the template funcs' "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
pick 33c8973 Begin workflow
pick 3502f2e Refactoring and typo fixes
```
In the case above we should merge the last to commits in the commit of this tutorial (`Add "How to contribute to Hugo" tutorial`). You can "squash" commits, i.e. merge two or more commits into a single one.
All operations are written before the commit message. Replace "pick" with an operation. In this case `squash` or `s` for short:
```
pick 80d02a1 tpl: Add hasPrefix to the template funcs' "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
squash 33c8973 Begin workflow
squash 3502f2e Refactoring and typo fixes
```
We also want to rewrite the commits message of the third last commit. We forgot "docs:" as prefix according to the code contribution guidelines. The operation to rewrite a commit is called `reword` (or `r` as shortcut).
You should end up with a similar setup:
```
pick 80d02a1 tpl: Add hasPrefix to the template funcs' "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
squash 33c8973 Begin workflow
squash 3502f2e Refactoring and typo fixes
```
Close the editor. It should open again with a new tab. A text is instructing you to define a new commit message for the last two commits that should be merged (aka "squashed"). Save the file with <kbd>CTRL</kbd>+<kbd>S</kbd> and close the editor again.
A last time a new tab opens. Enter a new commit message and save again. Your terminal should contain a status message. Hopefully this one:
```
Successfully rebased and updated refs/heads/<BRANCHNAME>.
```
Check the commit log if everything looks as expected. Should an error occur you can abort this rebase with `git rebase --abort`.
### Push commits
To push our commits to the fork on GitHub we need to specify a destination. A destination is defined by the remote and a branch name. Earlier, the defined that the remote url of our fork is the same as our GitHub handle, in my case `digitalcraftsman`. The branch should have the same as our local one. This makes it easy to identify corresponding branches.
```
git push --set-upstream <YOUR-GITHUB-USERNAME> <BRANCHNAME>
```
Now Git knows the destination. Next time when you to push commits you just need to enter `git push`.
If you modified your commit history in the last step GitHub will reject your try to push. This is a safety-feature because the commit history isn't the same and new commits can't be appended as usual. You can enforce this push explicitly with `git push --force`.
## Open a pull request
We made a lot of progress. Good work. In this step we finally open a pull request to submit our additions. Open the [Hugo master repository](https://github.com/gohugoio/hugo/) on GitHub in your browser.
You should find a green button labeled with "New pull request". But GitHub is clever and probably suggests you a pull request like in the beige box below:
![Open a pull request](/images/contribute/development/open-pull-request.png)
The new page summaries the most important information of your pull request. Scroll down and you find the additions of all your commits. Make sure everything looks as expected and click on "Create pull request".
### Accept the contributor license agreement
Last but not least you should accept the contributor license agreement (CLA). A new comment should be added automatically to your pull request. Click on the yellow badge, accept the agreement and authenticate yourself with your GitHub account. It just takes a few clicks and only needs to be done once.
![Accept the CLA](/images/contribute/development/accept-cla.png)
### Automatic builds
We use the [Travis CI loop](https://travis-ci.org/gohugoio/hugo) (Linux and OS&nbsp;X) and [AppVeyor](https://ci.appveyor.com/project/gohugoio/hugo/branch/master) (Windows) to compile Hugo with your additions. This should ensure that everything works as expected before merging your pull request. This in most cases only relevant if you made changes to the codebase of Hugo.
![Automic builds and their status](/images/contribute/development/ci-errors.png)
Above you can see that Travis wasn't able to compile the changes in this pull request. Click on "Details" and try to investigate why the build failed. But it doesn't have to be your fault. Mostly, the `master` branch that we used as foundation for your pull request should build without problems.
If you have questions, leave a comment in the pull request. We are willing to assist you.
## Where to start?
Thank you for reading through this contribution guide. Hopefully, we will see you again soon on GitHub. There are plenty of [open issues][issues] for you to help with.
Feel free to [open an issue][newissue] if you think you found a bug or you have a new idea to improve Hugo. We are happy to hear from you.
## Additional References for Learning Git and Go
* [Codecademy's Free "Learn Git" Course][codecademy] (Free)
* [Code School and GitHub's "Try Git" Tutorial][trygit] (Free)
* [The Git Book][gitbook] (Free)
* [Go Bootcamp][gobootcamp]
* [GitHub Pull Request Tutorial, Thinkful][thinkful]
[codecademy]: https://www.codecademy.com/learn/learn-git
[contributors]: https://github.com/gohugoio/hugo/graphs/contributors
[docscontrib]: /contribute/documentation/
[forums]: https://discourse.gohugo.io
[gitbook]: https://git-scm.com/
[gobootcamp]: http://www.golangbootcamp.com/book/get_setup
[godl]: https://golang.org/dl/
[goinstall]: https://golang.org/doc/install
[gvm]: https://github.com/moovweb/gvm
[issues]: https://github.com/gohugoio/hugo/issues
[newissue]: https://github.com/gohugoio/hugo/issues/new
[releases]: /getting-started/
[setupgopath]: https://golang.org/doc/code.html#Workspaces
[thinkful]: https://www.thinkful.com/learn/github-pull-request-tutorial/
[trygit]: https://try.github.io/levels/1/challenges/1

333
docs/content/en/contribute/documentation.md Normal file
View file

@ -0,0 +1,333 @@
---
title: Contribute to the Hugo Docs
linktitle: Documentation
description: 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.
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
categories: [contribute]
keywords: [docs,documentation,community, contribute]
menu:
docs:
parent: "contribute"
weight: 20
weight: 20
sections_weight: 20
draft: false
aliases: [/contribute/docs/]
toc: 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](https://github.com/gohugoio/hugoDocs) on GitHub and cloned the repository locally on your machine. For more information, you can see [GitHub's documentation on "forking"][ghforking] or follow along with [Hugo's development contribution guide][hugodev].
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](/functions/).
`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](#adding-code-blocks). 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](https://highlightjs.org/) 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" }}
<main>
<article>
<header>
<h1>{{.Title}}</h1>
{{with .Params.subtitle}}
<span>{{.}}</span>
</header>
<div>
{{.Content}}
</div>
<aside>
{{.TableOfContents}}
</aside>
</article>
</main>
{{ end }}
{{< /code >}}
<!-- #### Output Code Block
The `output` shortcode is almost identical to the `code` shortcode but only takes and requires `file`. The purpose of `output` is to show *rendered* HTML and therefore almost always follows another basic code block *or* and instance of the `code` shortcode:
```
{{%/* output file="posts/my-first-post/index.html" */%}}
<h1>This is my First Hugo Blog Post</h1>
<p>I am excited to be using Hugo.</p>
{{%/* /output */%}}
```
The preceding `output` example will render as follows to the Hugo docs:
{{< output file="posts/my-first-post/index.html" >}}
<h1>This is my First Hugo Blog Post</h1>
<p>I am excited to be using Hugo.</p>
{{< /output >}} -->
## Blockquotes
Blockquotes can be added to the Hugo documentation using [typical Markdown blockquote syntax][bqsyntax]:
```
> 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][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>`](http://html5doctor.com/cite-and-blockquote-reloaded/). 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][sourceforge]. 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][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](/contribute/development/), the Hugo team expects you to create a separate branch/fork when you make your contributions to the Hugo docs.
{{% /note %}}
[abe]: https://en.wikipedia.org/wiki/Kobo_Abe
[archetypes]: /content-management/archetypes/
[bqsyntax]: https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet#blockquotes
[charcount]: https://www.lettercount.com/
[`docs/static/images/showcase/`]: https://github.com/gohugoio/hugo/tree/master/docs/static/images/showcase/
[ghforking]: https://help.github.com/articles/fork-a-repo/
[hugodev]: /contribute/development/
[shortcodeparams]: content-management/shortcodes/#shortcodes-without-markdown
[sourceforge]: http://docutils.sourceforge.net/docs/ref/rst/directives.html#admonitions
[templating function]: /functions/

32
docs/content/en/contribute/themes.md Normal file
View file

@ -0,0 +1,32 @@
---
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.
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-27
categories: [contribute]
keywords: [contribute,themes,design]
authors: [digitalcraftsman]
menu:
docs:
parent: "contribute"
weight: 30
weight: 30
sections_weight: 30
draft: false
aliases: [/contribute/theme/]
wip: true
toc: true
---
A collection of all themes created by the Hugo community, including screenshots and demos, can be found at [www.themes.gohugo.io]. Every theme in this list will automatically be added to the theme site.
Another great site for Hugo themes is [jamstackthemes.dev/](https://jamstackthemes.dev/ssg/hugo/).
### Add Your Theme to the Repo
In order to add your Hugo theme to [www.themes.gohugo.io] please [open up a new issue in the theme repository](https://github.com/gohugoio/hugoThemes/issues/new?template=theme-submission.md). **Please make sure that you've read the theme submission guidelines in the [README](https://github.com/gohugoio/hugoThemes/blob/master/README.md#adding-a-theme-to-the-list) of the hugoThemes repository.**
[www.themes.gohugo.io]: https://themes.gohugo.io/

20
docs/content/en/documentation.md Normal file
View file

@ -0,0 +1,20 @@
---
title: Hugo Documentation
linktitle: Hugo
description: Hugo is the world's fastest static website engine. It's written in Go (aka Golang) and developed by bep, spf13 and friends.
date: 2017-02-01
publishdate: 2017-02-01
menu:
main:
parent: "section name"
weight: 01
weight: 01 #rem
draft: false
slug:
aliases: []
toc: false
layout: documentation-home
---
Hugo is the **world's fastest static website engine.** It's written in Go (aka Golang) and developed by [bep](https://github.com/bep), [spf13](https://github.com/spf13) and [friends](https://github.com/gohugoio/hugo/graphs/contributors).
Below you will find some of the most common and helpful pages from our documentation.

89
docs/content/en/functions/GetPage.md Normal file
View file

@ -0,0 +1,89 @@
---
title: .GetPage
description: "Gets a `Page` of a given `path`."
godocref:
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
categories: [functions]
menu:
docs:
parent: "functions"
keywords: [sections,lists,indexes]
signature: [".GetPage PATH"]
workson: []
hugoversion:
relatedfuncs: []
deprecated: false
aliases: []
---
`.GetPage` returns a page of a given `path`. Both `Site` and `Page` implements this method. The `Page` variant will, if given a relative path -- i.e. a path without a leading `/` -- try look for the page relative to the current page.
{{% note %}}
**Note:** We overhauled and simplified the `.GetPage` API in Hugo 0.45. Before that you needed to provide a `Kind` attribute in addition to the path, e.g. `{{ .Site.GetPage "section" "blog" }}`. This will still work, but is now superflous.
{{% /note %}}
```go-html-template
{{ with .Site.GetPage "/blog" }}{{ .Title }}{{ end }}
```
This method wil return `nil` when no page could be found, so the above will not print anything if the blog section is not found.
To find a regular page in the blog section::
```go-html-template
{{ with .Site.GetPage "/blog/my-post.md" }}{{ .Title }}{{ end }}
```
And since `Page` also provides a `.GetPage` method, the above is the same as:
```go-html-template
{{ with .Site.GetPage "/blog" }}
{{ with .GetPage "my-post.md" }}{{ .Title }}{{ end }}
{{ end }}
```
## .GetPage and Multilingual Sites
The previous examples have used the full content filename to lookup the post. Depending on how you have organized your content (whether you have the language code in the file name or not, e.g. `my-post.en.md`), you may want to do the lookup without extension. This will get you the current language's version of the page:
```go-html-template
{{ with .Site.GetPage "/blog/my-post" }}{{ .Title }}{{ end }}
```
## .GetPage Example
This code snippet---in the form of a [partial template][partials]---allows you to do the following:
1. Grab the index object of your `tags` [taxonomy][].
2. Assign this object to a variable, `$t`
3. Sort the terms associated with the taxonomy by popularity.
4. Grab the top two most popular terms in the taxonomy (i.e., the two most popular tags assigned to content.
{{< code file="grab-top-two-tags.html" >}}
<ul class="most-popular-tags">
{{ $t := .Site.GetPage "/tags" }}
{{ range first 2 $t.Data.Terms.ByCount }}
<li>{{ . }}</li>
{{ end }}
</ul>
{{< /code >}}
## `.GetPage` on Page Bundles
If the page retrieved by `.GetPage` is a [Leaf Bundle][leaf_bundle], and you
need to get the nested _**page** resources_ in that, you will need to use the
methods in `.Resources` as explained in the [Page Resources][page_resources]
section.
See the [Headless Bundle][headless_bundle] documentation for an example.
[partials]: /templates/partials/
[taxonomy]: /content-management/taxonomies/
[page_kinds]: /templates/section-templates/#page-kinds
[leaf_bundle]: /content-management/page-bundles/#leaf-bundles
[headless_bundle]: /content-management/page-bundles/#headless-bundle
[page_resources]: /content-management/page-resources/

38
docs/content/en/functions/NumFmt.md Normal file
View file

@ -0,0 +1,38 @@
---
title: lang.NumFmt
description: "Formats a number with a given precision using the requested `negative`, `decimal`, and `grouping` options. The `options` parameter is a string consisting of `<negative> <decimal> <grouping>`."
godocref: ""
workson: []
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-08-21
categories: [functions]
keywords: [numbers]
menu:
docs:
parent: "functions"
toc: false
signature: ["lang.NumFmt PRECISION NUMBER [OPTIONS [DELIMITER]]"]
workson: []
hugoversion:
relatedfuncs: []
deprecated: false
draft: false
aliases: []
comments:
---
The default options value is `- . ,`. The default delimiter within the options
value is a space. If you need to use a space as one of the options, set a
custom delimiter.
Numbers greater than or equal to 5 are rounded up. For example, if precision is set to `0`, `1.5` becomes `2`, and `1.4` becomes `1`.
```
{{ lang.NumFmt 2 12345.6789 }} → 12,345.68
{{ lang.NumFmt 2 12345.6789 "- , ." }} → 12.345,68
{{ lang.NumFmt 0 -12345.6789 "- . ," }} → -12,346
{{ lang.NumFmt 6 -12345.6789 "- ." }} → -12345.678900
{{ lang.NumFmt 6 -12345.6789 "-|.| " "|" }} → -1 2345.678900
{{ -98765.4321 | lang.NumFmt 2 }} → -98,765.43
```

20
docs/content/en/functions/_index.md Normal file
View file

@ -0,0 +1,20 @@
---
title: Functions Quick Reference
linktitle: Functions Quick Reference
description: Comprehensive list of Hugo templating functions, including basic and advanced usage examples.
godocref:
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
keywords: []
menu:
docs:
parent: "functions"
weight: 01 #rem
draft: false
aliases: [/layout/functions/,/templates/functions]
---
Go templates are lightweight but extensible. Go itself supplies built-in functions, including comparison operators and other basic tools. These are listed in the [Go template documentation][gofuncs]. Hugo has added additional functions to the basic template logic.
[gofuncs]: https://golang.org/pkg/text/template/#hdr-Functions

28
docs/content/en/functions/abslangurl.md Normal file
View file

@ -0,0 +1,28 @@
---
title: absLangURL
description: Adds the absolute URL with correct language prefix according to site configuration for multilingual.
godocref:
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
categories: [functions]
menu:
docs:
parent: "functions"
keywords: [multilingual,i18n,urls]
signature: ["absLangURL INPUT"]
workson: []
hugoversion:
relatedfuncs: [relLangURL]
deprecated: false
aliases: []
---
Both `absLangURL` and [`relLangURL`](/functions/rellangurl/) are similar to their [`absURL`](/functions/absurl/) and [`relURL`](/functions/relurl) relatives but will add the correct language prefix when the site is configured with more than one language.
So for a site `baseURL` set to `https://example.com/hugo/` and the current language is `en`:
```
{{ "blog/" | absLangURL }} → "https://example.com/hugo/en/blog/"
{{ "blog/" | relLangURL }} → "/hugo/en/blog/"
```

51
docs/content/en/functions/absurl.md Normal file
View file

@ -0,0 +1,51 @@
---
title: absURL
description: Creates an absolute URL based on the configured baseURL.
godocref:
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
categories: [functions]
menu:
docs:
parent: "functions"
keywords: [urls]
signature: ["absURL INPUT"]
workson: []
hugoversion:
relatedfuncs: [relURL]
deprecated: false
aliases: []
---
Both `absURL` and `relURL` consider the configured value of `baseURL` in your site's [`config` file][configuration]. Given a `baseURL` set to `https://example.com/hugo/`:
```
{{ "mystyle.css" | absURL }} → "https://example.com/hugo/mystyle.css"
{{ "mystyle.css" | relURL }} → "/hugo/mystyle.css"
{{ "http://gohugo.io/" | relURL }} → "http://gohugo.io/"
{{ "http://gohugo.io/" | absURL }} → "http://gohugo.io/"
```
The last two examples may look strange but can be very useful. For example, the following shows how to use `absURL` in [JSON-LD structured data (SEO)][jsonld], where some of your images for a piece of content may or may not be hosted locally:
{{< code file="layouts/partials/schemaorg-metadata.html" download="schemaorg-metadata.html" >}}
<script type="application/ld+json">
{
"@context" : "http://schema.org",
"@type" : "BlogPosting",
"image" : {{ apply .Params.images "absURL" "." }}
}
</script>
{{< /code >}}
The above uses the [apply function][] and also exposes how the Go template parser JSON-encodes objects inside `<script>` tags. See [the safeJS template function][safejs] for examples of how to tell Hugo not to escape strings inside of such tags.
{{% note "Ending Slash" %}}
`absURL` and `relURL` are smart about missing slashes, but they will *not* add a closing slash to a URL if it is not present.
{{% /note %}}
[apply function]: /functions/apply/
[configuration]: /getting-started/configuration/
[jsonld]: https://developers.google.com/search/docs/guides/intro-structured-data
[safejs]: /functions/safejs

52
docs/content/en/functions/adddate.md Normal file
View file

@ -0,0 +1,52 @@
---
title: .AddDate
description: Returns the time corresponding to adding the given number of years, months, and days passed to the function.
godocref: https://golang.org/pkg/time/#Time.AddDate
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
categories: [functions]
menu:
docs:
parent: "functions"
keywords: [dates,time]
signature: [".AddDate YEARS MONTHS DAYS"]
workson: [times]
hugoversion:
relatedfuncs: [now]
deprecated: false
aliases: []
---
The `AddDate` function takes three arguments in logical order of `years`, `months`, and `days`.
## Example: Randomized Tweets from the Last 2 Years
Let's assume you have a file at `data/tweets.toml` that contains a list of Tweets to display on your site's homepage. The file is filled with `[[tweet]]` blocks; e.g.---
```
[[tweet]]
name = "Steve Francia"
twitter_handle = "@spf13"
quote = "I'm creator of Hugo. #metadocreference"
link = "https://twitter.com/spf13"
date = "2017-01-07T00:00:00Z"
```
Let's assume you want to grab Tweets from the last two years and present them in a random order. In conjunction with the [`where`](/functions/where/) and [`now`](/functions/now/) functions, you can limit our range to the last two years via `now.AddDate -2 0 0`, which represents a point in time 2 years, 0 days, and 0 hours before the time of your last site build.
{{< code file="partials/templates/random-tweets.html" download="tweets.html" >}}
{{ range where $.Site.Data.tweets.tweet "date" "ge" (now.AddDate -2 0 0) | shuffle }}
<div class="item">
<blockquote>
<p>
{{ .quote | safeHTML }}
</p>
&mdash; {{ .name }} ({{ .twitter_handle }}) <a href="{{ .link }}">
{{ dateFormat "January 2, 2006" .date }}
</a>
</blockquote>
</div>
{{ end }}
{{< /code >}}

66
docs/content/en/functions/after.md Normal file
View file

@ -0,0 +1,66 @@
---
title: after
description: "`after` slices an array to only the items after the <em>N</em>th item."
godocref:
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
categories: [functions]
menu:
docs:
parent: "functions"
keywords: [iteration]
signature: ["after INDEX COLLECTION"]
workson: []
hugoversion:
relatedfuncs: [last,first,seq]
deprecated: false
aliases: []
---
The following shows `after` being used in conjunction with the [`slice` function][slice]:
```
{{ $data := slice "one" "two" "three" "four" }}
{{ range after 2 $data }}
{{ . }}
{{ end }}
→ ["three", "four"]
```
## Example of `after` with `first`: 2nd&ndash;4th Most Recent Articles
You can use `after` in combination with the [`first` function][] and Hugo's [powerful sorting methods][lists]. Let's assume you have a list page at `example.com/articles`. You have 10 articles, but you want your templating for the [list/section page][] to show only two rows:
1. The top row is titled "Featured" and shows only the most recently published article (i.e. by `publishdate` in the content files' front matter).
2. The second row is titled "Recent Articles" and shows only the 2nd- to 4th-most recently published articles.
{{< code file="layouts/section/articles.html" download="articles.html" >}}
{{ define "main" }}
<section class="row featured-article">
<h2>Featured Article</h2>
{{ range first 1 .Pages.ByPublishDate.Reverse }}
<header>
<h3><a href="{{.Permalink}}">{{.Title}}</a></h3>
</header>
<p>{{.Description}}</p>
{{ end }}
</section>
<div class="row recent-articles">
<h2>Recent Articles</h2>
{{ range first 3 (after 1 .Pages.ByPublishDate.Reverse) }}
<section class="recent-article">
<header>
<h3><a href="{{.Permalink}}">{{.Title}}</a></h3>
</header>
<p>{{.Description}}</p>
</section>
{{ end }}
</div>
{{ end }}
{{< /code >}}
[`first` function]: /functions/first/
[list/section page]: /templates/section-templates/
[lists]: /lists/
[slice]: /functions/slice/

Some files were not shown because too many files have changed in this diff Show more