mirror of
https://github.com/gohugoio/hugo.git
synced 2025-04-26 21:51:02 +03:00
Merge commit '5be51ac3db'
This commit is contained in:
Bjørn Erik Pedersen
commit
653f1c1d46
987 changed files with 12379 additions and 14083 deletions
|
|
@ -60,6 +60,7 @@
|
|||
"redirections",
|
||||
"subexpression",
|
||||
"suppressible",
|
||||
"synchronisation",
|
||||
"templating",
|
||||
"transpile",
|
||||
"unmarshal",
|
||||
|
|
@ -161,7 +162,7 @@
|
|||
"# ----------------------------------------------------------------------",
|
||||
"achristie",
|
||||
"ccpa",
|
||||
"crpa",
|
||||
"cpra",
|
||||
"ddmaurier",
|
||||
"dring",
|
||||
"fleqn",
|
||||
|
|
@ -171,6 +172,8 @@
|
|||
"jsmith",
|
||||
"leqno",
|
||||
"milli",
|
||||
"monokai",
|
||||
"mysanityprojectid",
|
||||
"rgba",
|
||||
"rsmith",
|
||||
"tdewolff",
|
||||
|
|
|
|||
3
docs/.gitignore
vendored
3
docs/.gitignore
vendored
|
|
@ -4,10 +4,9 @@
|
|||
/.vscode
|
||||
/dist
|
||||
/public
|
||||
/resources
|
||||
hugo_stats.json
|
||||
node_modules/
|
||||
nohup.out
|
||||
package-lock.json
|
||||
public/
|
||||
resources/
|
||||
trace.out
|
||||
|
|
@ -22,5 +22,6 @@ MD041: false
|
|||
MD046: false
|
||||
MD049: false
|
||||
MD050: false
|
||||
MD051: false
|
||||
MD053: false
|
||||
MD055: false
|
||||
|
|
|
|||
18
docs/.prettierignore
Normal file
18
docs/.prettierignore
Normal file
|
|
@ -0,0 +1,18 @@
|
|||
# Ignore all SVG icons.
|
||||
**/icons.html
|
||||
|
||||
# These are whitespace sensitive.
|
||||
layouts/_default/_markup/render-code*
|
||||
layouts/_default/_markup/render-table*
|
||||
layouts/shortcodes/glossary-term.html
|
||||
layouts/shortcodes/glossary.html
|
||||
layouts/shortcodes/highlighting-styles.html
|
||||
layouts/shortcodes/list-pages-in-section.html
|
||||
layouts/shortcodes/quick-reference.html
|
||||
|
||||
# No root node.
|
||||
layouts/partials/layouts/head/head.html
|
||||
|
||||
# Auto generated.
|
||||
assets/css/components/chroma*.css
|
||||
assets/jsconfig.json
|
||||
24
docs/.prettierrc
Normal file
24
docs/.prettierrc
Normal file
|
|
@ -0,0 +1,24 @@
|
|||
{
|
||||
"plugins": [
|
||||
"prettier-plugin-go-template",
|
||||
"@awmottaz/prettier-plugin-void-html"
|
||||
],
|
||||
"overrides": [
|
||||
{
|
||||
"files": ["*.html"],
|
||||
"options": {
|
||||
"parser": "go-template",
|
||||
"goTemplateBracketSpacing": true,
|
||||
"bracketSameLine": true
|
||||
}
|
||||
},
|
||||
{
|
||||
"files": ["*.js", "*.ts"],
|
||||
"options": {
|
||||
"useTabs": true,
|
||||
"printWidth": 120,
|
||||
"singleQuote": true
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
|
|
@ -19,7 +19,7 @@ Please see the [contributing] section for guidelines, examples, and process.
|
|||
|
||||
# Install
|
||||
|
||||
```bash
|
||||
```sh
|
||||
npm i
|
||||
hugo server
|
||||
```
|
||||
|
|
|
|||
6
docs/archetypes/default.md
Normal file
6
docs/archetypes/default.md
Normal file
|
|
@ -0,0 +1,6 @@
|
|||
---
|
||||
title: {{ replace .File.ContentBaseName "-" " " | strings.FirstUpper }}
|
||||
description:
|
||||
categories: []
|
||||
keywords: []
|
||||
---
|
||||
|
|
@ -3,9 +3,9 @@ title: {{ replace .File.ContentBaseName "-" " " | title }}
|
|||
description:
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
aliases: []
|
||||
related: []
|
||||
returnType:
|
||||
signatures: []
|
||||
params:
|
||||
functions_and_methods:
|
||||
aliases: []
|
||||
returnType:
|
||||
signatures: []
|
||||
---
|
||||
|
|
|
|||
|
|
@ -1,6 +1,7 @@
|
|||
---
|
||||
title: {{ replace .File.ContentBaseName "-" " " }}
|
||||
reference:
|
||||
params:
|
||||
reference:
|
||||
---
|
||||
|
||||
<!--
|
||||
|
|
|
|||
|
|
@ -3,8 +3,8 @@ title: {{ replace .File.ContentBaseName "-" " " | title }}
|
|||
description:
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related: []
|
||||
returnType:
|
||||
signatures: []
|
||||
params:
|
||||
functions_and_methods:
|
||||
returnType:
|
||||
signatures: []
|
||||
---
|
||||
|
|
|
|||
7
docs/archetypes/news.md
Normal file
7
docs/archetypes/news.md
Normal file
|
|
@ -0,0 +1,7 @@
|
|||
---
|
||||
title: {{ replace .File.ContentBaseName "-" " " | strings.FirstUpper }}
|
||||
description:
|
||||
categories: []
|
||||
keywords: []
|
||||
publishDate: {{ .Date }}
|
||||
---
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
---
|
||||
title: {{ replace .File.ContentBaseName "-" " " | title }}
|
||||
description:
|
||||
date: {{ .Date }}
|
||||
---
|
||||
|
|
@ -1,7 +0,0 @@
|
|||
|
||||
Add some **general info** about {{ replace .Name "-" " " | title }} here.
|
||||
|
||||
The site is built by:
|
||||
|
||||
* [Person 1](https://example.org)
|
||||
* [Person 1](https://example.org)
|
||||
|
|
@ -1,36 +0,0 @@
|
|||
---
|
||||
|
||||
title: {{ replace .File.ContentBaseName "-" " " | title }}
|
||||
date: {{ now.Format "2006-01-02" }}
|
||||
|
||||
description: A short description of this page.
|
||||
|
||||
# The URL to the site on the internet.
|
||||
siteURL: https://gohugo.io/
|
||||
|
||||
# Link to the site's Hugo source code if public and you can/want to share.
|
||||
# Remove or leave blank if not needed/wanted.
|
||||
siteSource: https://github.com/gohugoio/hugoDocs
|
||||
|
||||
# Add credit to the article author. Leave blank or remove if not needed/wanted.
|
||||
byline: "[bep](https://github.com/bep), Hugo Lead"
|
||||
|
||||
---
|
||||
|
||||
To complete this showcase:
|
||||
|
||||
1. Write the story about your site in this file.
|
||||
2. Add a summary to the `bio.md` file in this directory.
|
||||
3. Replace the `featured-template.png` with a screenshot of your site. You can rename it, but it must contain the word `featured`.
|
||||
4. Create a new pull request in https://github.com/gohugoio/hugoDocs/pulls
|
||||
|
||||
The content of this bundle explained:
|
||||
|
||||
index.md
|
||||
: The main content file. Fill in required front matter metadata and write your story. I does not have to be a novel. It can even be self-promotional, but it should include Hugo in some form.
|
||||
|
||||
bio.md
|
||||
: A short summary of the website. Site credits (who built it) fits nicely here.
|
||||
|
||||
featured.png
|
||||
: A reasonably sized screenshot of your website. It can be named anything, but the name must start with "featured". The sample image is `1500x750` (2:1 aspect ratio).
|
||||
|
|
@ -1,4 +1,4 @@
|
|||
/* The ordeer of these does not matter. */
|
||||
/* The order of these does not matter. */
|
||||
@import "./content.css";
|
||||
@import "./fonts.css";
|
||||
@import "./helpers.css";
|
||||
|
|
|
|||
|
|
@ -5,7 +5,7 @@
|
|||
/* CodeLine */ .dark .chroma .cl { }
|
||||
/* LineTableTD */ .dark .chroma .lntd { vertical-align: top; padding: 0; margin: 0; border: 0; }
|
||||
/* LineTable */ .dark .chroma .lntable { border-spacing: 0; padding: 0; margin: 0; border: 0; }
|
||||
/* LineHighlight */ .dark .chroma .hl { background-color: #ffffcc }
|
||||
/* LineHighlight */ .dark .chroma .hl { background-color: rgb(0,19,28) }
|
||||
/* LineNumbersTable */ .dark .chroma .lnt { white-space: pre; user-select: none; margin-right: 0.4em; padding: 0 0.4em 0 0.4em;color: #7f7f7f }
|
||||
/* LineNumbers */ .dark .chroma .ln { white-space: pre; user-select: none; margin-right: 0.4em; padding: 0 0.4em 0 0.4em;color: #7f7f7f }
|
||||
/* Line */ .dark .chroma .line { display: flex; }
|
||||
|
|
|
|||
|
|
@ -12,31 +12,32 @@
|
|||
}
|
||||
|
||||
.highlight code {
|
||||
@apply text-sm;
|
||||
@apply text-sm/6;
|
||||
}
|
||||
|
||||
.content {
|
||||
@apply prose prose-sm sm:prose-base prose-stone max-w-none dark:prose-invert dark:text-slate-200;
|
||||
/* headings */
|
||||
@apply prose-h4:font-bold prose-h5:font-bold prose-h6:font-bold;
|
||||
@apply prose-headings:font-semibold;
|
||||
/* lead */
|
||||
@apply prose-lead:text-slate-500 prose-lead:text-xl prose-lead:mt-2 sm:prose-lead:mt-4 prose-lead:leading-relaxed dark:prose-lead:text-slate-400;
|
||||
/* links */
|
||||
@apply prose-a:text-primary prose-a:hover:text-primary/70 prose-a:underline;
|
||||
@apply prose-a:prose-code:underline prose-a:prose-code:hover:text-primary/70 prose-a:prose-code:hover:underline;
|
||||
@apply prose-a:text-primary dark:prose-a:text-blue-500 prose-a:hover:text-blue-500 dark:prose-a:hover:text-blue-400 prose-a:underline;
|
||||
@apply prose-a:prose-code:underline prose-a:prose-code:hover:text-blue-500 prose-a:prose-code:hover:underline;
|
||||
/* pre */
|
||||
@apply prose-pre:text-gray-800 prose-pre:border-1 prose-pre:border-gray-100 prose-pre:bg-light dark:prose-pre:bg-dark dark:prose-pre:ring-1 dark:prose-pre:ring-slate-300/10;
|
||||
/* code */
|
||||
@apply prose-code:px-0.5 prose-code:text-gray-500 prose-code:dark:text-gray-300 border-none;
|
||||
@apply prose-code:before:hidden prose-code:after:hidden prose-code:font-mono;
|
||||
@apply prose-table:prose-th:prose-code:text-white;
|
||||
/* tables */
|
||||
@apply prose-table:border-2 prose-table:border-gray-100 prose-table:dark:border-gray-800 prose-table:relative prose-table:overflow-scroll prose-table:prose-th:font-bold prose-table:prose-th:bg-blue-500 dark:prose-table:prose-th:bg-blue-500/50 prose-table:prose-th:p-2 prose-table:prose-td:p-2 prose-table:prose-th:text-white;
|
||||
@apply prose-table:w-auto prose-table:border-2 prose-table:border-gray-100 prose-table:dark:border-gray-800 prose-table:prose-th:font-bold prose-table:prose-th:bg-blue-500 dark:prose-table:prose-th:bg-blue-500/50 prose-table:prose-th:p-2 prose-table:prose-td:p-2 prose-table:prose-th:text-white;
|
||||
/* hr */
|
||||
@apply dark:prose-hr:border-slate-800;
|
||||
|
||||
h6 + * {
|
||||
@apply mt-2;
|
||||
}
|
||||
/* ol */
|
||||
@apply prose-ol:marker:prose dark:prose-ol:marker:text-gray-300;
|
||||
/* ul */
|
||||
@apply prose-ul:marker:text-gray-500 dark:prose-ul:marker:text-gray-300;
|
||||
}
|
||||
|
||||
/* This will not match highlighting inside e.g. the code-toggle shortcode. */
|
||||
|
|
|
|||
|
|
@ -16,7 +16,5 @@
|
|||
|
||||
/* Turbo styles */
|
||||
.turbo-progress-bar {
|
||||
@apply bg-blue-500;
|
||||
opacity: 0.35;
|
||||
height: 3px;
|
||||
visibility: hidden;
|
||||
}
|
||||
|
|
|
|||
|
|
@ -76,8 +76,9 @@
|
|||
--color-green-950: #051410;
|
||||
|
||||
/* Fonts. */
|
||||
--font-sans: "Mulish", ui-sans-serif, system-ui, sans-serif,
|
||||
"Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";
|
||||
--font-sans:
|
||||
"Mulish", ui-sans-serif, system-ui, sans-serif, "Apple Color Emoji",
|
||||
"Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";
|
||||
}
|
||||
|
||||
html {
|
||||
|
|
@ -121,3 +122,10 @@ body {
|
|||
.algolia-docsearch-suggestion--highlight {
|
||||
color: var(--color-primary);
|
||||
}
|
||||
|
||||
/* Footnotes */
|
||||
.footnote-backref,
|
||||
.footnote-ref {
|
||||
text-decoration: none;
|
||||
padding-left: .0625em;
|
||||
}
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
var debug = 0 ? console.log.bind(console, '[explorer]') : function () {};
|
||||
|
||||
// This is cureently not used, but kept in case I change my mind.
|
||||
// This is currently not used, but kept in case I change my mind.
|
||||
export const explorer = (Alpine) => ({
|
||||
uiState: {
|
||||
containerScrollTop: -1,
|
||||
|
|
|
|||
|
|
@ -1,6 +1,24 @@
|
|||
export const navbar = (Alpine) => ({
|
||||
init: function () {
|
||||
Alpine.bind(this.$root, this.root);
|
||||
|
||||
return this.$nextTick(() => {
|
||||
let contentEl = document.querySelector('.content:not(.content--ready)');
|
||||
if (contentEl) {
|
||||
contentEl.classList.add('content--ready');
|
||||
let anchorTemplate = document.getElementById('anchor-heading');
|
||||
if (anchorTemplate) {
|
||||
let els = contentEl.querySelectorAll('h2[id], h3[id], h4[id], h5[id], h6[id], dt[id]');
|
||||
for (let i = 0; i < els.length; i++) {
|
||||
let el = els[i];
|
||||
el.classList.add('group');
|
||||
let a = anchorTemplate.content.cloneNode(true).firstElementChild;
|
||||
a.href = '#' + el.id;
|
||||
el.appendChild(a);
|
||||
}
|
||||
}
|
||||
}
|
||||
});
|
||||
},
|
||||
root: {
|
||||
['@scroll.window.debounce.10ms'](event) {
|
||||
|
|
|
|||
|
|
@ -1,3 +1,5 @@
|
|||
import { LRUCache } from '../../helpers';
|
||||
|
||||
const designMode = false;
|
||||
|
||||
const groupByLvl0 = (array) => {
|
||||
|
|
@ -33,10 +35,10 @@ const applyHelperFuncs = (array) => {
|
|||
};
|
||||
|
||||
export const search = (Alpine, cfg) => ({
|
||||
query: designMode ? 'shortcodes' : '',
|
||||
query: designMode ? 'apac' : '',
|
||||
open: designMode,
|
||||
result: {},
|
||||
|
||||
cache: new LRUCache(10), // Small cache, avoids network requests on e.g. backspace.
|
||||
init() {
|
||||
Alpine.bind(this.$root, this.root);
|
||||
|
||||
|
|
@ -66,6 +68,13 @@ export const search = (Alpine, cfg) => ({
|
|||
this.result = {};
|
||||
return;
|
||||
}
|
||||
|
||||
// Check cache first.
|
||||
const cached = this.cache.get(this.query);
|
||||
if (cached) {
|
||||
this.result = cached;
|
||||
return;
|
||||
}
|
||||
var queries = {
|
||||
requests: [
|
||||
{
|
||||
|
|
@ -91,6 +100,7 @@ export const search = (Alpine, cfg) => ({
|
|||
.then((response) => response.json())
|
||||
.then((data) => {
|
||||
this.result = groupByLvl0(applyHelperFuncs(data.results[0].hits));
|
||||
this.cache.put(this.query, this.result);
|
||||
});
|
||||
},
|
||||
root: {
|
||||
|
|
@ -102,7 +112,7 @@ export const search = (Alpine, cfg) => ({
|
|||
['@search-toggle.window']() {
|
||||
this.toggleOpen();
|
||||
},
|
||||
['@keydown.meta.k.window.prevent']() {
|
||||
['@keydown.slash.window.prevent']() {
|
||||
this.toggleOpen();
|
||||
},
|
||||
},
|
||||
|
|
|
|||
|
|
@ -23,7 +23,7 @@ export const toc = (Alpine) => ({
|
|||
});
|
||||
|
||||
return this.$nextTick(() => {
|
||||
let contentEl = document.getElementById('content');
|
||||
let contentEl = document.getElementById('article');
|
||||
if (contentEl) {
|
||||
const handleIntersect = (entries) => {
|
||||
if (this.justClicked) {
|
||||
|
|
|
|||
|
|
@ -87,8 +87,8 @@ export function initColorScheme() {
|
|||
|
||||
const toggleDarkMode = function (dark) {
|
||||
if (dark) {
|
||||
document.body.classList.add('dark');
|
||||
document.documentElement.classList.add('dark');
|
||||
} else {
|
||||
document.body.classList.remove('dark');
|
||||
document.documentElement.classList.remove('dark');
|
||||
}
|
||||
};
|
||||
|
|
|
|||
|
|
@ -1,2 +1,3 @@
|
|||
export * from './bridgeTurboAndAlpine';
|
||||
export * from './helpers';
|
||||
export * from './lrucache';
|
||||
|
|
|
|||
19
docs/assets/js/helpers/lrucache.js
Normal file
19
docs/assets/js/helpers/lrucache.js
Normal file
|
|
@ -0,0 +1,19 @@
|
|||
// A simple LRU cache implementation backed by a map.
|
||||
export class LRUCache {
|
||||
constructor(maxSize) {
|
||||
this.maxSize = maxSize;
|
||||
this.cache = new Map();
|
||||
}
|
||||
|
||||
get(key) {
|
||||
return this.cache.get(key);
|
||||
}
|
||||
|
||||
put(key, value) {
|
||||
if (this.cache.size >= this.maxSize) {
|
||||
const firstKey = this.cache.keys().next().value;
|
||||
this.cache.delete(firstKey);
|
||||
}
|
||||
this.cache.set(key, value);
|
||||
}
|
||||
}
|
||||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
cascade:
|
||||
_build:
|
||||
build:
|
||||
list: never
|
||||
publishResources: false
|
||||
render: never
|
||||
|
|
|
|||
13
docs/content/en/_common/content-format-table.md
Normal file
13
docs/content/en/_common/content-format-table.md
Normal file
|
|
@ -0,0 +1,13 @@
|
|||
---
|
||||
_comment: Do not remove front matter.
|
||||
---
|
||||
|
||||
Content format|Media type|Identifier|File extensions
|
||||
:--|:--|:--|:--
|
||||
Markdown|`text/markdown`|`markdown`|`markdown`,`md`, `mdown`
|
||||
HTML|`text/html`|`html`|`htm`, `html`
|
||||
Emacs Org Mode|`text/org`|`org`|`org`
|
||||
AsciiDoc|`text/asciidoc`|`asciidoc`|`ad`, `adoc`, `asciidoc`
|
||||
Pandoc|`text/pandoc`|`pandoc`|`pandoc`, `pdc`
|
||||
reStructuredText|`text/rst`|`rst`|`rst`
|
||||
<!-- do not remove this comment -->
|
||||
8
docs/content/en/_common/filter-sort-group.md
Normal file
8
docs/content/en/_common/filter-sort-group.md
Normal file
|
|
@ -0,0 +1,8 @@
|
|||
---
|
||||
_comment: Do not remove front matter.
|
||||
---
|
||||
|
||||
> [!note]
|
||||
> The [page collections quick reference guide] describes methods and functions to filter, sort, and group page collections.
|
||||
|
||||
[page collections quick reference guide]: /quick-reference/page-collections/
|
||||
108
docs/content/en/_common/functions/js/options.md
Normal file
108
docs/content/en/_common/functions/js/options.md
Normal file
|
|
@ -0,0 +1,108 @@
|
|||
---
|
||||
_comment: Do not remove front matter.
|
||||
---
|
||||
|
||||
params
|
||||
: (`map` or `slice`) Params that can be imported as JSON in your JS files, e.g.
|
||||
|
||||
```go-html-template
|
||||
{{ $js := resources.Get "js/main.js" | js.Build (dict "params" (dict "api" "https://example.org/api")) }}
|
||||
```
|
||||
And then in your JS file:
|
||||
|
||||
```js
|
||||
import * as params from '@params';
|
||||
```
|
||||
|
||||
Note that this is meant for small data sets, e.g., configuration settings. For larger data sets, please put/mount the files into `assets` and import them directly.
|
||||
|
||||
minify
|
||||
: (`bool`) Whether to let `js.Build` handle the minification.
|
||||
|
||||
loaders
|
||||
: {{< new-in 0.140.0 />}}
|
||||
: (`map`) Configuring a loader for a given file type lets you load that file type with an `import` statement or a `require` call. For example, configuring the `.png` file extension to use the data URL loader means importing a `.png` file gives you a data URL containing the contents of that image. Loaders available are `none`, `base64`, `binary`, `copy`, `css`, `dataurl`, `default`, `empty`, `file`, `global-css`, `js`, `json`, `jsx`, `local-css`, `text`, `ts`, `tsx`. See https://esbuild.github.io/api/#loader.
|
||||
|
||||
inject
|
||||
: (`slice`) This option allows you to automatically replace a global variable with an import from another file. The path names must be relative to `assets`. See https://esbuild.github.io/api/#inject.
|
||||
|
||||
shims
|
||||
: (`map`) This option allows swapping out a component with another. A common use case is to load dependencies like React from a CDN (with _shims_) when in production, but running with the full bundled `node_modules` dependency during development:
|
||||
|
||||
```go-html-template
|
||||
{{ $shims := dict "react" "js/shims/react.js" "react-dom" "js/shims/react-dom.js" }}
|
||||
{{ $js = $js | js.Build dict "shims" $shims }}
|
||||
```
|
||||
|
||||
The _shim_ files may look like these:
|
||||
|
||||
```js
|
||||
// js/shims/react.js
|
||||
module.exports = window.React;
|
||||
```
|
||||
|
||||
```js
|
||||
// js/shims/react-dom.js
|
||||
module.exports = window.ReactDOM;
|
||||
```
|
||||
|
||||
With the above, these imports should work in both scenarios:
|
||||
|
||||
```js
|
||||
import * as React from 'react';
|
||||
import * as ReactDOM from 'react-dom/client';
|
||||
```
|
||||
|
||||
target
|
||||
: (`string`) The language target. One of: `es5`, `es2015`, `es2016`, `es2017`, `es2018`, `es2019`, `es2020`, `es2021`, `es2022`, `es2023`, `es2024`, or `esnext`. Default is `esnext`.
|
||||
|
||||
platform
|
||||
: {{< new-in 0.140.0 />}}
|
||||
: (`string`) One of `browser`, `node`, `neutral`. Default is `browser`. See https://esbuild.github.io/api/#platform.
|
||||
|
||||
externals
|
||||
: (`slice`) External dependencies. Use this to trim dependencies you know will never be executed. See https://esbuild.github.io/api/#external.
|
||||
|
||||
defines
|
||||
: (`map`) This option allows you to define a set of string replacements to be performed when building. It must be a map where each key will be replaced by its value.
|
||||
|
||||
```go-html-template
|
||||
{{ $defines := dict "process.env.NODE_ENV" `"development"` }}
|
||||
```
|
||||
|
||||
drop
|
||||
: {{< new-in 0.144.0 />}}
|
||||
: (`string`) Edit your source code before building to drop certain constructs: One of `debugger` or `console`.
|
||||
: See https://esbuild.github.io/api/#drop
|
||||
|
||||
sourceMap
|
||||
: (`string`) Whether to generate `inline`, `linked`, or `external` source maps from esbuild. Linked and external source maps will be written to the target with the output file name + ".map". When `linked` a `sourceMappingURL` will also be written to the output file. By default, source maps are not created. Note that the `linked` option was added in Hugo 0.140.0.
|
||||
|
||||
sourcesContent
|
||||
: {{< new-in 0.140.0 />}}
|
||||
: (`bool`) Whether to include the content of the source files in the source map. By default, this is `true`.
|
||||
|
||||
JSX
|
||||
: {{< new-in 0.124.0 />}}
|
||||
: (`string`) How to handle/transform JSX syntax. One of: `transform`, `preserve`, `automatic`. Default is `transform`. Notably, the `automatic` transform was introduced in React 17+ and will cause the necessary JSX helper functions to be imported automatically. See https://esbuild.github.io/api/#jsx.
|
||||
|
||||
JSXImportSource
|
||||
: {{< new-in 0.124.0 />}}
|
||||
: (`string`) Which library to use to automatically import its JSX helper functions from. This only works if `JSX` is set to `automatic`. The specified library needs to be installed through npm and expose certain exports. See https://esbuild.github.io/api/#jsx-import-source.
|
||||
|
||||
The combination of `JSX` and `JSXImportSource` is helpful if you want to use a non-React JSX library like Preact, e.g.:
|
||||
|
||||
```go-html-template
|
||||
{{ $js := resources.Get "js/main.jsx" | js.Build (dict "JSX" "automatic" "JSXImportSource" "preact") }}
|
||||
```
|
||||
|
||||
With the above, you can use Preact components and JSX without having to manually import `h` and `Fragment` every time:
|
||||
|
||||
```jsx
|
||||
import { render } from 'preact';
|
||||
|
||||
const App = () => <>Hello world!</>;
|
||||
|
||||
const container = document.getElementById('app');
|
||||
if (container) render(<App />, container);
|
||||
```
|
||||
8
docs/content/en/_common/functions/locales.md
Normal file
8
docs/content/en/_common/functions/locales.md
Normal file
|
|
@ -0,0 +1,8 @@
|
|||
---
|
||||
_comment: Do not remove front matter.
|
||||
---
|
||||
|
||||
> [!note]
|
||||
> Localization of dates, currencies, numbers, and percentages is performed by the [gohugoio/locales] package. The language tag of the current site must match one of the listed locales.
|
||||
|
||||
[gohugoio/locales]: https://github.com/gohugoio/locales
|
||||
13
docs/content/en/_common/gomodules-info.md
Normal file
13
docs/content/en/_common/gomodules-info.md
Normal file
|
|
@ -0,0 +1,13 @@
|
|||
---
|
||||
_comment: Do not remove front matter.
|
||||
---
|
||||
|
||||
> [!note] Hugo Modules are Go Modules
|
||||
> You need [Go] version 1.18 or later and [Git] to use Hugo Modules. For older sites hosted on Netlify, please ensure the `GO_VERSION` environment variable is set to `1.18` or higher.
|
||||
>
|
||||
> Go Modules resources:
|
||||
> - [go.dev/wiki/Modules](https://go.dev/wiki/Modules)
|
||||
> - [blog.golang.org/using-go-modules](https://go.dev/blog/using-go-modules)
|
||||
|
||||
[Git]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git
|
||||
[Go]: https://go.dev/doc/install
|
||||
|
|
@ -13,4 +13,4 @@ Deploy your site directly to a Google Cloud Storage bucket, an AWS S3 bucket, or
|
|||
[dart sass]: /functions/css/sass/#dart-sass
|
||||
[processing images]: /content-management/image-processing/
|
||||
[transpile sass to css]: /functions/css/sass/
|
||||
[details]: /hosting-and-deployment/hugo-deploy/
|
||||
[details]: /host-and-deploy/deploy-with-hugo-deploy/
|
||||
|
|
@ -7,7 +7,7 @@ _comment: Do not remove front matter.
|
|||
To build the extended or extended/deploy edition from source you must:
|
||||
|
||||
1. Install [Git]
|
||||
1. Install [Go] version 1.20 or later
|
||||
1. Install [Go] version 1.23.0 or later
|
||||
1. Install a C compiler, either [GCC] or [Clang]
|
||||
1. Update your `PATH` environment variable as described in the [Go documentation]
|
||||
|
||||
31
docs/content/en/_common/menu-entry-properties.md
Normal file
31
docs/content/en/_common/menu-entry-properties.md
Normal file
|
|
@ -0,0 +1,31 @@
|
|||
---
|
||||
_comment: Do not remove front matter.
|
||||
---
|
||||
|
||||
<!--
|
||||
This description list intentionally excludes the `pageRef` and `url` properties. Add those properties manually after using the include shortcode to include this list.
|
||||
-->
|
||||
|
||||
identifier
|
||||
: (`string`) Required when two or more menu entries have the same `name`, or when localizing the `name` using translation tables. Must start with a letter, followed by letters, digits, or underscores.
|
||||
|
||||
name
|
||||
: (`string`) The text to display when rendering the menu entry.
|
||||
|
||||
params
|
||||
: (`map`) User-defined properties for the menu entry.
|
||||
|
||||
parent
|
||||
: (`string`) The `identifier` of the parent menu entry. If `identifier` is not defined, use `name`. Required for child entries in a nested menu.
|
||||
|
||||
post
|
||||
: (`string`) The HTML to append when rendering the menu entry.
|
||||
|
||||
pre
|
||||
: (`string`) The HTML to prepend when rendering the menu entry.
|
||||
|
||||
title
|
||||
: (`string`) The HTML `title` attribute of the rendered menu entry.
|
||||
|
||||
weight
|
||||
: (`int`) A non-zero integer indicating the entry's position relative the root of the menu, or to its parent for a child entry. Lighter entries float to the top, while heavier entries sink to the bottom.
|
||||
|
|
@ -32,13 +32,13 @@ content/
|
|||
|
||||
And these templates:
|
||||
|
||||
{{< code file=layouts/_default/list.html >}}
|
||||
```go-html-template {file="layouts/_default/list.html"}
|
||||
{{ range .Pages.ByWeight }}
|
||||
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
|
||||
{{ end }}
|
||||
{{< /code >}}
|
||||
```
|
||||
|
||||
{{< code file=layouts/_default/single.html >}}
|
||||
```go-html-template {file="layouts/_default/single.html"}
|
||||
{{ with .Prev }}
|
||||
<a href="{{ .RelPermalink }}">Previous</a>
|
||||
{{ end }}
|
||||
|
|
@ -46,7 +46,7 @@ And these templates:
|
|||
{{ with .Next }}
|
||||
<a href="{{ .RelPermalink }}">Next</a>
|
||||
{{ end }}
|
||||
{{< /code >}}
|
||||
```
|
||||
|
||||
When you visit page-2:
|
||||
|
||||
|
|
@ -55,6 +55,6 @@ When you visit page-2:
|
|||
|
||||
To reverse the meaning of _next_ and _previous_ you can change the sort direction in your [site configuration], or use the [`Next`] and [`Prev`] methods on a `Pages` object for more flexibility.
|
||||
|
||||
[site configuration]: /getting-started/configuration/#configure-page
|
||||
[site configuration]: /configuration/page/
|
||||
[`Next`]: /methods/pages/prev
|
||||
[`Prev`]: /methods/pages/prev
|
||||
|
|
@ -32,13 +32,13 @@ content/
|
|||
|
||||
And these templates:
|
||||
|
||||
{{< code file=layouts/_default/list.html >}}
|
||||
```go-html-template {file="layouts/_default/list.html"}
|
||||
{{ range .Pages.ByWeight }}
|
||||
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
|
||||
{{ end }}
|
||||
{{< /code >}}
|
||||
```
|
||||
|
||||
{{< code file=layouts/_default/single.html >}}
|
||||
```go-html-template {file="layouts/_default/single.html"}
|
||||
{{ with .PrevInSection }}
|
||||
<a href="{{ .RelPermalink }}">Previous</a>
|
||||
{{ end }}
|
||||
|
|
@ -46,7 +46,7 @@ And these templates:
|
|||
{{ with .NextInSection }}
|
||||
<a href="{{ .RelPermalink }}">Next</a>
|
||||
{{ end }}
|
||||
{{< /code >}}
|
||||
```
|
||||
|
||||
When you visit page-2:
|
||||
|
||||
|
|
@ -55,7 +55,7 @@ When you visit page-2:
|
|||
|
||||
To reverse the meaning of _next_ and _previous_ you can change the sort direction in your [site configuration], or use the [`Next`] and [`Prev`] methods on a `Pages` object for more flexibility.
|
||||
|
||||
[site configuration]: /getting-started/configuration/#configure-page
|
||||
[site configuration]: /configuration/page/
|
||||
[`Next`]: /methods/pages/prev
|
||||
[`Prev`]: /methods/pages/prev
|
||||
|
||||
|
|
@ -0,0 +1,35 @@
|
|||
---
|
||||
_comment: Do not remove front matter.
|
||||
---
|
||||
|
||||
### Get IDENTIFIER
|
||||
|
||||
(`any`) Returns the `OutputFormat` object with the given identifier.
|
||||
|
||||
### MediaType
|
||||
|
||||
(`media.Type`) Returns the media type of the output format.
|
||||
|
||||
### MediaType.MainType
|
||||
|
||||
(`string`) Returns the main type of the output format's media type.
|
||||
|
||||
### MediaType.SubType
|
||||
|
||||
(`string`) Returns the subtype of the current format's media type.
|
||||
|
||||
### Name
|
||||
|
||||
(`string`) Returns the output identifier of the output format.
|
||||
|
||||
### Permalink
|
||||
|
||||
(`string`) Returns the permalink of the page generated by the current output format.
|
||||
|
||||
### Rel
|
||||
|
||||
(`string`) Returns the `rel` value of the output format, either the default or as defined in the site configuration.
|
||||
|
||||
### RelPermalink
|
||||
|
||||
(`string`) Returns the relative permalink of the page generated by the current output format.
|
||||
|
|
@ -32,13 +32,13 @@ content/
|
|||
|
||||
And these templates:
|
||||
|
||||
{{< code file=layouts/_default/list.html >}}
|
||||
{{ range .Pages.ByWeight}}
|
||||
```go-html-template {file="layouts/_default/list.html"}
|
||||
{{ range .Pages.ByWeight }}
|
||||
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
|
||||
{{ end }}
|
||||
{{< /code >}}
|
||||
```
|
||||
|
||||
{{< code file=layouts/_default/single.html >}}
|
||||
```go-html-template {file="layouts/_default/single.html"}
|
||||
{{ $pages := .CurrentSection.Pages.ByWeight }}
|
||||
|
||||
{{ with $pages.Prev . }}
|
||||
|
|
@ -48,7 +48,7 @@ And these templates:
|
|||
{{ with $pages.Next . }}
|
||||
<a href="{{ .RelPermalink }}">Next</a>
|
||||
{{ end }}
|
||||
{{< /code >}}
|
||||
```
|
||||
|
||||
When you visit page-2:
|
||||
|
||||
|
|
@ -57,7 +57,7 @@ When you visit page-2:
|
|||
|
||||
To reverse the meaning of _next_ and _previous_ you can chain the [`Reverse`] method to the page collection definition:
|
||||
|
||||
{{< code file=layouts/_default/single.html >}}
|
||||
```go-html-template {file="layouts/_default/single.html"}
|
||||
{{ $pages := .CurrentSection.Pages.ByWeight.Reverse }}
|
||||
|
||||
{{ with $pages.Prev . }}
|
||||
|
|
@ -67,6 +67,6 @@ To reverse the meaning of _next_ and _previous_ you can chain the [`Reverse`] me
|
|||
{{ with $pages.Next . }}
|
||||
<a href="{{ .RelPermalink }}">Next</a>
|
||||
{{ end }}
|
||||
{{< /code >}}
|
||||
```
|
||||
|
||||
[`Reverse`]: /methods/pages/reverse/
|
||||
|
|
@ -0,0 +1,6 @@
|
|||
---
|
||||
_comment: Do not remove front matter.
|
||||
---
|
||||
|
||||
> [!note]
|
||||
> Use this method with [global resources](g), [page resources](g), or [remote resources](g).
|
||||
|
|
@ -34,9 +34,9 @@ To capture the "genres" `Taxonomy` object from within any template, use the [`Ta
|
|||
|
||||
To capture the "genres" `Taxonomy` object when rendering its page with a taxonomy template, use the [`Terms`] method on the page's [`Data`] object:
|
||||
|
||||
{{< code file=layouts/_default/taxonomy.html >}}
|
||||
```go-html-template {file="layouts/_default/taxonomy.html"}
|
||||
{{ $taxonomyObject := .Data.Terms }}
|
||||
{{< /code >}}
|
||||
```
|
||||
|
||||
To inspect the data structure:
|
||||
|
||||
71
docs/content/en/_common/permalink-tokens.md
Normal file
71
docs/content/en/_common/permalink-tokens.md
Normal file
|
|
@ -0,0 +1,71 @@
|
|||
---
|
||||
_comment: Do not remove front matter.
|
||||
---
|
||||
|
||||
`:year`
|
||||
: The 4-digit year as defined in the front matter `date` field.
|
||||
|
||||
`:month`
|
||||
: The 2-digit month as defined in the front matter `date` field.
|
||||
|
||||
`:monthname`
|
||||
: The name of the month as defined in the front matter `date` field.
|
||||
|
||||
`:day`
|
||||
: The 2-digit day as defined in the front matter `date` field.
|
||||
|
||||
`:weekday`
|
||||
: The 1-digit day of the week as defined in the front matter `date` field (Sunday = `0`).
|
||||
|
||||
`:weekdayname`
|
||||
: The name of the day of the week as defined in the front matter `date` field.
|
||||
|
||||
`:yearday`
|
||||
: The 1- to 3-digit day of the year as defined in the front matter `date` field.
|
||||
|
||||
`:section`
|
||||
: The content's section.
|
||||
|
||||
`:sections`
|
||||
: The content's sections hierarchy. 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.
|
||||
|
||||
`:title`
|
||||
: The `title` as defined in front matter, else the automatic title. Hugo generates titles automatically for section, taxonomy, and term pages that are not backed by a file.
|
||||
|
||||
`:slug`
|
||||
: The `slug` as defined in front matter, else the `title` as defined in front matter, else the automatic title. Hugo generates titles automatically for section, taxonomy, and term pages that are not backed by a file.
|
||||
|
||||
`:filename`
|
||||
: The content's file name without extension, applicable to the `page` page kind.
|
||||
|
||||
{{< deprecated-in v0.144.0 >}}
|
||||
The `:filename` token has been deprecated. Use `:contentbasename` instead.
|
||||
{{< /deprecated-in >}}
|
||||
|
||||
`:slugorfilename`
|
||||
: The `slug` as defined in front matter, else the content's file name without extension, applicable to the `page` page kind.
|
||||
|
||||
{{< deprecated-in v0.144.0 >}}
|
||||
The `:slugorfilename` token has been deprecated. Use `:slugorcontentbasename` instead.
|
||||
{{< /deprecated-in >}}
|
||||
|
||||
`:contentbasename`
|
||||
: {{< new-in 0.144.0 />}}
|
||||
: The [content base name].
|
||||
|
||||
[content base name]: /methods/page/file/#contentbasename
|
||||
|
||||
`:slugorcontentbasename`
|
||||
: {{< new-in 0.144.0 />}}
|
||||
: The `slug` as defined in front matter, else the [content base name].
|
||||
|
||||
For time-related values, you can also use the layout string components defined in Go's [time package]. For example:
|
||||
|
||||
[time package]: https://pkg.go.dev/time#pkg-constants
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
permalinks:
|
||||
posts: /:06/:1/:2/:title/
|
||||
{{< /code-toggle >}}
|
||||
|
||||
[content base name]: /methods/page/file/#contentbasename
|
||||
10
docs/content/en/_common/ref-and-relref-error-handling.md
Normal file
10
docs/content/en/_common/ref-and-relref-error-handling.md
Normal file
|
|
@ -0,0 +1,10 @@
|
|||
---
|
||||
_comment: Do not remove front matter.
|
||||
---
|
||||
|
||||
By default, Hugo will throw an error and fail the build if it cannot resolve the path. You can change this to a warning in your site configuration, and specify a URL to return when the path cannot be resolved.
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
refLinksErrorLevel = 'warning'
|
||||
refLinksNotFoundURL = '/some/other/url'
|
||||
{{< /code-toggle >}}
|
||||
12
docs/content/en/_common/ref-and-relref-options.md
Normal file
12
docs/content/en/_common/ref-and-relref-options.md
Normal file
|
|
@ -0,0 +1,12 @@
|
|||
---
|
||||
_comment: Do not remove front matter.
|
||||
---
|
||||
|
||||
path
|
||||
: (`string`) The path to the target page. Paths without a leading slash (`/`) are resolved first relative to the current page, and then relative to the rest of the site.
|
||||
|
||||
lang
|
||||
: (`string`) The language of the target page. Default is the current language. Optional.
|
||||
|
||||
outputFormat
|
||||
: (`string`) The output format of the target page. Default is the current output format. Optional.
|
||||
|
|
@ -8,7 +8,7 @@ _comment: Do not remove front matter.
|
|||
|
||||
The primary use case for `PageInner` is to resolve links and [page resources](g) relative to an included `Page`. For example, create an "include" shortcode to compose a page from multiple content files, while preserving a global context for footnotes and the table of contents:
|
||||
|
||||
{{< code file=layouts/shortcodes/include.html >}}
|
||||
```go-html-template {file="layouts/shortcodes/include.html" copy=true}
|
||||
{{ with .Get 0 }}
|
||||
{{ with $.Page.GetPage . }}
|
||||
{{- .RenderShortcodes }}
|
||||
|
|
@ -18,13 +18,13 @@ The primary use case for `PageInner` is to resolve links and [page resources](g)
|
|||
{{ else }}
|
||||
{{ errorf "The %q shortcode requires a positional parameter indicating the logical path of the file to include. See %s" .Name .Position }}
|
||||
{{ end }}
|
||||
{{< /code >}}
|
||||
```
|
||||
|
||||
Then call the shortcode in your Markdown:
|
||||
|
||||
{{< code file=content/posts/p1.md >}}
|
||||
```text {file="content/posts/p1.md"}
|
||||
{{%/* include "/posts/p2" */%}}
|
||||
{{< /code >}}
|
||||
```
|
||||
|
||||
Any render hook triggered while rendering `/posts/p2` will get:
|
||||
|
||||
|
|
@ -33,15 +33,15 @@ Any render hook triggered while rendering `/posts/p2` will get:
|
|||
|
||||
`PageInner` falls back to the value of `Page` if not relevant, and always returns a value.
|
||||
|
||||
{{% note %}}
|
||||
The `PageInner` method is only relevant for shortcodes that invoke the [`RenderShortcodes`] method, and you must call the shortcode using the `{{%/*..*/%}}` notation.
|
||||
|
||||
[`RenderShortcodes`]: /methods/page/rendershortcodes/
|
||||
{{% /note %}}
|
||||
> [!note]
|
||||
> The `PageInner` method is only relevant for shortcodes that invoke the [`RenderShortcodes`] method, and you must call the shortcode using [Markdown notation].
|
||||
|
||||
As a practical example, Hugo's embedded link and image render hooks use the `PageInner` method to resolve markdown link and image destinations. See the source code for each:
|
||||
|
||||
- [Embedded link render hook]({{% eturl render-link %}})
|
||||
- [Embedded image render hook]({{% eturl render-image %}})
|
||||
- [Embedded link render hook]
|
||||
- [Embedded image render hook]
|
||||
|
||||
[`RenderShortcodes`]: /methods/page/rendershortcodes/
|
||||
[Markdown notation]: /content-management/shortcodes/#notation
|
||||
[Embedded link render hook]: {{% eturl render-link %}}
|
||||
[Embedded image render hook]: {{% eturl render-image %}}
|
||||
|
|
@ -4,7 +4,7 @@
|
|||
|
||||
## Methods
|
||||
|
||||
###### Set
|
||||
### Set
|
||||
|
||||
Sets the value of the given key.
|
||||
|
||||
|
|
@ -12,7 +12,7 @@ Sets the value of the given key.
|
|||
{{ .Store.Set "greeting" "Hello" }}
|
||||
```
|
||||
|
||||
###### Get
|
||||
### Get
|
||||
|
||||
Gets the value of the given key.
|
||||
|
||||
|
|
@ -21,7 +21,7 @@ Gets the value of the given key.
|
|||
{{ .Store.Get "greeting" }} → Hello
|
||||
```
|
||||
|
||||
###### Add
|
||||
### Add
|
||||
|
||||
Adds the given value to the existing value(s) of the given key.
|
||||
|
||||
|
|
@ -45,7 +45,7 @@ For single values, `Add` accepts values that support Go's `+` operator. If the f
|
|||
{{ .Store.Get "greetings" }} → [Hello Welcome Cheers]
|
||||
```
|
||||
|
||||
###### SetInMap
|
||||
### SetInMap
|
||||
|
||||
Takes a `key`, `mapKey` and `value` and adds a map of `mapKey` and `value` to the given `key`.
|
||||
|
||||
|
|
@ -53,9 +53,9 @@ Takes a `key`, `mapKey` and `value` and adds a map of `mapKey` and `value` to th
|
|||
{{ .Store.SetInMap "greetings" "english" "Hello" }}
|
||||
{{ .Store.SetInMap "greetings" "french" "Bonjour" }}
|
||||
{{ .Store.Get "greetings" }} → map[english:Hello french:Bonjour]
|
||||
```
|
||||
```
|
||||
|
||||
###### DeleteInMap
|
||||
### DeleteInMap
|
||||
|
||||
Takes a `key` and `mapKey` and removes the map of `mapKey` from the given `key`.
|
||||
|
||||
|
|
@ -66,7 +66,7 @@ Takes a `key` and `mapKey` and removes the map of `mapKey` from the given `key`.
|
|||
{{ .Store.Get "greetings" }} → map[french:Bonjour]
|
||||
```
|
||||
|
||||
###### GetSortedMapValues
|
||||
### GetSortedMapValues
|
||||
|
||||
Returns an array of values from `key` sorted by `mapKey`.
|
||||
|
||||
|
|
@ -76,7 +76,7 @@ Returns an array of values from `key` sorted by `mapKey`.
|
|||
{{ .Store.GetSortedMapValues "greetings" }} → [Hello Bonjour]
|
||||
```
|
||||
|
||||
###### Delete
|
||||
### Delete
|
||||
|
||||
Removes the given key.
|
||||
|
||||
|
|
|
|||
|
|
@ -11,9 +11,8 @@ codeFences
|
|||
guessSyntax
|
||||
: (`bool`) Whether to automatically detect the language if the `LANG` argument is blank or set to a language for which there is no corresponding [lexer](g). Falls back to a plain text lexer if unable to automatically detect the language. Default is `false`.
|
||||
|
||||
{{% note %}}
|
||||
The Chroma syntax highlighter includes lexers for approximately 250 languages, but only 5 of these have implemented automatic language detection.
|
||||
{{% /note %}}
|
||||
> [!note]
|
||||
> The Chroma syntax highlighter includes lexers for approximately 250 languages, but only 5 of these have implemented automatic language detection.
|
||||
|
||||
hl_Lines
|
||||
: (`string`) A space-delimited list of lines to emphasize within the highlighted code. To emphasize lines 2, 3, 4, and 7, set this value to `2-4 7`. This option is independent of the `lineNoStart` option.
|
||||
|
|
@ -28,32 +27,30 @@ lineNoStart
|
|||
: (`int`) The number to display at the beginning of the first line. Irrelevant if `lineNos` is `false`. Default is `1`.
|
||||
|
||||
lineNos
|
||||
: (`bool`) Whether to display a number at the beginning of each line. Default is `false`.
|
||||
: (`any`) Controls line number display. Default is `false`.
|
||||
- `true`: Enable line numbers, controlled by `lineNumbersInTable`.
|
||||
- `false`: Disable line numbers.
|
||||
- `inline`: Enable inline line numbers (sets `lineNumbersInTable` to `false`).
|
||||
- `table`: Enable table-based line numbers (sets `lineNumbersInTable` to `true`).
|
||||
|
||||
lineNumbersInTable
|
||||
: (`bool`) Whether to render the highlighted code in an HTML table with two cells. The left table cell contains the line numbers, while the right table cell contains the code. Irrelevant if `lineNos` is `false`. Default is `true`.
|
||||
|
||||
noClasses
|
||||
: (`bool`) Whether to use inline CSS styles instead of an external CSS file. To use an external CSS file, set this value to `false` and generate the CSS file using the `hugo gen chromastyles` command. Default is `true`.
|
||||
: (`bool`) Whether to use inline CSS styles instead of an external CSS file. Default is `true`. To use an external CSS file, set this value to `false` and generate the CSS file from the command line:
|
||||
|
||||
```text
|
||||
hugo gen chromastyles --style=monokai > syntax.css
|
||||
```
|
||||
|
||||
style
|
||||
: (`string`) The CSS styles to apply to the highlighted code. See the [style gallery] for examples. Case-sensitive. Default is `monokai`.
|
||||
|
||||
[style gallery]: https://xyproto.github.io/splash/docs/
|
||||
: (`string`) The CSS styles to apply to the highlighted code. Case-sensitive. Default is `monokai`. See [syntax highlighting styles].
|
||||
|
||||
tabWidth
|
||||
: (`int`) Substitute this number of spaces for each tab character in your highlighted code. Irrelevant if `noClasses` is `false`. Default is `4`.
|
||||
|
||||
wrapperClass
|
||||
{{< new-in 0.140.2 />}}
|
||||
: {{< new-in 0.140.2 />}}
|
||||
: (`string`) The class or classes to use for the outermost element of the highlighted code. Default is `highlight`.
|
||||
|
||||
{{% note %}}
|
||||
Instead of specifying both `lineNos` and `lineNumbersInTable`, you can use the following shorthand notation:
|
||||
|
||||
lineNos=inline
|
||||
: equivalent to `lineNos=true` and `lineNumbersInTable=false`
|
||||
|
||||
lineNos=table
|
||||
: equivalent to `lineNos=true` and `lineNumbersInTable=true`
|
||||
{{% /note %}}
|
||||
[syntax highlighting styles]: /quick-reference/syntax-highlighting-styles/
|
||||
|
|
@ -1,49 +1,4 @@
|
|||
---
|
||||
title: The world’s fastest framework for building websites
|
||||
date: 2017-03-02T12:00:00-05:00
|
||||
features:
|
||||
- heading: Blistering Speed
|
||||
image_path: /images/icon-fast.svg
|
||||
tagline: What's modern about waiting for your site to build?
|
||||
copy: Hugo is the fastest tool of its kind. At <1 ms per page, the average site builds in less than a second.
|
||||
|
||||
- heading: Robust Content Management
|
||||
image_path: /images/icon-content-management.svg
|
||||
tagline: Flexibility rules. Hugo is a content strategist's dream.
|
||||
copy: Hugo supports unlimited content types, taxonomies, menus, dynamic API-driven content, and more, all without plugins.
|
||||
|
||||
- heading: Shortcodes
|
||||
image_path: /images/icon-shortcodes.svg
|
||||
tagline: Hugo's shortcodes are Markdown's hidden superpower.
|
||||
copy: We love the beautiful simplicity of Markdown’s syntax, but there are times when we want more flexibility. Hugo shortcodes allow for both beauty and flexibility.
|
||||
|
||||
- heading: Built-in Templates
|
||||
image_path: /images/icon-built-in-templates.svg
|
||||
tagline: Hugo has common patterns to get your work done quickly.
|
||||
copy: Hugo ships with pre-made templates to make quick work of SEO, commenting, analytics and other functions. One line of code, and you're done.
|
||||
|
||||
- heading: Multilingual and i18n
|
||||
image_path: /images/icon-multilingual2.svg
|
||||
tagline: Polyglot baked in.
|
||||
copy: Hugo provides full i18n support for multi-language sites with the same straightforward development experience Hugo users love in single-language sites.
|
||||
|
||||
- heading: Custom Outputs
|
||||
image_path: /images/icon-custom-outputs.svg
|
||||
tagline: HTML not enough?
|
||||
copy: Hugo allows you to output your content in multiple formats, including JSON or AMP, and makes it easy to create your own.
|
||||
sections:
|
||||
- heading: "300+ Themes"
|
||||
cta: Check out the Hugo themes.
|
||||
link: https://themes.gohugo.io/
|
||||
color_classes: bg-accent-color white
|
||||
image: /images/homepage-screenshot-hugo-themes.jpg
|
||||
copy: "Hugo provides a robust theming system that is easy to implement but capable of producing even the most complicated websites."
|
||||
- heading: "Capable Templating"
|
||||
cta: Get Started.
|
||||
link: templates/
|
||||
color_classes: bg-primary-color-light black
|
||||
image: /images/home-page-templating-example.png
|
||||
copy: "Hugo's Go-based templating provides just the right amount of logic to build anything from the simple to complex."
|
||||
title: The world's fastest framework for building websites
|
||||
description: Hugo is one of the most popular open-source static site generators. With its amazing speed and flexibility, Hugo makes building websites fun again.
|
||||
---
|
||||
|
||||
Hugo is one of the most popular open-source static site generators. With its amazing speed and flexibility, Hugo makes building websites fun again.
|
||||
|
|
|
|||
|
|
@ -1,16 +1,9 @@
|
|||
---
|
||||
title: About Hugo
|
||||
linktitle: About
|
||||
linkTitle: About
|
||||
description: Learn about Hugo and its features, privacy protections, and security model.
|
||||
categories: []
|
||||
keywords: []
|
||||
menu:
|
||||
docs:
|
||||
identifier: about-hugo-in-this-section
|
||||
parent: about
|
||||
weight: 10
|
||||
weight: 10
|
||||
aliases: [/about-hugo/,/docs/]
|
||||
---
|
||||
|
||||
Learn about Hugo and its features, privacy protections, and security model.
|
||||
|
|
|
|||
|
|
@ -1,14 +1,9 @@
|
|||
---
|
||||
title: Features
|
||||
description: Hugo's rich and powerful feature set provides the framework and tools to create static sites that build in seconds, often less.
|
||||
categories: [about]
|
||||
categories: []
|
||||
keywords: []
|
||||
menu:
|
||||
docs:
|
||||
parent: about
|
||||
weight: 30
|
||||
weight: 30
|
||||
toc: true
|
||||
weight: 20
|
||||
---
|
||||
|
||||
## Framework
|
||||
|
|
@ -61,7 +56,7 @@ toc: true
|
|||
: Syntactically highlight code examples using Hugo's embedded syntax highlighter, enabled by default for fenced code blocks in Markdown. The syntax highlighter supports hundreds of code languages and dozens of styles.
|
||||
|
||||
[Shortcodes]
|
||||
: Use Hugo's embedded shortcodes, or create your own, to insert complex content. For example, use shortcodes to include `audio` and `video` elements, render tables from local or remote data sources, insert snippets from other pages, and more.
|
||||
: Use Hugo's embedded shortcodes, or create your own, to insert complex content. For example, use shortcodes to include `audio` and `video` elements, render tables from local or remote data sources, insert snippets from other pages, and more.
|
||||
|
||||
## Content management
|
||||
|
||||
|
|
@ -83,7 +78,7 @@ toc: true
|
|||
## Asset pipelines
|
||||
|
||||
[Image processing]
|
||||
: Convert, resize, crop, rotate, adjust colors, apply filters, overlay text and images, and extract EXIF data.
|
||||
: Convert, resize, crop, rotate, adjust colors, apply filters, overlay text and images, and extract EXIF data.
|
||||
|
||||
[JavaScript bundling]
|
||||
: Transpile TypeScript and JSX to JavaScript, bundle, tree shake, minify, create source maps, and perform SRI hashing.
|
||||
|
|
@ -107,18 +102,18 @@ toc: true
|
|||
|
||||
[Multilingual]: /content-management/multilingual/
|
||||
[Multiplatform]: /installation/
|
||||
[Output formats]: /templates/output-formats/
|
||||
[Output formats]: /configuration/output-formats/
|
||||
[Templates]: /templates/introduction/
|
||||
[Themes]: https://themes.gohugo.io/
|
||||
[Modules]: /hugo-modules/
|
||||
[Privacy]: /about/privacy/
|
||||
[Privacy]: /configuration/privacy/
|
||||
[Security]: /about/security/
|
||||
|
||||
[Content formats]: /content-management/formats/
|
||||
[CommonMark]: https://spec.commonmark.org/current/
|
||||
[GitHub Flavored Markdown]: https://github.github.com/gfm/
|
||||
[Markdown attributes]: /content-management/markdown-attributes/
|
||||
[Markdown extensions]: /getting-started/configuration-markup/#goldmark-extensions
|
||||
[Markdown extensions]: /configuration/markup/#extensions
|
||||
[Markdown render hooks]: /render-hooks/introduction/
|
||||
[Diagrams]: /content-management/diagrams/
|
||||
[Mathematics]: /content-management/mathematics/
|
||||
|
|
@ -137,5 +132,5 @@ toc: true
|
|||
[Tailwind CSS processing]: /functions/css/tailwindcss/
|
||||
|
||||
[Caching]: /functions/partials/includecached/
|
||||
[Segmentation]: /getting-started/configuration/#configure-segments
|
||||
[Minification]: /getting-started/configuration/#configure-minify
|
||||
[Segmentation]: /configuration/segments/
|
||||
[Minification]: /configuration/minify/
|
||||
|
|
|
|||
|
|
@ -1,14 +1,9 @@
|
|||
---
|
||||
title: Introduction
|
||||
description: Hugo is a static site generator written in Go, optimized for speed and designed for flexibility.
|
||||
categories: [about]
|
||||
categories: []
|
||||
keywords: []
|
||||
menu:
|
||||
docs:
|
||||
identifier: about-introduction
|
||||
parent: about
|
||||
weight: 20
|
||||
weight: 20
|
||||
weight: 10
|
||||
aliases: [/about/what-is-hugo/,/about/benefits/]
|
||||
---
|
||||
|
||||
|
|
@ -32,8 +27,8 @@ Learn more about Hugo's [features], [privacy protections], and [security model].
|
|||
[Go]: https://go.dev
|
||||
[Hugo Modules]: /hugo-modules/
|
||||
[static site generator]: https://en.wikipedia.org/wiki/Static_site_generator
|
||||
[features]: /about/features
|
||||
[security model]: /about/security
|
||||
[privacy protections]: /about/privacy
|
||||
[features]: /about/features/
|
||||
[security model]: about/security/
|
||||
[privacy protections]: /configuration/privacy
|
||||
|
||||
{{< youtube 0RKpf3rK57I >}}
|
||||
|
|
|
|||
|
|
@ -1,18 +1,13 @@
|
|||
---
|
||||
title: License
|
||||
description: Hugo is released under the Apache 2.0 license.
|
||||
categories: [about]
|
||||
keywords: [apache]
|
||||
menu:
|
||||
docs:
|
||||
parent: about
|
||||
weight: 60
|
||||
weight: 60
|
||||
categories: []
|
||||
keywords: []
|
||||
weight: 40
|
||||
---
|
||||
|
||||
## Apache License
|
||||
|
||||
|
||||
_Version 2.0, January 2004_
|
||||
_<http://www.apache.org/licenses/>_
|
||||
|
||||
|
|
|
|||
|
|
@ -2,71 +2,57 @@
|
|||
title: Security model
|
||||
linkTitle: Security
|
||||
description: A summary of Hugo's security model.
|
||||
categories: [about]
|
||||
keywords: [security,privacy]
|
||||
menu:
|
||||
docs:
|
||||
parent: about
|
||||
weight: 50
|
||||
weight: 50
|
||||
toc: true
|
||||
categories: []
|
||||
keywords: []
|
||||
weight: 30
|
||||
aliases: [/about/security-model/]
|
||||
---
|
||||
|
||||
## Runtime security
|
||||
|
||||
Hugo produces static output, so once built, the runtime is the browser (assuming the output is HTML) and any server (API) that you integrate with.
|
||||
Hugo generates static websites, meaning the final output runs directly in the browser and interacts with any integrated APIs. However, during development and site building, the `hugo` executable itself is the runtime environment.
|
||||
|
||||
But when developing and building your site, the runtime is the `hugo` executable. Securing a runtime can be [a real challenge](https://blog.logrocket.com/how-to-protect-your-node-js-applications-from-malicious-dependencies-5f2e60ea08f9/).
|
||||
Securing a runtime is a complex task. Hugo addresses this through a robust sandboxing approach and a strict security policy with default protections. Key features include:
|
||||
|
||||
**Hugo's main approach is that of sandboxing and a security policy with strict defaults:**
|
||||
- Virtual file system: Hugo employs a virtual file system, limiting file access. Only the main project, not external components, can access files or directories outside the project root.
|
||||
- Read-Only access: User-defined components have read-only access to the file system, preventing unintended modifications.
|
||||
- Controlled external binaries: While Hugo utilizes external binaries for features like Asciidoctor support, these are strictly predefined with specific flags and are disabled by default. The [security policy] details these limitations.
|
||||
- No arbitrary commands: To mitigate risks, Hugo intentionally avoids implementing general functions that would allow users to execute arbitrary operating system commands.
|
||||
|
||||
* Hugo has a virtual file system and only the main project (not third-party components) is allowed to mount directories or files outside the project root.
|
||||
* User-defined components have read-only access to the filesystem.
|
||||
* We shell out to some external binaries to support [Asciidoctor](/content-management/formats/#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.
|
||||
This combination of sandboxing and strict defaults effectively minimizes potential security vulnerabilities during the Hugo build process.
|
||||
|
||||
## Security policy
|
||||
|
||||
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).
|
||||
|
||||
{{< code-toggle config=security />}}
|
||||
|
||||
By default, Hugo permits the [`resources.GetRemote`] function to download files with media types corresponding to an internal allow list. To add media types to the allow list:
|
||||
|
||||
[`resources.GetRemote`]: /functions/resources/getremote
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[security.http]
|
||||
mediaTypes = ['^image/avif$']
|
||||
{{< /code-toggle >}}
|
||||
|
||||
Note that these and other configuration settings in Hugo can be overridden by the OS environment. For example, if you want to block all remote HTTP fetching of data:
|
||||
|
||||
```txt
|
||||
HUGO_SECURITY_HTTP_URLS=none hugo
|
||||
```
|
||||
[security policy]: /configuration/security/
|
||||
|
||||
## Dependency security
|
||||
|
||||
Hugo is built as a static binary using [Go Modules](https://github.com/golang/go/wiki/Modules) to manage its dependencies. Go Modules have several safeguards, one of them being the `go.sum` file. This is a database of the expected cryptographic checksums of all of your dependencies, including transitive dependencies.
|
||||
Hugo utilizes [Go Modules] to manage its dependencies, compiling as a static binary. Go Modules create a `go.sum` file, a critical security feature. This file acts as a database, storing the expected cryptographic checksums of all dependencies, including those required indirectly (transitive dependencies).
|
||||
|
||||
[Hugo Modules](/hugo-modules/) is a feature built on top of the functionality of Go Modules. Like Go Modules, a Hugo project using Hugo Modules will have a `go.sum` file. We recommend that you commit this file to your version control system. The Hugo build will fail if there is a checksum mismatch, which would be an indication of [dependency tampering](https://julienrenaux.fr/2019/12/20/github-actions-security-risk/).
|
||||
[Hugo Modules], which extend Go Modules' functionality, also produce a `go.sum` file. To ensure dependency integrity, commit this `go.sum` file to your version control. If Hugo detects a checksum mismatch during the build process, it will fail, indicating a possible attempt to [tamper with your project's dependencies].
|
||||
|
||||
[Go Modules]: https://go.dev/wiki/Modules#modules
|
||||
[Hugo Modules]: /hugo-modules/
|
||||
[tamper with your project's dependencies]: https://julienrenaux.fr/2019/12/20/github-actions-security-risk/
|
||||
|
||||
## Web application security
|
||||
|
||||
These are the security threats as defined by [OWASP](https://en.wikipedia.org/wiki/OWASP).
|
||||
Hugo's security philosophy is rooted in established security standards, primarily aligning with the threats defined by [OWASP]. For HTML output, Hugo operates under a clear trust model. This model assumes that template and configuration authors, the developers, are trustworthy. However, the data supplied to these templates is inherently considered untrusted. This distinction is crucial for understanding how Hugo handles potential security risks.
|
||||
|
||||
For HTML output, this is the core security model:
|
||||
[OWASP]: https://en.wikipedia.org/wiki/OWASP
|
||||
|
||||
<https://pkg.go.dev/html/template#hdr-Security_Model>
|
||||
To prevent unintended escaping of data that developers know is safe, Hugo provides [`safe`] functions, such as [`safeHTML`]. These functions allow developers to explicitly mark data as trusted, bypassing the default escaping mechanisms. This is essential for scenarios where data is generated or sourced from reliable sources. However, an exception exists: enabling [inline shortcodes]. By activating this feature, you are implicitly trusting the logic within the shortcodes and the data contained within your content files.
|
||||
|
||||
In short:
|
||||
[`safeHTML`]: /functions/safe/html/
|
||||
[inline shortcodes]: /content-management/shortcodes/#inline
|
||||
|
||||
Template and configuration authors (you) are trusted, but the data you send in is not.
|
||||
This is why you sometimes need to use the _safe_ functions, such as `safeHTML`, to avoid escaping of data you know is safe.
|
||||
There is one exception to the above, as noted in the documentation: If you enable inline shortcodes, you also say that the shortcodes and data handling in content files are trusted, as those macros are treated as pure text.
|
||||
It may be worth adding that Hugo is a static site generator with no concept of dynamic user input.
|
||||
It's vital to remember that Hugo is a static site generator. This architectural choice significantly reduces the attack surface by eliminating the complexities and vulnerabilities associated with dynamic user input. Unlike dynamic websites, Hugo generates static HTML files, minimizing the risk of real-time attacks. Regarding content, Hugo's default Markdown renderer is [configured to sanitize] potentially unsafe content. This default behavior ensures that potentially malicious code or scripts are removed or escaped. However, this setting can be reconfigured if you have a high degree of confidence in the safety of your content sources.
|
||||
|
||||
For content, the default Markdown renderer is [configured](/getting-started/configuration-markup) to remove or escape potentially unsafe content. This behavior can be reconfigured if you trust your content.
|
||||
[configured to sanitize]: /configuration/markup/#rendererunsafe
|
||||
|
||||
In essence, Hugo prioritizes secure output by establishing a clear trust boundary between developers and data. By default, it errs on the side of caution, sanitizing potentially unsafe content and escaping data. Developers have the flexibility to adjust these defaults through [`safe`] functions and [configuration options], but they must do so with a clear understanding of the security implications. Hugo's static site generation model further strengthens its security posture by minimizing dynamic vulnerabilities.
|
||||
|
||||
[`safe`]: /functions/safe
|
||||
[configuration options]: /configuration/security
|
||||
|
||||
## Configuration
|
||||
|
||||
See [configure security](/configuration/security/).
|
||||
|
|
|
|||
|
|
@ -4,9 +4,5 @@ linkTitle: CLI
|
|||
description: Use the command line interface (CLI) to manage your site.
|
||||
categories: []
|
||||
keywords: []
|
||||
menu:
|
||||
docs:
|
||||
parent: commands
|
||||
weight: 10
|
||||
weight: 10
|
||||
---
|
||||
|
|
|
|||
|
|
@ -72,6 +72,7 @@ hugo [flags]
|
|||
* [hugo completion](/commands/hugo_completion/) - Generate the autocompletion script for the specified shell
|
||||
* [hugo config](/commands/hugo_config/) - Display site configuration
|
||||
* [hugo convert](/commands/hugo_convert/) - Convert front matter to another format
|
||||
* [hugo deploy](/commands/hugo_deploy/) - Deploy your site to a cloud provider
|
||||
* [hugo env](/commands/hugo_env/) - Display version and environment info
|
||||
* [hugo gen](/commands/hugo_gen/) - Generate documentation and syntax highlighting styles
|
||||
* [hugo import](/commands/hugo_import/) - Import a site from another system
|
||||
|
|
|
|||
7
docs/content/en/configuration/_index.md
Normal file
7
docs/content/en/configuration/_index.md
Normal file
|
|
@ -0,0 +1,7 @@
|
|||
---
|
||||
title: Configuration
|
||||
description: Configure your site.
|
||||
categories: []
|
||||
keywords: []
|
||||
weight: 10
|
||||
---
|
||||
362
docs/content/en/configuration/all.md
Normal file
362
docs/content/en/configuration/all.md
Normal file
|
|
@ -0,0 +1,362 @@
|
|||
---
|
||||
title: All settings
|
||||
description: The complete list of Hugo configuration settings.
|
||||
categories: []
|
||||
keywords: []
|
||||
weight: 20
|
||||
aliases: [/getting-started/configuration/]
|
||||
---
|
||||
|
||||
## Settings
|
||||
|
||||
archetypeDir
|
||||
: (`string`) The designated directory for [archetypes](g). Default is `archetypes`. {{% module-mounts-note %}}
|
||||
|
||||
assetDir
|
||||
: (`string`) The designated directory for [global resources](g). Default is `assets`. {{% module-mounts-note %}}
|
||||
|
||||
baseURL
|
||||
: (`string`) The absolute URL of your published site including the protocol, host, path, and a trailing slash.
|
||||
|
||||
build
|
||||
: See [configure build](/configuration/build/).
|
||||
|
||||
buildDrafts
|
||||
: (`bool`) Whether to include draft content when building a site. Default is `false`.
|
||||
|
||||
buildExpired
|
||||
: (`bool`) Whether to include expired content when building a site. Default is `false`.
|
||||
|
||||
buildFuture
|
||||
: (`bool`) Whether to include future content when building a site. Default is `false`.
|
||||
|
||||
cacheDir
|
||||
: (`string`) The designated cache directory. See [details](#cache-directory).
|
||||
|
||||
caches
|
||||
: See [configure file caches](/configuration/caches/).
|
||||
|
||||
canonifyURLs
|
||||
: (`bool`) See [details](/content-management/urls/#canonical-urls) before enabling this feature. Default is `false`.
|
||||
|
||||
capitalizeListTitles
|
||||
: {{< new-in 0.123.3 />}}
|
||||
: (`bool`) Whether to capitalize automatic list titles. Applicable to section, taxonomy, and term pages. Default is `true`. Use the [`titleCaseStyle`](#titlecasestyle) setting to configure capitalization rules.
|
||||
|
||||
cascade
|
||||
: See [configure cascade](/configuration/cascade/).
|
||||
|
||||
cleanDestinationDir
|
||||
: (`bool`) Whether to remove files from the site's destination directory that do not have corresponding files in the `static` directory during the build. Default is `false`.
|
||||
|
||||
contentDir
|
||||
: (`string`) The designated directory for content files. Default is `content`. {{% module-mounts-note %}}
|
||||
|
||||
copyright
|
||||
: (`string`) The copyright notice for a site, typically displayed in the footer.
|
||||
|
||||
dataDir
|
||||
: (`string`) The designated directory for data files. Default is `data`. {{% module-mounts-note %}}
|
||||
|
||||
defaultContentLanguage
|
||||
: (`string`) The project's default language key, conforming to the syntax described in [RFC 5646]. This value must match one of the defined language keys. Default is `en`.
|
||||
|
||||
defaultContentLanguageInSubdir
|
||||
: (`bool`) Whether to publish the default language site to a subdirectory matching the `defaultContentLanguage`. Default is `false`.
|
||||
|
||||
defaultOutputFormat
|
||||
: (`string`) The default output format for the site. If unspecified, the first available format in the defined order (by weight, then alphabetically) will be used.
|
||||
|
||||
deployment
|
||||
: See [configure deployment](/configuration/deployment/).
|
||||
|
||||
disableAliases
|
||||
: (`bool`) Whether to disable generation of alias redirects. Even if this option is enabled, the defined aliases will still be present on the page. This allows you to manage redirects separately, for example, by generating 301 redirects in an `.htaccess` file or a Netlify `_redirects` file using a custom output format. Default is `false`.
|
||||
|
||||
disableDefaultLanguageRedirect
|
||||
: {{< new-in 0.140.0 />}}
|
||||
: (`bool`) Whether to disable generation of the alias redirect to the default language when `DefaultContentLanguageInSubdir` is `true`. Default is `false`.
|
||||
|
||||
disableHugoGeneratorInject
|
||||
: (`bool`) Whether to disable injection of a `<meta name="generator">` tag into the home page. Default is `false`.
|
||||
|
||||
disableKinds
|
||||
: (`[]string`) A slice of page [kinds](g) to disable during the build process, any of `404`, `home`, `page`, `robotstxt`, `rss`, `section`, `sitemap`, `taxonomy`, or `term`.
|
||||
|
||||
disableLanguages
|
||||
: (`[]string]`) A slice of language keys representing the languages to disable during the build process. Although this is functional, consider using the [`disabled`] key under each language instead.
|
||||
|
||||
disableLiveReload
|
||||
: (`bool`) Whether to disable automatic live reloading of the browser window. Default is `false`.
|
||||
|
||||
disablePathToLower
|
||||
: (`bool`) Whether to disable transformation of page URLs to lower case.
|
||||
|
||||
enableEmoji
|
||||
: (`bool`) Whether to allow emoji in Markdown. Default is `false`.
|
||||
|
||||
enableGitInfo
|
||||
: (`bool`) For sites under Git version control, whether to enable the [`GitInfo`] object for each page. With the [default front matter configuration], the `Lastmod` method on a `Page` object will return the Git author date. Default is `false`.
|
||||
|
||||
enableMissingTranslationPlaceholders
|
||||
: (`bool`) Whether to show a placeholder instead of the default value or an empty string if a translation is missing. Default is `false`.
|
||||
|
||||
enableRobotsTXT
|
||||
: (`bool`) Whether to enable generation of a `robots.txt` file. Default is `false`.
|
||||
|
||||
environment
|
||||
: (`string`) The build environment. Default is `production` when running `hugo` and `development` when running `hugo server`.
|
||||
|
||||
frontmatter
|
||||
: See [configure front matter](/configuration/front-matter/).
|
||||
|
||||
hasCJKLanguage
|
||||
: (`bool`) Whether to automatically detect [CJK](g) languages in content. Affects the values returned by the [`WordCount`] and [`FuzzyWordCount`] methods. Default is `false`.
|
||||
|
||||
HTTPCache
|
||||
: See [configure HTTP cache](/configuration/http-cache/).
|
||||
|
||||
i18nDir
|
||||
: (`string`) The designated directory for translation tables. Default is `i18n`. {{% module-mounts-note %}}
|
||||
|
||||
ignoreCache
|
||||
: (`bool`) Whether to ignore the cache directory. Default is `false`.
|
||||
|
||||
ignoreFiles
|
||||
: (`[]string]`) A slice of [regular expressions](g) used to exclude specific files from a build. These expressions are matched against the absolute file path and apply to files within the `content`, `data`, and `i18n` directories. For more advanced file exclusion options, see the section on [module mounts].
|
||||
|
||||
ignoreLogs
|
||||
: (`[]string`) A slice of message identifiers corresponding to warnings and errors you wish to suppress. See [`erroridf`] and [`warnidf`].
|
||||
|
||||
ignoreVendorPaths
|
||||
: (`string`) A [glob](g) pattern matching the module paths to exclude from the `_vendor` directory.
|
||||
|
||||
imaging
|
||||
: See [configure imaging](/configuration/imaging/).
|
||||
|
||||
languageCode
|
||||
: (`string`) The site's language tag, conforming to the syntax described in [RFC 5646]. This value does not affect translations or localization. Hugo uses this value to populate:
|
||||
|
||||
- The `language` element in the [embedded RSS template]
|
||||
- The `lang` attribute of the `html` element in the [embedded alias template]
|
||||
- The `og:locale` `meta` element in the [embedded Open Graph template]
|
||||
|
||||
When present in the root of the configuration, this value is ignored if one or more language keys exists. Please specify this value independently for each language key.
|
||||
|
||||
languages
|
||||
: See [configure languages](/configuration/languages/).
|
||||
|
||||
layoutDir
|
||||
: (`string`) The designated directory for templates. Default is `layouts`. {{% module-mounts-note %}}
|
||||
|
||||
mainSections
|
||||
: (`string` or `[]string`) The main sections of a site. If set, the [`MainSections`] method on the `Site` object returns the given sections, otherwise it returns the section with the most pages.
|
||||
|
||||
markup
|
||||
: See [configure markup](/configuration/markup/).
|
||||
|
||||
mediaTypes
|
||||
: See [configure media types](/configuration/media-types/).
|
||||
|
||||
menus
|
||||
: See [configure menus](/configuration/menus/).
|
||||
|
||||
minify
|
||||
: See [configure minify](/configuration/minify/).
|
||||
|
||||
module
|
||||
: See [configure modules](/configuration/module/).
|
||||
|
||||
newContentEditor
|
||||
: (`string`) The editor to use when creating new content.
|
||||
|
||||
noBuildLock
|
||||
: (`bool`) Whether to disable creation of the `.hugo_build.lock` file. Default is `false`.
|
||||
|
||||
noChmod
|
||||
: (`bool`) Whether to disable synchronization of file permission modes. Default is `false`.
|
||||
|
||||
noTimes
|
||||
: (`bool`) Whether to disable synchronization of file modification times. Default is `false`.
|
||||
|
||||
outputFormats
|
||||
: See [configure output formats](/configuration/output-formats/).
|
||||
|
||||
outputs
|
||||
: See [configure outputs](/configuration/outputs/).
|
||||
|
||||
page
|
||||
: See [configure page](/configuration/page/).
|
||||
|
||||
pagination
|
||||
: See [configure pagination](/configuration/pagination/).
|
||||
|
||||
panicOnWarning
|
||||
: (`bool`) Whether to panic on the first WARNING. Default is `false`.
|
||||
|
||||
params
|
||||
: See [configure params](/configuration/params/).
|
||||
|
||||
permalinks
|
||||
: See [configure permalinks](/configuration/permalinks/).
|
||||
|
||||
pluralizeListTitles
|
||||
: (`bool`) Whether to pluralize automatic list titles. Applicable to section pages. Default is `true`.
|
||||
|
||||
printI18nWarnings
|
||||
: (`bool`) Whether to log WARNINGs for each missing translation. Default is `false`.
|
||||
|
||||
printPathWarnings
|
||||
: (`bool`) Whether to log WARNINGs when Hugo publishes two or more files to the same path. Default is `false`.
|
||||
|
||||
printUnusedTemplates
|
||||
: (`bool`) Whether to log WARNINGs for each unused template. Default is `false`.
|
||||
|
||||
privacy
|
||||
: See [configure privacy](/configuration/privacy/).
|
||||
|
||||
publishDir
|
||||
: (`string`) The designated directory for publishing the site. Default is `public`.
|
||||
|
||||
refLinksErrorLevel
|
||||
: (`string`) The logging error level to use when the `ref` and `relref` functions, methods, and shortcodes are unable to resolve a reference to a page. Either `ERROR` or `WARNING`. Any `ERROR` will fail the build. Default is `ERROR`.
|
||||
|
||||
refLinksNotFoundURL
|
||||
: (`string`) The URL to return when the `ref` and `relref` functions, methods, and shortcodes are unable to resolve a reference to a page.
|
||||
|
||||
related
|
||||
: See [configure related content](/configuration/related-content/).
|
||||
|
||||
relativeURLs
|
||||
: (`bool`) See [details](/content-management/urls/#relative-urls) before enabling this feature. Default is `false`.
|
||||
|
||||
removePathAccents
|
||||
: (`bool`) Whether to remove [non-spacing marks](https://www.compart.com/en/unicode/category/Mn) from [composite characters](https://en.wikipedia.org/wiki/Precomposed_character) in content paths. Default is `false`.
|
||||
|
||||
renderSegments
|
||||
: {{< new-in 0.124.0 />}}
|
||||
: (`[]string`) A slice of [segments](g) to render. If omitted, all segments are rendered. This option is typically set via a command-line flag, such as `hugo --renderSegments segment1,segment2`. The provided segment names must correspond to those defined in the [`segments`] configuration.
|
||||
|
||||
resourceDir
|
||||
: (`string`) The designated directory for caching output from [asset pipelines](g). Default is `resources`.
|
||||
|
||||
security
|
||||
: See [configure security](/configuration/security/).
|
||||
|
||||
sectionPagesMenu
|
||||
: (`string`) When set, each top-level section will be added to the menu identified by the provided value. See [details](/content-management/menus/#define-automatically).
|
||||
|
||||
segments
|
||||
: See [configure segments](/configuration/segments/).
|
||||
|
||||
server
|
||||
: See [configure server](/configuration/server/).
|
||||
|
||||
services
|
||||
: See [configure services](/configuration/services/).
|
||||
|
||||
sitemap
|
||||
: See [configure sitemap](/configuration/sitemap/).
|
||||
|
||||
staticDir
|
||||
: (`string`) The designated directory for static files. Default is `static`. {{% module-mounts-note %}}
|
||||
|
||||
summaryLength
|
||||
: (`int`) Applicable to [automatic summaries], the minimum number of words returned by the [`Summary`] method on a `Page` object. The `Summary` method will return content truncated at the paragraph boundary closest to the specified `summaryLength`, but at least this minimum number of words.
|
||||
|
||||
taxonomies
|
||||
: See [configure taxonomies](/configuration/taxonomies/).
|
||||
|
||||
templateMetrics
|
||||
: (`bool`) Whether to print template execution metrics to the console. Default is `false`. See [details](/troubleshooting/performance/#template-metrics).
|
||||
|
||||
templateMetricsHints
|
||||
: (`bool`) Whether to print template execution improvement hints to the console. Applicable when `templateMetrics` is `true`. Default is `false`. See [details](/troubleshooting/performance/#template-metrics).
|
||||
|
||||
theme
|
||||
: (`string` or `[]string`) The [theme](g) to use. Multiple themes can be listed, with precedence given from left to right. See [details](/hugo-modules/theme-components/).
|
||||
|
||||
themesDir
|
||||
: (`string`) The designated directory for themes. Default is `themes`.
|
||||
|
||||
timeout
|
||||
: (`string`) The timeout for generating page content, either as a [duration] or in seconds. This timeout is used to prevent infinite recursion during content generation. You may need to increase this value if your pages take a long time to generate, for example, due to extensive image processing or reliance on remote content. Default is `30s`.
|
||||
|
||||
timeZone
|
||||
: (`string`) The time zone used to parse dates without time zone offsets, including front matter date fields and values passed to the [`time.AsTime`] and [`time.Format`] template functions. The list of valid values may be system dependent, but should include `UTC`, `Local`, and any location in the [IANA Time Zone Database]. For example, `America/Los_Angeles` and `Europe/Oslo` are valid time zones.
|
||||
|
||||
title
|
||||
: (`string`) The site title.
|
||||
|
||||
titleCaseStyle
|
||||
: (`string`) The capitalization rules to follow when Hugo automatically generates a section title, or when using the [`strings.Title`] function. One of `ap`, `chicago`, `go`, `firstupper`, or `none`. Default is `ap`. See [details](#title-case-style).
|
||||
|
||||
uglyurls
|
||||
: See [configure ugly URLs](/configuration/ugly-urls/).
|
||||
|
||||
## Cache directory
|
||||
|
||||
Hugo's file cache directory is configurable via the [`cacheDir`] configuration option or the `HUGO_CACHEDIR` environment variable. If neither is set, Hugo will use, in order of preference:
|
||||
|
||||
1. If running on Netlify: `/opt/build/cache/hugo_cache/`. This means that if you run your builds on Netlify, all caches configured with `:cacheDir` will be saved and restored on the next build. For other [CI/CD](g) vendors, please read their documentation. For an CircleCI example, see [this configuration].
|
||||
1. In a `hugo_cache` directory below the OS user cache directory as defined by Go's [os.UserCacheDir] function. On Unix systems, per the [XDG base directory specification], this is `$XDG_CACHE_HOME` if non-empty, else `$HOME/.cache`. On MacOS, this is `$HOME/Library/Caches`. On Windows, this is`%LocalAppData%`. On Plan 9, this is `$home/lib/cache`.
|
||||
1. In a `hugo_cache_$USER` directory below the OS temp dir.
|
||||
|
||||
To determine the current `cacheDir`:
|
||||
|
||||
```sh
|
||||
hugo config | grep cachedir
|
||||
```
|
||||
|
||||
## Title case style
|
||||
|
||||
Hugo's [`titleCaseStyle`] setting governs capitalization for automatically generated section titles and the [`strings.Title`] function. By default, it follows the capitalization rules published in the Associated Press Stylebook. Change this setting to use other capitalization rules.
|
||||
|
||||
ap
|
||||
: Use the capitalization rules published in the [Associated Press Stylebook]. This is the default.
|
||||
|
||||
chicago
|
||||
: Use the capitalization rules published in the [Chicago Manual of Style].
|
||||
|
||||
go
|
||||
: Capitalize the first letter of every word.
|
||||
|
||||
firstupper
|
||||
: Capitalize the first letter of the first word.
|
||||
|
||||
none
|
||||
: Disable transformation of automatic section titles, and disable the transformation performed by the `strings.Title` function. This is useful if you would prefer to manually capitalize section titles as needed, and to bypass opinionated theme usage of the `strings.Title` function.
|
||||
|
||||
## Localized settings
|
||||
|
||||
Some configuration settings, such as menus and custom parameters, can be defined separately for each language. See [configure languages](/configuration/languages/#localized-settings).
|
||||
|
||||
[`cacheDir`]: #cachedir
|
||||
[`disabled`]: /configuration/languages/#disabled
|
||||
[`erroridf`]: /functions/fmt/erroridf/
|
||||
[`FuzzyWordCount`]: /methods/page/fuzzywordcount/
|
||||
[`GitInfo`]: /methods/page/gitinfo/
|
||||
[`MainSections`]: /methods/site/mainsections/
|
||||
[`segments`]: /configuration/segments/
|
||||
[`strings.Title`]: /functions/strings/title/
|
||||
[`strings.Title`]: /functions/strings/title
|
||||
[`Summary`]: /methods/page/summary/
|
||||
[`time.AsTime`]: /functions/time/astime/
|
||||
[`time.Format`]: /functions/time/format/
|
||||
[`titleCaseStyle`]: #titlecasestyle
|
||||
[`warnidf`]: /functions/fmt/warnidf/
|
||||
[`WordCount`]: /methods/page/wordcount/
|
||||
[Associated Press Stylebook]: https://www.apstylebook.com/
|
||||
[automatic summaries]: /content-management/summaries/#automatic-summary
|
||||
[Chicago Manual of Style]: https://www.chicagomanualofstyle.org/home.html
|
||||
[default front matter configuration]: /configuration/front-matter/
|
||||
[duration]: https://pkg.go.dev/time#Duration
|
||||
[embedded alias template]: {{% eturl alias %}}
|
||||
[embedded Open Graph template]: {{% eturl opengraph %}}
|
||||
[embedded RSS template]: {{% eturl rss %}}
|
||||
[IANA Time Zone Database]: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
|
||||
[module mounts]: /configuration/module/#mounts
|
||||
[os.UserCacheDir]: https://pkg.go.dev/os#UserCacheDir
|
||||
[RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646#section-2.1
|
||||
[this configuration]: https://github.com/bep/hugo-sass-test/blob/6c3960a8f4b90e8938228688bc49bdcdd6b2d99e/.circleci/config.yml
|
||||
[XDG base directory specification]: https://specifications.freedesktop.org/basedir-spec/latest/
|
||||
81
docs/content/en/configuration/build.md
Normal file
81
docs/content/en/configuration/build.md
Normal file
|
|
@ -0,0 +1,81 @@
|
|||
---
|
||||
title: Configure build
|
||||
linkTitle: Build
|
||||
description: Configure global build options.
|
||||
categories: []
|
||||
keywords: []
|
||||
aliases: [/getting-started/configuration-build/]
|
||||
---
|
||||
|
||||
The `build` configuration section contains global build-related configuration options.
|
||||
|
||||
{{< code-toggle config=build />}}
|
||||
|
||||
buildStats
|
||||
: See the [build stats](#build-stats) section below.
|
||||
|
||||
cachebusters
|
||||
: See the [cache busters](#cache-busters) section below.
|
||||
|
||||
noJSConfigInAssets
|
||||
: (`bool`) Whether to disable writing a `jsconfig.json` in your `assets` directory with mapping of imports from running [js.Build](/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.
|
||||
|
||||
useResourceCacheWhen
|
||||
: (`string`) When to use the resource file cache, one of `never`, `fallback`, or `always`. Applicable when transpiling Sass to CSS. Default is `fallback`.
|
||||
|
||||
## Cache busters
|
||||
|
||||
The `build.cachebusters` configuration option was added to support development using Tailwind 3.x's JIT compiler where a `build` configuration may look like this:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[build]
|
||||
[build.buildStats]
|
||||
enable = true
|
||||
[[build.cachebusters]]
|
||||
source = "assets/watching/hugo_stats\\.json"
|
||||
target = "styles\\.css"
|
||||
[[build.cachebusters]]
|
||||
source = "(postcss|tailwind)\\.config\\.js"
|
||||
target = "css"
|
||||
[[build.cachebusters]]
|
||||
source = "assets/.*\\.(js|ts|jsx|tsx)"
|
||||
target = "js"
|
||||
[[build.cachebusters]]
|
||||
source = "assets/.*\\.(.*)$"
|
||||
target = "$1"
|
||||
{{< /code-toggle >}}
|
||||
|
||||
When `buildStats` is enabled, Hugo writes a `hugo_stats.json` file on each build with HTML classes etc. that's used in the rendered output. Changes to this file will trigger a rebuild of the `styles.css` file. You also need to add `hugo_stats.json` to Hugo's server watcher. See [Hugo Starter Tailwind Basic](https://github.com/bep/hugo-starter-tailwind-basic) for a running example.
|
||||
|
||||
source
|
||||
: (`string`) A [regular expression](g) matching file(s) relative to one of the virtual component directories in Hugo, typically `assets/...`.
|
||||
|
||||
target
|
||||
: (`string`) A [regular expression](g) matching the keys in the resource cache that should be expired when `source` changes. You can use the matching regexp groups from `source` in the expression, e.g. `$1`.
|
||||
|
||||
## Build stats
|
||||
|
||||
{{< code-toggle config=build.buildStats />}}
|
||||
|
||||
enable
|
||||
: (`bool`) Whether to create a `hugo_stats.json` file in the root of your project. This file contains arrays of the `class` attributes, `id` attributes, and tags of every HTML element within your published site. Use this file as data source when [removing unused CSS] from your site. This process is also known as pruning, purging, or tree shaking. Default is `false`.
|
||||
|
||||
[removing unused CSS]: /functions/resources/postprocess/
|
||||
|
||||
disableIDs
|
||||
: (`bool`) Whether to exclude `id` attributes. Default is `false`.
|
||||
|
||||
disableTags
|
||||
: (`bool`) Whether to exclude element tags. Default is `false`.
|
||||
|
||||
disableClasses
|
||||
: (`bool`) Whether to exclude `class` attributes. Default is `false`.
|
||||
|
||||
> [!note]
|
||||
> Given that CSS purging is typically limited to production builds, place the `buildStats` object below [`config/production`].
|
||||
>
|
||||
> Built for speed, there may be "false positive" detections (e.g., HTML elements that are not HTML elements) while parsing the published site. These "false positives" are infrequent and inconsequential.
|
||||
|
||||
Due to the nature of partial server builds, new HTML entities are added while the server is running, but old values will not be removed until you restart the server or run a regular `hugo` build.
|
||||
|
||||
[`config/production`]: /configuration/introduction/#configuration-directory
|
||||
30
docs/content/en/configuration/caches.md
Normal file
30
docs/content/en/configuration/caches.md
Normal file
|
|
@ -0,0 +1,30 @@
|
|||
---
|
||||
title: Configure file caches
|
||||
linkTitle: Caches
|
||||
description: Configure file caches.
|
||||
categories: []
|
||||
keywords: []
|
||||
---
|
||||
|
||||
This is the default configuration:
|
||||
|
||||
{{< code-toggle config=caches />}}
|
||||
|
||||
## Keys
|
||||
|
||||
dir
|
||||
: (`string`) The absolute file system path where the cached files will be stored. You can begin the path with the `:cacheDir` or `:resourceDir` token. These tokens will be replaced with the actual configured cache directory and resource directory paths, respectively.
|
||||
|
||||
maxAge
|
||||
: (`string`) The [duration](g) a cached entry remains valid before being evicted. A value of `0` disables the cache. A value of `-1` means the cache entry never expires (the default).
|
||||
|
||||
## Tokens
|
||||
|
||||
`:cacheDir`
|
||||
: (`string`) The designated cache directory. See [details](/configuration/all/#cachedir).
|
||||
|
||||
`:project`
|
||||
: (`string`) The base directory name of the current Hugo project. By default, this ensures each project has isolated file caches, so running `hugo --gc` will only affect the current project's cache and not those of other Hugo projects on the same machine.
|
||||
|
||||
`:resourceDir`
|
||||
: (`string`) The designated directory for caching output from [asset pipelines](g). See [details](/configuration/all/#resourcedir).
|
||||
77
docs/content/en/configuration/cascade.md
Normal file
77
docs/content/en/configuration/cascade.md
Normal file
|
|
@ -0,0 +1,77 @@
|
|||
---
|
||||
title: Configure cascade
|
||||
linkTitle: Cascade
|
||||
description: Configure cascade.
|
||||
categories: []
|
||||
keywords: []
|
||||
---
|
||||
|
||||
You can configure your site to cascade front matter values to the home page and any of its descendants. However, this cascading will be prevented if the descendant already defines the field, or if a closer ancestor [node](g) has already cascaded a value for the same field through its front matter's `cascade` key.
|
||||
|
||||
> [!note]
|
||||
> You can also configure cascading behavior within a page's front matter. See [details].
|
||||
|
||||
For example, to cascade a "color" parameter to the home page and all its descendants:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
title = 'Home'
|
||||
[cascade.params]
|
||||
color = 'red'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
## Target
|
||||
|
||||
<!-- TODO
|
||||
Update the <version> and <date> below when we actually get around to deprecating _target.
|
||||
|
||||
We deprecated the `_target` front matter key in favor of `target` in <version> on <date>. Remove footnote #1 on or after 2026-03-10 (15 months after deprecation).
|
||||
-->
|
||||
|
||||
The `target`[^1] keyword allows you to target specific pages or [environments](g). For example, to cascade a "color" parameter to pages within the "articles" section, including the "articles" section page itself:
|
||||
|
||||
[^1]: The `_target` alias for `target` is deprecated and will be removed in a future release.
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[cascade.params]
|
||||
color = 'red'
|
||||
[cascade.target]
|
||||
path = '{/articles,/articles/**}'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
Use any combination of these keywords to target pages and/or environments:
|
||||
|
||||
environment
|
||||
: (`string`) A [glob](g) pattern matching the build [environment](g). For example: `{staging,production}`.
|
||||
|
||||
kind
|
||||
: (`string`) A [glob](g) pattern matching the [page kind](g). For example: ` {taxonomy,term}`.
|
||||
|
||||
lang
|
||||
: (`string`) A [glob](g) pattern matching the [page language]. For example: `{en,de}`.
|
||||
|
||||
path
|
||||
: (`string`) A [glob](g) pattern matching the page's [logical path](g). For example: `{/books,/books/**}`.
|
||||
|
||||
## Array
|
||||
|
||||
Define an array of cascade parameters to apply different values to different targets. For example:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[[cascade]]
|
||||
[cascade.params]
|
||||
color = 'red'
|
||||
[cascade.target]
|
||||
path = '{/books/**}'
|
||||
kind = 'page'
|
||||
lang = '{en,de}'
|
||||
[[cascade]]
|
||||
[cascade.params]
|
||||
color = 'blue'
|
||||
[cascade.target]
|
||||
path = '{/films/**}'
|
||||
kind = 'page'
|
||||
environment = 'production'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
[details]: /content-management/front-matter/#cascade-1
|
||||
[page language]: /methods/page/language/
|
||||
63
docs/content/en/configuration/content-types.md
Normal file
63
docs/content/en/configuration/content-types.md
Normal file
|
|
@ -0,0 +1,63 @@
|
|||
---
|
||||
title: Configure content types
|
||||
linkTitle: Content types
|
||||
description: Configure content types.
|
||||
categories: []
|
||||
keywords: []
|
||||
---
|
||||
|
||||
{{< new-in 0.144.0 />}}
|
||||
|
||||
Hugo supports six [content formats](g):
|
||||
|
||||
{{% include "/_common/content-format-table.md" %}}
|
||||
|
||||
These can be used as either page content or [page resources](g). When used as page resources, their [resource type](g) is `page`.
|
||||
|
||||
Consider this example of a [page bundle](g):
|
||||
|
||||
```text
|
||||
content/
|
||||
└── example/
|
||||
├── index.md <-- content
|
||||
├── a.adoc <-- resource (resource type: page)
|
||||
├── b.html <-- resource (resource type: page)
|
||||
├── c.md <-- resource (resource type: page)
|
||||
├── d.org <-- resource (resource type: page)
|
||||
├── e.pdc <-- resource (resource type: page)
|
||||
├── f.rst <-- resource (resource type: page)
|
||||
├── g.jpg <-- resource (resource type: image)
|
||||
└── h.png <-- resource (resource type: image)
|
||||
```
|
||||
|
||||
The `index.md` file is the page's content, while the other files are page resources. Files `a` through `f` are of resource type `page`, while `g` and `h` are of resource type `image`.
|
||||
|
||||
When you build a site, Hugo does not publish page resources having a resource type of `page`. For example, this is the result of building the site above:
|
||||
|
||||
```text
|
||||
public/
|
||||
├── example/
|
||||
│ ├── g.jpg
|
||||
│ ├── h.png
|
||||
│ └── index.html
|
||||
└── index.html
|
||||
```
|
||||
|
||||
The default behavior is appropriate in most cases. Given that page resources containing markup are typically intended for inclusion in the main content, publishing them independently is generally undesirable.
|
||||
|
||||
The default behavior is determined by the `contentTypes` configuration:
|
||||
|
||||
{{< code-toggle config=contentTypes />}}
|
||||
|
||||
In this default configuration, page resources with those media types will have a resource type of `page`, and will not be automatically published. To change the resource type assignment from `page` to `text` for a given media type, remove the corresponding entry from the list.
|
||||
|
||||
For example, to set the resource type of `text/html` files to `text`, thereby enabling automatic publication, remove the `text/html` entry:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
contentTypes:
|
||||
text/asciidoc: {}
|
||||
text/markdown: {}
|
||||
text/org: {}
|
||||
text/pandoc: {}
|
||||
text/rst: {}
|
||||
{{< /code-toggle >}}
|
||||
159
docs/content/en/configuration/deployment.md
Normal file
159
docs/content/en/configuration/deployment.md
Normal file
|
|
@ -0,0 +1,159 @@
|
|||
---
|
||||
title: Configure deployment
|
||||
linkTitle: Deployment
|
||||
description: Configure deployments to Amazon S3, Azure Blob Storage, or Google Cloud Storage.
|
||||
categories: []
|
||||
keywords: []
|
||||
---
|
||||
|
||||
> [!note]
|
||||
> This configuration is only relevant when running `hugo deploy`. See [details](/host-and-deploy/deploy-with-hugo-deploy/).
|
||||
|
||||
## Top-level options
|
||||
|
||||
These settings control the overall behavior of the deployment process. This is the default configuration:
|
||||
|
||||
{{< code-toggle file=hugo config=deployment />}}
|
||||
|
||||
confirm
|
||||
: (`bool`) Whether to prompt for confirmation before deploying. Default is `false`.
|
||||
|
||||
dryRun
|
||||
: (`bool`) Whether to simulate the deployment without any remote changes. Default is `false`.
|
||||
|
||||
force
|
||||
: (`bool`) Whether to re-upload all files. Default is `false`.
|
||||
|
||||
invalidateCDN
|
||||
: (`bool`) Whether to invalidate the CDN cache listed in the deployment target. Default is `true`.
|
||||
|
||||
maxDeletes
|
||||
: (`int`) The maximum number of files to delete, or `-1` to disable. Default is `256`.
|
||||
|
||||
matchers
|
||||
: (`[]*Matcher`) A slice of [matchers](#matchers-1).
|
||||
|
||||
order
|
||||
: (`[]string`) An ordered slice of [regular expressions](g) that determines upload priority (left to right). Files not matching any expression are uploaded last in an arbitrary order.
|
||||
|
||||
target
|
||||
: (`string`) The target deployment [`name`](#name). Defaults to the first target.
|
||||
|
||||
targets
|
||||
: (`[]*Target`) A slice of [targets](#targets-1).
|
||||
|
||||
workers
|
||||
: (`int`) The number of concurrent workers to use when uploading files. Default is `10`.
|
||||
|
||||
## Targets
|
||||
|
||||
A target represents a deployment target such as "staging" or "production".
|
||||
|
||||
cloudFrontDistributionID
|
||||
: (`string`) The CloudFront Distribution ID, applicable if you are using the Amazon Web Services CloudFront CDN. Hugo will invalidate the CDN when deploying this target.
|
||||
|
||||
exclude
|
||||
: (`string`) A [glob](g) pattern matching files to exclude when deploying to this target. Local files failing the include/exclude filters are not uploaded, and remote files failing these filters are not deleted.
|
||||
|
||||
googleCloudCDNOrigin
|
||||
: (`string`) The Google Cloud project and CDN origin to invalidate when deploying this target, specified as `<project>/<origin>`.
|
||||
|
||||
include
|
||||
: (`string`) A [glob](g) pattern matching files to include when deploying to this target. Local files failing the include/exclude filters are not uploaded, and remote files failing these filters are not deleted.
|
||||
|
||||
name
|
||||
: (`string`) An arbitrary name for this target.
|
||||
|
||||
stripIndexHTML
|
||||
: (`bool`) Whether to map files named `<dir>/index.html` to `<dir>` on the remote (except for the root `index.html`). This is useful for key-value cloud storage (e.g., Amazon S3, Google Cloud Storage, Azure Blob Storage) to align canonical URLs with object keys. Default is `false`.
|
||||
|
||||
url
|
||||
: (`string`) The [destination URL](#destination-urls) for deployment.
|
||||
|
||||
## Matchers
|
||||
|
||||
A Matcher represents a configuration to be applied to files whose paths match
|
||||
the specified pattern.
|
||||
|
||||
cacheControl
|
||||
: (`string`) The caching attributes to use when serving the blob. See [details][cacheControl].
|
||||
|
||||
contentEncoding
|
||||
: (`string`) The encoding used for the blob's content, if any. See [details][contentEncoding].
|
||||
|
||||
contentType
|
||||
: (`string`) The media type of the blob being written. See [details][contentType].
|
||||
|
||||
force
|
||||
: (`bool`) Whether matching files should be re-uploaded. Useful when other route-determined metadata (e.g., `contentType`) has changed. Default is `false`.
|
||||
|
||||
gzip
|
||||
: (`bool`) Whether the file should be gzipped before upload. If so, the `ContentEncoding` field will automatically be set to `gzip`. Default is `false`.
|
||||
|
||||
pattern
|
||||
: (`string`) A [regular expression](g) used to match paths. Paths are converted to use forward slashes (`/`) before matching.
|
||||
|
||||
[cacheControl]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control
|
||||
[contentEncoding]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Encoding
|
||||
[contentType]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type
|
||||
|
||||
## Destination URLs
|
||||
|
||||
Service|URL example
|
||||
:--|:--
|
||||
Amazon Simple Storage Service (S3)|`s3://my-bucket?region=us-west-1`
|
||||
Azure Blob Storage|`azblob://my-container`
|
||||
Google Cloud Storage (GCS)|`gs://my-bucket`
|
||||
|
||||
With Google Cloud Storage you can target a subdirectory:
|
||||
|
||||
```text
|
||||
gs://my-bucket?prefix=a/subdirectory
|
||||
```
|
||||
|
||||
You can also to deploy to storage servers compatible with Amazon S3 such as:
|
||||
|
||||
- [Ceph]
|
||||
- [MinIO]
|
||||
- [SeaweedFS]
|
||||
|
||||
[Ceph]: https://ceph.com/
|
||||
[Minio]: https://www.minio.io/
|
||||
[SeaweedFS]: https://github.com/chrislusf/seaweedfs
|
||||
|
||||
For example, the `url` for a MinIO deployment target might resemble this:
|
||||
|
||||
```text
|
||||
s3://my-bucket?endpoint=https://my.minio.instance&awssdk=v2&use_path_style=true&disable_https=false
|
||||
```
|
||||
|
||||
## Example
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[deployment]
|
||||
order = ['.jpg$', '.gif$']
|
||||
[[deployment.matchers]]
|
||||
cacheControl = 'max-age=31536000, no-transform, public'
|
||||
gzip = true
|
||||
pattern = '^.+\.(js|css|svg|ttf)$'
|
||||
[[deployment.matchers]]
|
||||
cacheControl = 'max-age=31536000, no-transform, public'
|
||||
gzip = false
|
||||
pattern = '^.+\.(png|jpg)$'
|
||||
[[deployment.matchers]]
|
||||
contentType = 'application/xml'
|
||||
gzip = true
|
||||
pattern = '^sitemap\.xml$'
|
||||
[[deployment.matchers]]
|
||||
gzip = true
|
||||
pattern = '^.+\.(html|xml|json)$'
|
||||
[[deployment.targets]]
|
||||
url = 's3://my_production_bucket?region=us-west-1'
|
||||
cloudFrontDistributionID = 'E1234567890ABCDEF0'
|
||||
exclude = '**.{heic,psd}'
|
||||
name = 'production'
|
||||
[[deployment.targets]]
|
||||
url = 's3://my_staging_bucket?region=us-west-1'
|
||||
exclude = '**.{heic,psd}'
|
||||
name = 'staging'
|
||||
{{< /code-toggle >}}
|
||||
91
docs/content/en/configuration/front-matter.md
Normal file
91
docs/content/en/configuration/front-matter.md
Normal file
|
|
@ -0,0 +1,91 @@
|
|||
---
|
||||
title: Configure front matter
|
||||
linkTitle: Front matter
|
||||
description: Configure front matter.
|
||||
categories: []
|
||||
keywords: []
|
||||
---
|
||||
|
||||
## Dates
|
||||
|
||||
There are four methods on a `Page` object that return a date.
|
||||
|
||||
Method|Description
|
||||
:--|:--
|
||||
[`Date`]|Returns the date of the given page.
|
||||
[`ExpiryDate`]|Returns the expiry date of the given page.
|
||||
[`Lastmod`]|Returns the last modification date of the given page.
|
||||
[`PublishDate`]|Returns the publish date of the given page.
|
||||
|
||||
[`Date`]: /methods/page/date
|
||||
[`ExpiryDate`]: /methods/page/expirydate
|
||||
[`Lastmod`]: /methods/page/lastmod
|
||||
[`PublishDate`]: /methods/page/publishdate
|
||||
|
||||
Hugo determines the values to return based on this configuration:
|
||||
|
||||
{{< code-toggle config=frontmatter />}}
|
||||
|
||||
The `ExpiryDate` method, for example, returns the `expirydate` value if it exists, otherwise it returns `unpublishdate`.
|
||||
|
||||
You can also use custom date parameters:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[frontmatter]
|
||||
date = ["myDate", "date"]
|
||||
{{< /code-toggle >}}
|
||||
|
||||
In the example above, the `Date` method returns the `myDate` value if it exists, otherwise it returns `date`.
|
||||
|
||||
To fall back to the default sequence of dates, use the `:default` token:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[frontmatter]
|
||||
date = ["myDate", ":default"]
|
||||
{{< /code-toggle >}}
|
||||
|
||||
In the example above, the `Date` method returns the `myDate` value if it exists, otherwise it returns the first valid date from `date`, `publishdate`, `pubdate`, `published`, `lastmod`, and `modified`.
|
||||
|
||||
## Aliases
|
||||
|
||||
Some of the front matter fields have aliases.
|
||||
|
||||
Front matter field|Aliases
|
||||
:--|:--
|
||||
`expiryDate`|`unpublishdate`
|
||||
`lastmod`|`modified`
|
||||
`publishDate`|`pubdate`, `published`
|
||||
|
||||
The default front matter configuration includes these aliases.
|
||||
|
||||
## Tokens
|
||||
|
||||
Hugo provides several [tokens](g) to assist with front matter configuration.
|
||||
|
||||
Token|Description
|
||||
:--|:--
|
||||
`:default`|The default ordered sequence of date fields.
|
||||
`:fileModTime`|The file's last modification timestamp.
|
||||
`:filename`|The date from the file name, if present.
|
||||
`:git`|The Git author date for the file's last revision.
|
||||
|
||||
When Hugo extracts a date from a file name, it uses the rest of the file name to generate the page's [`slug`], but only if a slug isn't already specified in the page's front matter. For example, given the name `2025-02-01-article.md`, Hugo will set the `date` to `2025-02-01` and the `slug` to `article`.
|
||||
|
||||
[`slug`]: /content-management/front-matter/#slug
|
||||
|
||||
To enable access to the Git author date, set [`enableGitInfo`] to `true`, or use\
|
||||
the `--enableGitInfo` flag when building your site.
|
||||
|
||||
[`enableGitInfo`]: /configuration/all/#enablegitinfo
|
||||
|
||||
Consider this example:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[frontmatter]
|
||||
date = [':filename', ':default']
|
||||
lastmod = ['lastmod', ':fileModTime']
|
||||
{{< /code-toggle >}}
|
||||
|
||||
To determine `date`, Hugo tries to extract the date from the file name, falling back to the default ordered sequence of date fields.
|
||||
|
||||
To determine `lastmod`, Hugo looks for a `lastmod` field in front matter, falling back to the file's last modification timestamp.
|
||||
107
docs/content/en/configuration/http-cache.md
Normal file
107
docs/content/en/configuration/http-cache.md
Normal file
|
|
@ -0,0 +1,107 @@
|
|||
---
|
||||
title: Configure the HTTP cache
|
||||
linkTitle: HTTP cache
|
||||
description: Configure the HTTP cache.
|
||||
categories: []
|
||||
keywords: []
|
||||
---
|
||||
|
||||
> [!note]
|
||||
> This configuration is only relevant when using the [`resources.GetRemote`] function.
|
||||
|
||||
## Layered caching
|
||||
|
||||
Hugo employs a layered caching system.
|
||||
|
||||
```goat {.w-40}
|
||||
.-----------.
|
||||
| dynacache |
|
||||
'-----+-----'
|
||||
|
|
||||
v
|
||||
.----------.
|
||||
| HTTP cache |
|
||||
'-----+----'
|
||||
|
|
||||
v
|
||||
.----------.
|
||||
| file cache |
|
||||
'-----+----'
|
||||
```
|
||||
|
||||
Dynacache
|
||||
: An in-memory cache employing a Least Recently Used (LRU) eviction policy. Entries are removed from the cache when changes occur, when they match [cache-busting] patterns, or under low-memory conditions.
|
||||
|
||||
HTTP Cache
|
||||
: An HTTP cache for remote resources as specified in [RFC 9111]. Optimal performance is achieved when resources include appropriate HTTP cache headers. The HTTP cache utilizes the file cache for storage and retrieval of cached resources.
|
||||
|
||||
File cache
|
||||
: See [configure file caches].
|
||||
|
||||
The HTTP cache involves two key aspects: determining which content to cache (the caching process itself) and defining the frequency with which to check for updates (the polling strategy).
|
||||
|
||||
## HTTP caching
|
||||
|
||||
The HTTP cache behavior is defined for a configured set of resources. Stale resources will be refreshed from the file cache, even if their configured Time-To-Live (TTL) has not expired. If HTTP caching is disabled for a resource, Hugo will bypass the cache and access the file directly.
|
||||
|
||||
The default configuration disables everything:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[HTTPCache.cache.for]
|
||||
excludes = ['**']
|
||||
includes = []
|
||||
{{< /code-toggle >}}
|
||||
|
||||
cache.for.excludes
|
||||
: (`string`) A list of [glob](g) patterns to exclude from caching.
|
||||
|
||||
cache.for.includes
|
||||
: (`string`) A list of [glob](g) patterns to cache.
|
||||
|
||||
## HTTP polling
|
||||
|
||||
Polling is used in watch mode (e.g., `hugo server`) to detect changes in remote resources. Polling can be enabled even if HTTP caching is disabled. Detected changes trigger a rebuild of pages using the affected resource. Polling can be disabled for specific resources, typically those known to be static.
|
||||
|
||||
The default configuration disables everything:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[[HTTPCache.polls]]
|
||||
disable = true
|
||||
high = '0s'
|
||||
low = '0s'
|
||||
[HTTPCache.polls.for]
|
||||
includes = ['**']
|
||||
excludes = []
|
||||
{{< /code-toggle >}}
|
||||
|
||||
polls
|
||||
: A slice of polling configurations.
|
||||
|
||||
polls.disable
|
||||
: (`bool`) Whether to disable polling for this configuration.
|
||||
|
||||
polls.low
|
||||
: (`string`) The minimum polling interval expressed as a [duration](g). This is used after a recent change and gradually increases towards `polls.high`.
|
||||
|
||||
polls.high
|
||||
: (`string`) The maximum polling interval expressed as a [duration](g). This is used when the resource is considered stable.
|
||||
|
||||
polls.for.excludes
|
||||
: (`string`) A list of [glob](g) patterns to exclude from polling for this configuration.
|
||||
|
||||
polls.for.includes
|
||||
: (`string`) A list of [glob](g) patterns to include in polling for this configuration.
|
||||
|
||||
## Behavior
|
||||
|
||||
Polling and HTTP caching interact as follows:
|
||||
|
||||
- With polling enabled, rebuilds are triggered only by actual changes, detected via `eTag` changes (Hugo generates an MD5 hash if the server doesn't provide one).
|
||||
- If polling is enabled but HTTP caching is disabled, the remote is checked for changes only after the file cache's TTL expires (e.g., a `maxAge` of `10h` with a `1s` polling interval is inefficient).
|
||||
- If both polling and HTTP caching are enabled, changes are checked for even before the file cache's TTL expires. Cached `eTag` and `last-modified` values are sent in `if-none-match` and `if-modified-since` headers, respectively, and a cached response is returned on HTTP [304].
|
||||
|
||||
[`resources.GetRemote`]: /functions/resources/getremote/
|
||||
[304]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/304
|
||||
[cache-busting]: /configuration/build/#cache-busters
|
||||
[configure file caches]: /configuration/caches/
|
||||
[RFC 9111]: https://datatracker.ietf.org/doc/html/rfc9111
|
||||
69
docs/content/en/configuration/imaging.md
Normal file
69
docs/content/en/configuration/imaging.md
Normal file
|
|
@ -0,0 +1,69 @@
|
|||
---
|
||||
title: Configure imaging
|
||||
linkTitle: Imaging
|
||||
description: Configure imaging.
|
||||
categories: []
|
||||
keywords: []
|
||||
---
|
||||
|
||||
## Processing options
|
||||
|
||||
These are the default settings for processing images:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[imaging]
|
||||
anchor = 'Smart'
|
||||
bgColor = '#ffffff'
|
||||
hint = 'photo'
|
||||
quality = 75
|
||||
resampleFilter = 'box'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
anchor
|
||||
: (`string`) When using the [`Crop`] or [`Fill`] method, the anchor determines the placement of the crop box. One of `TopLeft`, `Top`, `TopRight`, `Left`, `Center`, `Right`, `BottomLeft`, `Bottom`, `BottomRight`, or `Smart`. Default is `Smart`.
|
||||
|
||||
bgColor
|
||||
: (`string`) The background color of the resulting image. Applicable when converting from a format that supports transparency to a format that does not support transparency, for example, when converting from PNG to JPEG. Expressed as an RGB [hexadecimal] value. Default is `#ffffff`.
|
||||
|
||||
[hexadecimal]: https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color
|
||||
|
||||
hint
|
||||
: (`string`) Applicable to WebP images, this option corresponds to a set of predefined encoding parameters. One of `drawing`, `icon`, `photo`, `picture`, or `text`. Default is `photo`. See [details](/content-management/image-processing/#hint).
|
||||
|
||||
quality
|
||||
: (`int`) Applicable to JPEG and WebP images, this 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. Default is `75`.
|
||||
|
||||
resampleFilter
|
||||
: (`string`) The resampling filter used when resizing an image. Default is `box`. See [details](/content-management/image-processing/#resampling-filter)
|
||||
|
||||
## EXIF data
|
||||
|
||||
These are the default settings for extracting EXIF data from images:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[imaging.exif]
|
||||
includeFields = ""
|
||||
excludeFields = ""
|
||||
disableDate = false
|
||||
disableLatLong = false
|
||||
{{< /code-toggle >}}
|
||||
|
||||
disableDate
|
||||
: (`bool`) Whether to disable extraction of the image creation date/time. Default is `false`.
|
||||
|
||||
disableLatLong
|
||||
: (`bool`) Whether to disable extraction of the GPS latitude and longitude. Default is `false`.
|
||||
|
||||
excludeFields
|
||||
: (`string`) A [regular expression](g) matching the tags to exclude when extracting EXIF data.
|
||||
|
||||
includeFields
|
||||
: (`string`) A [regular expression](g) matching the tags to include when extracting EXIF data. To include all available tags, set this value to `".*"`.
|
||||
|
||||
> [!note]
|
||||
> To improve performance and decrease cache size, Hugo excludes the following tags: `ColorSpace`, `Contrast`, `Exif`, `Exposure[M|P|B]`, `Flash`, `GPS`, `JPEG`, `Metering`, `Resolution`, `Saturation`, `Sensing`, `Sharp`, and `WhiteBalance`.
|
||||
>
|
||||
> To control tag availability, change the `excludeFields` or `includeFields` settings as described above.
|
||||
|
||||
[`Crop`]: /methods/resource/crop/
|
||||
[`Fill`]: /methods/resource/fill/
|
||||
284
docs/content/en/configuration/introduction.md
Normal file
284
docs/content/en/configuration/introduction.md
Normal file
|
|
@ -0,0 +1,284 @@
|
|||
---
|
||||
title: Introduction
|
||||
description: Configure your site using files, directories, and environment variables.
|
||||
categories: []
|
||||
keywords: []
|
||||
weight: 10
|
||||
---
|
||||
|
||||
## Sensible defaults
|
||||
|
||||
Hugo offers many configuration options, but its defaults are often sufficient. A new site requires only these settings:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
baseURL = 'https://example.org/'
|
||||
languageCode = 'en-us'
|
||||
title = 'My New Hugo Site'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
Only define settings that deviate from the defaults. A smaller configuration file is easier to read, understand, and debug. Keep your configuration concise.
|
||||
|
||||
> [!note]
|
||||
> The best configuration file is a short configuration file.
|
||||
|
||||
## Configuration file
|
||||
|
||||
Create a site configuration file in the root of your project directory, naming it `hugo.toml`, `hugo.yaml`, or `hugo.json`, with that order of precedence.
|
||||
|
||||
```text
|
||||
my-project/
|
||||
└── hugo.toml
|
||||
```
|
||||
|
||||
> [!note]
|
||||
> For versions v0.109.0 and earlier, the site configuration file was named `config`. While you can still use this name, it's recommended to switch to the newer naming convention, `hugo`.
|
||||
|
||||
A simple example:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
baseURL = 'https://example.org/'
|
||||
languageCode = 'en-us'
|
||||
title = 'ABC Widgets, Inc.'
|
||||
[params]
|
||||
subtitle = 'The Best Widgets on Earth'
|
||||
[params.contact]
|
||||
email = 'info@example.org'
|
||||
phone = '+1 202-555-1212'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
To use a different configuration file when building your site, use the `--config` flag:
|
||||
|
||||
```sh
|
||||
hugo --config other.toml
|
||||
```
|
||||
|
||||
Combine two or more configuration files, with left-to-right precedence:
|
||||
|
||||
```sh
|
||||
hugo --config a.toml,b.yaml,c.json
|
||||
```
|
||||
|
||||
> [!note]
|
||||
> See the specifications for each file format: [TOML], [YAML], and [JSON].
|
||||
|
||||
## Configuration directory
|
||||
|
||||
Instead of a single site configuration file, split your configuration by [environment](g), root configuration key, and language. For example:
|
||||
|
||||
```text
|
||||
my-project/
|
||||
└── config/
|
||||
├── _default/
|
||||
│ ├── hugo.toml
|
||||
│ ├── menus.en.toml
|
||||
│ ├── menus.de.toml
|
||||
│ └── params.toml
|
||||
└── production/
|
||||
└── params.toml
|
||||
```
|
||||
|
||||
The root configuration keys are {{< root-configuration-keys >}}.
|
||||
|
||||
### Omit the root key
|
||||
|
||||
When splitting the configuration by root key, omit the root key in the component file. For example, these are equivalent:
|
||||
|
||||
{{< code-toggle file=config/_default/hugo >}}
|
||||
[params]
|
||||
foo = 'bar'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
{{< code-toggle file=config/_default/params >}}
|
||||
foo = 'bar'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
### Recursive parsing
|
||||
|
||||
Hugo parses the `config` directory recursively, allowing you to organize the files into subdirectories. For example:
|
||||
|
||||
```text
|
||||
my-project/
|
||||
└── config/
|
||||
└── _default/
|
||||
├── navigation/
|
||||
│ ├── menus.de.toml
|
||||
│ └── menus.en.toml
|
||||
└── hugo.toml
|
||||
```
|
||||
|
||||
### Example
|
||||
|
||||
```text
|
||||
my-project/
|
||||
└── config/
|
||||
├── _default/
|
||||
│ ├── hugo.toml
|
||||
│ ├── menus.en.toml
|
||||
│ ├── menus.de.toml
|
||||
│ └── params.toml
|
||||
├── production/
|
||||
│ ├── hugo.toml
|
||||
│ └── params.toml
|
||||
└── staging/
|
||||
├── hugo.toml
|
||||
└── params.toml
|
||||
```
|
||||
|
||||
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 a [Google tag ID] in your site configuration:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[services.googleAnalytics]
|
||||
ID = 'G-XXXXXXXXX'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
Now consider the following scenario:
|
||||
|
||||
1. You don't want to load the analytics code when running `hugo server`.
|
||||
1. You want to use different Google tag IDs for your production and staging environments. For example:
|
||||
- `G-PPPPPPPPP` for production
|
||||
- `G-SSSSSSSSS` for staging
|
||||
|
||||
To satisfy these requirements, configure your site as follows:
|
||||
|
||||
1. `config/_default/hugo.toml`
|
||||
- Exclude the `services.googleAnalytics` section. This will prevent loading of the analytics code when you run `hugo server`.
|
||||
- By default, Hugo sets its `environment` to `development` when running `hugo server`. In the absence of a `config/development` directory, Hugo uses the `config/_default` directory.
|
||||
1. `config/production/hugo.toml`
|
||||
- Include this section only:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[services.googleAnalytics]
|
||||
ID = 'G-PPPPPPPPP'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
- You do not need to include other parameters in this file. Include only those parameters that are specific to your production environment. Hugo will merge these parameters with the default configuration.
|
||||
- By default, Hugo sets its `environment` to `production` when running `hugo`. The analytics code will use the `G-PPPPPPPPP` tag ID.
|
||||
|
||||
1. `config/staging/hugo.toml`
|
||||
|
||||
- Include this section only:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[services.googleAnalytics]
|
||||
ID = 'G-SSSSSSSSS'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
- You do not need to include other parameters in this file. Include only those parameters that are specific to your staging environment. Hugo will merge these parameters with the default configuration.
|
||||
- To build your staging site, run `hugo --environment staging`. The analytics code will use the `G-SSSSSSSSS` tag ID.
|
||||
|
||||
## Merge configuration settings
|
||||
|
||||
Hugo merges configuration settings from themes and modules, prioritizing the project's own settings. Given this simplified project structure with two themes:
|
||||
|
||||
```text
|
||||
project/
|
||||
├── themes/
|
||||
│ ├── theme-a/
|
||||
│ │ └── hugo.toml
|
||||
│ └── theme-b/
|
||||
│ └── hugo.toml
|
||||
└── hugo.toml
|
||||
```
|
||||
|
||||
and this project-level configuration:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
baseURL = 'https://example.org/'
|
||||
languageCode = 'en-us'
|
||||
title = 'My New Hugo Site'
|
||||
theme = ['theme-a','theme-b']
|
||||
{{< /code-toggle >}}
|
||||
|
||||
Hugo merges settings in this order:
|
||||
|
||||
1. Project configuration (`hugo.toml` in the project root)
|
||||
1. `theme-a` configuration
|
||||
1. `theme-b` configuration
|
||||
|
||||
The `_merge` setting within each top-level configuration key controls _which_ settings are merged and _how_ they are merged.
|
||||
|
||||
The value for `_merge` can be one of:
|
||||
|
||||
none
|
||||
: No merge.
|
||||
|
||||
shallow
|
||||
: Only add values for new keys.
|
||||
|
||||
deep
|
||||
: Add values for new keys, merge existing.
|
||||
|
||||
Note that you don't need to be so verbose as in the default setup below; a `_merge` value higher up will be inherited if not set.
|
||||
|
||||
{{< code-toggle file=hugo dataKey="config_helpers.mergeStrategy" skipHeader=true />}}
|
||||
|
||||
## Environment variables
|
||||
|
||||
You can also configure settings using operating system environment variables:
|
||||
|
||||
```sh
|
||||
export HUGO_BASEURL=https://example.org/
|
||||
export HUGO_ENABLEGITINFO=true
|
||||
export HUGO_ENVIRONMENT=staging
|
||||
hugo
|
||||
```
|
||||
|
||||
The above sets the [`baseURL`], [`enableGitInfo`], and [`environment`] configuration options and then builds your site.
|
||||
|
||||
> [!note]
|
||||
> An environment variable takes precedence over the values set in the configuration file. This means that if you set a configuration value with both an environment variable and in the configuration file, the value in the environment variable will be used.
|
||||
|
||||
Environment variables simplify configuration for [CI/CD](g) deployments like GitHub Pages, GitLab Pages, and Netlify by allowing you to set values directly within their respective configuration and workflow files.
|
||||
|
||||
> [!note]
|
||||
> Environment variable names must be prefixed with `HUGO_`.
|
||||
>
|
||||
> To set custom site parameters, prefix the name with `HUGO_PARAMS_`.
|
||||
|
||||
For snake_case variable names, the standard `HUGO_` prefix won't work. Hugo infers the delimiter from the first character following `HUGO`. This allows for variations like `HUGOxPARAMSxAPI_KEY=abcdefgh` using any [permitted delimiter].
|
||||
|
||||
In addition to configuring standard settings, environment variables may be used to override default values for certain internal settings:
|
||||
|
||||
DART_SASS_BINARY
|
||||
: (`string`) The absolute path to the Dart Sass executable. By default, Hugo searches for the executable in each of the paths in the `PATH` environment variable.
|
||||
|
||||
HUGO_FILE_LOG_FORMAT
|
||||
: (`string`) A format string for the file path, line number, and column number displayed when reporting errors, or when calling the `Position` method from a shortcode or Markdown render hook. Valid tokens are `:file`, `:line`, and `:col`. Default is `:file::line::col`.
|
||||
|
||||
HUGO_MEMORYLIMIT
|
||||
: {{< new-in 0.123.0 />}}
|
||||
: (`int`) The maximum amount of system memory, in gigabytes, that Hugo can use while rendering your site. Default is 25% of total system memory. Note that The `HUGO_MEMORYLIMIT` is a “best effort” setting. Don't expect Hugo to build a million pages with only 1 GB memory. You can get more information about how this behaves during the build by building with `hugo --logLevel info` and look for the `dynacache` label.
|
||||
|
||||
HUGO_NUMWORKERMULTIPLIER
|
||||
: (`int`) The number of workers used in parallel processing. Default is the number of logical CPUs.
|
||||
|
||||
## Current configuration
|
||||
|
||||
Display the complete site configuration with:
|
||||
|
||||
```sh
|
||||
hugo config
|
||||
```
|
||||
|
||||
Display a specific configuration setting with:
|
||||
|
||||
```sh
|
||||
hugo config | grep [key]
|
||||
```
|
||||
|
||||
Display the configured file mounts with:
|
||||
|
||||
```sh
|
||||
hugo config mounts
|
||||
```
|
||||
|
||||
[`baseURL`]: /configuration/all#baseurl
|
||||
[`enableGitInfo`]: /configuration/all#enablegitinfo
|
||||
[`environment`]: /configuration/all#environment
|
||||
[Google tag ID]: https://support.google.com/tagmanager/answer/12326985?hl=en
|
||||
[JSON]: https://datatracker.ietf.org/doc/html/rfc7159
|
||||
[permitted delimiter]: https://pubs.opengroup.org/onlinepubs/000095399/basedefs/xbd_chap08.html
|
||||
[TOML]: https://toml.io/en/latest
|
||||
[YAML]: https://yaml.org/spec/
|
||||
193
docs/content/en/configuration/languages.md
Normal file
193
docs/content/en/configuration/languages.md
Normal file
|
|
@ -0,0 +1,193 @@
|
|||
---
|
||||
title: Configure languages
|
||||
linkTitle: Languages
|
||||
description: Configure the languages in your multilingual site.
|
||||
categories: []
|
||||
keywords: []
|
||||
---
|
||||
|
||||
## Base settings
|
||||
|
||||
Configure the following base settings within the site's root configuration:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
defaultContentLanguage = 'en'
|
||||
defaultContentLanguageInSubdir = false
|
||||
disableDefaultLanguageRedirect = false
|
||||
disableLanguages = []
|
||||
{{< /code-toggle >}}
|
||||
|
||||
defaultContentLanguage
|
||||
: (`string`) The project's default language key, conforming to the syntax described in [RFC 5646]. This value must match one of the defined [language keys](#language-keys). Default is `en`.
|
||||
|
||||
defaultContentLanguageInSubdir
|
||||
: (`bool`) Whether to publish the default language site to a subdirectory matching the `defaultContentLanguage`. Default is `false`.
|
||||
|
||||
disableDefaultLanguageRedirect
|
||||
: {{< new-in 0.140.0 />}}
|
||||
: (`bool`) Whether to disable generation of the alias redirect to the default language when `DefaultContentLanguageInSubdir` is `true`. Default is `false`.
|
||||
|
||||
disableLanguages
|
||||
: (`[]string]`) A slice of language keys representing the languages to disable during the build process. Although this is functional, consider using the [`disabled`](#disabled) key under each language instead.
|
||||
|
||||
## Language settings
|
||||
|
||||
Configure each language under the `languages` key:
|
||||
|
||||
{{< code-toggle config=languages />}}
|
||||
|
||||
In the above, `en` is the [language key](#language-keys).
|
||||
|
||||
disabled
|
||||
: (`bool`) Whether to disable this language when building the site. Default is `false`.
|
||||
|
||||
languageCode
|
||||
: (`string`) The language tag as described in [RFC 5646]. This value does not affect localization or URLs. Hugo uses this value to populate:
|
||||
|
||||
- The `lang` attribute of the `html` element in the [embedded alias template]
|
||||
- The `language` element in the [embedded RSS template]
|
||||
- The `locale` property in the [embedded OpenGraph template]
|
||||
|
||||
Access this value from a template using the [`Language.LanguageCode`] method on a `Site` or `Page` object.
|
||||
|
||||
languageDirection
|
||||
: (`string`) The language direction, either left-to-right (`ltr`) or right-to-left (`rtl`). Use this value in your templates with the global [`dir`] HTML attribute. Access this value from a template using the [`Language.LanguageDirection`] method on a `Site` or `Page` object.
|
||||
|
||||
languageName
|
||||
: (`string`) The language name, typically used when rendering a language switcher. Access this value from a template using the [`Language.LanguageName`] method on a `Site` or `Page` object.
|
||||
|
||||
title
|
||||
: (`string`) The site title for this language. Access this value from a template using the [`Title`] method on a `Site` object.
|
||||
|
||||
weight
|
||||
: (`int`) The language [weight](g). When set to a non-zero value, this is the primary sort criteria for this language. Access this value from a template using the [`Language.Weight`] method on a `Site` or `Page` object.
|
||||
|
||||
## Localized settings
|
||||
|
||||
Some configuration settings can be defined separately for each language. For example:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[languages.en]
|
||||
languageCode = 'en-US'
|
||||
languageName = 'English'
|
||||
weight = 1
|
||||
title = 'Project Documentation'
|
||||
timeZone = 'America/New_York'
|
||||
[languages.en.pagination]
|
||||
path = 'page'
|
||||
[languages.en.params]
|
||||
subtitle = 'Reference, Tutorials, and Explanations'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
The following configuration keys can be defined separately for each language:
|
||||
|
||||
{{< per-lang-config-keys >}}
|
||||
|
||||
Any key not defined in a `languages` object will fall back to the global value in the root of the site configuration.
|
||||
|
||||
## Language keys
|
||||
|
||||
Language keys must conform to the syntax described in [RFC 5646]. For example:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
defaultContentLanguage = 'de'
|
||||
[languages.de]
|
||||
weight = 1
|
||||
[languages.en-US]
|
||||
weight = 2
|
||||
[languages.pt-BR]
|
||||
weight = 3
|
||||
{{< /code-toggle >}}
|
||||
|
||||
Artificial languages with private use subtags as defined in [RFC 5646 § 2.2.7] are also supported. Omit the `art-x-` prefix from the language key. For example:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
defaultContentLanguage = 'en'
|
||||
[languages.en]
|
||||
weight = 1
|
||||
[languages.hugolang]
|
||||
weight = 2
|
||||
{{< /code-toggle >}}
|
||||
|
||||
> [!note]
|
||||
> Private use subtags must not exceed 8 alphanumeric characters.
|
||||
|
||||
## Example
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
defaultContentLanguage = 'de'
|
||||
defaultContentLanguageInSubdir = true
|
||||
disableDefaultLanguageRedirect = false
|
||||
|
||||
[languages.de]
|
||||
contentDir = 'content/de'
|
||||
disabled = false
|
||||
languageCode = 'de-DE'
|
||||
languageDirection = 'ltr'
|
||||
languageName = 'Deutsch'
|
||||
title = 'Projekt Dokumentation'
|
||||
weight = 1
|
||||
|
||||
[languages.de.params]
|
||||
subtitle = 'Referenz, Tutorials und Erklärungen'
|
||||
|
||||
[languages.en]
|
||||
contentDir = 'content/en'
|
||||
disabled = false
|
||||
languageCode = 'en-US'
|
||||
languageDirection = 'ltr'
|
||||
languageName = 'English'
|
||||
title = 'Project Documentation'
|
||||
weight = 2
|
||||
|
||||
[languages.en.params]
|
||||
subtitle = 'Reference, Tutorials, and Explanations'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
> [!note]
|
||||
> In the example above, omit `contentDir` if [translating by file name].
|
||||
|
||||
## Multihost
|
||||
|
||||
Hugo supports multiple languages in a multihost configuration. This means you can configure a `baseURL` per `language`.
|
||||
|
||||
> [!note]
|
||||
> If you define a `baseURL` for one language, you must define a unique `baseURL` for all languages.
|
||||
|
||||
For example:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
defaultContentLanguage = 'fr'
|
||||
[languages]
|
||||
[languages.en]
|
||||
baseURL = 'https://en.example.org/'
|
||||
languageName = 'English'
|
||||
title = 'In English'
|
||||
weight = 2
|
||||
[languages.fr]
|
||||
baseURL = 'https://fr.example.org'
|
||||
languageName = 'Français'
|
||||
title = 'En Français'
|
||||
weight = 1
|
||||
{{</ code-toggle >}}
|
||||
|
||||
With the above, Hugo publishes two sites, each with their own root:
|
||||
|
||||
```text
|
||||
public
|
||||
├── en
|
||||
└── fr
|
||||
```
|
||||
|
||||
[`dir`]: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/dir
|
||||
[`Language.LanguageCode`]: /methods/site/language/#languagecode
|
||||
[`Language.LanguageDirection`]: /methods/site/language/#languagedirection
|
||||
[`Language.LanguageName`]: /methods/site/language/#languagename
|
||||
[`Language.Weight`]: /methods/site/language/#weight
|
||||
[`Title`]: /methods/site/title/
|
||||
[embedded alias template]: {{% eturl alias %}}
|
||||
[embedded OpenGraph template]: {{% eturl opengraph %}}
|
||||
[embedded RSS template]: {{% eturl rss %}}
|
||||
[RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646#section-2.1
|
||||
[RFC 5646 § 2.2.7]: https://datatracker.ietf.org/doc/html/rfc5646#section-2.2.7
|
||||
[translating by file name]: /content-management/multilingual/#translation-by-file-name
|
||||
341
docs/content/en/configuration/markup.md
Normal file
341
docs/content/en/configuration/markup.md
Normal file
|
|
@ -0,0 +1,341 @@
|
|||
---
|
||||
title: Configure markup
|
||||
linkTitle: Markup
|
||||
description: Configure markup.
|
||||
categories: []
|
||||
keywords: []
|
||||
aliases: [/getting-started/configuration-markup/]
|
||||
---
|
||||
|
||||
## Default handler
|
||||
|
||||
In its default configuration, Hugo uses [Goldmark] to render Markdown to HTML.
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[markup]
|
||||
defaultMarkdownHandler = 'goldmark'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
Files with ending with `.md`, `.mdown`, or `.markdown` are processed as Markdown, unless you've explicitly set a different format using the `markup` field in your front matter.
|
||||
|
||||
To use a different renderer for Markdown files, specify one of `asciidocext`, `org`, `pandoc`, or `rst` in your site configuration.
|
||||
|
||||
`defaultMarkdownHandler`|Renderer
|
||||
:--|:--
|
||||
`asciidocext`|[AsciiDoc]
|
||||
`goldmark`|[Goldmark]
|
||||
`org`|[Emacs Org Mode]
|
||||
`pandoc`|[Pandoc]
|
||||
`rst`|[reStructuredText]
|
||||
|
||||
To use AsciiDoc, Pandoc, or reStructuredText you must install the relevant renderer and update your [security policy].
|
||||
|
||||
> [!note]
|
||||
> Unless you need a unique capability provided by one of the alternative Markdown handlers, we strongly recommend that you use the default setting. Goldmark is fast, well maintained, conforms to the [CommonMark] specification, and is compatible with [GitHub Flavored Markdown] (GFM).
|
||||
|
||||
## Goldmark
|
||||
|
||||
This is the default configuration for the Goldmark Markdown renderer:
|
||||
|
||||
{{< code-toggle config=markup.goldmark />}}
|
||||
|
||||
### Extensions
|
||||
|
||||
The extensions below, excluding Extras and Passthrough, are enabled by default.
|
||||
|
||||
Extension|Documentation|Enabled
|
||||
:--|:--|:-:
|
||||
`cjk`|[Goldmark Extensions: CJK]|:heavy_check_mark:
|
||||
`definitionList`|[PHP Markdown Extra: Definition lists]|:heavy_check_mark:
|
||||
`extras`|[Hugo Goldmark Extensions: Extras]||
|
||||
`footnote`|[PHP Markdown Extra: Footnotes]|:heavy_check_mark:
|
||||
`linkify`|[GitHub Flavored Markdown: Autolinks]|:heavy_check_mark:
|
||||
`passthrough`|[Hugo Goldmark Extensions: Passthrough]||
|
||||
`strikethrough`|[GitHub Flavored Markdown: Strikethrough]|:heavy_check_mark:
|
||||
`table`|[GitHub Flavored Markdown: Tables]|:heavy_check_mark:
|
||||
`taskList`|[GitHub Flavored Markdown: Task list items]|:heavy_check_mark:
|
||||
`typographer`|[Goldmark Extensions: Typographer]|:heavy_check_mark:
|
||||
|
||||
#### Extras
|
||||
|
||||
{{< new-in 0.126.0 />}}
|
||||
|
||||
Enable [deleted text], [inserted text], [mark text], [subscript], and [superscript] elements in Markdown.
|
||||
|
||||
Element|Markdown|Rendered
|
||||
:--|:--|:--
|
||||
Deleted text|`~~foo~~`|`<del>foo</del>`
|
||||
Inserted text|`++bar++`|`<ins>bar</ins>`
|
||||
Mark text|`==baz==`|`<mark>baz</mark>`
|
||||
Subscript|`H~2~O`|`H<sub>2</sub>O`
|
||||
Superscript|`1^st^`|`1<sup>st</sup>`
|
||||
|
||||
To avoid a conflict when enabling the "subscript" feature of the Extras extension, if you want to render subscript and strikethrough text concurrently you must:
|
||||
|
||||
1. Disable the Strikethrough extension
|
||||
1. Enable the "deleted text" feature of the Extras extension
|
||||
|
||||
For example:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[markup.goldmark.extensions]
|
||||
strikethrough = false
|
||||
|
||||
[markup.goldmark.extensions.extras.delete]
|
||||
enable = true
|
||||
|
||||
[markup.goldmark.extensions.extras.subscript]
|
||||
enable = true
|
||||
{{< /code-toggle >}}
|
||||
|
||||
#### Passthrough
|
||||
|
||||
{{< new-in 0.122.0 />}}
|
||||
|
||||
Enable the Passthrough extension to include mathematical equations and expressions in Markdown using LaTeX markup. See [mathematics in Markdown] for details.
|
||||
|
||||
#### Typographer
|
||||
|
||||
The Typographer extension replaces certain character combinations with HTML entities as specified below:
|
||||
|
||||
Markdown|Replaced by|Description
|
||||
:--|:--|:--
|
||||
`...`|`…`|horizontal ellipsis
|
||||
`'`|`’`|apostrophe
|
||||
`--`|`–`|en dash
|
||||
`---`|`—`|em dash
|
||||
`«`|`«`|left angle quote
|
||||
`“`|`“`|left double quote
|
||||
`‘`|`‘`|left single quote
|
||||
`»`|`»`|right angle quote
|
||||
`”`|`”`|right double quote
|
||||
`’`|`’`|right single quote
|
||||
|
||||
### Settings explained
|
||||
|
||||
Most of the Goldmark settings above are self-explanatory, but some require explanation.
|
||||
|
||||
duplicateResourceFiles
|
||||
: {{< new-in 0.123.0 />}}
|
||||
: (`bool`) Whether to duplicate shared page resources for each language on multilingual single-host sites. See [multilingual page resources] for details. Default is `false`.
|
||||
|
||||
> [!note]
|
||||
> With multilingual single-host sites, setting this parameter to `false` will enable Hugo's [embedded link render hook] and [embedded image render hook]. This is the default configuration for multilingual single-host sites.
|
||||
|
||||
parser.wrapStandAloneImageWithinParagraph
|
||||
: (`bool`) Whether to wrap image elements without adjacent content within a `p` element when rendered. This is the default Markdown behavior. Set to `false` when using an [image render hook] to render standalone images as `figure` elements. Default is `true`.
|
||||
|
||||
parser.autoDefinitionTermID
|
||||
: {{< new-in 0.144.0 />}}
|
||||
: (`bool`) Whether to automatically add `id` attributes to description list terms (i.e., `dt` elements). When `true`, the `id` attribute of each `dt` element is accessible through the [`Fragments.Identifiers`] method on a `Page` object.
|
||||
|
||||
parser.autoHeadingID
|
||||
: (`bool`) Whether to automatically add `id` attributes to headings (i.e., `h1`, `h2`, `h3`, `h4`, `h5`, and `h6` elements).
|
||||
|
||||
parser.autoIDType
|
||||
: (`string`) The strategy used to automatically generate `id` attributes, one of `github`, `github-ascii` or `blackfriday`.
|
||||
|
||||
- `github` produces GitHub-compatible `id` attributes
|
||||
- `github-ascii` drops any non-ASCII characters after accent normalization
|
||||
- `blackfriday` produces `id` attributes compatible with the Blackfriday Markdown renderer
|
||||
|
||||
This is also the strategy used by the [anchorize](/functions/urls/anchorize) template function. Default is `github`.
|
||||
|
||||
parser.attribute.block
|
||||
: (`bool`) Whether to enable [Markdown attributes] for block elements. Default is `false`.
|
||||
|
||||
parser.attribute.title
|
||||
: (`bool`) Whether to enable [Markdown attributes] for headings. Default is `true`.
|
||||
|
||||
renderHooks.image.enableDefault
|
||||
: {{< new-in 0.123.0 />}}
|
||||
: (`bool`) Whether to enable the [embedded image render hook]. Default is `false`.
|
||||
|
||||
> [!note]
|
||||
> The embedded image render hook is automatically enabled for multilingual single-host sites if [duplication of shared page resources] is disabled. This is the default configuration for multilingual single-host sites.
|
||||
|
||||
renderHooks.link.enableDefault
|
||||
: {{< new-in 0.123.0 />}}
|
||||
: (`bool`) Whether to enable the [embedded link render hook]. Default is `false`.
|
||||
|
||||
> [!note]
|
||||
> The embedded link render hook is automatically enabled for multilingual single-host sites if [duplication of shared page resources] is disabled. This is the default configuration for multilingual single-host sites.
|
||||
|
||||
renderer.hardWraps
|
||||
: (`bool`) Whether to replace newline characters within a paragraph with `br` elements. Default is `false`.
|
||||
|
||||
renderer.unsafe
|
||||
: (`bool`) Whether to render raw HTML mixed within Markdown. This is unsafe unless the content is under your control. Default is `false`.
|
||||
|
||||
## AsciiDoc
|
||||
|
||||
This is the default configuration for the AsciiDoc renderer:
|
||||
|
||||
{{< code-toggle config=markup.asciidocExt />}}
|
||||
|
||||
### Settings explained
|
||||
|
||||
attributes
|
||||
: (`map`) A map of key-value pairs, each a document attribute. See Asciidoctor's [attributes].
|
||||
|
||||
backend
|
||||
: (`string`) The backend output file format. Default is `html5`.
|
||||
|
||||
extensions
|
||||
: (`string array`) An array of enabled extensions, one or more of `asciidoctor-html5s`, `asciidoctor-bibtex`, `asciidoctor-diagram`, `asciidoctor-interdoc-reftext`, `asciidoctor-katex`, `asciidoctor-latex`, `asciidoctor-mathematical`, or `asciidoctor-question`.
|
||||
|
||||
> [!note]
|
||||
> To mitigate security risks, entries in the extension array may not contain forward slashes (`/`), backslashes (`\`), or periods. Due to this restriction, extensions must be in Ruby's `$LOAD_PATH`.
|
||||
|
||||
failureLevel
|
||||
: (`string`) The minimum logging level that triggers a non-zero exit code (failure). Default is `fatal`.
|
||||
|
||||
noHeaderOrFooter
|
||||
: (`bool`) Whether to output an embeddable document, which excludes the header, the footer, and everything outside the body of the document. Default is `true`.
|
||||
|
||||
preserveTOC
|
||||
: (`bool`) Whether to preserve the table of contents (TOC) rendered by Asciidoctor. By default, to make the TOC compatible with existing themes, Hugo removes the TOC rendered by Asciidoctor. To render the TOC, use the [`TableOfContents`] method on a `Page` object in your templates. Default is `false`.
|
||||
|
||||
safeMode
|
||||
: (`string`) The safe mode level, one of `unsafe`, `safe`, `server`, or `secure`. Default is `unsafe`.
|
||||
|
||||
sectionNumbers
|
||||
: (`bool`) Whether to number each section title. Default is `false`.
|
||||
|
||||
trace
|
||||
: (`bool`) Whether to include backtrace information on errors. Default is `false`.
|
||||
|
||||
verbose
|
||||
: (`bool`) Whether to verbosely print processing information and configuration file checks to stderr. Default is `false`.
|
||||
|
||||
workingFolderCurrent
|
||||
: (`bool`) Whether to set the working directory to be the same as that of the AsciiDoc file being processed, allowing [includes] to work with relative paths. Set to `true` to render diagrams with the [asciidoctor-diagram] extension. Default is `false`.
|
||||
|
||||
### Configuration example
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[markup.asciidocExt]
|
||||
extensions = ["asciidoctor-html5s", "asciidoctor-diagram"]
|
||||
workingFolderCurrent = true
|
||||
[markup.asciidocExt.attributes]
|
||||
my-base-url = "https://example.com/"
|
||||
my-attribute-name = "my value"
|
||||
{{< /code-toggle >}}
|
||||
|
||||
### Syntax highlighting
|
||||
|
||||
Follow the steps below to enable syntax highlighting.
|
||||
|
||||
#### Step 1
|
||||
|
||||
Set the `source-highlighter` attribute in your site configuration. For example:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[markup.asciidocExt.attributes]
|
||||
source-highlighter = 'rouge'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
#### Step 2
|
||||
|
||||
Generate the highlighter CSS. For example:
|
||||
|
||||
```text
|
||||
rougify style monokai.sublime > assets/css/syntax.css
|
||||
```
|
||||
|
||||
#### Step 3
|
||||
|
||||
In your base template add a link to the CSS file:
|
||||
|
||||
```go-html-template {file="layouts/_default/baseof.html"}
|
||||
<head>
|
||||
...
|
||||
{{ with resources.Get "css/syntax.css" }}
|
||||
<link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
|
||||
{{ end }}
|
||||
...
|
||||
</head>
|
||||
```
|
||||
|
||||
Then add the code to be highlighted to your markup:
|
||||
|
||||
```text
|
||||
[#hello,ruby]
|
||||
----
|
||||
require 'sinatra'
|
||||
|
||||
get '/hi' do
|
||||
"Hello World!"
|
||||
end
|
||||
----
|
||||
```
|
||||
|
||||
### Troubleshooting
|
||||
|
||||
Run `hugo --logLevel debug` to examine Hugo's call to the Asciidoctor executable:
|
||||
|
||||
```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 -] ...
|
||||
```
|
||||
|
||||
## Highlight
|
||||
|
||||
This is the default configuration.
|
||||
|
||||
{{< code-toggle config=markup.highlight />}}
|
||||
|
||||
{{% include "/_common/syntax-highlighting-options.md" %}}
|
||||
|
||||
## Table of contents
|
||||
|
||||
This is the default configuration for the table of contents, applicable to Goldmark and Asciidoctor:
|
||||
|
||||
{{< code-toggle config=markup.tableOfContents />}}
|
||||
|
||||
startLevel
|
||||
: (`int`) Heading levels less than this value will be excluded from the table of contents. For example, to exclude `h1` elements from the table of contents, set this value to `2`. Default is `2`.
|
||||
|
||||
endLevel
|
||||
: (`int`) Heading levels greater than this value will be excluded from the table of contents. For example, to exclude `h4`, `h5`, and `h6` elements from the table of contents, set this value to `3`. Default is `3`.
|
||||
|
||||
ordered
|
||||
: (`bool`) Whether to generates an ordered list instead of an unordered list. Default is `false`.
|
||||
|
||||
[`Fragments.Identifiers`]: /methods/page/fragments/#identifiers
|
||||
[`TableOfContents`]: /methods/page/tableofcontents/
|
||||
[asciidoctor-diagram]: https://asciidoctor.org/docs/asciidoctor-diagram/
|
||||
[attributes]: https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#attributes-and-substitutions
|
||||
[CommonMark]: https://spec.commonmark.org/current/
|
||||
[deleted text]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/del
|
||||
[duplication of shared page resources]: /configuration/markup/#duplicateresourcefiles
|
||||
[duplication of shared page resources]: /configuration/markup/#duplicateresourcefiles
|
||||
[embedded image render hook]: /render-hooks/images/#default
|
||||
[embedded image render hook]: /render-hooks/images/#default
|
||||
[embedded link render hook]: /render-hooks/links/#default
|
||||
[embedded link render hook]: /render-hooks/links/#default
|
||||
[GitHub Flavored Markdown]: https://github.github.com/gfm/
|
||||
[GitHub Flavored Markdown: Autolinks]: https://github.github.com/gfm/#autolinks-extension-
|
||||
[GitHub Flavored Markdown: Strikethrough]: https://github.github.com/gfm/#strikethrough-extension-
|
||||
[GitHub Flavored Markdown: Tables]: https://github.github.com/gfm/#tables-extension-
|
||||
[GitHub Flavored Markdown: Task list items]: https://github.github.com/gfm/#task-list-items-extension-
|
||||
[Goldmark]: https://github.com/yuin/goldmark/
|
||||
[Goldmark Extensions: CJK]: https://github.com/yuin/goldmark?tab=readme-ov-file#cjk-extension
|
||||
[Goldmark Extensions: Typographer]: https://github.com/yuin/goldmark?tab=readme-ov-file#typographer-extension
|
||||
[Hugo Goldmark Extensions: Extras]: https://github.com/gohugoio/hugo-goldmark-extensions?tab=readme-ov-file#extras-extension
|
||||
[Hugo Goldmark Extensions: Passthrough]: https://github.com/gohugoio/hugo-goldmark-extensions?tab=readme-ov-file#passthrough-extension
|
||||
[image render hook]: /render-hooks/images/
|
||||
[includes]: https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/#includes
|
||||
[inserted text]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/ins
|
||||
[mark text]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/mark
|
||||
[Markdown attributes]: /content-management/markdown-attributes/
|
||||
[mathematics in Markdown]: content-management/mathematics/
|
||||
[multilingual page resources]: /content-management/page-resources/#multilingual
|
||||
[PHP Markdown Extra: Definition lists]: https://michelf.ca/projects/php-markdown/extra/#def-list
|
||||
[PHP Markdown Extra: Footnotes]: https://michelf.ca/projects/php-markdown/extra/#footnotes
|
||||
[security policy]: /configuration/security/
|
||||
[subscript]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/sub
|
||||
[superscript]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/sup
|
||||
[AsciiDoc]: https://asciidoc.org/
|
||||
[Emacs Org Mode]: https://orgmode.org/
|
||||
[Pandoc]: https://www.pandoc.org/
|
||||
[reStructuredText]: https://docutils.sourceforge.io/rst.html
|
||||
82
docs/content/en/configuration/media-types.md
Normal file
82
docs/content/en/configuration/media-types.md
Normal file
|
|
@ -0,0 +1,82 @@
|
|||
---
|
||||
title: Configure media types
|
||||
linkTitle: Media types
|
||||
description: Configure media types.
|
||||
categories: []
|
||||
keywords: []
|
||||
---
|
||||
|
||||
{{% glossary-term "media type" %}}
|
||||
|
||||
Configured media types serve multiple purposes in Hugo, including the definition of [output formats](g). This is the default media type configuration in tabular form:
|
||||
|
||||
{{< datatable "config" "mediaTypes" "_key" "suffixes" >}}
|
||||
|
||||
The `suffixes` column in the table above shows the suffixes associated with each media type. For example, Hugo associates `.html` and `.htm` files with the `text/html` media type.
|
||||
|
||||
> [!note]
|
||||
> The first suffix is the primary suffix. Use the primary suffix when naming template files. For example, when creating a template for an RSS feed, use the `xml` suffix.
|
||||
|
||||
## Default configuration
|
||||
|
||||
The following is the default configuration that matches the table above:
|
||||
|
||||
{{< code-toggle file=hugo config=mediaTypes />}}
|
||||
|
||||
delimiter
|
||||
: (`string`) The delimiter between the file name and the suffix. The delimiter, in conjunction with the suffix, forms the file extension. Default is `"."`.
|
||||
|
||||
suffixes
|
||||
: (`[]string`) The suffixes associated with this media type. The first suffix is the primary suffix.
|
||||
|
||||
## Modify a media type
|
||||
|
||||
You can modify any of the default media types. For example, to switch the primary suffix for `text/html` from `html` to `htm`:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[mediaTypes.'text/html']
|
||||
suffixes = ['htm','html']
|
||||
{{< /code-toggle >}}
|
||||
|
||||
If you alter a default media type, you must also explicitly redefine all output formats that utilize that media type. For example, to ensure the changes above affect the `html` output format, redefine the `html` output format:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[outputFormats.html]
|
||||
mediaType = 'text/html'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
## Create a media type
|
||||
|
||||
You can create new media types as needed. For example, to create a media type for an Atom feed:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[mediaTypes.'application/atom+xml']
|
||||
suffixes = ['atom']
|
||||
{{< /code-toggle >}}
|
||||
|
||||
## Media types without suffixes
|
||||
|
||||
Occasionally, you may need to create a media type without a suffix or delimiter. For example, [Netlify] recognizes configuration files named `_redirects` and `_headers`, which Hugo can generate using custom [output formats](g).
|
||||
|
||||
To support these custom output formats, register a custom media type with no suffix or delimiter:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[mediaTypes."text/netlify"]
|
||||
delimiter = ""
|
||||
{{< /code-toggle >}}
|
||||
|
||||
The custom output format definitions would look something like this:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[outputFormats.redir]
|
||||
baseName = "_redirects"
|
||||
isPlainText = true
|
||||
mediatype = "text/netlify"
|
||||
[outputFormats.headers]
|
||||
baseName = "_headers"
|
||||
isPlainText = true
|
||||
mediatype = "text/netlify"
|
||||
notAlternative = true
|
||||
{{< /code-toggle >}}
|
||||
|
||||
[Netlify]: https://www.netlify.com/
|
||||
135
docs/content/en/configuration/menus.md
Normal file
135
docs/content/en/configuration/menus.md
Normal file
|
|
@ -0,0 +1,135 @@
|
|||
---
|
||||
title: Configure menus
|
||||
linkTitle: Menus
|
||||
description: Centrally define menu entries for one or more menus.
|
||||
categories: []
|
||||
keywords: []
|
||||
---
|
||||
|
||||
> [!note]
|
||||
> To understand Hugo's menu system, please refer to the [menus] page.
|
||||
|
||||
There are three ways to define menu entries:
|
||||
|
||||
1. [Automatically]
|
||||
1. [In front matter]
|
||||
1. In site configuration
|
||||
|
||||
This page covers the site configuration method.
|
||||
|
||||
## Example
|
||||
|
||||
To define entries for a "main" menu:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[[menus.main]]
|
||||
name = 'Home'
|
||||
pageRef = '/'
|
||||
weight = 10
|
||||
|
||||
[[menus.main]]
|
||||
name = 'Products'
|
||||
pageRef = '/products'
|
||||
weight = 20
|
||||
|
||||
[[menus.main]]
|
||||
name = 'Services'
|
||||
pageRef = '/services'
|
||||
weight = 30
|
||||
{{< /code-toggle >}}
|
||||
|
||||
This creates a menu structure that you can access with [`Menus`] method on a `Site` object:
|
||||
|
||||
```go-html-template
|
||||
{{ range .Site.Menus.main }}
|
||||
...
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
See [menu templates] for a detailed example.
|
||||
|
||||
To define entries for a "footer" menu:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[[menus.footer]]
|
||||
name = 'Terms'
|
||||
pageRef = '/terms'
|
||||
weight = 10
|
||||
|
||||
[[menus.footer]]
|
||||
name = 'Privacy'
|
||||
pageRef = '/privacy'
|
||||
weight = 20
|
||||
{{< /code-toggle >}}
|
||||
|
||||
Access this menu structure in the same way:
|
||||
|
||||
```go-html-template
|
||||
{{ range .Site.Menus.footer }}
|
||||
...
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
## Properties
|
||||
|
||||
Menu entries usually include at least three properties: `name`, `weight`, and either `pageRef` or `url`. Use `pageRef` for internal page destinations and `url` for external destinations.
|
||||
|
||||
These are the available menu entry properties:
|
||||
|
||||
{{% include "/_common/menu-entry-properties.md" %}}
|
||||
|
||||
pageRef
|
||||
: (`string`) The [logical path](g) of the target page. For example:
|
||||
|
||||
page kind|pageRef
|
||||
:--|:--
|
||||
home|`/`
|
||||
page|`/books/book-1`
|
||||
section|`/books`
|
||||
taxonomy|`/tags`
|
||||
term|`/tags/foo`
|
||||
|
||||
url
|
||||
: (`string`) The destination URL. Use this for external destinations only.
|
||||
|
||||
## Nested menu
|
||||
|
||||
This nested menu demonstrates some of the available properties:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[[menus.main]]
|
||||
name = 'Products'
|
||||
pageRef = '/products'
|
||||
weight = 10
|
||||
|
||||
[[menus.main]]
|
||||
name = 'Hardware'
|
||||
pageRef = '/products/hardware'
|
||||
parent = 'Products'
|
||||
weight = 1
|
||||
|
||||
[[menus.main]]
|
||||
name = 'Software'
|
||||
pageRef = '/products/software'
|
||||
parent = 'Products'
|
||||
weight = 2
|
||||
|
||||
[[menus.main]]
|
||||
name = 'Services'
|
||||
pageRef = '/services'
|
||||
weight = 20
|
||||
|
||||
[[menus.main]]
|
||||
name = 'Hugo'
|
||||
pre = '<i class="fa fa-heart"></i>'
|
||||
url = 'https://gohugo.io/'
|
||||
weight = 30
|
||||
[menus.main.params]
|
||||
rel = 'external'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
[`Menus`]: /methods/site/menus/
|
||||
[Automatically]: /content-management/menus/#define-automatically
|
||||
[In front matter]: /content-management/menus/#define-in-front-matter
|
||||
[menu templates]: /templates/menu/
|
||||
[menus]: /content-management/menus/
|
||||
15
docs/content/en/configuration/minify.md
Normal file
15
docs/content/en/configuration/minify.md
Normal file
|
|
@ -0,0 +1,15 @@
|
|||
---
|
||||
title: Configure minify
|
||||
linkTitle: Minify
|
||||
description: Configure minify.
|
||||
categories: []
|
||||
keywords: []
|
||||
---
|
||||
|
||||
This is the default configuration:
|
||||
|
||||
{{< code-toggle config=minify />}}
|
||||
|
||||
See the [tdewolff/minify] project page for details.
|
||||
|
||||
[tdewolff/minify]: https://github.com/tdewolff/minify
|
||||
179
docs/content/en/configuration/module.md
Normal file
179
docs/content/en/configuration/module.md
Normal file
|
|
@ -0,0 +1,179 @@
|
|||
---
|
||||
title: Configure modules
|
||||
linkTitle: Modules
|
||||
description: Configure modules.
|
||||
categories: []
|
||||
keywords: []
|
||||
aliases: [/hugo-modules/configuration/]
|
||||
---
|
||||
|
||||
## Top-level options
|
||||
|
||||
This is the default configuration:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[module]
|
||||
noProxy = 'none'
|
||||
noVendor = ''
|
||||
private = '*.*'
|
||||
proxy = 'direct'
|
||||
vendorClosest = false
|
||||
workspace = 'off'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
auth
|
||||
: {{< new-in 0.144.0 />}}
|
||||
: (`string`) Configures `GOAUTH` when running the Go command for module operations. This is a semicolon-separated list of authentication commands for go-import and HTTPS module mirror interactions. This is useful for private repositories. See `go help goauth` for more information.
|
||||
|
||||
noProxy
|
||||
: (`string`) A comma-separated list of [glob](g) patterns matching paths that should not use the [configured proxy server](#proxy).
|
||||
|
||||
noVendor
|
||||
: (`string`) A [glob](g) pattern matching module paths to skip when vendoring.
|
||||
|
||||
private
|
||||
: (`string`) A comma-separated list of [glob](g) patterns matching paths that should be treated as private.
|
||||
|
||||
proxy
|
||||
: (`string`) The proxy server to use to download remote modules. Default is `direct`, which means `git clone` and similar.
|
||||
|
||||
replacements
|
||||
: (`string`) Primarily useful for local module development, a comma-separated list of mappings from module paths to directories. Paths may be absolute or relative to the [`themesDir`].
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[module]
|
||||
replacements = 'github.com/bep/my-theme -> ../..,github.com/bep/shortcodes -> /some/path'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
vendorClosest
|
||||
: (`bool`) Whether to pick the vendored module closest to the module using it. The default behavior is to pick the first. Note that there can still be only one dependency of a given module path, so once it is in use it cannot be redefined. Default is `false`.
|
||||
|
||||
workspace
|
||||
: (`string`) The Go workspace file to use, either as an absolute path or a path relative to the current working directory. Enabling this activates Go workspace mode and requires Go 1.18 or later. The default is `off`.
|
||||
|
||||
You may also use environment variables to set any of the above. For example:
|
||||
|
||||
```sh
|
||||
export HUGO_MODULE_PROXY="https://proxy.example.org"
|
||||
export HUGO_MODULE_REPLACEMENTS="github.com/bep/my-theme -> ../.."
|
||||
export HUGO_MODULE_WORKSPACE="/my/hugo.work"
|
||||
```
|
||||
|
||||
{{% include "/_common/gomodules-info.md" %}}
|
||||
|
||||
## Hugo version
|
||||
|
||||
You can specify a required Hugo version for your module in the `module` section. Users will then receive a warning if their Hugo version is incompatible.
|
||||
|
||||
This is the default configuration:
|
||||
|
||||
{{< code-toggle config=module.hugoVersion />}}
|
||||
|
||||
You can omit any of the settings above.
|
||||
|
||||
extended
|
||||
: (`bool`) Whether the extended edition of Hugo is required, satisfied by installing either the extended or extended/deploy edition.
|
||||
|
||||
max
|
||||
: (`string`) The maximum Hugo version supported, for example `0.143.0`.
|
||||
|
||||
min
|
||||
: (`string`) The minimum Hugo version supported, for example `0.123.0`.
|
||||
|
||||
[`themesDir`]: /configuration/all/#themesdir
|
||||
|
||||
## Imports
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[[module.imports]]
|
||||
disable = false
|
||||
ignoreConfig = false
|
||||
ignoreImports = false
|
||||
path = "github.com/gohugoio/hugoTestModules1_linux/modh1_2_1v"
|
||||
[[module.imports]]
|
||||
path = "my-shortcodes"
|
||||
{{< /code-toggle >}}
|
||||
|
||||
disable
|
||||
: (`bool`) Whether to disable the module but keep version information in the `go.*` files. Default is `false`.
|
||||
|
||||
ignoreConfig
|
||||
: (`bool`) Whether to ignore module configuration files, for example, `hugo.toml`. This will also prevent loading of any transitive module dependencies. Default is `false`.
|
||||
|
||||
ignoreImports
|
||||
: (`bool`) Whether to ignore module imports. Default is `false`.
|
||||
|
||||
noMounts
|
||||
: (`bool`) Whether to disable directory mounting for this import. Default is `false`.
|
||||
|
||||
noVendor
|
||||
: (`bool`) Whether to disable vendoring for this import. This setting is restricted to the main project. Default is `false`.
|
||||
|
||||
path
|
||||
: (`string`) The module path, either a valid Go module path (e.g., `github.com/gohugoio/myShortcodes`) or the directory name if stored in the [`themesDir`].
|
||||
|
||||
[`themesDir`]: /configuration/all#themesDir
|
||||
|
||||
{{% include "/_common/gomodules-info.md" %}}
|
||||
|
||||
## Mounts
|
||||
|
||||
Before Hugo v0.56.0, custom component paths could only be configured by setting [`archetypeDir`], [`assetDir`], [`contentDir`], [`dataDir`], [`i18nDir`], [`layoutDi`], or [`staticDir`] in the site configuration. Module mounts offer greater flexibility than these legacy settings, but
|
||||
you cannot use both.
|
||||
|
||||
[`archetypeDir`]: /configuration/all/
|
||||
[`assetDir`]: /configuration/all/
|
||||
[`contentDir`]: /configuration/all/
|
||||
[`dataDir`]: /configuration/all/
|
||||
[`i18nDir`]: /configuration/all/
|
||||
[`layoutDi`]: /configuration/all/
|
||||
[`staticDir`]: /configuration/all/
|
||||
|
||||
> [!note]
|
||||
> If you use module mounts do not use the legacy settings.
|
||||
|
||||
### Default mounts
|
||||
|
||||
> [!note]
|
||||
> Adding a new mount to a target root will cause the existing default mount for that root to be ignored. If you still need the default mount, you must explicitly add it along with the new mount.
|
||||
|
||||
The are the default mounts:
|
||||
|
||||
{{< code-toggle config=module.mounts />}}
|
||||
|
||||
source
|
||||
: (`string`) The source directory of the mount. For the main project, this can be either project-relative or absolute. For other modules it must be project-relative.
|
||||
|
||||
target
|
||||
: (`string`) Where the mount will reside within Hugo's virtual file system. It must begin with one of Hugo's component directories: `archetypes`, `assets`, `content`, `data`, `i18n`, `layouts`, or `static`. For example, `content/blog`.
|
||||
|
||||
disableWatch
|
||||
: {{< new-in 0.128.0 />}}
|
||||
: (`bool`) Whether to disable watching in watch mode for this mount. Default is `false`.
|
||||
|
||||
lang
|
||||
: (`string`) The language code, e.g. "en". Relevant for `content` mounts, and `static` mounts when in multihost mode.
|
||||
|
||||
includeFiles
|
||||
: (`string` or `[]string`) One or more [glob](g) patterns matching files or directories to include. If `excludeFiles` is not set, the files matching `includeFiles` will be the files mounted.
|
||||
|
||||
The glob patterns are matched against file names relative to the source root. Use Unix-style forward slashes (`/`), even on Windows. A single forward slash (`/`) matches the mount root, and double asterisks (`**`) act as a recursive wildcard, matching all directories and files beneath a given point (e.g., `/posts/**.jpg`). The search is case-insensitive.
|
||||
|
||||
excludeFiles
|
||||
: (`string` or `[]string`) One or more [glob](g) patterns matching files to exclude.
|
||||
|
||||
### Example
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[module]
|
||||
[[module.mounts]]
|
||||
source="content"
|
||||
target="content"
|
||||
excludeFiles="docs/*"
|
||||
[[module.mounts]]
|
||||
source="node_modules"
|
||||
target="assets"
|
||||
[[module.mounts]]
|
||||
source="assets"
|
||||
target="assets"
|
||||
{{< /code-toggle >}}
|
||||
209
docs/content/en/configuration/output-formats.md
Normal file
209
docs/content/en/configuration/output-formats.md
Normal file
|
|
@ -0,0 +1,209 @@
|
|||
---
|
||||
title: Configure output formats
|
||||
linkTitle: Output formats
|
||||
description: Configure output formats.
|
||||
categories: []
|
||||
keywords: []
|
||||
---
|
||||
|
||||
{{% glossary-term "output format" %}}
|
||||
|
||||
You can output a page in as many formats as you want. Define an infinite number of output formats, provided they each resolve to a unique file system path.
|
||||
|
||||
This is the default output format configuration in tabular form:
|
||||
|
||||
{{< datatable
|
||||
"config"
|
||||
"outputFormats"
|
||||
"_key"
|
||||
"mediaType"
|
||||
"weight"
|
||||
"baseName"
|
||||
"isHTML"
|
||||
"isPlainText"
|
||||
"noUgly"
|
||||
"notAlternative"
|
||||
"path"
|
||||
"permalinkable"
|
||||
"protocol"
|
||||
"rel"
|
||||
"root"
|
||||
"ugly"
|
||||
>}}
|
||||
|
||||
## Default configuration
|
||||
|
||||
The following is the default configuration that matches the table above:
|
||||
|
||||
{{< code-toggle config=outputFormats />}}
|
||||
|
||||
baseName
|
||||
: (`string`) The base name of the published file. Default is `index`.
|
||||
|
||||
isHTML
|
||||
: (`bool`) Whether to classify the output format as HTML. Hugo uses this value to determine when to create alias redirects and when to inject the LiveReload script. Default is `false`.
|
||||
|
||||
isPlainText
|
||||
: (`bool`) Whether to parse templates for this output format with Go's [text/template] package instead of the [html/template] package. Default is `false`.
|
||||
|
||||
mediaType
|
||||
: (`string`) The [media type](g) of the published file. This must match one of the [configured media types].
|
||||
|
||||
notAlternative
|
||||
: (`bool`) Whether to exclude this output format from the values returned by the [`AlternativeOutputFormats`] method on a `Page` object. Default is `false`.
|
||||
|
||||
noUgly
|
||||
: (`bool`) Whether to disable ugly URLs for this output format when [`uglyURLs`] are enabled in your site configuration. Default is `false`.
|
||||
|
||||
path
|
||||
: (`string`) The published file's directory path, relative to the root of the publish directory. If not specified, the file will be published using its content path.
|
||||
|
||||
permalinkable
|
||||
: (`bool`) Whether to return the rendering output format rather than main output format when invoking the [`Permalink`] and [`RelPermalink`] methods on a `Page` object. See [details](#link-to-output-formats). Enabled by default for the `html` and `amp` output formats. Default is `false`.
|
||||
|
||||
protocol
|
||||
: (`string`) The protocol (scheme) of the URL for this output format. For example, `https://` or `webcal://`. Default is the scheme of the [`baseURL`] parameter in your site configuration, typically `https://`.
|
||||
|
||||
rel
|
||||
: (`string`) If provided, you can assign this value to `rel` attributes in `link` elements when iterating over output formats in your templates. Default is `alternate`.
|
||||
|
||||
root
|
||||
: (`bool`) Whether to publish files to the root of the publish directory. Default is `false`.
|
||||
|
||||
ugly
|
||||
: (`bool`) Whether to enable uglyURLs for this output format when `uglyURLs` is `false` in your site configuration. Default is `false`.
|
||||
|
||||
weight
|
||||
: (`int`) When set to a non-zero value, Hugo uses the `weight` as the first criteria when sorting output formats, falling back to the name of the output format. Lighter items float to the top, while heavier items sink to the bottom. Hugo renders output formats sequentially based on the sort order. Default is `0`, except for the `html` output format, which has a default weight of `10`.
|
||||
|
||||
## Modify an output format
|
||||
|
||||
You can modify any of the default output formats. For example, to prioritize `json` rendering over `html` rendering, when both are generated, adjust the [`weight`](#weight):
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[outputFormats.json]
|
||||
weight = 1
|
||||
[outputFormats.html]
|
||||
weight = 2
|
||||
{{< /code-toggle >}}
|
||||
|
||||
The example above shows that when you modify a default content format, you only need to define the properties that differ from their default values.
|
||||
|
||||
## Create an output format
|
||||
|
||||
You can create new output formats as needed. For example, you may wish to create an output format to support Atom feeds.
|
||||
|
||||
### Step 1
|
||||
|
||||
Output formats require a specified media type. Because Atom feeds use `application/atom+xml`, which is not one of the [default media types], you must create it first.
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[mediaTypes.'application/atom+xml']
|
||||
suffixes = ['atom']
|
||||
{{< /code-toggle >}}
|
||||
|
||||
See [configure media types] for more information.
|
||||
|
||||
### Step 2
|
||||
|
||||
Create a new output format:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[outputFormats.atom]
|
||||
mediaType = 'application/atom+xml'
|
||||
noUgly = true
|
||||
{{< /code-toggle >}}
|
||||
|
||||
Note that we use the default settings for all other output format properties.
|
||||
|
||||
### Step 3
|
||||
|
||||
Specify the page [kinds](g) for which to render this output format:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[outputs]
|
||||
home = ['html', 'rss', 'atom']
|
||||
section = ['html', 'rss', 'atom']
|
||||
taxonomy = ['html', 'rss', 'atom']
|
||||
term = ['html', 'rss', 'atom']
|
||||
{{< /code-toggle >}}
|
||||
|
||||
See [configure outputs] for more information.
|
||||
|
||||
### Step 4
|
||||
|
||||
Create a template to render the output format. Since Atom feeds are lists, you need to create a list template. Consult the [template lookup order] to find the correct template path:
|
||||
|
||||
```text
|
||||
layouts/_default/list.atom.atom
|
||||
```
|
||||
|
||||
We leave writing the template code as an exercise for you. Aim for a result similar to the [embedded RSS template].
|
||||
|
||||
## List output formats
|
||||
|
||||
To access output formats, each `Page` object provides two methods: [`OutputFormats`] (for all formats, including the current one) and [`AlternativeOutputFormats`]. Use `AlternativeOutputFormats` to create a link `rel` list within your site's `head` element, as shown below:
|
||||
|
||||
```go-html-template
|
||||
{{ range .AlternativeOutputFormats }}
|
||||
<link rel="{{ .Rel }}" type="{{ .MediaType.Type }}" href="{{ .Permalink | safeURL }}">
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
## Link to output formats
|
||||
|
||||
By default, a `Page` object's [`Permalink`] and [`RelPermalink`] methods return the URL of the [primary output format](g), typically `html`. This behavior remains consistent regardless of the template used.
|
||||
|
||||
For example, in `single.json.json`, you'll see:
|
||||
|
||||
```go-html-template
|
||||
{{ .RelPermalink }} → /that-page/
|
||||
{{ with .OutputFormats.Get "json" }}
|
||||
{{ .RelPermalink }} → /that-page/index.json
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
To make these methods return the URL of the _current_ template's output format, you must set the [`permalinkable`] setting to `true` for that format.
|
||||
|
||||
With `permalinkable` set to true for `json` in the same `single.json.json` template:
|
||||
|
||||
```go-html-template
|
||||
{{ .RelPermalink }} → /that-page/index.json
|
||||
{{ with .OutputFormats.Get "html" }}
|
||||
{{ .RelPermalink }} → /that-page/
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
## Template lookup order
|
||||
|
||||
Each output format requires a template conforming to the [template lookup order].
|
||||
|
||||
For the highest specificity in the template lookup order, include the page kind, output format, and suffix in the file name:
|
||||
|
||||
```text
|
||||
[page kind].[output format].[suffix]
|
||||
```
|
||||
|
||||
For example, for section pages:
|
||||
|
||||
Output format|Template path
|
||||
:--|:--
|
||||
`html`|`layouts/_default/section.html.html`
|
||||
`json`|`layouts/_default/section.json.json`
|
||||
`rss`|`layouts/_default/section.rss.xml`
|
||||
|
||||
[`AlternativeOutputFormats`]: /methods/page/alternativeoutputformats/
|
||||
[`OutputFormats`]: /methods/page/outputformats/
|
||||
[`Permalink`]: /methods/page/permalink/
|
||||
[`RelPermalink`]: /methods/page/relpermalink/
|
||||
[`baseURL`]: /configuration/all/#baseurl
|
||||
[`permalinkable`]: #permalinkable
|
||||
[`uglyURLs`]: /configuration/ugly-urls/
|
||||
[configure media types]: /configuration/media-types/
|
||||
[configure outputs]: /configuration/outputs/
|
||||
[configured media types]: /configuration/media-types/
|
||||
[default media types]: /configuration/media-types/
|
||||
[embedded RSS template]: {{% eturl rss %}}
|
||||
[html/template]: https://pkg.go.dev/html/template
|
||||
[template lookup order]: /templates/lookup-order/
|
||||
[text/template]: https://pkg.go.dev/text/template
|
||||
49
docs/content/en/configuration/outputs.md
Normal file
49
docs/content/en/configuration/outputs.md
Normal file
|
|
@ -0,0 +1,49 @@
|
|||
---
|
||||
title: Configure outputs
|
||||
linkTitle: Outputs
|
||||
description: Configure which output formats to render for each page kind.
|
||||
categories: []
|
||||
keywords: []
|
||||
---
|
||||
|
||||
{{% glossary-term "output format" %}}
|
||||
|
||||
Learn more about creating and configuring output formats in the [configure output formats] section.
|
||||
|
||||
## Outputs per page kind
|
||||
|
||||
The following default configuration determines the output formats generated for each page kind:
|
||||
|
||||
{{< code-toggle config=outputs />}}
|
||||
|
||||
To render the built-in `json` output format for the `home` page kind, assuming you've already created the necessary template, add the following to your configuration:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[outputs]
|
||||
home = ['html','rss','json']
|
||||
{{< /code-toggle >}}
|
||||
|
||||
Notice in this example that we only specified the `home` page kind. You don't need to include entries for other page kinds unless you intend to modify their default output formats.
|
||||
|
||||
> [!note]
|
||||
> The order of the output formats in the arrays above is important. The first element will be the _primary output format_ for that page kind, and in most cases that should be `html` as shown in the default configuration.
|
||||
>
|
||||
> The primary output format for a given page kind determines the value returned by the [`Permalink`] and [`RelPermalink`] methods on a `Page` object.
|
||||
>
|
||||
> See the [link to output formats] section for details.
|
||||
|
||||
## Outputs per page
|
||||
|
||||
Add output formats to a page's rendering using the `outputs` field in its front matter. For example, to include `json` in the output formats rendered for a specific page:
|
||||
|
||||
{{< code-toggle file=content/example.md fm=true >}}
|
||||
title = 'Example'
|
||||
outputs = ['json']
|
||||
{{< /code-toggle >}}
|
||||
|
||||
In its default configuration, Hugo will render both the `html` and `json` output formats for this page. The `outputs` field appends to, rather than replaces, the site's configured outputs.
|
||||
|
||||
[`Permalink`]: /methods/page/permalink/
|
||||
[`RelPermalink`]: /methods/page/relpermalink/
|
||||
[configure output formats]: /configuration/output-formats/
|
||||
[link to output formats]: configuration/output-formats/#link-to-output-formats
|
||||
34
docs/content/en/configuration/page.md
Normal file
34
docs/content/en/configuration/page.md
Normal file
|
|
@ -0,0 +1,34 @@
|
|||
---
|
||||
title: Configure page
|
||||
linkTitle: Page
|
||||
description: Configure page behavior.
|
||||
categories: []
|
||||
keywords: []
|
||||
---
|
||||
|
||||
{{< new-in 0.133.0 />}}
|
||||
|
||||
{{% glossary-term "default sort order" %}}
|
||||
|
||||
Hugo uses the default sort order to determine the _next_ and _previous_ page relative to the current page when calling these methods on a `Page` object:
|
||||
|
||||
- [`Next`](/methods/page/next/) and [`Prev`](/methods/page/prev/)
|
||||
- [`NextInSection`](/methods/page/nextinsection/) and [`PrevInSection`](/methods/page/previnsection/)
|
||||
|
||||
This is based on this default site configuration:
|
||||
|
||||
{{< code-toggle config=page />}}
|
||||
|
||||
To reverse the meaning of _next_ and _previous_:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[page]
|
||||
nextPrevInSectionSortOrder = 'asc'
|
||||
nextPrevSortOrder = 'asc'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
> [!note]
|
||||
> These settings do not apply to the [`Next`] or [`Prev`] methods on a `Pages` object.
|
||||
|
||||
[`Next`]: /methods/pages/next
|
||||
[`Prev`]: /methods/pages/next
|
||||
45
docs/content/en/configuration/pagination.md
Normal file
45
docs/content/en/configuration/pagination.md
Normal file
|
|
@ -0,0 +1,45 @@
|
|||
---
|
||||
title: Configure pagination
|
||||
linkTitle: Pagination
|
||||
description: Configure pagination.
|
||||
categories: []
|
||||
keywords: []
|
||||
---
|
||||
|
||||
This is the default configuration:
|
||||
|
||||
{{< code-toggle config=pagination />}}
|
||||
|
||||
disableAliases
|
||||
: (`bool`) Whether to disable alias generation for the first pager. Default is `false`.
|
||||
|
||||
pagerSize
|
||||
: (`int`) The number of pages per pager. Default is `10`.
|
||||
|
||||
path
|
||||
: (`string`) The segment of each pager URL indicating that the target page is a pager. Default is `page`.
|
||||
|
||||
With multilingual sites you can define the pagination behavior for each language:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[languages.en]
|
||||
contentDir = 'content/en'
|
||||
languageCode = 'en-US'
|
||||
languageDirection = 'ltr'
|
||||
languageName = 'English'
|
||||
weight = 1
|
||||
[languages.en.pagination]
|
||||
disableAliases = true
|
||||
pagerSize = 10
|
||||
path = 'page'
|
||||
[languages.de]
|
||||
contentDir = 'content/de'
|
||||
languageCode = 'de-DE'
|
||||
languageDirection = 'ltr'
|
||||
languageName = 'Deutsch'
|
||||
weight = 2
|
||||
[languages.de.pagination]
|
||||
disableAliases = true
|
||||
pagerSize = 20
|
||||
path = 'blatt'
|
||||
{{< /code-toggle >}}
|
||||
100
docs/content/en/configuration/params.md
Normal file
100
docs/content/en/configuration/params.md
Normal file
|
|
@ -0,0 +1,100 @@
|
|||
---
|
||||
title: Configure params
|
||||
linkTitle: Params
|
||||
description: Create custom site parameters.
|
||||
categories: []
|
||||
keywords: []
|
||||
---
|
||||
|
||||
Use the `params` key for custom parameters:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
baseURL = 'https://example.org/'
|
||||
title = 'Project Documentation'
|
||||
languageCode = 'en-US'
|
||||
[params]
|
||||
subtitle = 'Reference, Tutorials, and Explanations'
|
||||
[params.contact]
|
||||
email = 'info@example.org'
|
||||
phone = '+1 206-555-1212'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
Access the custom parameters from your templates using the [`Params`] method on a `Site` object:
|
||||
|
||||
[`Params`]: /methods/site/params/
|
||||
|
||||
```go-html-template
|
||||
{{ .Site.Params.subtitle }} → Reference, Tutorials, and Explanations
|
||||
{{ .Site.Params.contact.email }} → info@example.org
|
||||
```
|
||||
|
||||
Key names should use camelCase or snake_case. While TOML, YAML, and JSON allow kebab-case keys, they are not valid [identifiers](g) and cannot be used when [chaining](g) identifiers.
|
||||
|
||||
For example, you can do either of these:
|
||||
|
||||
```go-html-template
|
||||
{{ .Site.params.camelCase.foo }}
|
||||
{{ .Site.params.snake_case.foo }}
|
||||
```
|
||||
|
||||
But you cannot do this:
|
||||
|
||||
```go-html-template
|
||||
{{ .Site.params.kebab-case.foo }}
|
||||
```
|
||||
|
||||
## Multilingual sites
|
||||
|
||||
For multilingual sites, create a `params` key under each language:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
baseURL = 'https://example.org/'
|
||||
defaultContentLanguage = 'en'
|
||||
|
||||
[languages.de]
|
||||
languageCode = 'de-DE'
|
||||
languageDirection = 'ltr'
|
||||
languageName = 'Deutsch'
|
||||
title = 'Projekt Dokumentation'
|
||||
weight = 1
|
||||
|
||||
[languages.de.params]
|
||||
subtitle = 'Referenz, Tutorials und Erklärungen'
|
||||
|
||||
[languages.de.params.contact]
|
||||
email = 'info@de.example.org'
|
||||
phone = '+49 30 1234567'
|
||||
|
||||
[languages.en]
|
||||
languageCode = 'en-US'
|
||||
languageDirection = 'ltr'
|
||||
languageName = 'English'
|
||||
title = 'Project Documentation'
|
||||
weight = 2
|
||||
|
||||
[languages.en.params]
|
||||
subtitle = 'Reference, Tutorials, and Explanations'
|
||||
|
||||
[languages.en.params.contact]
|
||||
email = 'info@example.org'
|
||||
phone = '+1 206-555-1212'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
## Namespacing
|
||||
|
||||
To prevent naming conflicts, module and theme developers should namespace any custom parameters specific to their module or theme.
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[params.modules.myModule.colors]
|
||||
background = '#efefef'
|
||||
font = '#222222'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
To access the module/theme settings:
|
||||
|
||||
```go-html-template
|
||||
{{ $cfg := .Site.Params.module.mymodule }}
|
||||
|
||||
{{ $cfg.colors.background }} → #efefef
|
||||
{{ $cfg.colors.font }} → #222222
|
||||
```
|
||||
162
docs/content/en/configuration/permalinks.md
Normal file
162
docs/content/en/configuration/permalinks.md
Normal file
|
|
@ -0,0 +1,162 @@
|
|||
---
|
||||
title: Configure permalinks
|
||||
linkTitle: Permalinks
|
||||
description: Configure permalinks.
|
||||
categories: []
|
||||
keywords: []
|
||||
---
|
||||
|
||||
This is the default configuration:
|
||||
|
||||
{{< code-toggle config=permalinks />}}
|
||||
|
||||
Define a URL pattern for each top-level section. Each URL pattern can target a given language and/or page kind.
|
||||
|
||||
> [!note]
|
||||
> The [`url`] front matter field overrides any matching permalink pattern.
|
||||
|
||||
## Monolingual example
|
||||
|
||||
With this content structure:
|
||||
|
||||
```text
|
||||
content/
|
||||
├── posts/
|
||||
│ ├── bash-in-slow-motion.md
|
||||
│ └── tls-in-a-nutshell.md
|
||||
├── tutorials/
|
||||
│ ├── git-for-beginners.md
|
||||
│ └── javascript-bundling-with-hugo.md
|
||||
└── _index.md
|
||||
```
|
||||
|
||||
Render tutorials under "training", and render the posts under "articles" with a date-base hierarchy:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[permalinks.page]
|
||||
posts = '/articles/:year/:month/:slug/'
|
||||
tutorials = '/training/:slug/'
|
||||
[permalinks.section]
|
||||
posts = '/articles/'
|
||||
tutorials = '/training/'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
The structure of the published site will be:
|
||||
|
||||
```text
|
||||
public/
|
||||
├── articles/
|
||||
│ ├── 2023/
|
||||
│ │ ├── 04/
|
||||
│ │ │ └── bash-in-slow-motion/
|
||||
│ │ │ └── index.html
|
||||
│ │ └── 06/
|
||||
│ │ └── tls-in-a-nutshell/
|
||||
│ │ └── index.html
|
||||
│ └── index.html
|
||||
├── training/
|
||||
│ ├── git-for-beginners/
|
||||
│ │ └── index.html
|
||||
│ ├── javascript-bundling-with-hugo/
|
||||
│ │ └── index.html
|
||||
│ └── index.html
|
||||
└── index.html
|
||||
```
|
||||
|
||||
To create a date-based hierarchy for regular pages in the content root:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[permalinks.page]
|
||||
"/" = "/:year/:month/:slug/"
|
||||
{{< /code-toggle >}}
|
||||
|
||||
Use the same approach with taxonomy terms. For example, to omit the taxonomy segment of the URL:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[permalinks.term]
|
||||
'tags' = '/:slug/'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
## Multilingual example
|
||||
|
||||
Use the `permalinks` configuration as a component of your localization strategy.
|
||||
|
||||
With this content structure:
|
||||
|
||||
```text
|
||||
content/
|
||||
├── en/
|
||||
│ ├── books/
|
||||
│ │ ├── les-miserables.md
|
||||
│ │ └── the-hunchback-of-notre-dame.md
|
||||
│ └── _index.md
|
||||
└── es/
|
||||
├── books/
|
||||
│ ├── les-miserables.md
|
||||
│ └── the-hunchback-of-notre-dame.md
|
||||
└── _index.md
|
||||
```
|
||||
|
||||
And this site configuration:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
defaultContentLanguage = 'en'
|
||||
defaultContentLanguageInSubdir = true
|
||||
|
||||
[languages.en]
|
||||
contentDir = 'content/en'
|
||||
languageCode = 'en-US'
|
||||
languageDirection = 'ltr'
|
||||
languageName = 'English'
|
||||
weight = 1
|
||||
|
||||
[languages.en.permalinks.page]
|
||||
books = "/books/:slug/"
|
||||
|
||||
[languages.en.permalinks.section]
|
||||
books = "/books/"
|
||||
|
||||
[languages.es]
|
||||
contentDir = 'content/es'
|
||||
languageCode = 'es-ES'
|
||||
languageDirection = 'ltr'
|
||||
languageName = 'Español'
|
||||
weight = 2
|
||||
|
||||
[languages.es.permalinks.page]
|
||||
books = "/libros/:slug/"
|
||||
|
||||
[languages.es.permalinks.section]
|
||||
books = "/libros/"
|
||||
{{< /code-toggle >}}
|
||||
|
||||
The structure of the published site will be:
|
||||
|
||||
```text
|
||||
public/
|
||||
├── en/
|
||||
│ ├── books/
|
||||
│ │ ├── les-miserables/
|
||||
│ │ │ └── index.html
|
||||
│ │ ├── the-hunchback-of-notre-dame/
|
||||
│ │ │ └── index.html
|
||||
│ │ └── index.html
|
||||
│ └── index.html
|
||||
├── es/
|
||||
│ ├── libros/
|
||||
│ │ ├── les-miserables/
|
||||
│ │ │ └── index.html
|
||||
│ │ ├── the-hunchback-of-notre-dame/
|
||||
│ │ │ └── index.html
|
||||
│ │ └── index.html
|
||||
│ └── index.html
|
||||
└── index.html
|
||||
```
|
||||
|
||||
## Tokens
|
||||
|
||||
Use these tokens when defining a URL pattern.
|
||||
|
||||
{{% include "/_common/permalink-tokens.md" %}}
|
||||
|
||||
[`url`]: /content-management/front-matter/#url
|
||||
|
|
@ -1,17 +1,10 @@
|
|||
---
|
||||
title: Privacy
|
||||
title: Configure privacy
|
||||
linkTitle: Privacy
|
||||
description: Configure your site to help comply with regional privacy regulations.
|
||||
categories: [about]
|
||||
keywords: ["GDPR", "Privacy", "Data Protection"]
|
||||
menu:
|
||||
docs:
|
||||
parent: about
|
||||
weight: 40
|
||||
weight: 40
|
||||
toc: true
|
||||
aliases: [/gdpr/,/about/hugo-and-gdpr/]
|
||||
toc: true
|
||||
categories: []
|
||||
keywords: []
|
||||
aliases: [/about/privacy/]
|
||||
---
|
||||
|
||||
## Responsibility
|
||||
|
|
@ -31,12 +24,10 @@ Hugo provides [embedded templates](g) to simplify site and content creation. Som
|
|||
|
||||
Some of these templates include settings to enhance privacy.
|
||||
|
||||
|
||||
## Configuration
|
||||
|
||||
{{% note %}}
|
||||
These settings affect the behavior of some of Hugo's embedded templates. These settings may or may not affect the behavior of templates provided by third parties in their modules or themes.
|
||||
{{% /note %}}
|
||||
> [!note]
|
||||
> These settings affect the behavior of some of Hugo's embedded templates. These settings may or may not affect the behavior of templates provided by third parties in their modules or themes.
|
||||
|
||||
These are the default privacy settings for Hugo's embedded templates:
|
||||
|
||||
111
docs/content/en/configuration/related-content.md
Normal file
111
docs/content/en/configuration/related-content.md
Normal file
|
|
@ -0,0 +1,111 @@
|
|||
---
|
||||
title: Configure related content
|
||||
linkTitle: Related content
|
||||
description: Configure related content.
|
||||
categories: []
|
||||
keywords: []
|
||||
---
|
||||
|
||||
> [!note]
|
||||
> To understand Hugo's related content identification, please refer to the [related content] page.
|
||||
|
||||
Hugo provides a sensible default configuration for identifying related content, but you can customize it in your site configuration, either globally or per language.
|
||||
|
||||
## Default configuration
|
||||
|
||||
This is the default configuration:
|
||||
|
||||
{{< code-toggle config=related />}}
|
||||
|
||||
> [!note]
|
||||
> Adding a `related` section to your site configuration requires you to provide a full configuration. You cannot override individual default values without specifying all related settings.
|
||||
|
||||
## Top-level options
|
||||
|
||||
threshold
|
||||
: (`int`) A value between 0-100, inclusive. A lower value will return more, but maybe not so relevant, matches.
|
||||
|
||||
includeNewer
|
||||
: (`bool`) Whether to include pages newer than the current page in the related content listing. This will mean that the output for older posts may change as new related content gets added. Default is `false`.
|
||||
|
||||
toLower
|
||||
: (`bool`) Whether to transform keywords in both the indexes and the queries to lower case. This may give more accurate results at a slight performance penalty. Default is `false`.
|
||||
|
||||
## Per-index options
|
||||
|
||||
name
|
||||
: (`string`) The index name. This value maps directly to a page parameter. Hugo supports string values (`author` in the example) and lists (`tags`, `keywords` etc.) and time and date objects.
|
||||
|
||||
type
|
||||
: (`string`) One of `basic` or `fragments`. Default is `basic`.
|
||||
|
||||
applyFilter
|
||||
: (`string`) Apply a `type` specific filter to the result of a search. This is currently only used for the `fragments` type.
|
||||
|
||||
weight
|
||||
: (`int`) An integer weight that indicates how important this parameter is relative to the other parameters. It can be `0`, which has the effect of turning this index off, or even negative. Test with different values to see what fits your content best. Default is `0`.
|
||||
|
||||
cardinalityThreshold
|
||||
: (`int`) If between 1 and 100, this is a percentage. All keywords that are used in more than this percentage of documents are removed. For example, setting this to `60` will remove all keywords that are used in more than 60% of the documents in the index. If `0`, no keyword is removed from the index. Default is `0`.
|
||||
|
||||
pattern
|
||||
: (`string`) This is currently only relevant for dates. When listing related content, we may want to list content that is also close in time. Setting "2006" (default value for date indexes) as the pattern for a date index will add weight to pages published in the same year. For busier blogs, "200601" (year and month) may be a better default.
|
||||
|
||||
toLower
|
||||
: (`bool`) Whether to transform keywords in both the indexes and the queries to lower case. This may give more accurate results at a slight performance penalty. Default is `false`.
|
||||
|
||||
## Example
|
||||
|
||||
Imagine we're building a book review site. Our main content will be book reviews, and we'll use genres and authors as taxonomies. When someone views a book review, we want to show a short list of related reviews based on shared authors and genres.
|
||||
|
||||
Create the content:
|
||||
|
||||
```text
|
||||
content/
|
||||
└── book-reviews/
|
||||
├── book-review-1.md
|
||||
├── book-review-2.md
|
||||
├── book-review-3.md
|
||||
├── book-review-4.md
|
||||
└── book-review-5.md
|
||||
```
|
||||
|
||||
Configure the taxonomies:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[taxonomies]
|
||||
author = 'authors'
|
||||
genre = 'genres'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
Configure the related content identification:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[related]
|
||||
includeNewer = true
|
||||
threshold = 80
|
||||
toLower = true
|
||||
[[related.indices]]
|
||||
name = 'authors'
|
||||
weight = 2
|
||||
[[related.indices]]
|
||||
name = 'genres'
|
||||
weight = 1
|
||||
{{< /code-toggle >}}
|
||||
|
||||
We've configured the `authors` index with a weight of `2` and the `genres` index with a weight of `1`. This means Hugo prioritizes shared `authors` as twice as significant as shared `genres`.
|
||||
|
||||
Then render a list of 5 related reviews with a partial template like this:
|
||||
|
||||
```go-html-template {file="layouts/partials/related.html" copy=true}
|
||||
{{ with site.RegularPages.Related . | first 5 }}
|
||||
<p>Related content:</p>
|
||||
<ul>
|
||||
{{ range . }}
|
||||
<li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
[related content]: /content-management/related-content/
|
||||
50
docs/content/en/configuration/security.md
Normal file
50
docs/content/en/configuration/security.md
Normal file
|
|
@ -0,0 +1,50 @@
|
|||
---
|
||||
title: Configure security
|
||||
linkTitle: Security
|
||||
description: Configure security.
|
||||
categories: []
|
||||
keywords: []
|
||||
---
|
||||
|
||||
Hugo's built-in security policy, which restricts access to `os/exec`, remote communication, and similar operations, is configured via allow lists. By default, access is restricted. If a build attempts to use a feature not included in the allow list, it will fail, providing a detailed message.
|
||||
|
||||
This is the default security configuration:
|
||||
|
||||
{{< code-toggle config=security />}}
|
||||
|
||||
enableInlineShortcodes
|
||||
: (`bool`) Whether to enable [inline shortcodes]. Default is `false`.
|
||||
|
||||
exec.allow
|
||||
: (`[]string`) A slice of [regular expressions](g) matching the names of external executables that Hugo is allowed to run.
|
||||
|
||||
exec.osEnv
|
||||
: (`[]string`) A slice of [regular expressions](g) matching the names of operating system environment variables that Hugo is allowed to access.
|
||||
|
||||
funcs.getenv
|
||||
: (`[]string`) A slice of [regular expressions](g) matching the names of operating system environment variables that Hugo is allowed to access with the [`os.Getenv`] function.
|
||||
|
||||
http.methods
|
||||
: (`[]string`) A slice of [regular expressions](g) matching the HTTP methods that the [`resources.GetRemote`] function is allowed to use.
|
||||
|
||||
http.mediaTypes
|
||||
: (`[]string`) Applicable to the `resources.GetRemote` function, a slice of [regular expressions](g) matching the `Content-Type` in HTTP responses that Hugo trusts, bypassing file content analysis for media type detection.
|
||||
|
||||
http.urls
|
||||
: (`[]string`) A slice of [regular expressions](g) matching the URLs that the `resources.GetRemote` function is allowed to access.
|
||||
|
||||
> [!note]
|
||||
> Setting an allow list to the string `none` will completely disable the associated feature.
|
||||
|
||||
You can also override the site configuration with environment variables. For example, to block `resources.GetRemote` from accessing any URL:
|
||||
|
||||
```txt
|
||||
export HUGO_SECURITY_HTTP_URLS=none
|
||||
```
|
||||
|
||||
Learn more about [using environment variables] to configure your site.
|
||||
|
||||
[`os.Getenv`]: /functions/os/getenv
|
||||
[`resources.GetRemote`]: /functions/resources/getremote
|
||||
[inline shortcodes]: /content-management/shortcodes/#inline
|
||||
[using environment variables]: /configuration/introduction/#environment-variables
|
||||
77
docs/content/en/configuration/segments.md
Normal file
77
docs/content/en/configuration/segments.md
Normal file
|
|
@ -0,0 +1,77 @@
|
|||
---
|
||||
title: Configure segments
|
||||
linkTitle: Segments
|
||||
description: Configure your site for segmented rendering.
|
||||
categories: []
|
||||
keywords: []
|
||||
---
|
||||
|
||||
{{< new-in 0.124.0 />}}
|
||||
|
||||
> [!note]
|
||||
> The `segments` configuration applies only to segmented rendering. While it controls when content is rendered, it doesn't restrict access to Hugo's complete object graph (sites and pages), which remains fully available.
|
||||
|
||||
Segmented rendering offers several advantages:
|
||||
|
||||
- Faster builds: Process large sites more efficiently.
|
||||
- Rapid development: Render only a subset of your site for quicker iteration.
|
||||
- Scheduled rebuilds: Rebuild specific sections at different frequencies (e.g., home page and news hourly, full site weekly).
|
||||
- Targeted output: Generate specific output formats (like JSON for search indexes).
|
||||
|
||||
## Segment definition
|
||||
|
||||
Each segment is defined by include and exclude filters:
|
||||
|
||||
- Filters: Each segment has zero or more exclude filters and zero or more include filters.
|
||||
- Matchers: Each filter contains one or more field [glob](g) matchers.
|
||||
- Logic: Matchers within a filter use AND logic. Filters within a section (include or exclude) use OR logic.
|
||||
|
||||
## Filter fields
|
||||
|
||||
Available fields for filtering:
|
||||
|
||||
kind
|
||||
: (`string`) A [glob](g) pattern matching the [page kind](g). For example: ` {taxonomy,term}`.
|
||||
|
||||
lang
|
||||
: (`string`) A [glob](g) pattern matching the [page language]. For example: `{en,de}`.
|
||||
|
||||
output
|
||||
: (`string`) A [glob](g) pattern matching the [output format](g) of the page. For example: `{html,json}`.
|
||||
|
||||
path
|
||||
: (`string`) A [glob](g) pattern matching the page's [logical path](g). For example: `{/books,/books/**}`.
|
||||
|
||||
## Example
|
||||
|
||||
Place broad filters, such as those for language or output format, in the excludes section. For example:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[segments.segment1]
|
||||
[[segments.segment1.excludes]]
|
||||
lang = "n*"
|
||||
[[segments.segment1.excludes]]
|
||||
lang = "en"
|
||||
output = "rss"
|
||||
[[segments.segment1.includes]]
|
||||
kind = "{home,term,taxonomy}"
|
||||
[[segments.segment1.includes]]
|
||||
path = "{/docs,/docs/**}"
|
||||
{{< /code-toggle >}}
|
||||
|
||||
## Rendering segments
|
||||
|
||||
Render specific segments using the [`renderSegments`] configuration or the `--renderSegments` flag:
|
||||
|
||||
```bash
|
||||
hugo --renderSegments segment1
|
||||
```
|
||||
|
||||
You can configure multiple segments and use a comma-separated list with `--renderSegments` to render them all.
|
||||
|
||||
```bash
|
||||
hugo --renderSegments segment1,segment2
|
||||
```
|
||||
|
||||
[`renderSegments`]: /configuration/all/#rendersegments
|
||||
[page language]: /methods/page/language/
|
||||
128
docs/content/en/configuration/server.md
Normal file
128
docs/content/en/configuration/server.md
Normal file
|
|
@ -0,0 +1,128 @@
|
|||
---
|
||||
title: Configure server
|
||||
linkTitle: Server
|
||||
description: Configure the development server.
|
||||
categories: []
|
||||
keywords: []
|
||||
---
|
||||
|
||||
These settings are exclusive to Hugo's development server, so a dedicated [configuration directory] for development, where the server is configured accordingly, is the recommended approach.
|
||||
|
||||
[configuration directory]: /configuration/introduction/#configuration-directory
|
||||
|
||||
```text
|
||||
project/
|
||||
└── config/
|
||||
├── _default/
|
||||
│ └── hugo.toml
|
||||
└── development/
|
||||
└── server.toml
|
||||
```
|
||||
|
||||
## Default settings
|
||||
|
||||
The development server defaults to redirecting to `/404.html` for any requests to URLs that don't exist. See the [404 errors](#404-errors) section below for details.
|
||||
|
||||
{{< code-toggle config=server />}}
|
||||
|
||||
force
|
||||
: (`bool`) Whether to force a redirect even if there is existing content in the path.
|
||||
|
||||
from
|
||||
: (`string`) A [glob](g) pattern matching the requested URL. Either `from` or `fromRE` must be set. If both `from` and `fromRe` are specified, the URL must match both patterns.
|
||||
|
||||
fromHeaders
|
||||
: {{< new-in 0.144.0 />}}
|
||||
: (`map[string][string]`) Headers to match for the redirect. This maps the HTTP header name to a [glob](g) pattern with values to match. If the map is empty, the redirect will always be triggered.
|
||||
|
||||
fromRe
|
||||
: {{< new-in 0.144.0 />}}
|
||||
: (`string`) A [regular expression](g) used to match the requested URL. Either `from` or `fromRE` must be set. If both `from` and `fromRe` are specified, the URL must match both patterns. Capture groups from the regular expression are accessible in the `to` field as `$1`, `$2`, and so on.
|
||||
|
||||
status
|
||||
: (`string`) The HTTP status code to use for the redirect. A status code of 200 will trigger a URL rewrite.
|
||||
|
||||
to
|
||||
: (`string`) The URL to forward the request to.
|
||||
|
||||
## Headers
|
||||
|
||||
Include headers in every server response to facilitate testing, particularly for features like Content Security Policies.
|
||||
|
||||
[Content Security Policies]: https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP
|
||||
|
||||
{{< code-toggle file=config/development/server >}}
|
||||
[[headers]]
|
||||
for = "/**"
|
||||
|
||||
[headers.values]
|
||||
X-Frame-Options = "DENY"
|
||||
X-XSS-Protection = "1; mode=block"
|
||||
X-Content-Type-Options = "nosniff"
|
||||
Referrer-Policy = "strict-origin-when-cross-origin"
|
||||
Content-Security-Policy = "script-src localhost:1313"
|
||||
{{< /code-toggle >}}
|
||||
|
||||
## Redirects
|
||||
|
||||
You can define simple redirect rules.
|
||||
|
||||
{{< code-toggle file=config/development/server >}}
|
||||
[[redirects]]
|
||||
from = "/myspa/**"
|
||||
to = "/myspa/"
|
||||
status = 200
|
||||
force = false
|
||||
{{< /code-toggle >}}
|
||||
|
||||
The `200` status code in this example triggers a URL rewrite, which is typically the desired behavior for [single-page applications].
|
||||
|
||||
[single-page applications]: https://en.wikipedia.org/wiki/Single-page_application
|
||||
|
||||
## 404 errors
|
||||
|
||||
The development server defaults to redirecting to /404.html for any requests to URLs that don't exist.
|
||||
|
||||
{{< code-toggle config=server />}}
|
||||
|
||||
If you've already defined other redirects, you must explicitly add the 404 redirect.
|
||||
|
||||
{{< code-toggle file=config/development/server >}}
|
||||
[[redirects]]
|
||||
force = false
|
||||
from = "/**"
|
||||
to = "/404.html"
|
||||
status = 404
|
||||
{{< /code-toggle >}}
|
||||
|
||||
For multilingual sites, ensure the default language 404 redirect is defined last:
|
||||
|
||||
{{< code-toggle file=config/development/server >}}
|
||||
defaultContentLanguage = 'en'
|
||||
defaultContentLanguageInSubdir = false
|
||||
[[redirects]]
|
||||
from = '/fr/**'
|
||||
to = '/fr/404.html'
|
||||
status = 404
|
||||
|
||||
[[redirects]] # Default language must be last.
|
||||
from = '/**'
|
||||
to = '/404.html'
|
||||
status = 404
|
||||
{{< /code-toggle >}}
|
||||
|
||||
When the default language is served from a subdirectory:
|
||||
|
||||
{{< code-toggle file=config/development/server >}}
|
||||
defaultContentLanguage = 'en'
|
||||
defaultContentLanguageInSubdir = true
|
||||
[[redirects]]
|
||||
from = '/fr/**'
|
||||
to = '/fr/404.html'
|
||||
status = 404
|
||||
|
||||
[[redirects]] # Default language must be last.
|
||||
from = '/**'
|
||||
to = '/en/404.html'
|
||||
status = 404
|
||||
{{< /code-toggle >}}
|
||||
Some files were not shown because too many files have changed in this diff Show more
Loading…
Add table
Add a link
Reference in a new issue