github/hugo
1
0
Fork 0
mirror of https://github.com/gohugoio/hugo.git synced 2024-11-21 20:46:30 -05:00
Code Issues Projects Releases Packages Wiki Activity

Merge commit '00c4484c7092181729f6f470805bc7d72e8ad17b'

Browse source
This commit is contained in:
Bjørn Erik Pedersen 2022-11-17 16:16:19 +01:00
commit f04cc581e1
No known key found for this signature in database
GPG key ID: 330E6E2BD4859D8F
217 changed files with 2437 additions and 2821 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

30
docs/.cspell.json
View file

@ -34,6 +34,7 @@
"brlink",
"Brotli",
"Browsersync",
"canonicalization",
"canonify",
"Catmull",
"Catwoman",
@ -61,6 +62,8 @@
"datatable",
"DATOCMS",
"debugconfig",
"defang",
"Deindent",
"DELIM",
"dhersam",
"digitalcraftsman",
@ -72,17 +75,21 @@
"DRING",
"Eiqc",
"Eliott",
"embeddable",
"Emojify",
"Enwrite",
"eopkg",
"eparis",
"errorf",
"erroridf",
"esbuild",
"Evernote",
"Exif",
"exitwp",
"expirydate",
"Feminella",
"firstpost",
"Flickr",
"Formspree",
"fpath",
"Francia",
@ -91,10 +98,12 @@
"funcs",
"funcsig",
"Garen",
"Garuda",
"gcloud",
"Getenv",
"getjson",
"getpage",
"Gitee",
"Gmfc",
"Goel",
"Gohugo",
@ -106,6 +115,7 @@
"govendor",
"Gowans",
"Grayscale",
"Gregor",
"Gruber",
"gtag",
"gvfs",
@ -141,10 +151,12 @@
"Joomla",
"JRBR",
"jsonify",
"Karmada",
"katex",
"keycdn",
"KEYVALS",
"kubernetes",
"Kubuntu",
"Lanczos",
"langformatnumber",
"lastmod",
@ -152,6 +164,7 @@
"linktitle",
"Lipi",
"lrwxr",
"Lubuntu",
"maingo",
"markdownified",
"markdownify",
@ -188,6 +201,7 @@
"newparam",
"Nichlas",
"Nikhil",
"Nikola",
"Njjy",
"nlist",
"nobr",
@ -221,6 +235,7 @@
"Poupin",
"prerender",
"println",
"Pritchard",
"publishdate",
"Pygments",
"qref",
@ -249,6 +264,7 @@
"safejs",
"Samsa",
"schemaorg",
"setx",
"Shekhar",
"Shortcode",
"Shortcodes",
@ -257,7 +273,9 @@
"Sindre",
"sitemapindex",
"sitemapxml",
"slugorfilename",
"Smartcrop",
"Sobre",
"Sprintf",
"Startseite",
"strconv",
@ -278,6 +296,7 @@
"Tknx",
"TLDR",
"TMPDIR",
"toclevels",
"TOCSS",
"todos",
"tojson",
@ -288,6 +307,8 @@
"toyaml",
"twitteruser",
"Unmarshal",
"unpublishdate",
"Unsharp",
"urlize",
"urlset",
"utimestamp",
@ -301,15 +322,19 @@
"wibble",
"wordcount",
"workson",
"Wowchemy",
"wpxr",
"Xbaabbab",
"Xubuntu",
"xvzf",
"yoyoyo",
"yunbox",
"Zgotmpl",
"Zorin",
"zzbbaabb",
"مدونتي"
],
"language": "en,en-GB,en-US,de,fr",
"language": "en,en-US,de,fr",
"allowCompoundWords": true,
"files": [
"**/*.md"
@ -331,5 +356,6 @@
"**/news/*",
"**/showcase/*"
],
"useGitignore": true
"useGitignore": true,
"enabled": true
}

26
docs/.github/workflows/codeql-analysis.yml vendored Normal file
View file

@ -0,0 +1,26 @@
name: "CodeQL"
on:
schedule:
- cron: "0 0 1 * *"
jobs:
analyze:
name: Analyze
runs-on: ubuntu-latest
permissions:
actions: read
contents: read
security-events: write
steps:
- name: Checkout repository
uses: actions/checkout@v3
- name: Initialize CodeQL
uses: github/codeql-action/init@v2
with:
languages: "javascript"
- name: Perform CodeQL Analysis
uses: github/codeql-action/analyze@v2

5
docs/.github/workflows/spellcheck.yml vendored
View file

@ -1,4 +1,4 @@
name: 'Check spelling'
name: "Check spelling"
on: # rebuild any PRs and main branch changes
push:
branches-ignore:
@ -15,6 +15,7 @@ jobs:
- uses: actions/checkout@v3
- uses: streetsidesoftware/cspell-action@v2
with:
check_dot_files: false
incremental_files_only: true
inline: warning
strict: false
incremental_files_only: true

41
docs/.github/workflows/super-linter.yml vendored Normal file
View file

@ -0,0 +1,41 @@
name: Super Linter
on:
workflow_dispatch:
permissions:
contents: read # to fetch code (actions/checkout)
jobs:
build:
permissions:
contents: read # to fetch code (actions/checkout)
statuses: write # to mark status of each linter run (github/super-linter/slim)
name: Lint Code Base
runs-on: ubuntu-latest
if: ${{ github.actor != 'dependabot[bot]' }}
steps:
- name: Checkout Code
uses: actions/checkout@v3
- name: Lint Code Base
uses: github/super-linter/slim@v4
env:
DEFAULT_BRANCH: master
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
IGNORE_GITIGNORED_FILES: true
LINTER_RULES_PATH: /
LOG_LEVEL: NOTICE
MARKDOWN_CONFIG_FILE: .markdownlint.yaml
SUPPRESS_POSSUM: true
VALIDATE_CSS: false
VALIDATE_EDITORCONFIG: false
VALIDATE_GITLEAKS: false
VALIDATE_HTML: false
VALIDATE_JAVASCRIPT_STANDARD: false
VALIDATE_JSCPD: false
VALIDATE_NATURAL_LANGUAGE: false
VALIDATE_SHELL_SHFMT: false
VALIDATE_XML: false

24
docs/.markdownlint.yaml
View file

@ -1,4 +1,24 @@
# https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md
MD013: false # Line length
MD033: false # Inline HTML
MD002: false
MD003: false
MD004: false
MD007: false
MD012:
maximum: 2
MD013: false
MD014: false
MD022: false
MD024: false
MD031: false
MD032: false
MD033: false
MD034: false
MD036: false
MD037: false
MD038: false
MD041: false
MD046: false
MD049: false
MD050: false
MD053: false

6
docs/.markdownlintignore Normal file
View file

@ -0,0 +1,6 @@
**/commands/**
**/functions/**
**/news/**
**/showcase/**
**/zh/**
**/license.md

3
docs/.textlintignore Normal file
View file

@ -0,0 +1,3 @@
**/news/**
**/showcase/**
**/zh/**

3
docs/.vscode/extensions.json vendored
View file

@ -1,6 +1,7 @@
{
"recommendations": [
"DavidAnson.vscode-markdownlint",
"EditorConfig.EditorConfig",
"esbenp.prettier-vscode",
"streetsidesoftware.code-spell-checker"
]
}

2
docs/README.md
View file

@ -11,7 +11,7 @@ We welcome contributions to Hugo of any kind including documentation, suggestion
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.*
*Pull requests shall **only** contain changes to the actual documentation. However, changes on the codebase 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 the following criteria in mind when writing:

2
docs/_vendor/github.com/gohugoio/gohugoioTheme/assets/css/_font-family.css generated
View file

@ -1,4 +1,4 @@
/* From http://cssfontstack.com */
/* From https://www.cssfontstack.com */
code, .code, pre code, .highlight pre {
font-family: 'inconsolata',Menlo,Monaco,'Courier New',monospace;
}

11
docs/_vendor/github.com/gohugoio/gohugoioTheme/assets/css/_hljs.css generated
View file

@ -1,11 +0,0 @@
/* modified from:*/
@import 'highlight.js/styles/atom-one-light.css';
/* hljs-template-variable covers the handlebars templating*/
.hljs-template-variable {
color: var(--primary-color);
}
.hljs-attr {
color: var(--accent-color-light);
}

21
docs/_vendor/github.com/gohugoio/gohugoioTheme/assets/index.js generated
View file

@ -1,12 +1,11 @@
require("typeface-muli")
require('typeface-muli');
import styles from './css/main.css';
import './js/clipboardjs.js'
import './js/codeblocks.js'
import './js/docsearch.js'
import './js/hljs.js'
import './js/lazysizes.js'
import './js/menutoggle.js'
import './js/scrolldir.js'
import './js/smoothscroll.js'
import './js/tabs.js'
import './js/nojs.js'
import './js/clipboardjs.js';
import './js/codeblocks.js';
import './js/docsearch.js';
import './js/lazysizes.js';
import './js/menutoggle.js';
import './js/scrolldir.js';
import './js/smoothscroll.js';
import './js/tabs.js';
import './js/nojs.js';

19
docs/_vendor/github.com/gohugoio/gohugoioTheme/assets/js/hljs.js generated
View file

@ -1,19 +0,0 @@
var hljs = require('highlight.js/lib/highlight.js');
hljs.registerLanguage('bash', require('highlight.js/lib/languages/bash'));
hljs.registerLanguage('css', require('highlight.js/lib/languages/css'));
hljs.registerLanguage('markdown', require('highlight.js/lib/languages/markdown'));
hljs.registerLanguage('diff', require('highlight.js/lib/languages/diff'));
// hljs.registerLanguage('go', require('highlight.js/lib/languages/go'));
hljs.registerLanguage('javascript', require('highlight.js/lib/languages/javascript'));
hljs.registerLanguage('json', require('highlight.js/lib/languages/json'));
hljs.registerLanguage('yaml', require('highlight.js/lib/languages/yaml'));
hljs.registerLanguage('xml', require('highlight.js/lib/languages/xml'));
hljs.registerLanguage('html', require('highlight.js/lib/languages/handlebars'));
hljs.registerLanguage("go", function(e) {
var t = { keyword: "code output note warning break default func interface select case map struct chan else goto package switch const fallthrough if range end type continue for import return var go defer bool byte complex64 complex128 float32 float64 int8 int16 int32 int64 string uint8 uint16 uint32 uint64 int uint uintptr rune id autoplay Get", literal: "file download copy true false iota nil Pages with", built_in: "append cap close complex highlight copy imag len make new panic print println real recover delete Site Data tweet youtube ref relref vimeo instagram gist figure innershortcode" };
return { aliases: ["golang","hugo"], k: t, i: "</", c: [e.CLCM, e.CBCM, { cN: "string", v: [e.QSM, { b: "'", e: "[^\\\\]'" }, { b: "`", e: "`" }] }, { cN: "number", v: [{ b: e.CNR + "[dflsi]", r: 1 }, e.CNM] }, { b: /:=/ }, { cN: "function", bK: "func", e: /\s*\{/, eE: !0, c: [e.TM, { cN: "params", b: /\(/, e: /\)/, k: t, i: /["']/ }] }] }
});
hljs.initHighlightingOnLoad();

11
docs/_vendor/github.com/gohugoio/gohugoioTheme/assets/output/css/app.css generated
View file

@ -4083,7 +4083,7 @@ img { max-width: 100%; }
max-width: 30em;
}
.measure-wide-l {
max-width: 40em;
max-width: 34em;
}
.measure-narrow-l {
max-width: 20em;
@ -4768,11 +4768,6 @@ h6:hover .header-link {
padding: 0;
margin: 0;
}
pre, .pre {
overflow-x: auto;
overflow-y: hidden;
overflow: scroll;
}
code {
padding: 0.2em;
margin: 0;
@ -4780,7 +4775,7 @@ code {
background-color: rgba(27, 31, 35, .05);
border-radius: 3px;
}
pre code {
pre code {
display: block;
padding: 1.5em 1.5em;
font-size: .875rem;
@ -4992,7 +4987,7 @@ dd {
font-size: calc(0.70833rem + 0.83333vw);
}
}
/* From http://cssfontstack.com */
/* From https://www.cssfontstack.com */
code, .code, pre code, .highlight pre {
font-family: 'inconsolata',Menlo,Monaco,'Courier New',monospace;
}

8
docs/_vendor/github.com/gohugoio/gohugoioTheme/assets/output/js/app.js generated
View file

File diff suppressed because one or more lines are too long

30
docs/_vendor/github.com/gohugoio/gohugoioTheme/data/sponsors.toml generated
View file

@ -1,18 +1,22 @@
[[banners]]
name = "Linode"
link = "https://www.linode.com/"
logo = "/images/sponsors/linode-logo_standard_light_medium.png"
copy = ""
name = "Linode"
link = "https://www.linode.com/"
logo = "/images/sponsors/linode-logo_standard_light_medium.png"
utm_campaign = "hugosponsor"
[[banners]]
name = "eSolia"
link = "https://esolia.com/post/why-did-esolia-choose-hugo/"
logo = "/images/sponsors/esolia-logo.svg"
copy = ""
name = "eSolia"
link = "https://esolia.com/post/why-did-esolia-choose-hugo/"
logo = "/images/sponsors/esolia-logo.svg"
utm_campaign = "hugosponsor"
[[banners]]
name = "BEP Consulting"
link = "https://bep.consulting"
logo = "/images/sponsors/bep-consulting.svg"
bgcolor = "#004887"
copy = ""
name = "ButterCMS"
link = "https://buttercms.com/hugo-cms/"
logo = "/images/sponsors/butter-light.svg"
utm_campaign = "sponsorship"
bgcolor = "#131A3E"
#hugohome
#hugofooter
#hugogithub

65
docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/home-page-sections/sponsors.html generated
View file

@ -1,38 +1,41 @@
{{$classes_box := "ba b--dark-gray bg-light-gray br3 flex flex-column flex-wrap items-center justify-center ph3 pv4 mb4 w-100 w-30-l "}}
{{$gtag := .gtag | default "unknown" }}
{{ $classes_box := "ba b--dark-gray bg-light-gray br3 flex flex-column flex-wrap items-center justify-center ph3 pv4 mb4 w-100 w-30-l " }}
{{ $gtag := .gtag | default "unknown" }}
{{ $classes_box := "ba b--dark-gray bg-light-gray br3 flex flex-column flex-wrap items-center justify-center ph3 pv4 mb4 w-100 w-30-l " }}
{{ $gtag := .gtag | default "unknown" }}
{{ $utmSource := cond (eq $gtag "footer") "hugofooter" "hugohome" }}
{{ with .cx.Site.Data.sponsors }}
<section class="{{ $.classes_section | default "bg-primary-color-dark b--dark-gray bb bt ph5 pv4 w-100"}}">
<div class="center mw9"> 
<section
class="{{ $.classes_section | default "bg-primary-color-dark b--dark-gray bb bt ph5 pv4 w-100" }}">
<div class="center mw9">
<h3 class="b f3 mv0 light-gray">Hugo Sponsors</h3>
<div class="flex-ns flex-wrap center justify-between pt3">
{{ range .banners }}
{{ $banner := . }}
{{if .logo}}
<div class="{{$classes_box}} o-100"{{ with .bgcolor }} style="background-color: {{ . }};"{{ end}}>
{{with .link -}}
{{ $url := printf "%s?%s" . (querify "utm_source" "homepage" "utm_medium" "banner" "utm_campaign" "hugosponsor") | safeURL }}
{{ if eq (getenv "HUGO_ENV") "production" | or (eq $.cx.Site.Params.env "production") }}
{{ $gtagID := printf "Sponsor %s %s" $banner.name $gtag | title }}
<a href="{{ $url }}" onclick="trackOutboundLink({{ printf "'%s', '%s'" $gtagID $url | safeJS }});" class="grow">
{{ else }}
<a href="{{ $url }}" class="grow">
{{ end }}
{{- end}}
<img src="{{ .logo }}" alt="Logo for {{ .name }}" class="img h3 center" />
{{with .link}}</a>{{end}}
{{with .copy}}
<p class="center lh-copy gray mv1 tc {{$.classes_copy | default "f5 w-70-ns"}}">
{{- . -}}
</p>
{{end}}
</div>
{{else}}
<div class="{{$classes_box}} o-10">
<p class="b black tc">Your Logo Here</p>
</div>
{{end}}
{{end}}
<div
class="{{ $classes_box }} o-100"
{{ with .bgcolor }}style="background-color: {{ . }};"{{ end }}>
{{ $url := printf "%s?%s" .link (querify "utm_source" $utmSource "utm_medium" "banner" "utm_campaign" (.utm_campaign | default "hugosponsor")) | safeURL }}
{{ if eq (getenv "HUGO_ENV") "production" | or (eq $.cx.Site.Params.env "production") }}
{{ $gtagID := printf "Sponsor %s %s" .name $gtag | title }}
<a
href="{{ $url }}"
onclick="trackOutboundLink({{ printf "'%s', '%s'" $gtagID $url | safeJS }});"
class="grow">
<img
src="{{ .logo }}"
alt="Logo for {{ .name }}"
class="img h3 center" />
</a>
{{ else }}
<a href="{{ $url }}" class="grow">
<img
src="{{ .logo }}"
alt="Logo for {{ .name }}"
class="img h3 center"
/></a>
{{ end }}
</div>
{{ end }}
</div>
</div>
</section>
{{end}}
{{ end }}

18
docs/_vendor/github.com/gohugoio/gohugoioTheme/package.json generated
View file

@ -3,14 +3,7 @@
"version": "1.1.0",
"description": "Default Theme for Hugo Sites",
"main": "index.js",
"homepage": "https://gohugo.io/",
"bugs": {
"url": "https://github.com/gohugoio/gohugoioTheme/issues"
},
"repository": {
"type": "git",
"url": "git+https://github.com/gohugoio/gohugoioTheme.git"
},
"repository": "",
"author": "budparr",
"license": "MIT",
"scripts": {
@ -21,14 +14,13 @@
"devDependencies": {
"clean-webpack-plugin": "^1.0.0",
"clipboard": "^2.0.4",
"css-loader": "^4.3.0",
"css-loader": "^1.0.1",
"docsearch.js": "^2.6.1",
"file-loader": "^2.0.0",
"glob-all": "^3.1.0",
"highlight.js": "^9.13.1",
"lazysizes": "^5.2.1",
"lazysizes": "^4.1.4",
"mini-css-extract-plugin": "^0.4.4",
"postcss": "^7.0.36",
"postcss": "^7.0.5",
"postcss-cssnext": "^3.1.0",
"postcss-import": "^12.0.1",
"postcss-loader": "^3.0.0",
@ -36,7 +28,7 @@
"scrolldir": "^1.4.0",
"tachyons": "^4.7.0",
"typeface-muli": "0.0.54",
"webpack": "^4.44.1",
"webpack": "^4.25.1",
"webpack-command": "^0.4.2"
},
"dependencies": {}

1
docs/_vendor/github.com/gohugoio/gohugoioTheme/static/images/sponsors/brave-logo.svg generated
View file

File diff suppressed because one or more lines are too long
Side by side

Before

Width:  |  Height:  |  Size: 5.6 KiB

1
docs/_vendor/github.com/gohugoio/gohugoioTheme/static/images/sponsors/butter-dark.svg generated Normal file
View file

@ -0,0 +1 @@
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 402 58"><g fill="#231F20"><path d="M24.6 23c.4 0 .7-.1 1-.2l10-5.4c1-.5 1.3-1.8.8-2.8-.5-1-1.8-1.3-2.8-.8l-9.9 5.4c-1 .3-1.5 1.3-1.3 2.3.3 1 1.3 1.7 2.3 1.5h-.1zM39.8 30.9c.3 0 .7-.1 1-.3L56.7 22c.6-.3 1-1 1-1.7 0-.8-.3-1.5-.9-1.8-.7-.4-1.4-.4-2.1-.1L38.8 27c-.9.4-1.5 1.4-1.2 2.4.2 1 1.2 1.6 2.2 1.5z"/><path d="M81 19.6c-.4-1.2-1.3-2.2-2.4-2.7L61.4 7.7c-2.8-1.4-6.1-1.4-9 0l-1.4.7L39.1 2C36.3.6 33 .6 30.1 2L2.5 16.9c-1.4.6-2.3 1.9-2.5 3.4v15.2c0 .8.4 1.5 1.1 1.8l35 19c2.8 1.4 6.2 1.4 9 0L80 37.1c.7-.3 1.1-1 1.1-1.8v-15c0-.2-.1-.5-.1-.7zm-76.5.9L32 5.6c1.6-.7 3.5-.7 5.2 0L51 13l3.3-1.8c1.7-.7 3.6-.7 5.2 0l17.1 9.2.2.1-.2.1-33.4 18c-1.7.8-3.6.8-5.2 0l-33.5-18-.2-.1h.2zm38.6 32.2c-1.6.7-3.5.7-5.1 0L4.1 34.3v-9.2L36 42.3c2.8 1.4 6.2 1.4 9 0l32-17.2v9L43.1 52.7zM115.7 10.2h18.2c8.7 0 13.1 3.1 13.1 9.1 0 1.9-.5 3.7-1.6 5.2s-2.6 2.6-4.3 3.2c2.2.4 4.2 1.5 5.7 3.1s2.2 3.6 2.2 5.7c0 3.8-1.4 6.7-4.1 8.7-2.7 2-6.6 3-11.8 3h-17.5v-5.4l1.8-.2c.4 0 .8-.2 1.1-.5.2-.4.3-.9.3-1.3V16.1l-3.1-.3v-5.6zm13.1 6.4v9h2.7c3.5 0 5.3-1.6 5.3-4.8 0-2.8-1.7-4.2-5.1-4.2h-2.9zm0 15.1v9.9h3.7c3.8 0 5.8-1.8 5.8-5.2 0-3.1-1.9-4.7-5.7-4.7h-3.8zM180.7 19v22c0 .5 0 .9.3 1.3.2.3.6.4 1 .5l1.5.1v5.2h-11.7v-3.6h-.2c-1.7 3-4.5 4.4-8.5 4.4-3.1 0-5.3-.8-6.8-2.3-1.4-1.6-2.1-4-2.1-7.3V26.2c0-.4-.1-.8-.4-1.1-.2-.3-.6-.5-1-.5l-1.6-.2V19H164v18.4c-.1 1.1.1 2.2.6 3.1.6.8 1.6 1.1 2.5 1 1.1.1 2.2-.4 2.9-1.2.7-1 1.1-2.2 1-3.4V26.3c0-.5-.1-.9-.3-1.3-.3-.3-.7-.4-1.1-.4l-1.3-.2V19h12.4zM198.9 12.3V19h8.1c2.5-1.1 4.3-3.4 5.5-6.7h5.3V19h6.9l-.5 6.3h-6.4v12.3c-.1 1.1.2 2.2.7 3.2.4.5 1.3.8 2.7.8 1.2 0 2.5-.3 3.6-.8l1.4 6.3c-2.5 1.3-5.2 1.9-7.9 1.8-1.3 0-2.5-.1-3.8-.3-.9-.2-1.8-.4-2.7-.8-.7-.3-1.3-.8-1.8-1.4-.4-.5-.8-1-1.1-1.6-.3-.6-.5-1.3-.6-2-.1-.6-.2-1.3-.3-2V25.3h-9v12.3c-.1 1 .1 2.1.6 3.1.5.7 1.4 1.1 2.3 1 1.1 0 2.2-.3 3.2-.8l1.7 6.2c-2.3 1.2-4.9 1.9-7.5 1.8-3.7 0-6.4-.9-7.9-2.6-1.5-1.7-2.3-4.2-2.3-7.6V25.3h-3.9l.8-5.5c3.6-.8 6.2-3.3 7.6-7.4l5.3-.1zM242.7 18.2c2.7-.1 5.3.6 7.5 2.2 2 1.6 3 4.1 2.8 6.6 0 6.9-5.3 10.2-16 10 .1 1.3.7 2.6 1.7 3.5 1.2 1 2.7 1.4 4.2 1.4 2.6-.1 5.2-.9 7.4-2.3l2.6 6.3c-.5.4-1 .7-1.6.9-1.3.6-2.6 1-4 1.4-1.9.5-3.8.7-5.7.7-4.9 0-8.5-1.3-10.8-4-2.3-2.6-3.5-6.2-3.5-10.7-.1-4.1 1.3-8.2 4-11.4 2.7-3 6.5-4.6 11.4-4.6zm2 9.3c0-.7-.2-1.4-.7-1.9-.5-.5-1.2-.7-1.9-.6-1.4 0-2.8.6-3.6 1.8-1 1.3-1.6 2.9-1.6 4.6 5.2.2 7.7-1.2 7.7-3.9h.1zM272.5 25.5c-1.1 0-2.1.5-2.7 1.3-.7.9-1.1 2.1-1 3.3v12.5l5.1.3v5.3h-18.1V43l1.9-.2c.4.1.8-.1 1.1-.4.2-.4.3-.9.3-1.4V26.2c0-.4-.1-.8-.3-1.2-.3-.3-.6-.4-1-.4l-2-.2V19H268v4.4h.1c.7-1.4 1.7-2.7 3-3.6 1.6-1.1 3.5-1.7 5.4-1.6 1.9-.1 3.7.2 5.4.9v11.3l-7.6.4v-3.9c0-.7-.2-1.1-.5-1.2-.4-.1-.9-.2-1.3-.2zM308.7 17.5c-1.2-.3-2.3-.4-3.4-.4-6.1 0-9.2 3.9-9.2 11.8 0 3.8.8 6.8 2.3 9 1.5 2.2 3.9 3.3 7.1 3.4 1.1 0 2.1-.1 3.2-.4.6-.2 1-.8 1-1.5v-3.7l7.3.4v10.5c-3.8 1.7-7.9 2.5-12.1 2.3-6.1 0-10.8-1.6-14.1-4.9-3.3-3.3-5-8.1-5-14.5 0-3.2.5-6.4 1.6-9.4.9-2.5 2.4-4.6 4.4-6.3 1.8-1.4 3.8-2.5 6-3.3 2.2-.7 4.6-1 6.9-1 4.2-.1 8.3.7 12.2 2.4v10l-7.4.4V19c0-.9-.3-1.4-.8-1.5zM323.6 10.2h14.6l7.5 24.8h.2l7.7-24.7h14.6v5.4l-1.8.2c-.5 0-.9.2-1.2.5-.3.4-.4.9-.3 1.3l1.9 24.8 2.9.1v5.6h-15.3v-5.5l1.8-.2c.4.1.8-.1 1-.4.2-.4.3-.9.2-1.3l-.9-16.1h-.1l-7.2 23.5h-7.1l-7-23.1h-.2l-1 17.3 2.8.2v5.6h-15.3v-5.5l1.8-.2c.5 0 .9-.2 1.2-.5.2-.4.4-.9.4-1.4l2-24.6-3.2-.2v-5.6zM385.5 41.6c3.5 0 5.3-1.4 5.3-4.2 0-1.1-.5-2.2-1.4-2.8-1.4-.8-2.9-1.4-4.5-1.8-1.3-.3-2.7-.8-4-1.3-1.2-.5-2.3-1.2-3.4-1.9-1.2-.9-2.2-2-2.8-3.3-.6-1.5-1-3.2-1-4.8-.1-3.4 1.4-6.7 4-8.8 2.7-2.1 6.2-3.1 10.6-3.1 4-.2 8 .6 11.7 2.2v9.3l-7.4.5v-2.9c0-.8-.3-1.3-.8-1.4-1.1-.3-2.2-.4-3.3-.4-1.1 0-2.2.3-3.1.8-.8.6-1.3 1.6-1.2 2.6-.1 1.1.5 2.2 1.4 2.8 1.5.9 3.1 1.6 4.8 2 1.4.4 2.5.8 3.3 1.1.9.4 1.9.8 2.8 1.3 1 .5 1.9 1.2 2.6 2 .7.9 1.2 1.8 1.6 2.9.5 1.3.7 2.6.7 4 .2 3.6-1.3 7-4.1 9.3-2.7 2.2-6.4 3.3-11.2 3.3-4.3.1-8.6-.7-12.6-2.3v-9.8l7.5-.5v3.2c0 .9.3 1.4.9 1.6 1.1.2 2.3.4 3.6.4z"/></g></svg>
Side by side

After

Width:  |  Height:  |  Size: 3.8 KiB

1
docs/_vendor/github.com/gohugoio/gohugoioTheme/static/images/sponsors/butter-light.svg generated Normal file
View file

@ -0,0 +1 @@
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 402 58"><g fill="#fff"><path d="M24.6 23c.4 0 .7-.1 1-.2l10-5.4c1-.5 1.3-1.8.8-2.8-.5-1-1.8-1.3-2.8-.8l-9.9 5.4c-1 .3-1.5 1.3-1.3 2.3.3 1 1.3 1.7 2.3 1.5h-.1zM39.8 30.9c.3 0 .7-.1 1-.3L56.7 22c.6-.3 1-1 1-1.7 0-.8-.3-1.5-.9-1.8-.7-.4-1.4-.4-2.1-.1L38.8 27c-.9.4-1.5 1.4-1.2 2.4.2 1 1.2 1.6 2.2 1.5z"/><path d="M81 19.6c-.4-1.2-1.3-2.2-2.4-2.7L61.4 7.7c-2.8-1.4-6.1-1.4-9 0l-1.4.7L39.1 2C36.3.6 33 .6 30.1 2L2.5 16.9c-1.4.6-2.3 1.9-2.5 3.4v15.2c0 .8.4 1.5 1.1 1.8l35 19c2.8 1.4 6.2 1.4 9 0L80 37.1c.7-.3 1.1-1 1.1-1.8v-15c0-.2-.1-.5-.1-.7zm-76.5.9L32 5.6c1.6-.7 3.5-.7 5.2 0L51 13l3.3-1.8c1.7-.7 3.6-.7 5.2 0l17.1 9.2.2.1-.2.1-33.4 18c-1.7.8-3.6.8-5.2 0l-33.5-18-.2-.1h.2zm38.6 32.2c-1.6.7-3.5.7-5.1 0L4.1 34.3v-9.2L36 42.3c2.8 1.4 6.2 1.4 9 0l32-17.2v9L43.1 52.7zM115.7 10.2h18.2c8.7 0 13.1 3.1 13.1 9.1 0 1.9-.5 3.7-1.6 5.2s-2.6 2.6-4.3 3.2c2.2.4 4.2 1.5 5.7 3.1s2.2 3.6 2.2 5.7c0 3.8-1.4 6.7-4.1 8.7-2.7 2-6.6 3-11.8 3h-17.5v-5.4l1.8-.2c.4 0 .8-.2 1.1-.5.2-.4.3-.9.3-1.3V16.1l-3.1-.3v-5.6zm13.1 6.4v9h2.7c3.5 0 5.3-1.6 5.3-4.8 0-2.8-1.7-4.2-5.1-4.2h-2.9zm0 15.1v9.9h3.7c3.8 0 5.8-1.8 5.8-5.2 0-3.1-1.9-4.7-5.7-4.7h-3.8zM180.7 19v22c0 .5 0 .9.3 1.3.2.3.6.4 1 .5l1.5.1v5.2h-11.7v-3.6h-.2c-1.7 3-4.5 4.4-8.5 4.4-3.1 0-5.3-.8-6.8-2.3-1.4-1.6-2.1-4-2.1-7.3V26.2c0-.4-.1-.8-.4-1.1-.2-.3-.6-.5-1-.5l-1.6-.2V19H164v18.4c-.1 1.1.1 2.2.6 3.1.6.8 1.6 1.1 2.5 1 1.1.1 2.2-.4 2.9-1.2.7-1 1.1-2.2 1-3.4V26.3c0-.5-.1-.9-.3-1.3-.3-.3-.7-.4-1.1-.4l-1.3-.2V19h12.4zM198.9 12.3V19h8.1c2.5-1.1 4.3-3.4 5.5-6.7h5.3V19h6.9l-.5 6.3h-6.4v12.3c-.1 1.1.2 2.2.7 3.2.4.5 1.3.8 2.7.8 1.2 0 2.5-.3 3.6-.8l1.4 6.3c-2.5 1.3-5.2 1.9-7.9 1.8-1.3 0-2.5-.1-3.8-.3-.9-.2-1.8-.4-2.7-.8-.7-.3-1.3-.8-1.8-1.4-.4-.5-.8-1-1.1-1.6-.3-.6-.5-1.3-.6-2-.1-.6-.2-1.3-.3-2V25.3h-9v12.3c-.1 1 .1 2.1.6 3.1.5.7 1.4 1.1 2.3 1 1.1 0 2.2-.3 3.2-.8l1.7 6.2c-2.3 1.2-4.9 1.9-7.5 1.8-3.7 0-6.4-.9-7.9-2.6-1.5-1.7-2.3-4.2-2.3-7.6V25.3h-3.9l.8-5.5c3.6-.8 6.2-3.3 7.6-7.4l5.3-.1zM242.7 18.2c2.7-.1 5.3.6 7.5 2.2 2 1.6 3 4.1 2.8 6.6 0 6.9-5.3 10.2-16 10 .1 1.3.7 2.6 1.7 3.5 1.2 1 2.7 1.4 4.2 1.4 2.6-.1 5.2-.9 7.4-2.3l2.6 6.3c-.5.4-1 .7-1.6.9-1.3.6-2.6 1-4 1.4-1.9.5-3.8.7-5.7.7-4.9 0-8.5-1.3-10.8-4-2.3-2.6-3.5-6.2-3.5-10.7-.1-4.1 1.3-8.2 4-11.4 2.7-3 6.5-4.6 11.4-4.6zm2 9.3c0-.7-.2-1.4-.7-1.9-.5-.5-1.2-.7-1.9-.6-1.4 0-2.8.6-3.6 1.8-1 1.3-1.6 2.9-1.6 4.6 5.2.2 7.7-1.2 7.7-3.9h.1zM272.5 25.5c-1.1 0-2.1.5-2.7 1.3-.7.9-1.1 2.1-1 3.3v12.5l5.1.3v5.3h-18.1V43l1.9-.2c.4.1.8-.1 1.1-.4.2-.4.3-.9.3-1.4V26.2c0-.4-.1-.8-.3-1.2-.3-.3-.6-.4-1-.4l-2-.2V19H268v4.4h.1c.7-1.4 1.7-2.7 3-3.6 1.6-1.1 3.5-1.7 5.4-1.6 1.9-.1 3.7.2 5.4.9v11.3l-7.6.4v-3.9c0-.7-.2-1.1-.5-1.2-.4-.1-.9-.2-1.3-.2zM308.7 17.5c-1.2-.3-2.3-.4-3.4-.4-6.1 0-9.2 3.9-9.2 11.8 0 3.8.8 6.8 2.3 9 1.5 2.2 3.9 3.3 7.1 3.4 1.1 0 2.1-.1 3.2-.4.6-.2 1-.8 1-1.5v-3.7l7.3.4v10.5c-3.8 1.7-7.9 2.5-12.1 2.3-6.1 0-10.8-1.6-14.1-4.9-3.3-3.3-5-8.1-5-14.5 0-3.2.5-6.4 1.6-9.4.9-2.5 2.4-4.6 4.4-6.3 1.8-1.4 3.8-2.5 6-3.3 2.2-.7 4.6-1 6.9-1 4.2-.1 8.3.7 12.2 2.4v10l-7.4.4V19c0-.9-.3-1.4-.8-1.5zM323.6 10.2h14.6l7.5 24.8h.2l7.7-24.7h14.6v5.4l-1.8.2c-.5 0-.9.2-1.2.5-.3.4-.4.9-.3 1.3l1.9 24.8 2.9.1v5.6h-15.3v-5.5l1.8-.2c.4.1.8-.1 1-.4.2-.4.3-.9.2-1.3l-.9-16.1h-.1l-7.2 23.5h-7.1l-7-23.1h-.2l-1 17.3 2.8.2v5.6h-15.3v-5.5l1.8-.2c.5 0 .9-.2 1.2-.5.2-.4.4-.9.4-1.4l2-24.6-3.2-.2v-5.6zM385.5 41.6c3.5 0 5.3-1.4 5.3-4.2 0-1.1-.5-2.2-1.4-2.8-1.4-.8-2.9-1.4-4.5-1.8-1.3-.3-2.7-.8-4-1.3-1.2-.5-2.3-1.2-3.4-1.9-1.2-.9-2.2-2-2.8-3.3-.6-1.5-1-3.2-1-4.8-.1-3.4 1.4-6.7 4-8.8 2.7-2.1 6.2-3.1 10.6-3.1 4-.2 8 .6 11.7 2.2v9.3l-7.4.5v-2.9c0-.8-.3-1.3-.8-1.4-1.1-.3-2.2-.4-3.3-.4-1.1 0-2.2.3-3.1.8-.8.6-1.3 1.6-1.2 2.6-.1 1.1.5 2.2 1.4 2.8 1.5.9 3.1 1.6 4.8 2 1.4.4 2.5.8 3.3 1.1.9.4 1.9.8 2.8 1.3 1 .5 1.9 1.2 2.6 2 .7.9 1.2 1.8 1.6 2.9.5 1.3.7 2.6.7 4 .2 3.6-1.3 7-4.1 9.3-2.7 2.2-6.4 3.3-11.2 3.3-4.3.1-8.6-.7-12.6-2.3v-9.8l7.5-.5v3.2c0 .9.3 1.4.9 1.6 1.1.2 2.3.4 3.6.4z"/></g></svg>
Side by side

After

Width:  |  Height:  |  Size: 3.8 KiB

1
docs/_vendor/github.com/gohugoio/gohugoioTheme/static/images/sponsors/forestry-logotype.svg generated
View file

File diff suppressed because one or more lines are too long
Side by side

Before

Width:  |  Height:  |  Size: 6.7 KiB

2
docs/_vendor/modules.txt
View file

@ -1 +1 @@
# github.com/gohugoio/gohugoioTheme v0.0.0-20220912070954-88dcaf003b4d
# github.com/gohugoio/gohugoioTheme v0.0.0-20221116211530-5ae8dcdd68d6

80
docs/config.toml
View file

@ -1,80 +0,0 @@
baseURL = "https://gohugo.io/"
paginate = 100
defaultContentLanguage = "en"
enableEmoji = true
timeZone = "Europe/Oslo"
# Set the unicode character used for the "return" link in page footnotes.
footnotereturnlinkcontents = "↩"
languageCode = "en-us"
title = "Hugo"
ignoreErrors = ["error-remote-getjson", "error-missing-instagram-accesstoken"]
googleAnalytics = "UA-7131036-4"
pluralizeListTitles = false
# We do redirects via Netlify's _redirects file, generated by Hugo (see "outputs" below).
disableAliases = true
[minify]
[minify.tdewolff]
[minify.tdewolff.css]
[minify.tdewolff.html]
keepWhitespace = true
[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"
[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"

38
docs/config/_default/config.toml
View file

@ -1,19 +1,28 @@
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"
ignoreErrors = ["error-remote-getjson", "error-missing-instagram-accesstoken"]
languageCode = "en-us"
paginate = 100
pluralizeListTitles = false
timeZone = "Europe/Oslo"
title = "Hugo"
# We do redirects via Netlify's _redirects file, generated by Hugo (see "outputs" below).
disableAliases = true
[minify]
[minify.tdewolff]
[minify.tdewolff.html]
keepWhitespace = true
[module]
[module.hugoVersion]
min = "0.56.0"
[[module.imports]]
path = "github.com/gohugoio/gohugoioTheme"
[outputs]
home = [ "HTML", "RSS", "REDIR", "HEADERS" ]
section = [ "HTML", "RSS"]
@ -48,13 +57,10 @@ maxAge = "1440h"
dir = ":resourceDir/_gen"
maxAge = -1
[related]
threshold = 80
includeNewer = true
toLower = false
[[related.indices]]
name = "keywords"
weight = 100
@ -66,25 +72,13 @@ 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]

126
docs/config/_default/menus/menus.en.toml
View file

@ -1,114 +1,102 @@
[[docs]]
name = "About Hugo"
weight = 1
weight = 10
identifier = "about"
url = "/about/"
[[docs]]
name = "Installation"
weight = 20
identifier = "installation"
url = "/installation/"
[[docs]]
name = "Getting Started"
weight = 5
weight = 30
identifier = "getting-started"
url = "/getting-started/"
[[docs]]
name = "Hugo Modules"
weight = 15
weight = 40
identifier = "modules"
post = "break"
url = "/hugo-modules/"
# Core Menus
# Core menus
[[docs]]
name = "Content Management"
weight = 20
weight = 50
identifier = "content-management"
post = "expanded"
url = "/content-management/"
[[docs]]
name = "Templates"
weight = 25
weight = 60
identifier = "templates"
url = "/templates/"
[[docs]]
name = "Functions"
weight = 30
weight = 70
identifier = "functions"
url = "/functions/"
[[docs]]
name = "Variables"
weight = 35
weight = 80
identifier = "variables"
url = "/variables/"
[[docs]]
name = "Hugo Pipes"
weight = 36
weight = 90
identifier = "pipes"
url = "/hugo-pipes/"
[[docs]]
name = "CLI"
weight = 40
weight = 100
post = "break"
identifier = "commands"
url = "/commands/"
# LOW LEVEL ITEMS
# Low level items
[[docs]]
name = "Troubleshooting"
weight = 60
weight = 110
identifier = "troubleshooting"
url = "/troubleshooting/"
[[docs]]
name = "Tools"
weight = 70
weight = 120
identifier = "tools"
url = "/tools/"
[[docs]]
name = "Hosting & Deployment"
weight = 80
weight = 130
identifier = "hosting-and-deployment"
url = "/hosting-and-deployment/"
[[docs]]
name = "Contribute"
weight = 100
weight = 140
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/"
[[quicklinks]]
name = "Fundamentals"
weight = 1
identifier = "fundamentals"
url = "/tags/fundamentals/"
######## GLOBAL ITEMS TO BE SHARED WITH THE HUGO SITES
@ -118,37 +106,37 @@
identifier = "news"
url = "/news/"
[[global]]
name = "Docs"
weight = 5
identifier = "docs"
url = "/documentation/"
[[global]]
name = "Docs"
weight = 5
identifier = "docs"
url = "/documentation/"
[[global]]
name = "Themes"
weight = 10
identifier = "themes"
url = "https://themes.gohugo.io/"
[[global]]
name = "Themes"
weight = 10
identifier = "themes"
url = "https://themes.gohugo.io/"
[[global]]
name = "Showcase"
weight = 20
identifier = "showcase"
url = "/showcase/"
[[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/"
# 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"
[[global]]
name = "GitHub"
weight = 200
identifier = "github"
post = "external"
url = "https://github.com/gohugoio/hugo"

1
docs/content/en/about/benefits.md
View file

@ -34,7 +34,6 @@ This has many benefits. The most noticeable is performance. HTTP servers are *ve
* ["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://github.com/gohugoio/hugoDocs/files/1242701/static-site-generators.pdf
["Top 10 Static Website Generators", Netlify blog]: https://www.netlify.com/blog/2016/05/02/top-ten-static-website-generators/

5
docs/content/en/about/features.md
View file

@ -54,7 +54,6 @@ toc: true
* Support for [Go][] HTML templates
* [Syntax highlighting][] powered by [Chroma][]
[aliases]: /content-management/urls/#aliases
[Chroma]: https://github.com/alecthomas/chroma
[content summaries]: /content-management/summaries/
@ -64,11 +63,11 @@ toc: true
[Extremely fast]: https://github.com/bep/hugo-benchmark
[front matter]: /content-management/front-matter/
[functions]: /functions/
[Go]: https://golang.org/pkg/html/template/
[Go]: https://pkg.go.dev/html/template
[Google Analytics]: https://google-analytics.com/
[homepage]: /templates/homepage/
[hostanywhere]: /hosting-and-deployment/
[install]: /getting-started/installing/
[install]: /installation/
[LiveReload]: /getting-started/usage/
[organization for your projects]: /getting-started/directory-structure/
[pagevars]: /variables/page/

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

@ -16,7 +16,6 @@ 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.**
@ -95,6 +94,7 @@ useSessionStorage
{{% warning %}}
`useSessionStorage` is not supported when using Google Analytics v4 (gtag.js).
{{% /warning %}}
### Instagram
simple
@ -116,8 +116,7 @@ enableDNT
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:
**Note:** If you use the _simple mode_ for Twitter, you may want to disable the inline styles provided by Hugo:
{{< code-toggle file="config">}}
[services]
@ -137,4 +136,3 @@ enableDNT
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.

8
docs/content/en/about/security-model/index.md
View file

@ -10,7 +10,6 @@ menu:
weight: 4
weight: 5
sections_weight: 5
draft: false
aliases: [/security/]
toc: true
---
@ -28,11 +27,8 @@ But when developing and building your site, the runtime is the `hugo` executable
* User-defined components have read-only access to the filesystem.
* We shell out to some external binaries to support [Asciidoctor](/content-management/formats/#list-of-content-formats) and similar, but those binaries and their flags are predefined and disabled by default (see [Security Policy](#security-policy)). General functions to run arbitrary external OS commands have been [discussed](https://github.com/gohugoio/hugo/issues/796), but not implemented because of security concerns.
## Security Policy
{{< new-in "0.91.0" >}}
Hugo has a built-in security policy that restricts access to [os/exec](https://pkg.go.dev/os/exec), remote communication and similar.
The default configuration is listed below. Any build using features not in the allow list of the security policy will fail with a detailed message about what needs to be done. Most of these settings are allow lists (string or slice, [Regular Expressions](https://pkg.go.dev/regexp) or `none` which matches nothing).
@ -41,7 +37,7 @@ The default configuration is listed below. Any build using features not in the a
Note that these and other config settings in Hugo can be overridden by the OS environment. If you want to block all remote HTTP fetching of data:
```
```txt
HUGO_SECURITY_HTTP_URLS=none hugo
```
@ -57,7 +53,7 @@ These are the security threats as defined by [OWASP](https://en.wikipedia.org/wi
For HTML output, this is the core security model:
https://golang.org/pkg/html/template/#hdr-Security_Model
<https://pkg.go.dev/html/template#hdr-Security_Model>
In short:

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

@ -47,7 +47,7 @@ Hugo is for people building a blog, a company site, a portfolio site, documentat
[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/
[Go language]: https://go.dev/
[GoDaddy]: https://www.godaddy.com/ "GoDaddy.com Hosting"
[Google Cloud Storage]: https://cloud.google.com/storage/
[Heroku]: https://www.heroku.com/

14
docs/content/en/content-management/_index.md
View file

@ -1,20 +1,16 @@
---
title: Content Management
linktitle: Content Management Overview
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
parent: content-management
weight: 10
keywords: [source, organization]
categories: [content management]
weight: 01 #rem
draft: false
aliases: [/content/,/content/organization]
toc: false
weight: 10
aliases: [/content/,/content/organization]
---
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.

18
docs/content/en/content-management/archetypes.md
View file

@ -1,20 +1,17 @@
---
title: Archetypes
linktitle: 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"]
categories: [content management]
menu:
docs:
parent: "content-management"
weight: 70
parent: content-management
weight: 140
quicklinks:
weight: 70 #rem
draft: false
aliases: [/content/archetypes/]
toc: true
weight: 140
aliases: [/content/archetypes/]
---
## What are Archetypes?
@ -69,7 +66,6 @@ It will create a new newsletter type of content file based on the archetype temp
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:
@ -90,8 +86,6 @@ 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/

21
docs/content/en/content-management/build-options.md
View file

@ -1,19 +1,16 @@
---
title: Build Options
linktitle: Build Options
linkTitle: Build Options
description: Build options help define how Hugo must treat a given page when building the site.
date: 2020-03-02
publishdate: 2020-03-02
keywords: [build,content,front matter, page resources]
categories: ["content management"]
categories: [content management]
menu:
docs:
parent: "content-management"
weight: 31
weight: 31 #rem
draft: false
aliases: [/content/build-options/]
parent: content-management
weight: 70
toc: true
weight: 70
aliases: [/content/build-options/]
---
They are stored in a reserved Front Matter object named `_build` with the following defaults:
@ -26,9 +23,10 @@ _build:
{{< /code-toggle >}}
#### render
If `always`, the page will be treated as a published page, holding its dedicated output files (`index.html`, etc...) and permalink.
{{< new-in "0.76.0" >}} We extended this property from a boolean to an enum in Hugo 0.76.0. Valid values are:
We extended this property from a boolean to an enum in Hugo 0.76.0. Valid values are:
never
: The page will not be included in any page collection.
@ -52,7 +50,7 @@ always (default)
: The page will be included in all page collections, e.g. `site.RegularPages`, `$page.Pages`.
local
: The page will be included in any _local_ page collection, e.g. `$page.RegularPages`, `$page.Pages`. One use case for this would be to create fully navigable, but headless content sections. {{< new-in "0.68.0" >}}
: The page will be included in any _local_ page collection, e.g. `$page.RegularPages`, `$page.Pages`. One use case for this would be to create fully navigable, but headless content sections.
If true, the page will be treated as part of the project's collections and, when appropriate, returned by Hugo's listing methods (`.Pages`, `.RegularPages` etc...).
@ -70,6 +68,7 @@ Any page, regardless of their build options, will always be available using the
### Illustrative use cases
#### Not publishing a page
Project needs a "Who We Are" content file for Front Matter and body to be used by the homepage but nowhere else.
```yaml

18
docs/content/en/content-management/comments.md
View file

@ -1,19 +1,16 @@
---
title: Comments
linktitle: 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
keywords: [sections,content,organization]
categories: [project organization, fundamentals]
menu:
docs:
parent: "content-management"
weight: 140
weight: 140 #rem
draft: false
aliases: [/extras/comments/]
parent: content-management
weight: 220
toc: true
weight: 220
aliases: [/extras/comments/]
---
Hugo ships with support for [Disqus](https://disqus.com/), a third-party service that provides comment and community capabilities to websites via JavaScript.
@ -42,7 +39,7 @@ For many websites, this is enough configuration. However, you also have the opti
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:
```
```go-html-template
{{ template "_internal/disqus.html" . }}
```
@ -55,9 +52,10 @@ These are some alternatives to Disqus:
* [Graph Comment](https://graphcomment.com/)
* [Hyvor Talk](https://talk.hyvor.com/) (Available as a service)
* [IntenseDebate](https://intensedebate.com/)
* [Isso](https://posativ.org/isso/) (Self-hosted, Python) ([tutorial][issotutorial])
* [Isso](https://isso-comments.de/) (Self-hosted, Python) ([tutorial][issotutorial])
* [Muut](https://muut.com/)
* [Remark42](https://remark42.com/) (Open source, Golang, Easy to run docker)
* [ReplyBox](https://getreplybox.com/)
* [Staticman](https://staticman.net/)
* [Talkyard](https://blog-comments.talkyard.io/) (Open source, & serverless hosting)
* [Utterances](https://utteranc.es/) (Open source, GitHub comments widget built on GitHub issues)

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

@ -1,31 +1,49 @@
---
title: Links and Cross References
linkTitle: 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/]
parent: content-management
weight: 170
toc: true
weight: 170
aliases: [/extras/crossreferences/]
---
The `ref` and `relref` shortcodes display the absolute and relative permalinks to a document, respectively.
## Use `ref` and `relref`
## Use of `ref` and `relref`
```go-html-template
{{</* ref "document" */>}}
{{</* ref "document#anchor" */>}}
{{</* ref "document.md" */>}}
{{</* ref "document.md#anchor" */>}}
{{</* ref "#anchor" */>}}
{{</* ref "/blog/my-post" */>}}
The `ref` and `relref` shortcodes require a single parameter: the path to a content document, with or without a file extension, with or without an anchor. Paths without a leading `/` are first resolved relative to the current page, then to the remainder of the site.
```
.
└── content
├── about
| ├── _index.md
| └── credits.md
├── pages
| ├── document1.md
| └── document2.md // has anchor #anchor
├── products
| └── index.md
└── blog
└── my-post.md
```
The pages can be referenced as follows:
```text
{{</* ref "document2" */>}} // <- From pages/document1.md, relative path
{{</* ref "document2#anchor" */>}}
{{</* ref "document2.md" */>}}
{{</* ref "document2.md#anchor" */>}}
{{</* ref "#anchor" */>}} // <- From pages/document2.md
{{</* ref "/blog/my-post" */>}} // <- From anywhere, absolute path
{{</* ref "/blog/my-post.md" */>}}
{{</* relref "document" */>}}
{{</* relref "document.md" */>}}
@ -33,15 +51,22 @@ The `ref` and `relref` shortcodes display the absolute and relative permalinks t
{{</* relref "/blog/my-post.md" */>}}
```
To generate a hyperlink using `ref` or `relref` in markdown:
index.md can be reference either by its path or by its containing folder without the ending `/`. \_index.md can be referenced only by its containing folder:
```md
[About]({{</* ref "/page/about" */>}} "About Us")
```text
{{</* ref "/about" */>}} // <- References /about/_index.md
{{</* ref "/about/_index" */>}} // Raises REF_NOT_FOUND error
{{</* ref "/about/credits.md" */>}} // <- References /about/credits.md
{{</* ref "/products" */>}} // <- References /products/index.md
{{</* ref "/products/index" */>}} // <- References /products/index.md
```
The `ref` and `relref` shortcodes require a single parameter: the path to a content document, with or without a file extension, with or without an anchor.
To generate a hyperlink using `ref` or `relref` in markdown:
**Paths without a leading `/` are first resolved relative to the current page, then to the remainder of the site.
```text
[About]({{</* ref "/about" */>}} "About Us")
```
Hugo emits an error or warning if a document cannot be uniquely resolved. The error behavior is configurable; see below.

38
docs/content/en/content-management/diagrams.md
View file

@ -1,25 +1,23 @@
---
title: Diagrams
date: 2022-02-20
LinkTitle: Diagrams
description: Use fenced code blocks and markdown render hooks to display diagrams.
categories: [content management]
keywords: [diagrams,drawing]
menu:
docs:
parent: "content-management"
weight: 22
weight: 22
parent: content-management
weight: 50
toc: true
weight: 50
---
{{< new-in "0.93.0" >}}
## GoAT Diagrams (Ascii)
Hugo! supports [GoAT](https://github.com/bep/goat) natively. This means that this code block:
Hugo supports [GoAT](https://github.com/bep/goat) natively. This means that this code block:
````
````txt
```goat
. . . .--- 1 .-- 1 / 1
/ \ | | .---+ .-+ +
@ -45,14 +43,9 @@ Will be rendered as:
1 2 3 4 1 2 3 4 1 2 3 4 '--- 4 '-- 4 \ 4
```
## Mermaid Diagrams
Hugo currently does not provide default templates for Mermaid diagrams. But you can easily add your own. One way to do it would be to create ` layouts/_default/_markup/render-codeblock-mermaid.html`:
Hugo currently does not provide default templates for Mermaid diagrams. But you can easily add your own. One way to do it would be to create `layouts/_default/_markup/render-codeblock-mermaid.html`:
```go-html-template
<div class="mermaid">
@ -61,7 +54,7 @@ Hugo currently does not provide default templates for Mermaid diagrams. But you
{{ .Page.Store.Set "hasMermaid" true }}
```
And then include this snippet at the bottom of the content template (below `.Content`):
And then include this snippet at the bottom of the content template (**Note**: below `.Content` as the render hook is not processed until `.Content` is executed):
```go-html-template
{{ if .Page.Store.Get "hasMermaid" }}
@ -88,8 +81,6 @@ sequenceDiagram
Bob-->>John: Jolly good!
```
## Goat Ascii Diagram Examples
### Graphics
@ -160,7 +151,7 @@ sequenceDiagram
### File tree
Created from https://arthursonzogni.com/Diagon/#Tree
Created from <https://arthursonzogni.com/Diagon/#Tree>
```goat { width=300 color="orange" }
───Linux─┬─Android
@ -176,7 +167,7 @@ Created from https://arthursonzogni.com/Diagon/#Tree
### Sequence Diagram
https://arthursonzogni.com/Diagon/#Sequence
<https://arthursonzogni.com/Diagon/#Sequence>
```goat { class="w-40" }
┌─────┐ ┌───┐
@ -197,7 +188,7 @@ https://arthursonzogni.com/Diagon/#Sequence
### Flowchart
https://arthursonzogni.com/Diagon/#Flowchart
<https://arthursonzogni.com/Diagon/#Flowchart>
```goat
_________________
@ -243,7 +234,7 @@ https://arthursonzogni.com/Diagon/#Flowchart
### Table
https://arthursonzogni.com/Diagon/#Table
<https://arthursonzogni.com/Diagon/#Table>
```goat { class="w-80 dark-blue" }
┌────────────────────────────────────────────────┐
@ -272,6 +263,3 @@ https://arthursonzogni.com/Diagon/#Table
│LITERAL = """" character { character } """" .│
└────────────────────────────────────────────────┘
```

19
docs/content/en/content-management/formats.md
View file

@ -1,19 +1,16 @@
---
title: Content Formats
linktitle: Content Formats
linkTitle: Content Formats
description: Both HTML and Markdown are supported content formats.
date: 2017-01-10
publishdate: 2017-01-10
categories: [content management]
keywords: [markdown,asciidoc,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/]
parent: content-management
weight: 40
toc: true
weight: 40
aliases: [/content/markdown-extras/,/content/supported-formats/,/doc/supported-formats/]
---
You can put any file type into your `/content` directories, but Hugo uses the `markup` front matter value if set or the file extension (see `Markup identifiers` in the table below) to determine if the markup needs to be processed, e.g.:
@ -28,7 +25,7 @@ The current list of content formats in Hugo:
| Name | Markup identifiers | Comment |
| ------------- | ------------- |-------------|
| Goldmark | md, markdown, goldmark |Note that you can set the default handler of `md` and `markdown` to something else, see [Configure Markup](/getting-started/configuration-markup/).{{< new-in "0.60.0" >}} |
| Goldmark | md, markdown, goldmark |Note that you can set the default handler of `md` and `markdown` to something else, see [Configure Markup](/getting-started/configuration-markup/).|
|Emacs Org-Mode|org|See [go-org](https://github.com/niklasfasching/go-org).|
|AsciiDoc|asciidocext, adoc, ad|Needs [Asciidoctor][ascii] installed.|
|RST|rst|Needs [RST](https://docutils.sourceforge.io/rst.html) installed.|
@ -100,7 +97,7 @@ Notice that for security concerns only extensions that do not have path separato
Example of how to set extensions and attributes:
```
```yml
[markup.asciidocExt]
extensions = ["asciidoctor-html5s", "asciidoctor-diagram"]
workingFolderCurrent = true
@ -112,7 +109,7 @@ Example of how to set extensions and attributes:
In a complex Asciidoctor environment it is sometimes helpful to debug the exact call to your external helper with all
parameters. Run Hugo with `-v`. You will get an output like
```
```txt
INFO 2019/12/22 09:08:48 Rendering book-as-pdf.adoc with C:\Ruby26-x64\bin\asciidoctor.bat using asciidoc args [--no-header-footer -r asciidoctor-html5s -b html5s -r asciidoctor-diagram --base-dir D:\prototypes\hugo_asciidoc_ddd\docs -a outdir=D:\prototypes\hugo_asciidoc_ddd\build -] ...
```

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

@ -1,20 +1,17 @@
---
title: Front Matter
linktitle:
linkTitle: Front Matter
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/]
parent: content-management
weight: 60
toc: true
weight: 60
aliases: [/content/front-matter/]
---
**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.
@ -68,7 +65,7 @@ cascade
: a map of Front Matter keys whose values are passed down to the page's descendants 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.
: the datetime assigned to this page. This is usually fetched from the `date` field in front matter, but this behavior is configurable.
description
: the description for the content.
@ -137,7 +134,7 @@ weight
: used for [ordering your content in lists][ordering]. Lower weight gets higher precedence. So content with lower weight will come first. If set, weights should be non-zero, as 0 is interpreted as an *unset* weight.
\<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._
: 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.
@ -160,9 +157,7 @@ Any node or section can pass down to descendants a set of Front Matter values as
### Target Specific Pages
{{< new-in "0.76.0" >}}
Since Hugo 0.76 the `cascade` block can be a slice with a optional `_target` keyword, allowing for multiple `cascade` values targeting different page sets.
The `cascade` block can be a slice with a optional `_target` keyword, allowing for multiple `cascade` values targeting different page sets.
{{< code-toggle copy="false" >}}
title ="Blog"
@ -181,7 +176,7 @@ kind="section"
Keywords available for `_target`:
path
: A [Glob](https://github.com/gobwas/glob) pattern matching the content path below /content. Expects Unix-styled slashes. Note that this is the virtual path, so it starts at the mount root. The matching support double-asterisks so you can match for patterns like `/blog/*/**` to match anything from the third level and down.
: A [Glob](https://github.com/gobwas/glob) pattern matching the content path below /content. Expects Unix-styled slashes. Note that this is the virtual path, so it starts at the mount root. The matching supports double-asterisks so you can match for patterns like `/blog/*/**` to match anything from the third level and down.
kind
: A Glob pattern matching the Page's Kind(s), e.g. "{home,section}".
@ -209,8 +204,6 @@ With the above example the Blog section page and its descendants will return `im
- Said descendant 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.
@ -221,9 +214,9 @@ It's possible to set some options for Markdown rendering in a content's front ma
## Front Matter Format Specs
* [TOML Spec][toml]
* [YAML Spec][yaml]
* [JSON Spec][json]
- [TOML Spec][toml]
- [YAML Spec][yaml]
- [JSON Spec][json]
[variables]: /variables/
[aliases]: /content-management/urls/#aliases

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

@ -1,16 +1,15 @@
---
title: "Image Processing"
description: "Resize, crop, rotate, filter, and convert images."
date: 2018-01-24T13:10:00-05:00
categories: ["content management"]
title: Image Processing
linkTitle: Image Processing
description: Resize, crop, rotate, filter, and convert images.
categories: [content management]
keywords: [resources, images]
weight: 4004
draft: false
toc: true
menu:
docs:
parent: "content-management"
weight: 32
parent: content-management
weight: 90
toc: true
weight: 90
---
## Image Resources
@ -28,16 +27,6 @@ content/
└── sunset.jpg <-- page resource
```
## The Image Resource
The `image` resource gives you access to image-specific attributes like the picture's `Width` and `Height`, as well as powerful processing methods and filters. More on that below.
Note that the `image` resource can also be retrieved from a [global resource]({{< relref "/hugo-pipes/introduction#from-file-to-resource" >}})
```go-html-template
{{ $image := .Resources.GetMatch "sunset.jpg" }}
```
### Global Resources
A global resource is a file:
@ -94,10 +83,10 @@ Example 3: A more concise way to skip image rendering if the resource is not fou
## Image Processing Methods
The `image` resource implements the `Resize`, `Fit`, `Fill`, `Crop`, `Filter`, and `Exif` methods.
The `image` resource implements the [`Resize`], [`Fit`], [`Fill`], [`Crop`], [`Filter`], [`Colors`] and [`Exif`] methods.
{{% note %}}
Metadata (Exif, IPTC, XMP, etc.) is not preserved during image transformation. Use the`Exif` method with the _original_ image to extract Exif metadata from JPEG or TIFF images.
Metadata (Exif, IPTC, XMP, etc.) is not preserved during image transformation. Use the [`Exif`] method with the _original_ image to extract Exif metadata from JPEG or TIFF images.
{{% /note %}}
### Resize
@ -167,7 +156,7 @@ Sometimes it can be useful to create the filter chain once and then reuse it.
{{< new-in "0.104.0" >}}
`.Colors` returns a slice of hex string with the dominant colors in the image using a simple histogram method.
`.Colors` returns a slice of hex strings with the dominant colors in the image using a simple histogram method.
```go-html-template
{{ $colors := $image.Colors }}
@ -180,7 +169,7 @@ This method is fast, but if you also scale down your images, it would be good fo
Provides an [Exif] object containing image metadata.
You may access Exif data in JPEG and TIFF images. To prevent errors when processing images without Exif data, wrap the access in a `with` statement.
You may access Exif data in JPEG and TIFF images. To prevent errors when processing images without Exif data, wrap the access in a [`with`] statement.
```go-html-template
{{ with $image.Exif }}
@ -226,11 +215,11 @@ You may also access Exif fields individually, using the [`lang.FormatNumber`] fu
## Image Processing Options
The `Resize`, `Fit`, `Fill`, and `Crop` methods accept a space-separated, case-insensitive list of options. The order of the options within the list is irrelevant.
The [`Resize`], [`Fit`], [`Fill`], and [`Crop`] methods accept a space-separated, case-insensitive list of options. The order of the options within the list is irrelevant.
### Dimensions
With the `Resize` method you must specify width, height, or both. The `Fit`, `Fill`, and `Crop` methods require both width and height. All dimensions are in pixels.
With the [`Resize`] method you must specify width, height, or both. The [`Fit`], [`Fill`], and [`Crop`] methods require both width and height. All dimensions are in pixels.
```go-html-template
{{ $image := $image.Resize "600x" }}
@ -265,9 +254,9 @@ In the example above, on the second line, we have reversed width and height to r
### Anchor
When using the `Crop` or `Fill` method, the _anchor_ determines the placement of the crop box. You may specify `TopLeft`, `Top`, `TopRight`, `Left`, `Center`,`Right`, `BottomLeft`, `Bottom`, `BottomRight`, or `Smart`.
When using the [`Crop`] or [`Fill`] method, the _anchor_ determines the placement of the crop box. You may specify `TopLeft`, `Top`, `TopRight`, `Left`, `Center`,`Right`, `BottomLeft`, `Bottom`, `BottomRight`, or `Smart`.
The default value is `Smart`, which uses [Smartcrop] image analysis to determine the optimal placement of the crop box. You may override the default value in the [site configuration](#processing-options).
The default value is `Smart`, which uses [Smartcrop] image analysis to determine the optimal placement of the crop box. You may override the default value in the [site configuration].
For example, if you have a 400x200 image with a bird in the upper left quadrant, you can create a 200x100 thumbnail containing the bird:
@ -275,7 +264,7 @@ For example, if you have a 400x200 image with a bird in the upper left quadrant,
{{ $image.Crop "200x100 TopLeft" }}
```
If you apply rotation when using the `Crop` or `Fill` method, specify the anchor relative to the rotated image.
If you apply [rotation](#rotation) when using the [`Crop`] or [`Fill`] method, specify the anchor relative to the rotated image.
### Target Format
@ -299,7 +288,7 @@ To convert an image without scaling, use the dimensions of the original image:
Applicable to JPEG and WebP images, the `q` value determines the quality of the converted image. Higher values produce better quality images, while lower values produce smaller files. Set this value to a whole number between 1 and 100, inclusive.
The default value is 75. You may override the default value in the [site configuration](#processing-options).
The default value is 75. You may override the default value in the [site configuration].
```go-html-template
{{ $image.Resize "600x webp q50" }}
@ -309,7 +298,7 @@ The default value is 75. You may override the default value in the [site configu
<!-- Specifies a libwebp preset, not a libwebp image hint. -->
Applicable to WebP images, this option corresponds to a set of pre-defined encoding parameters.
Applicable to WebP images, this option corresponds to a set of predefined encoding parameters.
Value|Example
:--|:--
@ -319,7 +308,7 @@ Value|Example
`picture`|Indoor photograph such as a portrait
`text`|Image that is primarily text
The default value is `photo`. You may override the default value in the [site configuration](#processing-options).
The default value is `photo`. You may override the default value in the [site configuration].
```go-html-template
{{ $image.Resize "600x webp picture" }}
@ -331,7 +320,7 @@ When converting an image from a format that supports transparency (e.g., PNG) to
Use either a 3-digit or a 6-digit hexadecimal color code (e.g., `#00f` or `#0000ff`).
The default value is `#ffffff` (white). You may override the default value in the [site configuration](#processing-options).
The default value is `#ffffff` (white). You may override the default value in the [site configuration].
```go-html-template
{{ $image.Resize "600x jpg #b31280" }}
@ -350,7 +339,7 @@ Filter|Description
`Linear`|Bilinear resampling filter, produces smooth output, faster than cubic filters
`NearestNeighbor`|Fastest resampling filter, no antialiasing
The default value is `Box`. You may override the default value in the [site configuration](#processing-options).
The default value is `Box`. You may override the default value in the [site configuration].
```go-html-template
{{ $image.Resize "600x400 Lanczos" }}
@ -380,7 +369,7 @@ This is the shortcode used to generate the examples above:
{{< readfile file="layouts/shortcodes/imgproc.html" >}}
{{< /code >}}
Call the shortcode from your markdown like this:
Call the shortcode from your Markdown like this:
```go-html-template
{{</* imgproc sunset Resize "300x" /*/>}}
@ -477,3 +466,12 @@ hugo --gc
[page bundle]: {{< relref "content-management/page-bundles" >}}
[Smartcrop]: <https://github.com/muesli/smartcrop#smartcrop>
[time.Format]: {{< relref "functions/dateformat" >}}
[`Colors`]: #colors
[`Crop`]: #crop
[`Exif`]: #exif
[`Fill`]: #fill
[`Filter`]: #filter
[`Fit`]: #fit
[`Resize`]: #resize
[site configuration]: #processing-options
[`with`]: /functions/with/

16
docs/content/en/content-management/menus.md
View file

@ -1,20 +1,16 @@
---
title: Menus
linktitle: 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
aliases: [/extras/menus/]
parent: content-management
weight: 190
toc: true
weight: 190
aliases: [/extras/menus/]
---
{{% note "Lazy Blogger"%}}
@ -69,7 +65,7 @@ menu:
## 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].
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] (see [Menu Entry Properties][me-props] for full details of available variables).
Here’s an example snippet pulled from a configuration file:

22
docs/content/en/content-management/multilingual.md
View file

@ -1,19 +1,16 @@
---
title: Multilingual Mode
linktitle: Multilingual
linkTitle: Multilingual
description: Hugo supports the creation of websites with multiple languages side by side.
date: 2017-01-10
publishdate: 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/]
parent: content-management
weight: 230
toc: true
weight: 230
aliases: [/content/multilingual/,/tutorials/create-a-multilingual-site/]
---
You should define the available languages in a `languages` section in your site configuration.
@ -59,7 +56,7 @@ weight = 3
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,
With the configuration above, all content, sitemap, RSS feeds, pagination,
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], omit the `params` in the key for the translation.
@ -229,7 +226,7 @@ If using `url`, remember to include the language part as well: `/fr/compagnie/a-
### 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...).
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.
@ -507,6 +504,7 @@ The rendering of the main navigation works as usual. `.Site.Menus` will just con
```
### Dynamically localizing menus with i18n
While customizing menus per language is useful, your config file can become hard to maintain if you have a lot of languages
If your menus are the same in all languages (ie. if the only thing that changes is the translated name) you can use the `.Identifier` as a translation key for the menu name:
@ -539,7 +537,6 @@ And do the appropriate changes in the menu code to use the `i18n` tag with the `
</ul>
{{< /code >}}
## 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.
@ -570,9 +567,8 @@ If there is more than one language defined, the `LanguagePrefix` variable will e
## Generate multilingual content with `hugo new`
Currently, `hugo new` is not ready to support generating multilingual content. But there is a [proposal topic](https://github.com/gohugoio/hugo/issues/7732) about this in Github issue to discuss how it should work.
Currently, `hugo new` is not ready to support generating multilingual content. But there is a [proposal topic](https://github.com/gohugoio/hugo/issues/7732) about this in GitHub issue to discuss how it should work.
[abslangurl]: /functions/abslangurl
[config]: /getting-started/configuration/

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

@ -1,20 +1,16 @@
---
title: Content Organization
linktitle: 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/]
parent: content-management
weight: 20
toc: true
weight: 20
aliases: [/content/sections/]
---
## Page Bundles
@ -35,14 +31,13 @@ The bundle documentation is a **work in progress**. We will publish more compreh
## 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 automatically work:
```
```txt
.
└── content
└── about
@ -73,7 +68,7 @@ The following demonstrates the relationships between your content organization a
You can create 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:
```
```txt
. url
. ⊢--^-⊣
. path slug
@ -85,7 +80,7 @@ content/posts/_index.md
At build, this will output to the following destination with the associated values:
```
```txt
url ("/posts/")
⊢-^-⊣
@ -104,7 +99,7 @@ The [sections] can be nested as deeply as you want. The important thing to under
Single content files in each of your sections will be rendered as [single page templates][singles]. Here is an example of a single `post` within `posts`:
```
```txt
path ("posts/my-first-hugo-post.md")
. ⊢-----------^------------⊣
. section slug
@ -114,7 +109,7 @@ content/posts/my-first-hugo-post.md
When Hugo builds your site, the content will be output to the following destination:
```
```txt
url ("/posts/my-first-hugo-post/")
⊢------------^----------⊣
@ -180,7 +175,7 @@ slug: "new-post"
This will render to the following destination according to Hugo's default behavior:
```
```txt
example.com/posts/new-post/
```
@ -217,7 +212,7 @@ url: /blog/new-url/
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:
```
```txt
https://example.com/blog/new-url/
```

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

@ -1,16 +1,17 @@
---
title : "Page Bundles"
description : "Content organization using Page Bundles"
date : 2018-01-24T13:09:00-05:00
linktitle : "Page Bundles"
keywords : ["page", "bundle", "leaf", "branch"]
categories : ["content management"]
toc : true
title: Page Bundles
linkTitle: Page Bundles
description: Content organization using Page Bundles
linkTitle: Page Bundles
keywords: [page, bundle, leaf, branch]
categories: [content management]
menu :
docs:
identifier : "page-bundles"
parent : "content-management"
weight : 11
identifier: "page-bundles"
parent: "content-management"
weight: 30
toc: true
weight: 30
---
Page Bundles are a way to group [Page Resources](/content-management/page-resources/).
@ -23,8 +24,8 @@ A Page Bundle can be one of:
| | 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 |
| Index filename | `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 |
@ -99,8 +100,8 @@ as long as it is not inside another **leaf** 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.
- 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:
@ -121,9 +122,9 @@ _In this example, we are assuming the `some-headless-bundle` to be a headless
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
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
3. Loop through that _slice_ of nested pages, and output their `.Title` and
`.Content`.
---
@ -137,9 +138,8 @@ headless = true
There are many use cases of such headless page bundles:
- Shared media galleries
- Reusable page content "snippets"
- Shared media galleries
- Reusable page content "snippets"
## Branch Bundles {#branch-bundles}

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

@ -1,17 +1,15 @@
---
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"]
title: Page Resources
linkTitle: Page Resources
description: Page resources -- images, other pages, documents, etc. -- have page-relative URLs and their own metadata.
categories: [content management]
keywords: [bundle,content,resources]
weight: 4003
draft: false
toc: true
linktitle: "Page Resources"
menu:
docs:
parent: "content-management"
weight: 31
parent: content-management
weight: 80
toc: true
weight: 80
---
Page resources are only accessible from [page bundles]({{< relref
"/content-management/page-bundles" >}}), those directories with `index.md` or
@ -45,8 +43,6 @@ content
ResourceType
: The main type of the resource's [Media Type](/templates/output-formats/#media-types). For example, a file of MIME type `image/jpeg` has the ResourceType `image`. A `Page` will have `ResourceType` with value `page`.
{{< new-in "0.80.0" >}} Note that we in Hugo `v0.80.0` fixed a bug where non-image resources (e.g. video) would return the MIME sub type, e.g. `json`.
Name
: Default value is the filename (relative to the owning page). Can be set in front matter.
@ -90,16 +86,17 @@ MediaType.Suffixes
: A slice of possible suffixes for the resource's MIME type.
## Methods
ByType
: Returns the page resources of the given type.
```go
```go-html-template
{{ .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
```go-html-template
{{ .Resources.Match "images/*" }}
```
@ -107,6 +104,7 @@ 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*" ✅
@ -140,8 +138,7 @@ title
params
: A map of custom key/values.
### Resources metadata example
### Resources metadata example
{{< code-toggle copy="false">}}
title: Application

29
docs/content/en/content-management/related.md
View file

@ -1,25 +1,22 @@
---
title: Related Content
linkTitle: 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/]
parent: content-management
weight: 110
toc: true
weight: 110
aliases: [/content/related/,/related/]
---
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" >}}
@ -27,9 +24,9 @@ To list up to 5 related pages (which share the same _date_ or _keyword_ paramete
{{ with $related }}
<h3>See Also</h3>
<ul>
{{ range . }}
<li><a href="{{ .RelPermalink }}">{{ .Title }}</a></li>
{{ end }}
{{ range . }}
<li><a href="{{ .RelPermalink }}">{{ .Title }}</a></li>
{{ end }}
</ul>
{{ end }}
{{< /code >}}
@ -39,25 +36,28 @@ To list up to 5 related pages (which share the same _date_ or _keyword_ paramete
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.
```
```go-html-template
{{ $related := site.RegularPages.Related . }}
```
#### .RelatedIndices PAGE INDICE1 [INDICE2 ...]
Returns a collection of pages related to a given one restricted to a list of indices.
```
```go-html-template
{{ $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 consecutive ones its potential `matches`.
```
```go-html-template
{{ $related := site.RegularPages.RelatedTo ( keyVals "tags" "hugo" "rocks") ( keyVals "date" .Date ) }}
```
@ -66,6 +66,7 @@ Read [this blog article](https://regisphilibert.com/blog/2018/04/hugo-optmized-r
{{% /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

17
docs/content/en/content-management/sections.md
View file

@ -1,7 +1,7 @@
---
title: Content Sections
linktitle: Sections
description: "Hugo generates a **section tree** that matches your content."
linkTitle: Sections
description: Hugo generates a **section tree** that matches your content.
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
@ -9,12 +9,11 @@ categories: [content management]
keywords: [lists,sections,content types,organization]
menu:
docs:
parent: "content-management"
weight: 50
weight: 50 #rem
draft: false
aliases: [/content/sections/]
parent: content-management
weight: 120
toc: true
weight: 120
aliases: [/content/sections/]
---
A **Section** is a collection of pages that gets defined based on the
@ -73,7 +72,7 @@ With the available [section variables and methods](#section-page-variables-and-m
{{ else if not .p1.IsHome }}
{{ template "breadcrumbnav" (dict "p1" .p1.Site.Home "p2" .p2 ) }}
{{ end }}
<li{{ if eq .p1 .p2 }} class="active"{{ end }}>
<li{{ if eq .p1 .p2 }} class="active" aria-current="page" {{ end }}>
<a href="{{ .p1.Permalink }}">{{ .p1.Title }}</a>
</li>
{{ end }}
@ -87,7 +86,7 @@ Also see [Page Variables](/variables/page/).
## 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.
Hugo will automatically create a page for each *root section* that lists all 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*

70
docs/content/en/content-management/shortcodes.md
View file

@ -1,21 +1,17 @@
---
title: Shortcodes
linktitle:
linkTitle: Shortcodes
description: Shortcodes are simple snippets inside your content files calling built-in or custom templates.
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2019-11-07
menu:
docs:
parent: "content-management"
weight: 35
weight: 35 #rem
categories: [content management]
keywords: [markdown,content,shortcodes]
draft: false
menu:
docs:
parent: content-management
weight: 100
toc: true
weight: 100
aliases: [/extras/shortcodes/]
testparam: "Hugo Rocks!"
toc: true
---
## What a Shortcode is
@ -40,11 +36,11 @@ Some shortcodes use or require closing shortcodes. Again like HTML, the opening
Here are two examples of paired shortcodes:
```
```go-html-template
{{%/* mdshortcode */%}}Stuff to `process` in the *center*.{{%/* /mdshortcode */%}}
```
```
```go-html-template
{{</* highlight go */>}} A bunch of code here {{</* /highlight */>}}
```
@ -52,11 +48,9 @@ The examples above use two different delimiters, the difference being the `%` ch
### Shortcodes with raw string parameters
{{< new-in "0.64.1" >}}
You can pass multiple lines as parameters to a shortcode by using raw string literals:
```
```go-html-template
{{</* myshortcode `This is some <b>HTML</b>,
and a new line with a "quoted string".` */>}}
```
@ -67,16 +61,15 @@ In Hugo `0.55` we changed how the `%` delimiter works. Shortcodes using the `%`
If you want the old behavior, you can put the following line in the start of your shortcode template:
```
```go-html-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:
The `<` character indicates that the shortcode's inner content does *not* need further rendering. Often shortcodes without Markdown include internal HTML:
```
```go-html-template
{{</* myshortcode */>}}<p>Hello <strong>World!</strong></p>{{</* /myshortcode */>}}
```
@ -86,11 +79,11 @@ You can call shortcodes within other shortcodes by creating your own templates t
## 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.
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].
`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:
@ -151,13 +144,13 @@ attrlink
Bloggers often want to include GitHub gists when writing posts. Let's suppose we want to use the [gist at the following url][examplegist]:
```
```txt
https://gist.github.com/spf13/7896402
```
We can embed the gist in our content via username and gist ID pulled from the URL:
```
```go-html-template
{{</* gist spf13 7896402 */>}}
```
@ -177,7 +170,7 @@ If the gist contains several files and you want to quote just one of them, you c
#### 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.
To demonstrate the remarkable 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 depend on your stylesheets and surrounding markup.
{{< gist spf13 7896402 >}}
@ -223,7 +216,7 @@ To see even more options for adding syntax-highlighted code blocks to your websi
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:
```
```txt
https://www.instagram.com/p/BWNjjyYFxVx/
```
@ -249,19 +242,18 @@ By adding the preceding `hidecaption` example, the following HTML will be added
#### 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.
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 style sheets and surrounding markup.
{{< instagram BWNjjyYFxVx hidecaption >}}
{{% note %}}
The `instagram`-shortcode refers an endpoint of Instagram's API, that's deprecated since October 24th, 2020. Thus, no images can be fetched from this API endpoint, resulting in an error when the `instagram`-shortcode is used. For more information please have a look at GitHub issue [#7879](https://github.com/gohugoio/hugo/issues/7879).
{{% /note %}}
### `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.
Gets a value from the current `Page's` params set in front matter, with a fallback 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 */>}}
@ -291,7 +283,7 @@ Read a more extensive description of `ref` and `relref` in the [cross references
#### Example `ref` and `relref` Input
```
```go-html-template
[Neat]({{</* ref "blog/neat.md" */>}})
[Who]({{</* relref "about.md#who" */>}})
```
@ -300,7 +292,7 @@ Read a more extensive description of `ref` and `relref` in the [cross references
Assuming that standard Hugo pretty URLs are turned on.
```
```html
<a href="https://example.com/blog/neat">Neat</a>
<a href="/about/#who">Who</a>
```
@ -309,13 +301,13 @@ Assuming that standard Hugo pretty URLs are turned on.
You want to include a single tweet into your blog post? Everything you need is the URL of the tweet:
```
```txt
https://twitter.com/SanDiegoZoo/status/1453110110599868418
```
#### Example `tweet` Input
Pass the tweet's user (case-insensitive) and id from the URL as parameters to the `tweet` shortcode.
Pass the tweet's user (case-insensitive) and ID from the URL as parameters to the `tweet` shortcode.
{{< code file="example-tweet-input.md" >}}
{{</* tweet user="SanDiegoZoo" id="1453110110599868418" */>}}
@ -339,7 +331,7 @@ Using the preceding `tweet` example, the following simulates the displayed exper
Adding a video from [Vimeo][] is equivalent to the [YouTube Input shortcode][].
```
```txt
https://vimeo.com/channels/staffpicks/146022717
```
@ -362,7 +354,7 @@ Using the preceding `vimeo` example, the following HTML will be added to your re
{{% 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`.
```
```go
{{</* vimeo id="146022717" class="my-vimeo-wrapper-class" title="My vimeo video" */>}}
```
{{% /tip %}}
@ -377,11 +369,10 @@ Using the preceding `vimeo` example, the following simulates the displayed exper
The `youtube` shortcode embeds a responsive video player for [YouTube videos][]. Only the ID of the video is required, e.g.:
```
```txt
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:
@ -390,7 +381,7 @@ Copy the YouTube video ID that follows `v=` in the video's URL and pass it to th
{{</* 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`:
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" >}}
@ -403,7 +394,6 @@ For [accessibility reasons](https://dequeuniversity.com/tips/provide-iframe-titl
{{</* youtube id="w7Ft2ymGmfc" title="A New Hugo Site in Under Two Minutes" */>}}
{{< /code >}}
#### Example `youtube` Output
Using the preceding `youtube` example, the following HTML will be added to your rendered website's markup:
@ -414,7 +404,7 @@ Using the preceding `youtube` example, the following HTML will be added to your
#### 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].
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 style sheets and surrounding markup. The video is also include in the [Quick Start of the Hugo documentation][quickstart].
{{< youtube w7Ft2ymGmfc >}}

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

@ -1,16 +1,16 @@
---
title: Static Files
description: "Files that get served **statically** (as-is, no modification) on the site root."
date: 2017-11-18
linkTitle: Static Files
description: Files that get served **statically** (as-is, no modification) on the site root.
categories: [content management]
keywords: [source, directories]
menu:
docs:
parent: "content-management"
weight: 130
weight: 130 #rem
aliases: [/static-files]
parent: content-management
weight: 200
toc: true
weight: 200
aliases: [/static-files]
---
By default, the `static/` directory in the site project is used for
@ -65,6 +65,5 @@ 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

14
docs/content/en/content-management/summaries.md
View file

@ -1,20 +1,16 @@
---
title: Content Summaries
linktitle: 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/]
parent: content-management
weight: 160
toc: true
weight: 160
aliases: [/content/summaries/,/content-management/content-summaries/]
---
With the use of the `.Summary` [page variable][pagevariables], Hugo generates summaries of content to use as a short version in summary views.

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

@ -1,22 +1,19 @@
---
title: Syntax Highlighting
linkTitle: Syntax Highlighting
description: Hugo comes with really fast syntax highlighting from Chroma.
date: 2017-02-01
publishdate: 2017-02-01
keywords: [highlighting,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/]
parent: content-management
weight: 240
toc: true
weight: 240
aliases: [/extras/highlighting/,/extras/highlight/,/tools/syntax-highlighting/]
---
Hugo uses [Chroma](https://github.com/alecthomas/chroma) as its code highlighter; it is built in Go and is really, really fast -- and for the most important parts compatible with Pygments we used before.
Hugo uses [Chroma](https://github.com/alecthomas/chroma) as its code highlighter; it is built in Go and is really, really fast.
## Configure Syntax Highlighter
@ -36,11 +33,11 @@ Run `hugo gen chromastyles -h` for more options. See https://xyproto.github.io/s
## Highlight Shortcode
Highlighting is carried out via the built-in [`highlight` shortcode](https://gohugo.io/content-management/shortcodes/#highlight). It 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.
Highlighting is carried out via the built-in [`highlight` shortcode](https://gohugo.io/content-management/shortcodes/#highlight). It takes exactly one required parameter for the programming language to be highlighted and requires a closing shortcode.
Options:
* `linenos`: configure line numbers. Valid values are `true`, `false`, `table`, or `inline`. `false` will turn off line numbers if it's configured to be on in site config. {{< new-in "0.60.0" >}} `table` will give copy-and-paste friendly code blocks.
* `linenos`: configure line numbers. Valid values are `true`, `false`, `table`, or `inline`. `false` will turn off line numbers if it's configured to be on in site config. `table` will give copy-and-paste friendly code blocks.
* `hl_lines`: lists a set of line numbers or line number ranges to be highlighted.
* `linenostart=199`: starts the line number count from 199.
* `anchorlinenos`: Configure anchors on line numbers. Valid values are `true` or `false`;
@ -49,7 +46,7 @@ Options:
### Example: Highlight Shortcode
```
```go-html-template
{{</* highlight go "linenos=table,hl_lines=8 15-17,linenostart=199" */>}}
// ... code
{{</* / highlight */>}}
@ -100,9 +97,9 @@ See [Highlight](/functions/highlight/).
## Highlighting in Code Fences
Highlighting in code fences is enabled by default.{{< new-in "0.60.0" >}}
Highlighting in code fences is enabled by default.
````
````txt
```go {linenos=table,hl_lines=[8,"15-17"],linenostart=199}
// ... code
```
@ -134,8 +131,6 @@ func GetTitleFunc(style string) func(s string) string {
}
```
{{< new-in "0.60.0" >}}Note that only Goldmark supports passing attributes such as `hl_lines`, and it's important that it does not contain any spaces. See [goldmark-highlighting](https://github.com/yuin/goldmark-highlighting) for more information.
The options are the same as in the [highlighting shortcode](/content-management/syntax-highlighting/#highlight-shortcode),including `linenos=false`, but note the slightly different Markdown attribute syntax.
## List of Chroma Highlighting Languages
@ -143,11 +138,3 @@ The options are the same as in the [highlighting shortcode](/content-management/
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 >}}
[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/

27
docs/content/en/content-management/taxonomies.md
View file

@ -1,19 +1,16 @@
---
title: Taxonomies
linktitle:
linkTitle: Taxonomies
description: Hugo includes support for user-defined taxonomies.
date: 2017-02-01
publishdate: 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]
parent: content-management
weight: 150
toc: true
weight: 150
aliases: [/taxonomies/overview/,/taxonomies/usage/,/indexes/overview/,/doc/indexes/,/extras/indexes]
---
## What is a Taxonomy?
@ -49,7 +46,7 @@ Then, in each of the movies, you would specify terms for each of these taxonomie
To continue with the example of a movie site, the following demonstrates content relationships from the perspective of the taxonomy:
```
```txt
Actor <- Taxonomy
Bruce Willis <- Term
The Sixth Sense <- Value
@ -63,7 +60,7 @@ Actor <- Taxonomy
From the perspective of the content, the relationships would appear differently, although the data and labels used are the same:
```
```txt
Unbreakable <- Value
Actors <- Taxonomy
Bruce Willis <- Term
@ -98,8 +95,6 @@ If you do not want Hugo to create any taxonomies, set `disableKinds` in your [si
disableKinds = ["taxonomy","term"]
{{</ code-toggle >}}
{{< new-in "0.73.0" >}} We have fixed the before confusing page kinds used for taxonomies (see the listing below) to be in line with the terms used when we talk about taxonomies. We have been careful to avoid site breakage, and you should get an ERROR in the console if you need to adjust your `disableKinds` section.
{{% page-kinds %}}
### Default Destinations
@ -111,7 +106,7 @@ When taxonomies are used---and [taxonomy templates][] are provided---Hugo will a
## Configure 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.
Custom taxonomies other than the [defaults]({{< relref "taxonomies.md#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"
@ -135,7 +130,7 @@ If you want to have just the default `tags` taxonomy, and remove the `categories
tag = "tags"
{{</ code-toggle >}}
If you want to disable all taxonomies altogether, see the use of `disableKinds` in [Hugo Taxonomy Defaults](#default-taxonomies).
If you want to disable all taxonomies altogether, see the use of `disableKinds` in [Hugo Taxonomy Defaults]({{< relref "taxonomies.md#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.
@ -174,7 +169,7 @@ project_url = "https://github.com/gohugoio/hugo"
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.
The following 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`
@ -194,7 +189,7 @@ Currently taxonomies only support the [default `weight => date` ordering of list
## Add custom metadata to a Taxonomy or 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:
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 its 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" >}}
---

18
docs/content/en/content-management/toc.md
View file

@ -1,20 +1,16 @@
---
title: Table of Contents
linktitle:
linkTitle: Table of Contents
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/]
parent: content-management
weight: 210
toc: true
weight: 210
aliases: [/extras/toc/]
---
{{% note "TOC Heading Levels are Fixed" %}}
@ -27,9 +23,9 @@ Hugo [v0.60.0](https://github.com/gohugoio/hugo/releases/tag/v0.60.0) made a swi
## Usage
Create your markdown the way you normally would with the appropriate headings. Here is some example content:
Create your Markdown the way you normally would with the appropriate headings. Here is some example content:
```
```md
<!-- Your front matter up here -->
## Introduction

19
docs/content/en/content-management/types.md
View file

@ -1,24 +1,21 @@
---
title: Content Types
linkTitle: Content Types
description: Hugo is built around content organized in sections.
date: 2017-02-01
categories: [content management]
keywords: [lists,sections,content types,types,organization]
keywords: [lists, sections, content types, types, organization]
menu:
docs:
parent: "content-management"
weight: 60
weight: 60 #rem
draft: false
aliases: [/content/types]
parent: content-management
weight: 130
toc: true
weight: 130
aliases: [/content/types]
---
A **content type** is a way to organize your content. Hugo resolves the content type from either the `type` in front matter or, if not set, the first directory in the file path. E.g. `content/blog/my-first-event.md` will be of type `blog` if no `type` is set.
A content type is used to
* Determine how the content is rendered. See [Template Lookup Order](/templates/lookup-order/) and [Content Views](https://gohugo.io/templates/views) for more.
* Determine which [archetype](/content-management/archetypes/) template to use for new content.
- Determine how the content is rendered. See [Template Lookup Order](/templates/lookup-order/) and [Content Views](https://gohugo.io/templates/views) for more.
- Determine which [archetype](/content-management/archetypes/) template to use for new content.

42
docs/content/en/content-management/urls.md
View file

@ -1,20 +1,16 @@
---
title: URL Management
linktitle: 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]
keywords: [aliases,redirects,permalinks,urls]
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/]
parent: content-management
weight: 180
toc: true
weight: 180
aliases: [/extras/permalinks/,/extras/aliases/,/extras/urls/,/doc/redirects/,/doc/alias/,/doc/aliases/]
---
## Permalinks
@ -45,7 +41,7 @@ permalinks:
/: /:year/:month/:filename/
{{< /code-toggle >}}
If the standard date-based permalink configuration does not meet your needs, you can also format URL segments using [Go time formatting directives](https://golang.org/pkg/time/#Time.Format). For example, a URL structure with two digit years and month and day digits without zero padding can be accomplished with:
If the standard date-based permalink configuration does not meet your needs, you can also format URL segments using [Go time formatting directives](https://pkg.go.dev/time#Time.Format). For example, a URL structure with two digit years and month and day digits without zero padding can be accomplished with:
{{< code-toggle file="config" copy="false" >}}
permalinks:
@ -83,7 +79,7 @@ The following is a list of values that can be used in a `permalink` definition i
: the content's section
`:sections`
: the content's sections hierarchy. {{< new-in "0.83.0" >}} Since Hugo 0.83 you can use a selection of the sections using _slice syntax_: `:sections[1:]` includes all but the first, `:sections[:last]` includes all but the last, `:sections[last]` includes only the last, `:sections[1:2]` includes section 2 and 3. Note that this slice access will not throw any out-of-bounds errors, so you don't have to be exact.
: the content's sections hierarchy. Uou can use a selection of the sections using _slice syntax_: `:sections[1:]` includes all but the first, `:sections[:last]` includes all but the last, `:sections[last]` includes only the last, `:sections[1:2]` includes section 2 and 3. Note that this slice access will not throw any out-of-bounds errors, so you don't have to be exact.
`:title`
: the content's title
@ -133,7 +129,7 @@ aliases:
---
{{< /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/`.
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
@ -141,14 +137,14 @@ On [multilingual sites][multilingual], each translation of a post can have uniqu
In `/posts/my-new-post.es.md`:
```
```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/`
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
@ -156,7 +152,7 @@ When aliases are specified, Hugo creates a directory to match the alias entry. I
For example, a content file at `posts/my-intended-url.md` with the following in the front matter:
```
```yml
---
title: My New post
aliases: [/posts/my-old-url/]
@ -165,7 +161,7 @@ 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:
```
```html
<!DOCTYPE html>
<html>
<head>
@ -204,7 +200,7 @@ Hugo's default behavior is to render your content with "pretty" URLs. No non-sta
The following demonstrates the concept:
```
```txt
content/posts/_index.md
=> example.com/posts/
content/posts/post-1.md
@ -219,7 +215,7 @@ If you want a specific piece of content to have an exact URL, you can specify th
See [Content Organization][contentorg] for more details on paths.
```
```txt
.
└── content
└── about
@ -236,7 +232,7 @@ See [Content Organization][contentorg] for more details on paths.
Here's the same organization run with `hugo --uglyURLs`:
```
```txt
.
└── content
└── about
@ -251,7 +247,6 @@ Here's the same organization run with `hugo --uglyURLs`:
└── 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`.
@ -268,13 +263,13 @@ In the May 2014 release of Hugo v0.11, the default value of `canonifyURLs` was s
To find out the current value of `canonifyURLs` for your website, you may use the handy `hugo config` command added in v0.13.
```
```txt
hugo config | grep -i canon
```
Or, if you are on Windows and do not have `grep` installed:
```
```txt
hugo config | FINDSTR /I canon
```
@ -300,7 +295,6 @@ 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.

88
docs/content/en/contribute/development.md
View file

@ -4,7 +4,6 @@ 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]
@ -14,7 +13,6 @@ menu:
weight: 10
weight: 10
sections_weight: 10
draft: false
toc: true
---
@ -45,13 +43,13 @@ If you are having trouble following the installation guides for Go, check out [G
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:
```
```txt
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:
```
```txt
go version go1.12 darwin/amd64
```
@ -59,13 +57,13 @@ Next, make sure that you set up your `GOPATH` [as described in the installation
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:
```
```txt
/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:
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
@ -87,7 +85,7 @@ You will need to have Git installed on your computer to contribute to Hugo devel
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.
Go ships with a sub-command called `get` that will download these packages for us when we set up 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).
@ -95,7 +93,7 @@ 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.
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)
@ -103,19 +101,19 @@ Hub is a great tool for working with GitHub. The main site for it is [hub.github
On a Mac, you can install [Hub](https://github.com/github/hub) using [Homebrew](https://brew.sh):
```
```txt
brew install hub
```
Now we'll create an [alias in Bash](https://tldp.org/LDP/abs/html/aliases.html) so that typing `git` actually runs `Hub`:
```
```txt
echo "alias git='hub'" >> ~/.bash_profile
```
Confirm the installation:
```
```txt
git version 2.21.0
hub version 2.10.0
```
@ -134,7 +132,7 @@ We're going to clone the [master Hugo repository](https://github.com/gohugoio/hu
So, let's make a new directory and clone that master repository:
```
```txt
mkdir $HOME/src
cd $HOME/src
git clone https://github.com/gohugoio/hugo.git
@ -145,15 +143,14 @@ git clone https://github.com/gohugoio/hugo.git
And then, install dependencies of Hugo by running the following in the cloned directory:
```
```txt
cd $HOME/src/hugo
go install
```
Hugo relies on [mage](https://github.com/magefile/mage) for some convenient build and test targets. If you don't already have it, get it:
```
```txt
go install github.com/magefile/mage@latest
```
@ -169,19 +166,19 @@ Open the [Hugo repository](https://github.com/gohugoio/hugo) on GitHub and click
![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/).
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.
```
```txt
cd $HOME/src/hugo
```
Now Git needs to know that our fork exists by adding the copied remote url:
```
```txt
git remote add <YOUR-GITHUB-USERNAME> <COPIED REMOTE-URL>
```
@ -189,7 +186,7 @@ git remote add <YOUR-GITHUB-USERNAME> <COPIED REMOTE-URL>
Alternatively, you can use the Git wrapper Hub. Hub makes forking a repository easy:
```
```txt
git fork
```
@ -199,13 +196,13 @@ That command will log in to GitHub using your account, create a fork of the repo
Let's check if everything went right by listing all known remotes:
```
```txt
git remote -v
```
The output should look similar:
```
```txt
digitalcraftsman git@github.com:digitalcraftsman/hugo.git (fetch)
digitalcraftsman git@github.com:digitalcraftsman/hugo.git (push)
origin https://github.com/gohugoio/hugo (fetch)
@ -220,14 +217,14 @@ You should never develop against the "master" branch. The development team will
First, you should always pull the latest changes from the master repository:
```
```txt
git checkout master
git pull
```
Now we can create a new branch for your additions:
```
```txt
git checkout -b <BRANCH-NAME>
```
@ -245,7 +242,7 @@ We have developed a [separate Hugo documentation contribution guide][docscontrib
While making changes in the codebase it's a good idea to build the binary to test them:
```
```txt
mage hugo
```
@ -253,31 +250,33 @@ This command generates the binary file at the root of the repository.
If you want to install the binary in `$GOPATH/bin`, run
```
```txt
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
```
```txt
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:
```
The Go code style guide 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 style guide to our additions:
```txt
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):
```
```txt
# Add all changed files
git add --all
git commit --message "YOUR COMMIT MESSAGE"
@ -295,20 +294,20 @@ If you are unsure what a command does leave the commit as it is. We can fix your
Let's say you want to modify the last commit message. Run the following command and replace the current message:
```
```txt
git commit --amend -m"YOUR NEW COMMIT MESSAGE"
```
Take a look at the commit log to see the change:
```
```txt
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:
After making the last commit you may have forgotten something. There is no need to create a new commit. Just add the latest changes and merge them into the intended commit:
```
```txt
git add --all
git commit --amend
```
@ -321,13 +320,13 @@ Modifications such as those described in this section can have serious unintende
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.
```
```txt
git rebase --interactive @~6
```
The `6` at the end of the command represents the number of commits that should be modified. An editor should open and present a list of last six commit messages:
```
```txt
pick 80d02a1 tpl: Add hasPrefix to the template funcs' "smoke test"
pick aaee038 tpl: Sort the smoke tests
pick f0dbf2c tpl: Add the other test case for hasPrefix
@ -340,7 +339,7 @@ In the case above we should merge the last two commits in the commit of this tut
All operations are written before the commit message. Replace "pick" with an operation. In this case `squash` or `s` for short:
```
```txt
pick 80d02a1 tpl: Add hasPrefix to the template funcs' "smoke test"
pick aaee038 tpl: Sort the smoke tests
pick f0dbf2c tpl: Add the other test case for hasPrefix
@ -353,7 +352,7 @@ We also want to rewrite the commits message of the third last commit. We forgot
You should end up with a similar setup:
```
```txt
pick 80d02a1 tpl: Add hasPrefix to the template funcs' "smoke test"
pick aaee038 tpl: Sort the smoke tests
pick f0dbf2c tpl: Add the other test case for hasPrefix
@ -366,7 +365,7 @@ Close the editor. It should open again with a new tab. A text is instructing you
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:
```
```txt
Successfully rebased and updated refs/heads/<BRANCHNAME>.
```
@ -374,9 +373,9 @@ Check the commit log if everything looks as expected. Should an error occur you
### 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.
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.
```
```txt
git push --set-upstream <YOUR-GITHUB-USERNAME> <BRANCHNAME>
```
@ -402,7 +401,7 @@ Last but not least you should accept the contributor license agreement (CLA). A
### Automatic builds
We use a GitHub Actions workflow to build and test. This is a matrix build across combinations of operating system (masOS, Windows, and Ubuntu) and Go versions. The workflow is triggered by the submission of a pull request. If you are a first-time contributor, the workflow requires approval from a project maintainer.
We use a GitHub Actions workflow to build and test. This is a matrix build across combinations of operating system (macOS, Windows, and Ubuntu) and Go versions. The workflow is triggered by the submission of a pull request. If you are a first-time contributor, the workflow requires approval from a project maintainer.
## Where to start?
@ -417,18 +416,17 @@ Feel free to [open an issue][newissue] if you think you found a bug or you have
* [The Git Book][gitbook] (Free)
* [Go Bootcamp][gobootcamp]
[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]: https://www.golangbootcamp.com/book/get_setup
[godl]: https://golang.org/dl/
[goinstall]: https://golang.org/doc/install
[godl]: https://go.dev/dl/
[goinstall]: https://go.dev/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
[setupgopath]: https://go.dev/doc/code#Workspaces
[trygit]: https://try.github.io/levels/1/challenges/1

31
docs/content/en/contribute/documentation.md
View file

@ -4,7 +4,6 @@ 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:
@ -13,7 +12,6 @@ menu:
weight: 20
weight: 20
sections_weight: 20
draft: false
aliases: [/contribute/docs/]
toc: true
---
@ -24,7 +22,7 @@ It's best to make changes to the Hugo docs on your local machine to check for co
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:
```
```txt
git checkout -b jon-doe-showcase-addition
```
@ -34,15 +32,15 @@ The Hugo docs make heavy use of Hugo's [archetypes][] feature. All content secti
Adding new content to the Hugo docs follows the same pattern, regardless of the content section:
```
```txt
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.
Once you have cloned the Hugo repository, you can create a new function via the following command. Keep the filename lowercase.
```
```txt
hugo new functions/newfunction.md
```
@ -94,13 +92,13 @@ Code blocks are crucial for providing examples of Hugo's new features to end use
### 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.
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.
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>
````txt
```go-html-template
{{ range site.RegularPages }}
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
{{ end }}
```
````
@ -117,7 +115,7 @@ With the `code` shortcodes, *you must include triple back ticks and a language d
`code` is the Hugo docs shortcode you'll use most often. `code` requires has only one named parameter: `file`. Here is the pattern:
```
```go-html-template
{{%/* code file="smart/file/name/with/path.html" download="download.html" copy="true" */%}}
A whole bunch of coding going on up in here!
{{%/* /code */%}}
@ -125,7 +123,6 @@ A whole bunch of coding going on up in here!
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.
@ -142,7 +139,7 @@ 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"`.
```
```go-html-template
{{</* code file="layouts/_default/single.html" download="single.html" */>}}
{{ define "main" }}
<main>
@ -210,7 +207,7 @@ The preceding `output` example will render as follows to the Hugo docs:
Blockquotes can be added to the Hugo documentation using [typical Markdown blockquote syntax][bqsyntax]:
```
```md
> Without the threat of punishment, there is no joy in flight.
```
@ -220,7 +217,7 @@ The preceding blockquote will render as follows in the Hugo docs:
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:
```
```md
> Without the threat of punishment, there is no joy in flight. - [Kobo Abe](https://en.wikipedia.org/wiki/Kobo_Abe)
```

2
docs/content/en/contribute/themes.md
View file

@ -4,7 +4,6 @@ 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]
@ -14,7 +13,6 @@ menu:
weight: 30
weight: 30
sections_weight: 30
draft: false
aliases: [/contribute/theme/]
wip: true
toc: true

2
docs/content/en/functions/GetPage.md
View file

@ -46,7 +46,7 @@ And since `Page` also provides a `.GetPage` method, the above is the same as:
## .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:
The previous examples have used the full content filename to look up 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 }}

5
docs/content/en/functions/RenderString.md
View file

@ -10,8 +10,6 @@ keywords: [markdown,goldmark,render]
signature: [".RenderString MARKUP"]
---
{{< new-in "0.62.0" >}}
`.RenderString` is a method on `Page` that renders some markup to HTML using the content renderer defined for that page (if not set in the options).
The method takes an optional map argument with these options:
@ -32,5 +30,4 @@ Some examples:
{{ "/italic org mode/" | $p.RenderString $optOrg }}
```
**Note** that this method is more powerful than the similar [markdownify](/functions/markdownify/) function as it also supports [Render Hooks](/getting-started/configuration-markup/#markdown-render-hooks) and it has options to render other markup formats.
{{< new-in "0.93.0" >}} **Note**: [markdownify](/functions/markdownify/) uses this function in order to support [Render Hooks](/getting-started/configuration-markup/#markdown-render-hooks).

64
docs/content/en/functions/abslangurl.md
View file

@ -1,27 +1,61 @@
---
title: absLangURL
description: Adds the absolute URL with correct language prefix according to site configuration for multilingual.
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
description: Returns an absolute URL with a language prefix, if any.
categories: [functions]
menu:
docs:
parent: "functions"
keywords: [multilingual,i18n,urls]
parent: functions
keywords: [urls, multilingual,i18n]
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.
Use this function with both monolingual and multilingual configurations. The URL returned by this function depends on:
So for a site `baseURL` set to `https://example.com/hugo/` and the current language is `en`:
- Whether the input begins with a slash
- The `baseURL` in site configuration
- The language prefix, if any
In examples that follow, the project is multilingual with content in both Español (`es`) and English (`en`). The default language is Español. The returned values are from the English site.
### Input does not begin with a slash
If the input does not begin with a slash, the resulting URL will be correct regardless of the `baseURL`.
With `baseURL = https://example.org/`
```go-html-template
{{ absLangURL "" }} → https://example.org/en/
{{ absLangURL "articles" }} → https://example.org/en/articles
{{ absLangURL "style.css" }} → https://example.org/en/style.css
```
{{ "blog/" | absLangURL }} → "https://example.com/hugo/en/blog/"
{{ "blog/" | relLangURL }} → "/hugo/en/blog/"
With `baseURL = https://example.org/docs/`
```go-html-template
{{ absLangURL "" }} → https://example.org/docs/en/
{{ absLangURL "articles" }} → https://example.org/docs/en/articles
{{ absLangURL "style.css" }} → https://example.org/docs/en/style.css
```
### Input begins with a slash
If the input begins with a slash, the resulting URL will be incorrect when the `baseURL` includes a subdirectory. With a leading slash, the function returns a URL relative to the protocol+host section of the `baseURL`.
With `baseURL = https://example.org/`
```go-html-template
{{ absLangURL "/" }} → https://example.org/en/
{{ absLangURL "/articles" }} → https://example.org/en/articles
{{ absLangURL "/style.css" }} → https://example.org/en/style.css
```
With `baseURL = https://example.org/docs/`
```go-html-template
{{ absLangURL "/" }} → https://example.org/en/
{{ absLangURL "/articles" }} → https://example.org/en/articles
{{ absLangURL "/style.css" }} → https://example.org/en/style.css
{{% note %}}
The last three examples are not desirable in most situations. As a best practice, never include a leading slash when using this function.
{{% /note %}}

77
docs/content/en/functions/absurl.md
View file

@ -1,50 +1,61 @@
---
title: absURL
description: Creates an absolute URL based on the configured baseURL.
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
description: Returns an absolute URL.
categories: [functions]
menu:
docs:
parent: "functions"
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/`:
With multilingual configurations, use the [`absLangURL`] function instead. The URL returned by this function depends on:
```
{{ "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/"
- Whether the input begins with a slash
- The `baseURL` in site configuration
### Input does not begin with a slash
If the input does not begin with a slash, the resulting URL will be correct regardless of the `baseURL`.
With `baseURL = https://example.org/`
```go-html-template
{{ absURL "" }} → https://example.org/
{{ absURL "articles" }} → https://example.org/articles
{{ absURL "style.css" }} → https://example.org/style.css
```
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:
With `baseURL = https://example.org/docs/`
{{< 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 >}}
```go-html-template
{{ absURL "" }} → https://example.org/docs/
{{ absURL "articles" }} → https://example.org/docs/articles
{{ absURL "style.css" }} → https://example.org/docs/style.css
```
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.
### Input begins with a slash
{{% 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.
If the input begins with a slash, the resulting URL will be incorrect when the `baseURL` includes a subdirectory. With a leading slash, the function returns a URL relative to the protocol+host section of the `baseURL`.
With `baseURL = https://example.org/`
```go-html-template
{{ absURL "/" }} → https://example.org/
{{ absURL "/articles" }} → https://example.org/articles
{{ absURL "/style.css" }} → https://example.org/style.css
```
With `baseURL = https://example.org/docs/`
```go-html-template
{{ absURL "/" }} → https://example.org/
{{ absURL "/articles" }} → https://example.org/articles
{{ absURL "/style.css" }} → https://example.org/style.css
```
{{% note %}}
The last three examples are not desirable in most situations. As a best practice, never include a leading slash when using this function.
{{% /note %}}
[apply function]: /functions/apply/
[configuration]: /getting-started/configuration/
[jsonld]: https://developers.google.com/search/docs/guides/intro-structured-data
[safejs]: /functions/safejs
[`absLangURL`]: /functions/abslangurl/

77
docs/content/en/functions/complement.md
View file

@ -1,29 +1,80 @@
---
title: "complement"
description: "`collections.Complement` (alias `complement`) gives the elements of a collection that are not in any of the others."
date: 2018-11-07
title: complement
description: Returns the elements of the last collection that are not in any of the others.
categories: [functions]
menu:
docs:
parent: "functions"
keywords: [collections,intersect,union]
signature: ["COLLECTION | complement COLLECTION [COLLECTION]..." ]
hugoversion: "0.51"
parent: functions
keywords: [collections]
signature:
- "complement COLLECTION [COLLECTION]..."
- "collections.Complement COLLECTION [COLLECTION]..."
relatedfuncs: [intersect,symdiff,union]
aliases: []
---
Example:
To find the elements within `$c3` that do not exist in `$c1` or `$c2`:
```go-html-template
{{ $pages := site.RegularPages | first 50 }}
{{ $news := where $pages "Type" "news" | first 5 }}
{{ $blog := where $pages "Type" "blog" | first 5 }}
{{ $other := $pages | complement $news $blog | first 10 }}
{{ $c1 := slice 3 }}
{{ $c2 := slice 4 5 }}
{{ $c3 := slice 1 2 3 4 5 }}
{{ complement $c1 $c2 $c3 }} → [1 2]
```
The above is an imaginary use case for the home page where you want to display different page listings in sections/boxes on different places on the page: 5 from `news`, 5 from the `blog` and then 10 of the pages not shown in the other listings, to _complement_ them.
{{% note %}}
Make your code simpler to understand by using a [chained pipeline]:
[chained pipeline]: https://pkg.go.dev/text/template#hdr-Pipelines
{{% /note %}}
```go-html-template
{{ $c3 | complement $c1 $c2 }} → [1 2]
```
You can also use the `complement` function with page collections. Let's say your site has five content types:
```text
content/
├── blog/
├── books/
├── faqs/
├── films/
└── songs/
```
To list everything except blog articles (`blog`) and frequently asked questions (`faqs`):
```go-html-template
{{ $blog := where site.RegularPages "Type" "blog" }}
{{ $faqs := where site.RegularPages "Type" "faqs" }}
{{ range site.RegularPages | complement $blog $faqs }}
<a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>
{{ end }}
```
{{% note %}}
Although the example above demonstrates the `complement` function, you could use the [`where`] function as well:
[`where`]: /functions/where/
{{% /note %}}
```go-html-template
{{ range where site.RegularPages "Type" "not in" (slice "blog" "faqs") }}
<a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>
{{ end }}
```
In this example we use the `complement` function to remove [stop words] from a sentence:
```go-html-template
{{ $text := "The quick brown fox jumps over the lazy dog" }}
{{ $stopWords := slice "a" "an" "in" "over" "the" "under" }}
{{ $filtered := split $text " " | complement $stopWords }}
{{ delimit $filtered " " }} → The quick brown fox jumps lazy dog
```
[stop words]: https://en.wikipedia.org/wiki/Stop_word

6
docs/content/en/functions/dateformat.md
View file

@ -22,7 +22,7 @@ deprecated: false
{{ time.Format "Monday, Jan 2, 2006" "2015-01-21" }} → "Wednesday, Jan 21, 2015"
```
Note that since Hugo 0.87.0, `time.Format` will return a localized string for the current language. {{< new-in "0.87.0" >}}
`time.Format` returns a localized string for the current language.
The `LAYOUT` string can be either:
@ -34,9 +34,7 @@ See the [`time` function](/functions/time/) to convert a timestamp string to a G
## Date/time formatting layouts
{{< new-in "0.87.0" >}}
Go's date layout strings can be hard to reason about, especially with multiple languages. Since Hugo 0.87.0 you can alternatively use some predefined layout identifiers that will output localized dates or times:
Go's date layout strings can be hard to reason about, especially with multiple languages. You can alternatively use some predefined layout identifiers that will output localized dates or times:
```go-html-template
{{ .Date | time.Format ":date_long" }}

10
docs/content/en/functions/dict.md
View file

@ -3,7 +3,6 @@ title: dict
description: Creates a dictionary from a list of key and value pairs.
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-26
categories: [functions]
menu:
docs:
@ -25,12 +24,11 @@ Note that the `key` can be either a `string` or a `string slice`. The latter is
{{ $m := dict (slice "a" "b" "c") "value" }}
```
## Example: Using `dict` to pass multiple values to a `partial`
The partial below creates a SVG and expects `fill`, `height` and `width` from the caller:
The partial below creates an SVG and expects `fill`, `height` and `width` from the caller:
**Partial definition**
### Partial definition
{{< code file="layouts/partials/svgs/external-links.svg" download="external-links.svg" >}}
<svg version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"
@ -39,7 +37,7 @@ fill="{{ .fill }}" width="{{ .width }}" height="{{ .height }}" viewBox="0 0 32 3
</svg>
{{< /code >}}
**Partial call**
### Partial call
The `fill`, `height` and `width` values can be stored in one object with `dict` and passed to the partial:
@ -47,6 +45,4 @@ The `fill`, `height` and `width` values can be stored in one object with `dict`
{{ partial "svgs/external-links.svg" (dict "fill" "#01589B" "width" 10 "height" 20 ) }}
{{< /code >}}
[partials]: /templates/partials/

2
docs/content/en/functions/errorf.md
View file

@ -30,7 +30,7 @@ Both functions return an empty string, so the messages are only printed to the c
{{ warnf "You should update the shortcodes in %q" .Path }}
```
Note that `errorf`, `erroridf`, and `warnf` support all the formatting verbs of the [fmt](https://golang.org/pkg/fmt/) package.
Note that `errorf`, `erroridf`, and `warnf` support all the formatting verbs of the [fmt](https://pkg.go.dev/fmt) package.
## Suppress errors

46
docs/content/en/functions/findRe.md
View file

@ -1,44 +1,40 @@
---
title: findRE
description: Returns a list of strings that match the regular expression.
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
description: Returns a slice of strings that match the regular expression.
categories: [functions]
menu:
docs:
parent: "functions"
parent: functions
keywords: [regex]
signature: ["findRE PATTERN INPUT [LIMIT]"]
workson: []
hugoversion:
relatedfuncs: []
deprecated: false
signature:
- "findRE PATTERN INPUT [LIMIT]"
- "strings.FindRE PATTERN INPUT [LIMIT]"
relatedfuncs: [replaceRE]
aliases: []
---
By default, the `findRE` function finds all matches. You can limit the number of matches with an optional LIMIT paramater.
By default all matches will be included. The number of matches can be limited with an optional third parameter.
When specifying the regular expression, use a raw [string literal] (backticks) instead of an interpreted string literal (double quotes) to simplify the syntax. With an interpreted string literal you must escape backslashes.
The example below returns a list of all second level headers (`<h2>`) in the content:
The syntax of the regular expression is the same general syntax used by Perl, Python, and other languages. More precisely, it is the syntax accepted by [RE2] except for `\C`.
```
{{ findRE "<h2.*?>(.|\n)*?</h2>" .Content }}
This example returns a slice of all second level headings (`h2` elements) within the rendered `.Content`:
```go-html-template
{{ findRE `(?s)<h2.*?>.*?</h2>` .Content }}
```
You can limit the number of matches in the list with a third parameter. The following example shows how to limit the returned value to just one match (or none, if there are no matched substrings):
The `s` flag causes `.` to match `\n` as well, allowing us to find an `h2` element that contains newlines.
```
{{ findRE "<h2.*?>(.|\n)*?</h2>" .Content 1 }}
<!-- returns ["<h2 id="#foo">Foo</h2>"] -->
To limit the number of matches to one:
```go-html-template
{{ findRE `(?s)<h2.*?>.*?</h2>` .Content 1 }}
```
{{% note %}}
Hugo uses Go's [Regular Expression package](https://golang.org/pkg/regexp/), which is the same general syntax used by Perl, Python, and other languages but with a few minor differences for those coming from a background in PCRE. For a full syntax listing, see the [GitHub wiki for re2](https://github.com/google/re2/wiki/Syntax).
If you are just learning RegEx, or at least Go's flavor, you can practice pattern matching in the browser at <https://regex101.com/>.
You can write and test your regular expression using [regex101.com](https://regex101.com/). Be sure to select the Go flavor before you begin.
{{% /note %}}
[partials]: /templates/partials/
[`plainify`]: /functions/plainify/
[toc]: /content-management/toc/
[`urlize`]: /functions/urlize
[RE2]: https://github.com/google/re2/wiki/Syntax
[string literal]: https://go.dev/ref/spec#String_literals

5
docs/content/en/functions/get.md
View file

@ -18,12 +18,11 @@ aliases: []
needsexample: true
---
`.Get` is specifically used when creating your own [shortcode template][sc], to access the [positional and named](/templates/shortcode-templates/#positional-vs-named-parameters) parameters passed to it. When used with a numeric INDEX, it queries positional parameters (starting with 0). With a string KEY, it queries named parameters.
When accessing a named parameter that does not exist, `.Get` returns an empty string instead of interrupting the build. The same goes with positional parameters in hugo version 0.40 and after. This allows you to chain `.Get` with `if`, `with`, `default` or `cond` to check for parameter existence. For example, you may now use:
When accessing named or positional parameters that do not exist, `.Get` returns an empty string instead of interrupting the build. This allows you to chain `.Get` with `if`, `with`, `default` or `cond` to check for parameter existence. For example:
```
```go-html-template
{{ $quality := default "100" (.Get 1) }}
```

3
docs/content/en/functions/getenv.md
View file

@ -41,3 +41,6 @@ And then retrieve the values within a template:
{{ os.Getenv "MY_VAR1" }} --> foo
{{ os.Getenv "MY_VAR2" }} --> bar
```
With Hugo v0.91.0 and later, you must explicitly allow access to environment variables. For details, review [Hugo's Security Policy](/about/security-model/#security-policy). By default, environment variables beginning with `HUGO_` are allowed when using the `os.Getenv` function.

22
docs/content/en/functions/haschildren.md
View file

@ -1,22 +0,0 @@
---
title: .HasChildren
description:
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
categories: [functions]
menu:
docs:
parent: "functions"
keywords: [menus]
toc:
signature: ["HasChildren"]
workson: [menus]
hugoversion:
relatedfuncs: []
deprecated: false
draft: true
aliases: []
---
Used in [menu templates](/templates/menu-templates/).

2
docs/content/en/functions/hasmenucurrent.md
View file

@ -23,6 +23,6 @@ aliases: []
returns `true` if the PAGE is the same object as the `.Page` in one of the
**children menu entries** under MENUENTRY in a given MENU.
{{< new-in "0.86.0" >}} If MENUENTRY's `.Page` is a [section](/content-management/sections/) then, from Hugo `0.86.0`, this method also returns true for any descendant of that section..
If MENUENTRY's `.Page` is a [section](/content-management/sections/) then, from Hugo `0.86.0`, this method also returns true for any descendant of that section..
You can find its example use in [menu templates](/templates/menu-templates/).

4
docs/content/en/functions/hugo.md
View file

@ -25,7 +25,7 @@ hugo.Generator
: `<meta>` tag for the version of Hugo that generated the site. `hugo.Generator` outputs a *complete* HTML tag; e.g. `<meta name="generator" content="Hugo 0.63.2">`
hugo.Version
: the current version of the Hugo binary you are using e.g. `0.63.2`
: the current version of the Hugo binary you are using e.g. `0.99.1`
hugo.GoVersion
: returns the version of Go that the Hugo binary was built with. {{< new-in "0.101.0" >}}
@ -39,7 +39,7 @@ hugo.CommitHash
hugo.BuildDate
: the compile date of the current Hugo binary formatted with RFC 3339 e.g. `2002-10-02T10:00:00-05:00`
hugo.IsExtended {{< new-in "0.83.0" >}}
hugo.IsExtended
: whether this is the extended Hugo binary.
hugo.IsProduction

4
docs/content/en/functions/images/index.md
View file

@ -15,8 +15,6 @@ See [images.Filter](#filter) for how to apply these filters to an image.
## Overlay
{{< new-in "0.80.0" >}}
{{% funcsig %}}
images.Overlay SRC X Y
{{% /funcsig %}}
@ -39,8 +37,6 @@ The above will overlay `$logo` in the upper left corner of `$img` (at position `
## Text
{{< new-in "0.90.0" >}}
Using the `Text` filter, you can add text to an image.
{{% funcsig %}}

2
docs/content/en/functions/int.md
View file

@ -38,7 +38,7 @@ this purpose.
{{ int ("00987" | strings.TrimLeft "0") }}
```
**Explanation**
### Explanation
The `int` function eventually calls the `ParseInt` function from the Go library
`strconv`.

2
docs/content/en/functions/intersect.md
View file

@ -17,7 +17,7 @@ relatedfuncs: []
deprecated: false
aliases: []
---
An useful example is to use it as `AND` filters when combined with where:
A useful example is to use it as `AND` filters when combined with where:
## AND filter in where query

2
docs/content/en/functions/jsonify.md
View file

@ -35,7 +35,7 @@ more copies of *indent* according to the indentation nesting.
## Jsonify options
indent ("")
: Indendation to use.
: Indentation to use.
prefix ("")
: Indentation prefix.

5
docs/content/en/functions/markdownify.md
View file

@ -23,7 +23,6 @@ aliases: []
{{ .Title | markdownify }}
```
*Note*: if you need [Render Hooks][], which `markdownify` doesn't currently
support, use [.RenderString](/functions/renderstring/) instead.
{{< new-in "0.93.0" >}} **Note**: `markdownify` now supports [Render Hooks][] just like [.RenderString](/functions/renderstring/).
[Render Hooks]: /getting-started/configuration-markup/#markdown-render-hooks
[Render Hooks]: /templates/render-hooks/

2
docs/content/en/functions/md5.md
View file

@ -25,6 +25,6 @@ aliases: []
This can be useful if you want to use [Gravatar](https://en.gravatar.com/) for generating a unique avatar:
```
```html
<img src="https://www.gravatar.com/avatar/{{ md5 "your@email.com" }}?s=100&d=identicon">
```

2
docs/content/en/functions/partialCached.md
View file

@ -43,4 +43,4 @@ If you need to pass additional parameters to create unique variants, you can pas
Note that the variant parameters are not made available to the underlying partial template. They are only use to create a unique cache key. Since Hugo `0.61.0` you can use any object as cache key(s), not just strings.
> See also the [The Full Partial Series Part 1: Caching!](https://regisphilibert.com/blog/2019/12/hugo-partial-series-part-1-caching-with-partialcached/)
> See also [The Full Partial Series Part 1: Caching!](https://regisphilibert.com/blog/2019/12/hugo-partial-series-part-1-caching-with-partialcached/)

67
docs/content/en/functions/relLangURL.md
View file

@ -1,29 +1,62 @@
---
title: relLangURL
description: Adds the relative URL with correct language prefix according to site configuration for multilingual.
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
keywords: [multilingual,i18n,urls]
description: Returns a relative URL with a language prefix, if any.
categories: [functions]
menu:
docs:
parent: "functions"
parent: functions
keywords: [urls, multilingual,i18n]
signature: ["relLangURL INPUT"]
workson: []
hugoversion:
relatedfuncs: []
deprecated: false
aliases: []
---
`absLangURL` and `relLangURL` functions 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. (See [Configure Languages][multiliconfig].)
Use this function with both monolingual and multilingual configurations. The URL returned by this function depends on:
So for a site `baseURL` set to `https://example.com/hugo/` and the current language is `en`:
- Whether the input begins with a slash
- The `baseURL` in site configuration
- The language prefix, if any
```
{{ "blog/" | absLangURL }} → "https://example.com/hugo/en/blog/"
{{ "blog/" | relLangURL }} → "/hugo/en/blog/"
In examples that follow, the project is multilingual with content in both Español (`es`) and English (`en`). The default language is Español. The returned values are from the English site.
### Input does not begin with a slash
If the input does not begin with a slash, the resulting URL will be correct regardless of the `baseURL`.
With `baseURL = https://example.org/`
```go-html-template
{{ relLangURL "" }} → /en/
{{ relLangURL "articles" }} → /en/articles
{{ relLangURL "style.css" }} → /en/style.css
```
[multiliconfig]: /content-management/multilingual/#configure-languages
With `baseURL = https://example.org/docs/`
```go-html-template
{{ relLangURL "" }} → /docs/en/
{{ relLangURL "articles" }} → /docs/en/articles
{{ relLangURL "style.css" }} → /docs/en/style.css
```
### Input begins with a slash
If the input begins with a slash, the resulting URL will be incorrect when the `baseURL` includes a subdirectory. With a leading slash, the function returns a URL relative to the protocol+host section of the `baseURL`.
With `baseURL = https://example.org/`
```go-html-template
{{ relLangURL "/" }} → /en/
{{ relLangURL "/articles" }} → /en/articles
{{ relLangURL "/style.css" }} → /en/style.css
```
With `baseURL = https://example.org/docs/`
```go-html-template
{{ relLangURL "/" }} → /en/
{{ relLangURL "/articles" }} → /en/articles
{{ relLangURL "/style.css" }} → /en/style.css
```
{{% note %}}
The last three examples are not desirable in most situations. As a best practice, never include a leading slash when using this function.
{{% /note %}}

76
docs/content/en/functions/relurl.md
View file

@ -1,49 +1,61 @@
---
title: relURL
description: Creates a baseURL-relative URL.
date: 2017-02-01
publishdate: 2017-02-01
description: Returns a relative URL.
categories: [functions]
menu:
docs:
parent: "functions"
parent: functions
keywords: [urls]
signature: ["relURL INPUT"]
workson: []
hugoversion:
relatedfuncs: [absURL]
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/`:
With multilingual configurations, use the [`relLangURL`] function instead. The URL returned by this function depends on:
```
{{ "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/"
- Whether the input begins with a slash
- The `baseURL` in site configuration
### Input does not begin with a slash
If the input does not begin with a slash, the resulting URL will be correct regardless of the `baseURL`.
With `baseURL = https://example.org/`
```go-html-template
{{ relURL "" }} → /
{{ relURL "articles" }} → /articles
{{ relURL "style.css" }} → /style.css
```
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 for SEO][jsonld] where some of your images for a piece of content may or may not be hosted locally:
With `baseURL = https://example.org/docs/`
{{< code file="layouts/partials/schemaorg-metadata.html" download="schemaorg-metadata.html" >}}
<script type="application/ld+json">
{
"@context" : "https://schema.org",
"@type" : "BlogPosting",
"image" : {{ apply .Params.images "absURL" "." }}
}
</script>
{{< /code >}}
```go-html-template
{{ relURL "" }} → /docs/
{{ relURL "articles" }} → /docs/articles
{{ relURL "style.css" }} → /docs/style.css
```
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.
### Input begins with a slash
{{% 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.
If the input begins with a slash, the resulting URL will be incorrect when the `baseURL` includes a subdirectory. With a leading slash, the function returns a URL relative to the protocol+host section of the `baseURL`.
With `baseURL = https://example.org/`
```go-html-template
{{ relURL "/" }} → /
{{ relURL "/articles" }} → /articles
{{ relURL "style.css" }} → /style.css
```
With `baseURL = https://example.org/docs/`
```go-html-template
{{ relURL "/" }} → /
{{ relURL "/articles" }} → /articles
{{ relURL "/style.css" }} → /style.css
```
{{% note %}}
The last three examples are not desirable in most situations. As a best practice, never include a leading slash when using this function.
{{% /note %}}
[apply function]: /functions/apply/
[configuration]: /getting-started/configuration/
[jsonld]: https://developers.google.com/search/docs/advanced/structured-data/intro-structured-data
[safejs]: /functions/safejs
[`relLangURL`]: /functions/rellangurl/

51
docs/content/en/functions/replacere.md
View file

@ -1,34 +1,47 @@
---
title: replaceRE
description: Replaces all occurrences of a regular expression with the replacement pattern.
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2020-09-07
description: Returns a string, replacing all occurrences of a regular expression with a replacement pattern.
categories: [functions]
menu:
docs:
parent: "functions"
parent: functions
keywords: [regex]
signature: ["strings.ReplaceRE PATTERN REPLACEMENT INPUT [LIMIT]", "replaceRE PATTERN REPLACEMENT INPUT [LIMIT]"]
workson: []
hugoversion:
relatedfuncs: []
deprecated: false
signature:
- "replaceRE PATTERN REPLACEMENT INPUT [LIMIT]"
- "strings.ReplaceRE PATTERN REPLACEMENT INPUT [LIMIT]"
relatedfuncs: [findRE]
aliases: []
---
By default, the `replaceRE` function replaces all matches. You can limit the number of matches with an optional LIMIT paramater.
`strings.ReplaceRE` returns a copy of `INPUT`, replacing all matches of the regular
expression `PATTERN` with the replacement text `REPLACEMENT`.
The number of replacements can be limited with an optional `LIMIT` parameter.
When specifying the regular expression, use a raw [string literal] (backticks) instead of an interpreted string literal (double quotes) to simplify the syntax. With an interpreted string literal you must escape backslashes.
The syntax of the regular expression is the same general syntax used by Perl, Python, and other languages. More precisely, it is the syntax accepted by [RE2] except for `\C`.
This example replaces two or more consecutive hyphens with a single hyphen:
```go-html-template
{{ $s := "a-b--c---d" }}
{{ replaceRE `(-{2,})` "-" $s }} → a-b-c-d
```
{{ replaceRE "^https?://([^/]+).*" "$1" "http://gohugo.io/docs" }}` → "gohugo.io"
{{ "http://gohugo.io/docs" | replaceRE "^https?://([^/]+).*" "$1" }}` → "gohugo.io"
{{ replaceRE "a+b" "X" "aabbaabbab" 1 }} → "Xbaabbab"
To limit the number of replacements to one:
```go-html-template
{{ $s := "a-b--c---d" }}
{{ replaceRE `(-{2,})` "-" $s 1 }} → a-b-c---d
```
You can use `$1`, `$2`, etc. within the replacement string to insert the groups captured within the regular expression:
```go-html-template
{{ $s := "http://gohugo.io/docs" }}
{{ replaceRE "^https?://([^/]+).*" "$1" $s }} → gohugo.io
```
{{% note %}}
Hugo uses Go's [Regular Expression package](https://golang.org/pkg/regexp/), which is the same general syntax used by Perl, Python, and other languages but with a few minor differences for those coming from a background in PCRE. For a full syntax listing, see the [GitHub wiki for re2](https://github.com/google/re2/wiki/Syntax).
If you are just learning RegEx, or at least Go's flavor, you can practice pattern matching in the browser at <https://regex101.com/>.
You can write and test your regular expression using [regex101.com](https://regex101.com/). Be sure to select the Go flavor before you begin.
{{% /note %}}
[RE2]: https://github.com/google/re2/wiki/Syntax
[string literal]: https://go.dev/ref/spec#String_literals

2
docs/content/en/functions/safeHTML.md
View file

@ -27,7 +27,7 @@ copyright = "© 2015 Jane Doe. <a href=\"https://creativecommons.org/licenses/b
`{{ .Site.Copyright | safeHTML }}` in a template would then output:
```
```html
© 2015 Jane Doe. <a href="https://creativecommons.org/licenses/by/4.0/">Some rights reserved</a>.
```

42
docs/content/en/functions/safeHTMLAttr.md
View file

@ -1,30 +1,46 @@
---
title: safeHTMLAttr
# linktitle: safeHTMLAttr
description: Declares the provided string as a safe HTML attribute.
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
categories: [functions]
menu:
docs:
parent: "functions"
parent: functions
keywords: [strings]
signature: ["safeHTMLAttr INPUT"]
workson: []
hugoversion:
relatedfuncs: []
deprecated: false
aliases: []
---
Example: Given a site-wide `config.toml` that contains this menu entry:
Given a site configuration that contains this menu entry:
{{< code-toggle file="config" >}}
[[menu.main]]
name = "IRC: #golang at freenode"
url = "irc://irc.freenode.net/#golang"
name = "IRC"
url = "irc://irc.freenode.net/#golang"
{{< /code-toggle >}}
* <span class="bad">`<a href="{{ .URL }}">` &rarr; `<a href="#ZgotmplZ">`</span>
* <span class="good">`<a {{ printf "href=%q" .URL | safeHTMLAttr }}>` &rarr; `<a href="irc://irc.freenode.net/#golang">`</span>
Attempting to use the `url` value directly in an attribute:
```go-html-template
{{ range site.Menus.main }}
<a href="{{ .URL }}">{{ .Name }}</a>
{{ end }}
```
Will produce:
```html
<a href="#ZgotmplZ">IRC</a>
```
`ZgotmplZ` is a special value, inserted by Go's [template/html] package, that indicates that unsafe content reached a CSS or URL context.
To override the safety check, use the `safeHTMLAttr` function:
```go-html-template
{{ range site.Menus.main }}
<a {{ printf "href=%q" .URL | safeHTMLAttr }}>{{ .Name }}</a>
{{ end }}
```
[template/html]: https://pkg.go.dev/html/template

4
docs/content/en/functions/scratch.md
View file

@ -42,7 +42,7 @@ Since Hugo 0.43, there are two different ways of using Scratch:
#### The local `newScratch`
{{< new-in "0.43" >}} A Scratch instance can also be assigned to any variable using the `newScratch` function. In this case, no Page or Shortcode context is required and the scope of the scratch is only local. The methods detailed below are available from the variable the Scratch instance was assigned to.
A Scratch instance can also be assigned to any variable using the `newScratch` function. In this case, no Page or Shortcode context is required and the scope of the scratch is only local. The methods detailed below are available from the variable the Scratch instance was assigned to.
```go-html-template
{{ $data := newScratch }}
@ -138,7 +138,7 @@ Return an array of values from `key` sorted by `mapKey`.
#### .Delete
{{< new-in "0.38" >}} Remove the given key.
Remove the given key.
```go-html-template
{{ $scratch.Set "greeting" "Hello" }}

17
docs/content/en/functions/split.md
View file

@ -1,10 +1,9 @@
---
title: split
# linktitle: split
description: splits a string into substrings separated by a delimiter
description: Returns a slice of strings by splitting STRING by DELIM.
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
lastmod: 2022-11-06
categories: [functions]
menu:
docs:
@ -18,4 +17,14 @@ deprecated: false
aliases: []
---
* `{{split "tag1,tag2,tag3" "," }}` → ["tag1" "tag2" "tag3"]
Examples:
```go-html-template
{{ split "tag1,tag2,tag3" "," }} → ["tag1", "tag2", "tag3"]
{{ split "abc" "" }} → ["a", "b", "c"]
```
{{% note %}}
`split` essentially does the opposite of [delimit]({{< ref "functions/delimit" >}}). While `split` creates a slice from a string, `delimit` creates a string from a slice.
{{% /note %}}

2
docs/content/en/functions/strings.Count.md
View file

@ -17,8 +17,6 @@ deprecated: false
aliases: []
---
{{< new-in "0.74.0" >}}
If `SUBSTR` is an empty string, this function returns 1 plus the number of Unicode code points in `STRING`.
Example|Result

2
docs/content/en/functions/strings.HasSuffix.md
View file

@ -1,6 +1,6 @@
---
title: strings.HasSuffix
description: Determine whether or not a given string ends with the provided trailing suffix string.
description: Determine whether a given string ends with the provided trailing suffix string.
date: 2019-08-13
publishdate: 2019-08-13
lastmod: 2019-08-13

5
docs/content/en/functions/symdiff.md
View file

@ -21,8 +21,3 @@ Example:
The above will print `[1 2 4]`.
Also see https://en.wikipedia.org/wiki/Symmetric_difference

2
docs/content/en/functions/upper.md
View file

@ -22,7 +22,7 @@ aliases: []
Note that `upper` can be applied in your templates in more than one way:
```
```go-html-template
{{ upper "BatMan" }} → "BATMAN"
{{ "BatMan" | upper }} → "BATMAN"
```

2
docs/content/en/functions/urlize.md
View file

@ -68,6 +68,4 @@ The preceding partial would then output to the rendered page as follows, assumin
</header>
{{< /output >}}
[singletemplate]: /templates/single-page-templates/

33
docs/content/en/functions/urlquery.md Normal file
View file

@ -0,0 +1,33 @@
---
title: urlquery
linktitle: urlquery
description: Returns the escaped value of the textual representation of its arguments in a form suitable for embedding in a URL query.
date: 2022-01-18
publishdate: 2022-01-18
lastmod: 2022-01-18
categories: [functions]
menu:
docs:
parent: "functions"
keywords: [urls]
signature: ["urlquery INPUT [INPUT]..."]
hugoversion:
deprecated: false
workson: []
relatedfuncs: []
aliases: []
---
This template code:
```go-html-template
{{ $u := urlquery "https://" "example.com" | safeURL }}
<a href="https://example.org?url={{ $u }}">Link</a>
```
Is rendered to:
```html
<a href="https://example.org?url=https%3A%2F%2Fexample.com">Link</a>
```

4
docs/content/en/functions/urls.Parse.md
View file

@ -19,13 +19,13 @@ aliases: []
`urls.Parse` takes a url as input
```
```go-html-template
{{ $url := urls.Parse "http://www.gohugo.io" }}
```
and returns a [URL](https://godoc.org/net/url#URL) structure. The struct fields are accessed via the `.` notation:
```
```go-html-template
{{ $url.Scheme }} → "http"
{{ $url.Host }} → "www.gohugo.io"
```

4
docs/content/en/functions/where.md
View file

@ -115,7 +115,7 @@ You can also put the returned value of the `where` clauses into a variable:
Using `first` and `where` together can be very
powerful. Below snippet gets a list of posts only from [**main
sections**](#mainsections), sorts it using the [default
sections**]({{< relref "where.md#mainsections" >}}), sorts it using the [default
ordering](/templates/lists/) for lists (i.e., `weight => date`), and
then ranges through only the first 5 posts in that list:
@ -163,7 +163,7 @@ section names to hard-coded values like `"posts"` or `"post"`.
```
If the user has not set this config parameter in their site config, it
will default to the _section with the most pages_.
will default to the *section with the most pages*.
The user can override the default:

4
docs/content/en/getting-started/_index.md
View file

@ -4,7 +4,6 @@ linktitle: Get Started Overview
description: Quick start and guides for installing Hugo on your preferred operating system.
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
categories: [getting started]
keywords: [usage,docs]
menu:
@ -12,13 +11,12 @@ menu:
parent: "getting-started"
weight: 1
weight: 0001 #rem
draft: false
aliases: [/overview/introduction/]
toc: false
---
If this is your first time using Hugo and you've [already installed Hugo on your machine][installed], we recommend the [quick start][]. You can also use [external learning resources][] to learn Hugo.
[installed]: /getting-started/installing/
[installed]: /installation/
[quick start]: /getting-started/quick-start/
[external learning resources]: /getting-started/external-learning-resources/

13
docs/content/en/getting-started/configuration-markup.md
View file

@ -12,8 +12,6 @@ toc: true
## Configure Markup
{{< new-in "0.60.0" >}}
See [Goldmark](#goldmark) for settings related to the default Markdown handler in Hugo.
Below are all markup related configuration in Hugo with their default settings:
@ -43,7 +41,7 @@ typographer
attribute
: Enable custom attribute support for titles and blocks by adding attribute lists inside single curly brackets (`{.myclass class="class1 class2" }`) and placing it _after the Markdown element it decorates_, on the same line for titles and on a new line directly below for blocks.
{{< new-in "0.81.0" >}} In Hugo 0.81.0 we added support for adding attributes (e.g. CSS classes) to Markdown blocks, e.g. tables, lists, paragraphs etc.
Hugo supports adding attributes (e.g. CSS classes) to Markdown blocks, e.g. tables, lists, paragraphs etc.
A blockquote with a CSS class:
@ -70,15 +68,14 @@ There are some current limitations: For tables you can currently only apply it t
Note that attributes in [code fences](/content-management/syntax-highlighting/#highlighting-in-code-fences) must come after the opening tag, with any other highlighting processing instruction, e.g.:
````
````txt
```go {.myclass linenos=table,hl_lines=[8,"15-17"],linenostart=199}
// ... code
```
````
autoHeadingIDType ("github") {{< new-in "0.62.2" >}}
: The strategy used for creating auto IDs (anchor names). Available types are `github`, `github-ascii` and `blackfriday`. `github` produces GitHub-compatible IDs, `github-ascii` will drop any non-Ascii characters after accent normalization, and `blackfriday` will make the IDs compatible with [Blackfriday](#blackfriday), the default Markdown engine before Hugo 0.60. Note that if Goldmark is your default Markdown engine, this is also the strategy used in the [anchorize](/functions/anchorize/) template func.
autoHeadingIDType ("github")
: The strategy used for creating auto IDs (anchor names). Available types are `github`, `github-ascii` and `blackfriday`. `github` produces GitHub-compatible IDs, `github-ascii` will drop any non-Ascii characters after accent normalization, and `blackfriday` will make the IDs compatible with Blackfriday, the default Markdown engine before Hugo 0.60. Note that if Goldmark is your default Markdown engine, this is also the strategy used in the [anchorize](/functions/anchorize/) template func.
### Highlight
@ -108,8 +105,6 @@ endLevel
ordered
: Whether or not to generate an ordered list instead of an unordered list.
## Markdown Render Hooks
See [Markdown Render Hooks](/templates/render-hooks/).

92
docs/content/en/getting-started/configuration.md
View file

@ -12,7 +12,6 @@ menu:
weight: 60
weight: 60
sections_weight: 60
draft: false
aliases: [/overview/source-directory/,/overview/configuration/]
toc: true
---
@ -23,11 +22,11 @@ Hugo uses the `config.toml`, `config.yaml`, or `config.json` (if found in the
site root) as the default site config file.
The user can choose to override that default with one or more site config files
using the command line `--config` switch.
using the command-line `--config` switch.
Examples:
```
```txt
hugo --config debugconfig.toml
hugo --config a.toml,b.toml,c.toml
```
@ -58,7 +57,7 @@ foo = "bar"
- Files can be localized to become language specific.
```
```txt
├── config
│ ├── _default
│ │ ├── config.toml
@ -74,7 +73,7 @@ foo = "bar"
│ └── params.toml
```
Considering the structure above, when running `hugo --environment staging`, Hugo will use every settings from `config/_default` and merge `staging`'s on top of those.
Considering the structure above, when running `hugo --environment staging`, Hugo will use every setting from `config/_default` and merge `staging`'s on top of those.
Let's take an example to understand this better. Let's say you are using Google Analytics for your website. This requires you to specify `googleAnalytics = "G-XXXXXXXX"` in `config.toml`. Now consider the following scenario:
- You don't want the Analytics code to be loaded in development i.e. in your `localhost`
@ -95,15 +94,12 @@ This is how you need to configure your `config.toml` files considering the above
Now you need to tell Hugo that you are using the staging environment. So your build command should be `hugo --environment staging` which will load the `G-SSSSSSSS` analytics code in your staging website
{{% note %}}
Default environments are __development__ with `hugo server` and __production__ with `hugo`.
{{%/ note %}}
## Merge Configuration from Themes
{{< new-in "0.84.0" >}} The configuration merge described below was improved in Hugo 0.84.0 and made fully configurable. The big change/improvement was that we now, by default, do deep merging of `params` maps from themes.
The configuration value for `_merge` can be one of:
none
@ -138,9 +134,11 @@ The directory where Hugo finds archetype files (content templates). {{% module-m
The directory where Hugo finds asset files used in [Hugo Pipes](/hugo-pipes/). {{% module-mounts-note %}}
### baseURL
Hostname (and path) to the root, e.g. https://bep.is/
### build
See [Configure Build](#configure-build)
### buildDrafts (false)
@ -162,12 +160,11 @@ Include content already expired.
Include content with publishdate in the future.
### caches
See [Configure File Caches](#configure-file-caches)
### cascade
{{< new-in "0.86.0" >}}
Pass down default configuration values (front matter) to pages in the content tree. The options in site config is the same as in page front matter, see [Front Matter Cascade](/content-management/front-matter#front-matter-cascade).
### canonifyURLs
@ -304,19 +301,24 @@ See [Configure Languages](/content-management/multilingual/#configure-languages)
See [Disable a Language](/content-management/multilingual/#disable-a-language)
### markup
See [Configure Markup](/getting-started/configuration-markup).{{< new-in "0.60.0" >}}
See [Configure Markup](/getting-started/configuration-markup).
### mediaTypes
See [Configure Media Types](/templates/output-formats/#media-types).
### menus
See [Add Non-content Entries to a Menu](/content-management/menus/#add-non-content-entries-to-a-menu).
### minify
See [Configure Minify](#configure-minify)
### module
Module config see [Module Config](/hugo-modules/configuration/).{{< new-in "0.56.0" >}}
Module config see [Module Config](/hugo-modules/configuration/).
### newContentEditor
@ -337,6 +339,7 @@ Don't sync permission mode of files.
Don't sync modification time of files.
### outputFormats
See [Configure Output Formats](#configure-additional-output-formats).
### paginate
@ -352,6 +355,7 @@ Default number of elements per page in [pagination](/templates/pagination/).
The path element used during pagination (`https://example.com/page/2`).
### permalinks
See [Content Management](/content-management/urls/#permalinks).
### pluralizeListTitles
@ -367,7 +371,8 @@ Pluralize titles in lists.
The directory to where Hugo will write the final static site (the HTML files etc.).
### related
: See [Related Content](/content-management/related/#configure-related-content).{{< new-in "0.27" >}}
: See [Related Content](/content-management/related/#configure-related-content).
### relativeURLs
@ -379,9 +384,10 @@ Enable this to make all relative URLs relative to content root. Note that this d
**Default value:** "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`).
When using `ref` or `relref` to resolve page links and a link cannot be 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.
### removePathAccents
@ -394,7 +400,6 @@ Removes [non-spacing marks](https://www.compart.com/en/unicode/category/Mn) from
content/post/hügó.md --> https://example.org/post/hugo/
```
### rssLimit
**Default value:** -1 (unlimited)
@ -402,6 +407,7 @@ content/post/hügó.md --> https://example.org/post/hugo/
Maximum number of items in the RSS feed.
### sectionPagesMenu
See ["Section Menu for Lazy Bloggers"](/templates/menu-templates/#section-menu-for-lazy-bloggers).
### security
@ -409,6 +415,7 @@ See ["Section Menu for Lazy Bloggers"](/templates/menu-templates/#section-menu-f
See [Security Policy](/about/security-model/#security-policy)
### sitemap
Default [sitemap configuration](/templates/sitemap-template/#configuration).
### summaryLength
@ -418,9 +425,11 @@ Default [sitemap configuration](/templates/sitemap-template/#configuration).
The length of text in words to show in a [`.Summary`](/content-management/summaries/#automatic-summary-splitting).
### taxonomies
See [Configure Taxonomies](/content-management/taxonomies#configure-taxonomies).
### theme
: See [Module Config](/hugo-modules/configuration/#module-config-imports) for how to import a theme.
### themesDir
@ -437,11 +446,10 @@ Timeout for generating page contents, specified as a [duration](https://pkg.go.d
### timeZone
{{< new-in "0.87.0" >}}
The time zone (or location), e.g. `Europe/Oslo`, used to parse front matter dates without such information and in the [`time` function](/functions/time/). The list of valid values may be system dependent, but should include `UTC`, `Local`, and any location in the [IANA Time Zone database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
### title
Site title.
### titleCaseStyle
@ -451,6 +459,9 @@ Site title.
See [Configure Title Case](#configure-title-case)
### uglyURLs
**Default value:** false
When enabled, creates URL of the form `/filename.html` instead of `/filename/`.
### watch
@ -461,22 +472,20 @@ Watch filesystem for changes and recreate as needed.
{{% note %}}
If you are developing your site on a \*nix machine, here is a handy shortcut for finding a configuration option from the command line:
```
```txt
cd ~/sites/yourhugosite
hugo config | grep emoji
```
which shows output like
```
```txt
enableemoji: true
```
{{% /note %}}
## Configure Build
{{< new-in "0.66.0" >}}
The `build` configuration section contains global build-related configuration options.
{{< code-toggle file="config">}}
@ -490,18 +499,16 @@ noJSConfigInAssets = false
useResourceCacheWhen
: When to use the cached resources in `/resources/_gen` for PostCSS and ToCSS. Valid values are `never`, `always` and `fallback`. The last value means that the cache will be tried if PostCSS/extended version is not available.
writeStats {{< new-in "0.69.0" >}}
writeStats
: When enabled, a file named `hugo_stats.json` will be written to your project root with some aggregated data about the build, e.g. list of HTML entities published to be used to do [CSS pruning](/hugo-pipes/postprocess/#css-purging-with-postcss). If you're only using this for the production build, you should consider placing it below [config/production](/getting-started/configuration/#configuration-directory). It's also worth mentioning that, due to the nature of the partial server builds, new HTML entities will be added when you add or change them while the server is running, but the old values will not be removed until you restart the server or run a regular `hugo` build.
**Note** that the prime use case for this is purging of unused CSS; it is build for speed and there may be false positives (e.g. elements that isn't really a HTML element).
**Note** that the prime use case for this is purging of unused CSS; it is built for speed and there may be false positives (e.g., detection of HTML elements that are not HTML elements).
noJSConfigInAssets {{< new-in "0.78.0" >}}
noJSConfigInAssets
: Turn off writing a `jsconfig.json` into your `/assets` folder with mapping of imports from running [js.Build](https://gohugo.io/hugo-pipes/js). This file is intended to help with intellisense/navigation inside code editors such as [VS Code](https://code.visualstudio.com/). Note that if you do not use `js.Build`, no file will be written.
## Configure Server
{{< new-in "0.67.0" >}}
This is only relevant when running `hugo server`, and it allows to set HTTP headers during development, which allows you to test out your Content Security Policy and similar. The configuration format matches [Netlify's](https://docs.netlify.com/routing/headers/#syntax-for-the-netlify-configuration-file) with slightly more powerful [Glob matching](https://github.com/gobwas/glob):
@ -518,7 +525,7 @@ Referrer-Policy = "strict-origin-when-cross-origin"
Content-Security-Policy = "script-src localhost:1313"
{{< /code-toggle >}}
Since this is is "development only", it may make sense to put it below the `development` environment:
Since this is "development only", it may make sense to put it below the `development` environment:
{{< code-toggle file="config/development/server">}}
@ -533,9 +540,6 @@ Referrer-Policy = "strict-origin-when-cross-origin"
Content-Security-Policy = "script-src localhost:1313"
{{< /code-toggle >}}
{{< new-in "0.72.0" >}}
You can also specify simple redirects rules for the server. The syntax is again similar to Netlify's.
Note that a `status` code of 200 will trigger a [URL rewrite](https://docs.netlify.com/routing/redirects/rewrites-proxies/), which is what you want in SPA situations, e.g:
@ -548,7 +552,20 @@ status = 200
force = false
{{< /code-toggle >}}
{{< new-in "0.76.0" >}} Setting `force=true` will make a redirect even if there is existing content in the path. Note that before Hugo 0.76 `force` was the default behaviour, but this is inline with how Netlify does it.
Setting `force=true` will make a redirect even if there is existing content in the path. Note that before Hugo 0.76 `force` was the default behavior, but this is inline with how Netlify does it.
## 404 Server Error Page
{{< new-in "0.103.0" >}}
Hugo will, by default, render all 404 errors when running `hugo server` with the `404.html` template. Note that if you have already added one or more redirects to your [Server Config](#configure-server), you need to add the 404 redirect explicitly, e.g:
```toml
[[redirects]]
from = "/**"
to = "/404.html"
status = 404
```
## 404 Server Error Page
@ -608,7 +625,7 @@ In addition to the 3 config options already mentioned, configuration key-values
For example, the following command will effectively set a website's title on Unix-like systems:
```
```txt
$ env HUGO_TITLE="Some Title" hugo
```
@ -620,7 +637,7 @@ Names must be prefixed with `HUGO_` and the configuration key must be set in upp
To set config params, prefix the name with `HUGO_PARAMS_`
{{% /note %}}
{{< new-in "0.79.0" >}} If you are using snake_cased variable names, the above will not work, so since Hugo 0.79.0 Hugo determines the delimiter to use by the first character after `HUGO`. This allows you to define environment variables on the form `HUGOxPARAMSxAPI_KEY=abcdefgh`, using any [allowed](https://stackoverflow.com/questions/2821043/allowed-characters-in-linux-environment-variable-names#:~:text=So%20names%20may%20contain%20any,not%20begin%20with%20a%20digit.) delimiter.
If you are using snake_cased variable names, the above will not work. Hugo determines the delimiter to use by the first character after `HUGO`. This allows you to define environment variables on the form `HUGOxPARAMSxAPI_KEY=abcdefgh`, using any [allowed](https://stackoverflow.com/questions/2821043/allowed-characters-in-linux-environment-variable-names#:~:text=So%20names%20may%20contain%20any,not%20begin%20with%20a%20digit.) delimiter.
{{< todo >}}
Test and document setting params via JSON env var.
@ -648,7 +665,6 @@ ignoreFiles = ['^/home/user/project/content/test\.md$']
Dates are important in Hugo, and you can configure how Hugo assigns dates to your content pages. You do this by adding a `frontmatter` section to your `config.toml`.
The default configuration is:
{{< code-toggle file="config" >}}
@ -709,8 +725,6 @@ Hugo v0.20 introduced the ability to render your content to multiple output form
## Configure Minify
{{< new-in "0.68.0" >}}
Default configuration:
{{< code-toggle config="minify" />}}
@ -762,9 +776,9 @@ dir
## Configuration Format Specs
* [TOML Spec][toml]
* [YAML Spec][yaml]
* [JSON Spec][json]
- [TOML Spec][toml]
- [YAML Spec][yaml]
- [JSON Spec][json]
[`.Site.Params`]: /variables/site/
[directory structure]: /getting-started/directory-structure

13
docs/content/en/getting-started/directory-structure.md
View file

@ -4,7 +4,6 @@ linktitle: Directory Structure
description: Hugo's CLI scaffolds a project directory structure and then takes that single directory and uses it as the input to create a complete website.
date: 2017-01-02
publishdate: 2017-02-01
lastmod: 2017-03-09
categories: [getting started,fundamentals]
keywords: [source, organization, directories]
menu:
@ -13,7 +12,6 @@ menu:
weight: 50
weight: 50
sections_weight: 50
draft: false
aliases: [/overview/source-directory/]
toc: true
---
@ -22,9 +20,9 @@ toc: true
{{< youtube sB0HLHjgQ7E >}}
Running the `hugo new site` generator from the command line will create a directory structure with the following elements:
Running the `hugo new site` generator from the command-line will create a directory structure with the following elements:
```
```txt
.
├── archetypes
├── config.toml
@ -36,14 +34,13 @@ Running the `hugo new site` generator from the command line will create a direct
└── themes
```
## Directory Structure Explained
The following is a high-level overview of each of the directories with links to each of their respective sections within the Hugo docs.
[`archetypes`](/content-management/archetypes/)
: You can create new content files in Hugo using the `hugo new` command.
By default, Hugo will create new content files with at least `date`, `title` (inferred from the file name), and `draft = true`. This saves time and promotes consistency for sites using multiple content types. You can create your own [archetypes][] with custom preconfigured front matter fields as well.
By default, Hugo will create new content files with at least `date`, `title` (inferred from the filename), and `draft = true`. This saves time and promotes consistency for sites using multiple content types. You can create your own [archetypes][] with custom preconfigured front matter fields as well.
[`assets`][]
: Stores all the files which need be processed by [Hugo Pipes](/hugo-pipes/). Only the files whose `.Permalink` or `.RelPermalink` are used will be published to the `public` directory. Note: assets directory is not created by default.
@ -73,7 +70,7 @@ From **Hugo 0.31** you can have multiple static directories.
{{% /note %}}
[`resources`][]
: Caches some files to speed up generation. Can be also used by template authors to distribute built SASS files, so you don't have to have the preprocessor installed. Note: resources directory is not created by default.
: Caches some files to speed up generation. Can be also used by template authors to distribute built Sass files, so you don't have to have the preprocessor installed. Note: resources directory is not created by default.
[archetypes]: /content-management/archetypes/
[`assets`]: /hugo-pipes/introduction#asset-directory/
@ -89,7 +86,7 @@ From **Hugo 0.31** you can have multiple static directories.
[lists]: /templates/list/
[pagevars]: /variables/page/
[partials]: /templates/partials/
[searchconsole]: https://support.google.com/analytics/answer/1142414?hl=en
[searchconsole]: https://support.google.com/webmasters/answer/9008080#zippy=%2Chtml-file-upload
[singles]: /templates/single-page-templates/
[starters]: /tools/starter-kits/
[taxonomies]: /content-management/taxonomies/

4
docs/content/en/getting-started/external-learning-resources/index.md
View file

@ -38,6 +38,6 @@ Hugo in Action is a step-by-step guide to using Hugo to create static websites.
## Video tutorials
### Video Playlist by Mike Dane
* Mike Dane explains the various features of Hugo via dedicated tutorials on [YouTube](https://www.youtube.com/watch?list=PLLAZ4kZ9dFpOnyRlyS-liKL5ReHDcj4G3&v=qtIqKaDlqXo).
Mike Dane explains the various features of Hugo via dedicated tutorials on [YouTube](https://www.youtube.com/watch?list=PLLAZ4kZ9dFpOnyRlyS-liKL5ReHDcj4G3&v=qtIqKaDlqXo).
* [Introduction to building your first Hugo site](https://cloudcannon.com/community/learn/hugo-beginner-tutorial/) by Mike Neumegen.

586
docs/content/en/getting-started/installing.md
View file

@ -1,586 +0,0 @@
---
title: Install Hugo
linktitle: Install Hugo
description: Install Hugo on macOS, Windows, Linux, OpenBSD, FreeBSD, and on any machine where the Go compiler tool chain can run.
date: 2016-11-01
publishdate: 2016-11-01
lastmod: 2018-01-02
categories: [getting started,fundamentals]
authors: ["Michael Henderson"]
keywords: [install,pc,windows,linux,macos,binary,tarball]
menu:
docs:
parent: "getting-started"
weight: 30
weight: 30
sections_weight: 30
draft: false
aliases: [/tutorials/installing-on-windows/,/tutorials/installing-on-mac/,/overview/installing/,/getting-started/install,/install/]
toc: true
---
{{% note %}}
There is lots of talk about "Hugo being written in Go", but you don't need to install Go to enjoy Hugo. Just grab a precompiled binary!
{{% /note %}}
Hugo is written in [Go](https://golang.org/) with support for multiple platforms. The latest release can be found at [Hugo Releases][releases].
Hugo currently provides pre-built binaries for the following:
* macOS (Darwin) for x64, i386, and ARM architectures
* Windows
* Linux
* OpenBSD
* FreeBSD
Hugo may also be compiled from source wherever the Go toolchain can run; e.g., on other operating systems such as DragonFly BSD, OpenBSD, Plan&nbsp;9, Solaris, and others. See <https://golang.org/doc/install/source> for the full set of supported combinations of target operating systems and compilation architectures.
## Quick Install
### Binary (Cross-platform)
Download the appropriate version for your platform from [Hugo Releases][releases]. Once downloaded, the binary can be run from anywhere. You don't need to install it into a global location. This works well for shared hosts and other systems where you don't have a privileged account.
Ideally, you should install it somewhere in your `PATH` for easy use. `/usr/local/bin` is the most probable location.
### Docker
We currently do not offer official Hugo images for Docker, but we do recommend these up to date distributions: https://hub.docker.com/r/klakegg/hugo/
### Homebrew (macOS)
If you are on macOS and using [Homebrew][brew], you can install Hugo with the following one-liner:
{{< code file="install-with-homebrew.sh" >}}
brew install hugo
{{< /code >}}
For more detailed explanations, read the installation guides that follow for installing on macOS and Windows.
### MacPorts (macOS)
If you are on macOS and using [MacPorts][macports], you can install Hugo with the following one-liner:
{{< code file="install-with-macports.sh" >}}
port install hugo
{{< /code >}}
### Homebrew (Linux)
If you are using [Homebrew][linuxbrew] on Linux, you can install Hugo with the following one-liner:
{{< code file="install-with-linuxbrew.sh" >}}
brew install hugo
{{< /code >}}
Installation guides for Homebrew on Linux are available on their [website][linuxbrew].
### Chocolatey (Windows)
If you are on a Windows machine and use [Chocolatey][] for package management, you can install Hugo with the following one-liner:
{{< code file="install-with-chocolatey.ps1" >}}
choco install hugo -confirm
{{< /code >}}
Or if you need the “extended” Sass/SCSS version:
{{< code file="install-extended-with-chocolatey.ps1" >}}
choco install hugo-extended -confirm
{{< /code >}}
### Scoop (Windows)
If you are on a Windows machine and use [Scoop][] for package management, you can install Hugo with the following one-liner:
```bash
scoop install hugo
```
Or install the extended version with:
```bash
scoop install hugo-extended
```
### Source
#### Prerequisite Tools
* [Git][installgit]
* [GCC][] (For Windows users only)
* [Go (at least Go 1.11)](https://golang.org/dl/)
#### Fetch from GitHub
Since Hugo 0.48, Hugo uses the Go Modules support built into Go 1.11 to build. The easiest way to get started is to clone Hugo in a directory outside of the GOPATH, as in the following example:
{{< code file="from-gh.sh" >}}
mkdir $HOME/src
cd $HOME/src
git clone https://github.com/gohugoio/hugo.git
cd hugo
go install --tags extended
{{< /code >}}
Remove `--tags extended` if you do not want/need Sass/SCSS support.
{{% note %}}
##### For installation on Windows
* Substitute the `$HOME` environment variable above with `%USERPROFILE%`.
* If you install `--tags extended` version, you may encounter this error `"gcc": executable file not found in %PATH%`
* Please make sure you have installed `gcc` command and add it to `%PATH%`.
* "MinGW" is recommended, it has been tested and built successfully
{{% /note %}}
## macOS
### Assumptions
1. You know how to open the macOS terminal.
2. You're running a modern 64-bit Mac.
3. You will use `~/Sites` as the starting point for your site. (`~/Sites` is used for example purposes. If you are familiar enough with the command line and file system, you should have no issues following along with the instructions.)
### Pick Your Method
There are three ways to install Hugo on your Mac
1. A package manager, like [Homebrew][brew] (`brew`) or [MacPorts][macports] (`port`)
2. Distribution (i.e., tarball)
3. Building from Source
There is no "best" way to install Hugo on your Mac. You should use the method that works best for your use case.
#### Pros and Cons
There are pros and cons to each of the aforementioned methods:
1. **Package Manager.** Using a package manager is the simplest method and will require the least amount of work to maintain. The drawbacks aren't severe. The default package will be for the most recent release, so it will not have bug fixes until the next release (i.e., unless you install it with the `--HEAD` option in Homebrew). Releases may lag a few days behind because it has to be coordinated with another team. Nevertheless, this is the recommended installation method if you want to work from a stable, widely used source. Package managers work well and they are easy to update.
2. **Tarball.** Downloading and installing from the tarball is also easy, although it requires a few more command line skills than does Homebrew. Updates are easy as well: you just repeat the process with the new binary. This gives you the flexibility to have multiple versions on your computer. If you don't want to use `brew`, then the tarball/binary is a good choice.
3. **Building from Source.** Building from source is the most work. The advantage of building from source is that you don't have to wait for a release to add features or bug fixes. The disadvantage is that you need to spend more time managing the setup, which is manageable but requires more time than the preceding two options.
{{% note %}}
Since building from source is appealing to more seasoned command line users, this guide will focus more on installing Hugo via Homebrew and Tarball.
{{% /note %}}
### Install Hugo with Brew
{{< youtube WvhCGlLcrF8 >}}
#### Step 1: Install `brew` if you haven't already
Go to the `brew` website, <https://brew.sh/>, and follow the directions there. The most important step is the installation from the command line:
{{< code file="install-brew.sh" >}}
ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
{{< /code >}}
#### Step 2: Run the `brew` Command to Install `hugo`
Installing Hugo using `brew` is as easy as the following:
{{< code file="install-brew.sh" >}}
brew install hugo
{{< /code >}}
If Homebrew is working properly, you should see something similar to the following:
```
==> Downloading https://homebrew.bintray.com/bottles/hugo-0.21.sierra.bottle.tar.gz
######################################################################### 100.0%
==> Pouring hugo-0.21.sierra.bottle.tar.gz
🍺 /usr/local/Cellar/hugo/0.21: 32 files, 17.4MB
```
{{% note "Installing the Latest Hugo with Brew" %}}
Replace `brew install hugo` with `brew install hugo --HEAD` if you want the absolute latest in-development version.
{{% /note %}}
`brew` should have updated your path to include Hugo. You can confirm by opening a new terminal window and running a few commands:
```
$ # show the location of the hugo executable
which hugo
/usr/local/bin/hugo
# show the installed version
ls -l $( which hugo )
lrwxr-xr-x 1 mdhender admin 30 Mar 28 22:19 /usr/local/bin/hugo -> ../Cellar/hugo/0.13_1/bin/hugo
# verify that hugo runs correctly
hugo version
Hugo Static Site Generator v0.13 BuildDate: 2015-03-09T21:34:47-05:00
```
### Install Hugo from Tarball
#### Step 1: Decide on the location
When installing from the tarball, you have to decide if you're going to install the binary in `/usr/local/bin` or in your home directory. There are three camps on this:
1. Install it in `/usr/local/bin` so that all the users on your system have access to it. This is a good idea because it's a fairly standard place for executables. The downside is that you may need elevated privileges to put software into that location. Also, if there are multiple users on your system, they will all run the same version. Sometimes this can be an issue if you want to try out a new release.
2. Install it in `~/bin` so that only you can execute it. This is a good idea because it's easy to do, easy to maintain, and doesn't require elevated privileges. The downside is that only you can run Hugo. If there are other users on your site, they have to maintain their own copies. That can lead to people running different versions. Of course, this does make it easier for you to experiment with different releases.
3. Install it in your `Sites` directory. This is not a bad idea if you have only one site that you're building. It keeps every thing in a single place. If you want to try out new releases, you can make a copy of the entire site and update the Hugo executable.
All three locations will work for you. In the interest of brevity, this guide focuses on option #2.
#### Step 2: Download the Tarball
1. Open <https://github.com/gohugoio/hugo/releases> in your browser.
2. Find the current release by scrolling down and looking for the green tag that reads "Latest Release."
3. Download the current tarball for the Mac. The name will be something like `hugo_X.Y_osx-64bit.tgz`, where `X.YY` is the release number.
4. By default, the tarball will be saved to your `~/Downloads` directory. If you choose to use a different location, you'll need to change that in the following steps.
#### Step 3: Confirm your download
Verify that the tarball wasn't corrupted during the download:
```
tar tvf ~/Downloads/hugo_X.Y_osx-64bit.tgz
-rwxrwxrwx 0 0 0 0 Feb 22 04:02 hugo_X.Y_osx-64bit/hugo_X.Y_osx-64bit.tgz
-rwxrwxrwx 0 0 0 0 Feb 22 03:24 hugo_X.Y_osx-64bit/README.md
-rwxrwxrwx 0 0 0 0 Jan 30 18:48 hugo_X.Y_osx-64bit/LICENSE.md
```
The `.md` files are documentation for Hugo. The other file is the executable.
#### Step 4: Install Into Your `bin` Directory
```
# create the directory if needed
mkdir -p ~/bin
# make it the working directory
cd ~/bin
# extract the tarball
tar -xvzf ~/Downloads/hugo_X.Y_osx-64bit.tgz
Archive: hugo_X.Y_osx-64bit.tgz
x ./
x ./hugo
x ./LICENSE.md
x ./README.md
# verify that it runs
./hugo version
Hugo Static Site Generator v0.13 BuildDate: 2015-02-22T04:02:30-06:00
```
You may need to add your bin directory to your `PATH` environment variable. The `which` command will check for us. If it can find `hugo`, it will print the full path to it. Otherwise, it will not print anything.
```
# check if hugo is in the path
which hugo
/Users/USERNAME/bin/hugo
```
If `hugo` is not in your `PATH`:
1. Determine your default shell (zsh or bash).
```
echo $SHELL
```
2. Edit your profile.
If your default shell is zsh:
```
nano ~/.zprofile
```
If your default shell is bash:
```
nano ~/.bash_profile
```
3. Insert a line to add `$HOME/bin` to your existing `PATH`.
```
export PATH=$PATH:$HOME/bin
```
4. Save the file by pressing Control-X, then Y.
5. Close the terminal and open a new terminal to pick up the changes to your profile. Verify the change by running the `which hugo` command again.
You've successfully installed Hugo.
### Build from Source on Mac
If you want to compile Hugo yourself, you'll need to install Go (aka Golang). You can [install Go directly from the Go website](https://golang.org/dl/) or via Homebrew using the following command:
```
brew install go
```
#### Step 1: Get the Source
If you want to compile a specific version of Hugo, go to <https://github.com/gohugoio/hugo/releases> and download the source code for the version of your choice. If you want to compile Hugo with all the latest changes (which might include bugs), clone the Hugo repository:
```
git clone https://github.com/gohugoio/hugo
```
{{% warning "Sometimes \"Latest\" = \"Bugs\""%}}
Cloning the Hugo repository directly means taking the good with the bad. By using the bleeding-edge version of Hugo, you make your development susceptible to the latest features, as well as the latest bugs. Your feedback is appreciated. If you find a bug in the latest release, [please create an issue on GitHub](https://github.com/gohugoio/hugo/issues/new).
{{% /warning %}}
#### Step 2: Compiling
Make the directory containing the source your working directory and then fetch Hugo's dependencies:
```
mkdir -p src/github.com/gohugoio
ln -sf $(pwd) src/github.com/gohugoio/hugo
go get
```
This will fetch the absolute latest version of the dependencies. If Hugo fails to build, it may be the result of a dependency's author introducing a breaking change.
Once you have properly configured your directory, you can compile Hugo using the following command:
```
go build -o hugo main.go
```
Then place the `hugo` executable somewhere in your `$PATH`. You're now ready to start using Hugo.
## Windows
The following aims to be a complete guide to installing Hugo on your Windows PC.
{{< youtube G7umPCU-8xc >}}
### Assumptions for Windows
1. You will use `C:\Hugo\Sites` as the starting point for your new project.
2. You will use `C:\Hugo\bin` to store executable files.
### Set up Your Directories
You'll need a place to store the Hugo executable, your [content][], and the generated Hugo website:
1. Open Windows Explorer.
2. Create a new folder: `C:\Hugo`, assuming you want Hugo on your C drive, although this can go anywhere
3. Create a subfolder in the Hugo folder: `C:\Hugo\bin`
4. Create another subfolder in Hugo: `C:\Hugo\Sites`
### Technical Users
1. Download the latest zipped Hugo executable from [Hugo Releases][releases].
2. Extract all contents to your `..\Hugo\bin` folder.
3. Open Windows Command Line (cmd, "DOS") to add the `hugo.exe` executable to your PATH
* do `set PATH=%PATH%;C:\Hugo\bin` to have hugo in PATH for the currently opened cmd box
* do `setx PATH "%PATH%;C:\Hugo\bin"` to have hugo in PATH for every newly opened cmd box
* note: "setx", not "set", plus syntax 'key "val"', not 'key=val'
> You may also use "Git CMD" from the [Git for Windows package](https://gitforwindows.org/) for the native Windows commands [set](https://ss64.com/nt/set.html) and [setx](https://ss64.com/nt/setx.html), but not "Git Bash", PowerShell, or any other "CLI" with different commands
### Less-technical Users
1. Go to the [Hugo Releases][releases] page.
2. The latest release is announced on top. Scroll to the bottom of the release announcement to see the downloads. They're all ZIP files.
3. Find the Windows files near the bottom (they're in alphabetical order, so Windows is last) – download either the 32-bit or 64-bit file depending on whether you have 32-bit or 64-bit Windows. (If you don't know, [see here](https://esupport.trendmicro.com/en-us/home/pages/technical-support/1038680.aspx).)
4. Move the ZIP file into your `C:\Hugo\bin` folder.
5. Double-click on the ZIP file and extract its contents. Be sure to extract the contents into the same `C:\Hugo\bin` folder – Windows will do this by default unless you tell it to extract somewhere else.
6. You should now have three new files: The hugo executable (`hugo.exe`), `LICENSE`, and `README.md`.
Now you need to add Hugo to your Windows PATH settings:
#### For Windows 10 Users:
* Right click on the **Start** button.
* Click on **System**.
* Click on **Advanced System Settings** on the right.
* Click on the **Environment Variables...** button on the bottom.
* In the User variables section, select the row labeled "Path" and click the **Edit...** button.
* Click the **Browse...** button and select the directory to which `hugo.exe` was extracted, which is `C:\Hugo\bin` if you went by the instructions above. *The path entry should be the folder where Hugo lives and not the binary itself.*
* Click OK at every window to exit.
#### For Windows 7 and 8.x users:
Windows 7 and 8.1 do not include the easy path editor included in Windows 10, so non-technical users on those platforms are advised to install a free third-party path editor like [Windows Environment Variables Editor].
### Verify the Executable
Run a few commands to verify that the executable is ready to run, and then build a sample site to get started.
#### 1. Open a Command Prompt
At the prompt, type `hugo help` and press the <kbd>Enter</kbd> key. You should see output that starts with:
```
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/.
```
If you do, then the installation is complete. If you don't, double-check the path that you placed the `hugo.exe` file in and that you typed that path correctly when you added it to your `PATH` variable. If you're still not getting the output, search the [Hugo discussion forum][forum] to see if others have already figured out our problem. If not, add a note---in the "Support" category---and be sure to include your command and the output.
At the prompt, change your directory to the `Sites` directory.
```
C:\Program Files> cd C:\Hugo\Sites
C:\Hugo\Sites>
```
#### 2. Run the Command
Run the command to generate a new site. I'm using `example.com` as the name of the site.
```
C:\Hugo\Sites> hugo new site example.com
```
You should now have a directory at `C:\Hugo\Sites\example.com`. Change into that directory and list the contents. You should get output similar to the following:
```
C:\Hugo\Sites> cd example.com
C:\Hugo\Sites\example.com> dir
Directory of C:\hugo\sites\example.com
04/13/2015 10:44 PM <DIR> .
04/13/2015 10:44 PM <DIR> ..
04/13/2015 10:44 PM <DIR> archetypes
04/13/2015 10:44 PM 83 config.toml
04/13/2015 10:44 PM <DIR> content
04/13/2015 10:44 PM <DIR> data
04/13/2015 10:44 PM <DIR> layouts
04/13/2015 10:44 PM <DIR> static
1 File(s) 83 bytes
7 Dir(s) 6,273,331,200 bytes free
```
### Troubleshoot Windows Installation
[@dhersam][] has created a nice video on common issues:
{{< youtube c8fJIRNChmU >}}
## Linux
### Snap Package
In any of the [Linux distributions that support snaps][snaps], you may install the "extended" Sass/SCSS version with this command:
```
snap install hugo --channel=extended
```
To install the non-extended version without Sass/SCSS support:
```
snap install hugo
```
To switch between the two, use either `snap refresh hugo --channel=extended` or `snap refresh hugo --channel=stable`.
{{% note %}}
Hugo installed via Snap can write only inside the user’s `$HOME` directory---and gvfs-mounted directories owned by the user---because of Snaps’ confinement and security model. More information is also available [in this related GitHub issue](https://github.com/gohugoio/hugo/issues/3143).
{{% /note %}}
### Debian and Ubuntu
[@anthonyfok](https://github.com/anthonyfok) and friends in the [Debian Go Packaging Team](https://go-team.pages.debian.net/) maintains an official hugo [Debian package](https://packages.debian.org/hugo) which is shared with [Ubuntu](https://packages.ubuntu.com/hugo) and is installable via `apt-get`:
```
sudo apt-get install hugo
```
What this installs depends on your Debian/Ubuntu version. On Ubuntu bionic (18.04), this installs the non-extended version without Sass/SCSS support. On Ubuntu disco (19.04), this installs the extended version with Sass/SCSS support.
This option is not recommended because the Hugo in Linux package managers for Debian and Ubuntu is usually a few versions behind as described [here](https://github.com/gcushen/hugo-academic/issues/703)
### Arch Linux
You can also install Hugo from the Arch Linux [community](https://www.archlinux.org/packages/community/x86_64/hugo/) repository. Applies also to derivatives such as Manjaro.
```
sudo pacman -S hugo
```
### Fedora, Red Hat and CentOS
Fedora maintains an [official package for Hugo](https://packages.fedoraproject.org/pkgs/hugo/hugo) which may be installed with:
```
sudo dnf install hugo
```
For the latest version, the Hugo package maintained by [@daftaupe](https://github.com/daftaupe) at Fedora Copr is recommended:
* <https://copr.fedorainfracloud.org/coprs/daftaupe/hugo/>
See the [related discussion in the Hugo forums][redhatforum].
### openSUSE Tumbleweed
openSUSE maintains an [official package](https://software.opensuse.org/package/hugo) for the Tumbleweed rolling release distribution, it may be installed with:
````
sudo zypper install hugo
````
### Solus
Solus includes Hugo in its package repository, it may be installed with:
```
sudo eopkg install hugo
```
## OpenBSD
OpenBSD provides a package for Hugo via `pkg_add`:
```
doas pkg_add hugo
```
## Upgrade Hugo
Upgrading Hugo is as easy as downloading and replacing the executable you’ve placed in your `PATH` or run `brew upgrade hugo` if using Homebrew.
## Next Steps
Now that you've installed Hugo, read the [Quick Start guide][quickstart] and explore the rest of the documentation. If you have questions, ask the Hugo community directly by visiting the [Hugo Discussion Forum][forum].
[brew]: https://brew.sh/
[macports]: https://www.macports.org/
[Chocolatey]: https://chocolatey.org/
[content]: /content-management/
[@dhersam]: https://github.com/dhersam
[forum]: https://discourse.gohugo.io
[mage]: https://github.com/magefile/mage
[dep]: https://github.com/golang/dep
[highlight shortcode]: /content-management/shortcodes/#highlight
[installgit]: https://git-scm.com/
[GCC]: http://www.mingw.org/
[installgo]: https://golang.org/dl/
[linuxbrew]: https://docs.brew.sh/Homebrew-on-Linux
[quickstart]: /getting-started/quick-start/
[redhatforum]: https://discourse.gohugo.io/t/solved-fedora-copr-repository-out-of-service/2491
[releases]: https://github.com/gohugoio/hugo/releases
[Scoop]: https://scoop.sh/
[snaps]: https://snapcraft.io/docs/installing-snapd
[windowsarch]: https://esupport.trendmicro.com/en-us/home/pages/technical-support/1038680.aspx
[Windows Environment Variables Editor]: https://eveditor.com/

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