mirror of
https://github.com/gohugoio/hugo.git
synced 2026-08-24 07:18:54 +00:00
Merge commit 'c86d9f4aa8a58931f52df6516f10b67c807505fb'
This commit is contained in:
Bjørn Erik Pedersen
@@ -104,6 +104,8 @@
|
||||
// ------------------------------------------------------------------------
|
||||
// cspell: ignore foreign language words
|
||||
// ------------------------------------------------------------------------
|
||||
"Bokmål",
|
||||
"Norsk",
|
||||
"bezpieczeństwo",
|
||||
"blatt",
|
||||
"buch",
|
||||
|
||||
@@ -27,7 +27,7 @@
|
||||
/* 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:px-0.5 prose-code:text-gray-600 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 */
|
||||
|
||||
@@ -1,20 +1,24 @@
|
||||
/* Opt in to native cross-document view transitions on navigation. */
|
||||
@view-transition {
|
||||
navigation: auto;
|
||||
}
|
||||
|
||||
/* Global slight fade */
|
||||
::view-transition-old(root),
|
||||
::view-transition-new(root) {
|
||||
animation-duration: 200ms;
|
||||
}
|
||||
|
||||
::view-transition-old(qr),
|
||||
::view-transition-new(qr) {
|
||||
animation-duration: 800ms;
|
||||
animation-delay: 250ms;
|
||||
}
|
||||
|
||||
.view-transition-qr {
|
||||
view-transition-name: qr;
|
||||
}
|
||||
|
||||
/* Turbo styles */
|
||||
.turbo-progress-bar {
|
||||
visibility: hidden;
|
||||
/*
|
||||
* Persistent chrome (header/footer) is named so it gets its own snapshot
|
||||
* instead of being part of the root crossfade. Holding it static prevents
|
||||
* the flicker that the sticky header otherwise shows on every navigation.
|
||||
*/
|
||||
::view-transition-group(site-header),
|
||||
::view-transition-group(site-footer),
|
||||
::view-transition-old(site-header),
|
||||
::view-transition-new(site-header),
|
||||
::view-transition-old(site-footer),
|
||||
::view-transition-new(site-footer) {
|
||||
animation: none;
|
||||
}
|
||||
|
||||
@@ -1,123 +0,0 @@
|
||||
var debug = 0 ? console.log.bind(console, '[explorer]') : function () {};
|
||||
|
||||
// This is currently not used, but kept in case I change my mind.
|
||||
export const explorer = (Alpine) => ({
|
||||
uiState: {
|
||||
containerScrollTop: -1,
|
||||
lastActiveRef: '',
|
||||
},
|
||||
treeState: {
|
||||
// The href of the current page.
|
||||
currentNode: '',
|
||||
// The state of each node in the tree.
|
||||
nodes: {},
|
||||
|
||||
// We currently only list the sections, not regular pages, in the side bar.
|
||||
// This strikes me as the right balance. The pages gets listed on the section pages.
|
||||
// This array is sorted by length, so we can find the longest prefix of the current page
|
||||
// without having to iterate over all the keys.
|
||||
nodeRefsByLength: [],
|
||||
},
|
||||
async init() {
|
||||
let keys = Reflect.ownKeys(this.$refs);
|
||||
for (let key of keys) {
|
||||
let n = {
|
||||
open: false,
|
||||
active: false,
|
||||
};
|
||||
this.treeState.nodes[key] = n;
|
||||
this.treeState.nodeRefsByLength.push(key);
|
||||
}
|
||||
|
||||
this.treeState.nodeRefsByLength.sort((a, b) => b.length - a.length);
|
||||
|
||||
this.setCurrentActive();
|
||||
},
|
||||
|
||||
longestPrefix(ref) {
|
||||
let longestPrefix = '';
|
||||
for (let key of this.treeState.nodeRefsByLength) {
|
||||
if (ref.startsWith(key)) {
|
||||
longestPrefix = key;
|
||||
break;
|
||||
}
|
||||
}
|
||||
return longestPrefix;
|
||||
},
|
||||
|
||||
setCurrentActive() {
|
||||
let ref = this.longestPrefix(window.location.pathname);
|
||||
let activeChanged = this.uiState.lastActiveRef !== ref;
|
||||
debug('setCurrentActive', this.uiState.lastActiveRef, window.location.pathname, '=>', ref, activeChanged);
|
||||
this.uiState.lastActiveRef = ref;
|
||||
if (this.uiState.containerScrollTop === -1 && activeChanged) {
|
||||
// Navigation outside of the explorer menu.
|
||||
let el = document.querySelector(`[x-ref="${ref}"]`);
|
||||
if (el) {
|
||||
this.$nextTick(() => {
|
||||
debug('scrolling to', ref);
|
||||
el.scrollIntoView({ behavior: 'smooth', block: 'center' });
|
||||
});
|
||||
}
|
||||
}
|
||||
this.treeState.currentNode = ref;
|
||||
for (let key in this.treeState.nodes) {
|
||||
let n = this.treeState.nodes[key];
|
||||
n.active = false;
|
||||
n.open = ref == key || ref.startsWith(key);
|
||||
if (n.open) {
|
||||
debug('open', key);
|
||||
}
|
||||
}
|
||||
|
||||
let n = this.treeState.nodes[this.longestPrefix(ref)];
|
||||
if (n) {
|
||||
n.active = true;
|
||||
}
|
||||
},
|
||||
|
||||
getScrollingContainer() {
|
||||
return document.getElementById('leftsidebar');
|
||||
},
|
||||
|
||||
onLoad() {
|
||||
debug('onLoad', this.uiState.containerScrollTop);
|
||||
if (this.uiState.containerScrollTop >= 0) {
|
||||
debug('onLoad: scrolling to', this.uiState.containerScrollTop);
|
||||
this.getScrollingContainer().scrollTo(0, this.uiState.containerScrollTop);
|
||||
}
|
||||
this.uiState.containerScrollTop = -1;
|
||||
},
|
||||
|
||||
onBeforeRender() {
|
||||
debug('onBeforeRender', this.uiState.containerScrollTop);
|
||||
this.setCurrentActive();
|
||||
},
|
||||
|
||||
toggleNode(ref) {
|
||||
this.uiState.containerScrollTop = this.getScrollingContainer().scrollTop;
|
||||
this.uiState.lastActiveRef = '';
|
||||
debug('toggleNode', ref, this.uiState.containerScrollTop);
|
||||
|
||||
let node = this.treeState.nodes[ref];
|
||||
if (!node) {
|
||||
debug('node not found', ref);
|
||||
return;
|
||||
}
|
||||
let wasOpen = node.open;
|
||||
},
|
||||
|
||||
isCurrent(ref) {
|
||||
let n = this.treeState.nodes[ref];
|
||||
return n && n.active;
|
||||
},
|
||||
|
||||
isOpen(ref) {
|
||||
let node = this.treeState.nodes[ref];
|
||||
if (!node) return false;
|
||||
if (node.open) {
|
||||
debug('isOpen', ref);
|
||||
}
|
||||
return node.open;
|
||||
},
|
||||
});
|
||||
@@ -10,7 +10,7 @@ const groupByLvl0 = (array) => {
|
||||
}, {});
|
||||
};
|
||||
|
||||
const applyHelperFuncs = (array) => {
|
||||
const adjustHits = (array, isServer) => {
|
||||
if (!array) return [];
|
||||
return array.map((item) => {
|
||||
item.getHeadingHTML = function () {
|
||||
@@ -30,6 +30,11 @@ const applyHelperFuncs = (array) => {
|
||||
|
||||
return `${lvl2.value} <span class="text-gray-500"> > </span> ${lvl3.value}`;
|
||||
};
|
||||
|
||||
if (isServer) {
|
||||
// Trim https://gohugo.io from the url to make it work locally.
|
||||
item.url = item.url.replace('https://gohugo.io', '');
|
||||
}
|
||||
return item;
|
||||
});
|
||||
};
|
||||
@@ -99,7 +104,7 @@ export const search = (Alpine, cfg) => ({
|
||||
})
|
||||
.then((response) => response.json())
|
||||
.then((data) => {
|
||||
this.result = groupByLvl0(applyHelperFuncs(data.results[0].hits));
|
||||
this.result = groupByLvl0(adjustHits(data.results[0].hits, cfg.params.isServer));
|
||||
this.cache.put(this.query, this.result);
|
||||
});
|
||||
},
|
||||
|
||||
@@ -1,67 +0,0 @@
|
||||
export function bridgeTurboAndAlpine(Alpine) {
|
||||
document.addEventListener('turbo:before-render', (event) => {
|
||||
event.detail.newBody.querySelectorAll('[data-alpine-generated]').forEach((el) => {
|
||||
if (el.hasAttribute('data-alpine-generated')) {
|
||||
el.removeAttribute('data-alpine-generated');
|
||||
el.remove();
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
document.addEventListener('turbo:render', () => {
|
||||
if (document.documentElement.hasAttribute('data-turbo-preview')) {
|
||||
return;
|
||||
}
|
||||
|
||||
document.querySelectorAll('[data-alpine-ignored]').forEach((el) => {
|
||||
el.removeAttribute('x-ignore');
|
||||
el.removeAttribute('data-alpine-ignored');
|
||||
});
|
||||
|
||||
document.body.querySelectorAll('[x-data]').forEach((el) => {
|
||||
if (el.hasAttribute('data-turbo-permanent')) {
|
||||
return;
|
||||
}
|
||||
Alpine.initTree(el);
|
||||
});
|
||||
|
||||
Alpine.startObservingMutations();
|
||||
});
|
||||
|
||||
// Cleanup Alpine state on navigation.
|
||||
document.addEventListener('turbo:before-cache', () => {
|
||||
// This will be restarted in turbo:render.
|
||||
Alpine.stopObservingMutations();
|
||||
|
||||
document.body.querySelectorAll('[data-turbo-permanent]').forEach((el) => {
|
||||
if (!el.hasAttribute('x-ignore')) {
|
||||
el.setAttribute('x-ignore', true);
|
||||
el.setAttribute('data-alpine-ignored', true);
|
||||
}
|
||||
});
|
||||
|
||||
document.body.querySelectorAll('[x-for],[x-if],[x-teleport]').forEach((el) => {
|
||||
if (el.hasAttribute('x-for') && el._x_lookup) {
|
||||
Object.values(el._x_lookup).forEach((el) => el.setAttribute('data-alpine-generated', true));
|
||||
}
|
||||
|
||||
if (el.hasAttribute('x-if') && el._x_currentIfEl) {
|
||||
el._x_currentIfEl.setAttribute('data-alpine-generated', true);
|
||||
}
|
||||
|
||||
if (el.hasAttribute('x-teleport') && el._x_teleport) {
|
||||
el._x_teleport.setAttribute('data-alpine-generated', true);
|
||||
}
|
||||
});
|
||||
|
||||
document.body.querySelectorAll('[x-data]').forEach((el) => {
|
||||
if (!el.hasAttribute('data-turbo-permanent')) {
|
||||
Alpine.destroyTree(el);
|
||||
// Turbo leaks DOM elements via their data-turbo-permanent handling.
|
||||
// That needs to be fixed upstream, but until then.
|
||||
let clone = el.cloneNode(true);
|
||||
el.replaceWith(clone);
|
||||
}
|
||||
});
|
||||
});
|
||||
}
|
||||
@@ -5,7 +5,7 @@ export const scrollToActive = (when) => {
|
||||
}
|
||||
els.forEach((el) => {
|
||||
// Find scrolling container.
|
||||
let container = el.closest('[data-turbo-preserve-scroll-container]');
|
||||
let container = el.closest('[data-preserve-scroll-container]');
|
||||
if (container) {
|
||||
// Avoid scrolling if el is already in view.
|
||||
if (el.offsetTop >= container.scrollTop && el.offsetTop <= container.scrollTop + container.clientHeight) {
|
||||
|
||||
@@ -1,3 +1,2 @@
|
||||
export * from './bridgeTurboAndAlpine';
|
||||
export * from './helpers';
|
||||
export * from './lrucache';
|
||||
|
||||
+12
-36
@@ -1,10 +1,10 @@
|
||||
import Alpine from 'alpinejs';
|
||||
import { registerMagics } from './alpinejs/magics/index';
|
||||
import { navbar, search, toc } from './alpinejs/data/index';
|
||||
import { navStore, initColorScheme } from './alpinejs/stores/index';
|
||||
import { bridgeTurboAndAlpine } from './helpers/index';
|
||||
import { navStore } from './alpinejs/stores/index';
|
||||
import persist from '@alpinejs/persist';
|
||||
import focus from '@alpinejs/focus';
|
||||
import * as params from '@params';
|
||||
|
||||
var debug = 0 ? console.log.bind(console, '[index]') : function () {};
|
||||
|
||||
@@ -28,6 +28,7 @@ var debug = 0 ? console.log.bind(console, '[index]') : function () {};
|
||||
index: 'hugodocs',
|
||||
app_id: 'D1BPLZHGYQ',
|
||||
api_key: '6df94e1e5d55d258c56f60d974d10314',
|
||||
params: params,
|
||||
};
|
||||
|
||||
Alpine.data('navbar', () => navbar(Alpine));
|
||||
@@ -43,39 +44,14 @@ var debug = 0 ? console.log.bind(console, '[index]') : function () {};
|
||||
// Start AlpineJS.
|
||||
Alpine.start();
|
||||
|
||||
// Start the Turbo-Alpine bridge.
|
||||
bridgeTurboAndAlpine(Alpine);
|
||||
|
||||
{
|
||||
let containerScrollTops = {};
|
||||
|
||||
// To preserve scroll position in scrolling elements on navigation add data-turbo-preserve-scroll-container="somename" to the scrolling container.
|
||||
addEventListener('turbo:click', () => {
|
||||
document.querySelectorAll('[data-turbo-preserve-scroll-container]').forEach((el2) => {
|
||||
containerScrollTops[el2.dataset.turboPreserveScrollContainer] = el2.scrollTop;
|
||||
});
|
||||
// On cross-document navigation the browser snapshots the current page for
|
||||
// the view transition. An open overlay (e.g. the search modal) would
|
||||
// otherwise linger in that outgoing snapshot while the page crossfades.
|
||||
// `pageswap` runs right before the snapshot is taken, so hide such
|
||||
// elements here to make them disappear instantly on navigation.
|
||||
window.addEventListener('pageswap', () => {
|
||||
document.querySelectorAll('[data-hide-on-navigate]').forEach((el) => {
|
||||
el.classList.add('hidden');
|
||||
});
|
||||
|
||||
addEventListener('turbo:render', () => {
|
||||
document.querySelectorAll('[data-turbo-preserve-scroll-container]').forEach((ele) => {
|
||||
const containerScrollTop = containerScrollTops[ele.dataset.turboPreserveScrollContainer];
|
||||
if (containerScrollTop) {
|
||||
ele.scrollTop = containerScrollTop;
|
||||
} else {
|
||||
let els = ele.querySelectorAll('.scroll-active');
|
||||
if (els.length) {
|
||||
els.forEach((el) => {
|
||||
// Avoid scrolling if el is already in view.
|
||||
if (el.offsetTop >= ele.scrollTop && el.offsetTop <= ele.scrollTop + ele.clientHeight) {
|
||||
return;
|
||||
}
|
||||
ele.scrollTop = el.offsetTop - ele.offsetTop;
|
||||
});
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
containerScrollTops = {};
|
||||
});
|
||||
}
|
||||
});
|
||||
})();
|
||||
|
||||
@@ -1 +0,0 @@
|
||||
import * as Turbo from '@hotwired/turbo';
|
||||
@@ -1,6 +1,5 @@
|
||||
{
|
||||
"compilerOptions": {
|
||||
"baseUrl": ".",
|
||||
"paths": {
|
||||
"*": [
|
||||
"*"
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
_comment: Do not remove front matter.
|
||||
---
|
||||
|
||||
locale
|
||||
`locale`
|
||||
: (`string`) The language tag as described in [RFC 5646][]. This is the primary value used by the [`language.Translate`][] function to select a translation table, and for localization of dates, currencies, numbers, and percentages, falling back to the [language key][] in both cases.
|
||||
|
||||
Hugo also uses this value to populate:
|
||||
|
||||
@@ -4,19 +4,19 @@ _comment: Do not remove front matter.
|
||||
|
||||
A _page matcher_ filters pages by logical path, page kind, environment, or site. Specify filtering criteria using any combination of the following keywords.
|
||||
|
||||
environment
|
||||
`environment`
|
||||
: (`string`) A [glob pattern](g) matching the build [environment](g). For example: `{staging,production}`.
|
||||
|
||||
kind
|
||||
`kind`
|
||||
: (`string`) A [glob pattern](g) matching the [page kind](g). For example: `{taxonomy,term}`.
|
||||
|
||||
lang
|
||||
`lang`
|
||||
: {{< deprecated-in 0.153.0 />}}
|
||||
: Use [`sites`](#sites) instead.
|
||||
: Use the [`sites`](#sites) setting instead.
|
||||
|
||||
path
|
||||
`path`
|
||||
: (`string`) A [glob pattern](g) matching the page's [logical path](g). For example: `{/books,/books/**}`.
|
||||
|
||||
sites
|
||||
`sites`
|
||||
: {{< new-in 0.153.0 />}}
|
||||
: (`map`) A [sites matrix](g) matching any combination of [content dimensions](g) including language, version, and role.
|
||||
|
||||
@@ -0,0 +1,7 @@
|
||||
---
|
||||
_comment: Do not remove front matter.
|
||||
---
|
||||
|
||||
When the `images` front matter parameter is set, Hugo processes each value. For internal paths, it searches page resources then global resources, using the resource permalink if found or converting the path to an absolute URL if not. External URLs are used as-is.
|
||||
|
||||
When `images` is not set, Hugo searches page resources for a name matching `*feature*`, falling back to `*cover*` or `*thumbnail*` if none is found. If still no image is found, Hugo uses the first entry in the site configuration's `params.images` array, if present, and processes it as described above.
|
||||
@@ -2,7 +2,7 @@
|
||||
_comment: Do not remove front matter.
|
||||
---
|
||||
|
||||
> [!note]
|
||||
> The [page collections quick reference guide] describes methods and functions to filter, sort, and group page collections.
|
||||
> [!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/
|
||||
|
||||
@@ -10,5 +10,5 @@ By default, Hugo uses the `html/template` package when rendering HTML files.
|
||||
|
||||
To generate HTML output that is safe against code injection, the `html/template` package escapes strings in certain contexts.
|
||||
|
||||
[`text/template`]: https://pkg.go.dev/text/template
|
||||
[`html/template`]: https://pkg.go.dev/html/template
|
||||
[`text/template`]: https://pkg.go.dev/text/template
|
||||
|
||||
@@ -2,9 +2,7 @@
|
||||
_comment: Do not remove front matter.
|
||||
---
|
||||
|
||||
Apply the filter using the [`images.Filter`] function:
|
||||
|
||||
[`images.Filter`]: /functions/images/filter/
|
||||
Apply the filter using the [`images.Filter`][] function:
|
||||
|
||||
```go-html-template
|
||||
{{ with resources.Get "images/original.jpg" }}
|
||||
@@ -14,9 +12,7 @@ Apply the filter using the [`images.Filter`] function:
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
You can also apply the filter using the [`Filter`] method on a `Resource` object:
|
||||
|
||||
[`Filter`]: /methods/resource/filter/
|
||||
You can also apply the filter using the [`Filter`][] method on a `Resource` object:
|
||||
|
||||
```go-html-template
|
||||
{{ with resources.Get "images/original.jpg" }}
|
||||
@@ -25,3 +21,6 @@ You can also apply the filter using the [`Filter`] method on a `Resource` object
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
[`Filter`]: /methods/resource/filter/
|
||||
[`images.Filter`]: /functions/images/filter/
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
_comment: Do not remove front matter.
|
||||
---
|
||||
|
||||
params
|
||||
`params`
|
||||
: (`map` or `slice`) Params that can be imported as JSON in your JS files, e.g.
|
||||
|
||||
```go-html-template
|
||||
@@ -17,17 +17,17 @@ 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
|
||||
`minify`
|
||||
: (`bool`) Whether to minify the generated JS code. Default is `false`.
|
||||
|
||||
loaders
|
||||
`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
|
||||
`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
|
||||
`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
|
||||
@@ -54,39 +54,39 @@ shims
|
||||
import * as ReactDOM from 'react-dom/client';
|
||||
```
|
||||
|
||||
target
|
||||
`target`
|
||||
: (`string`) The language target. One of: `es5`, `es2015`, `es2016`, `es2017`, `es2018`, `es2019`, `es2020`, `es2021`, `es2022`, `es2023`, `es2024`, or `esnext`. Default is `esnext`.
|
||||
|
||||
platform
|
||||
`platform`
|
||||
: {{< new-in 0.140.0 />}}
|
||||
: (`string`) One of `browser`, `node`, `neutral`. Default is `browser`. See <https://esbuild.github.io/api/#platform>.
|
||||
|
||||
externals
|
||||
`externals`
|
||||
: (`slice`) External dependencies. Use this to trim dependencies you know will never be executed. See <https://esbuild.github.io/api/#external>.
|
||||
|
||||
defines
|
||||
`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
|
||||
`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
|
||||
`sourceMap`
|
||||
: (`string`) The type of source map to generate. One of `external`, `inline`, `linked`, or `none`. Default is `none`. 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.
|
||||
|
||||
sourcesContent
|
||||
`sourcesContent`
|
||||
: {{< new-in 0.140.0 />}}
|
||||
: (`bool`) Whether to include the content of the source files in the source map. Default is `true`.
|
||||
|
||||
JSX
|
||||
`JSX`
|
||||
: (`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
|
||||
`JSXImportSource`
|
||||
: (`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.:
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
_comment: Do not remove front matter.
|
||||
---
|
||||
|
||||
> [!note]
|
||||
> [!NOTE]
|
||||
> Localization of dates, currencies, numbers, and percentages is performed by the [`bep/golocales`][] package. Hugo determines the locale using the [`locale`][] configuration setting, falling back to the language key itself. The resolved value must be a locale supported by the package.
|
||||
|
||||
[`bep/golocales`]: https://github.com/bep/golocales
|
||||
|
||||
@@ -14,7 +14,7 @@ The table below shows the values these functions return for various file formats
|
||||
|
||||
|Format|IsImageResource|IsImageResourceProcessable|IsImageResourceWithMeta|
|
||||
|:-----|:--------------|:-------------------------|:----------------------|
|
||||
|AVIF |true |**false** |true |
|
||||
|AVIF |true |true |true |
|
||||
|BMP |true |true |true |
|
||||
|GIF |true |true |true |
|
||||
|HEIC |true |**false** |true |
|
||||
@@ -44,6 +44,6 @@ This contrived example demonstrates how to iterate through resources and use the
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
[`reflect.IsImageResource`]: /functions/reflect/isimageresource/
|
||||
[`reflect.IsImageResourceProcessable`]: /functions/reflect/isimageresourceprocessable/
|
||||
[`reflect.IsImageResourceWithMeta`]: /functions/reflect/isimageresourcewithmeta/
|
||||
[`reflect.IsImageResource`]: /functions/reflect/isimageresource/
|
||||
|
||||
@@ -2,11 +2,11 @@
|
||||
_comment: Do not remove front matter.
|
||||
---
|
||||
|
||||
When specifying the regular expression, use a raw [string literal] (backticks) instead of an interpreted string literal (double quotes) to simplify the syntax. With an interpreted string literal you must escape backslashes.
|
||||
When specifying the regular expression, use a raw [string literal][] (backticks) instead of an interpreted string literal (double quotes) to simplify the syntax. With an interpreted string literal you must escape backslashes.
|
||||
|
||||
Go's regular expression package implements the [RE2 syntax]. The RE2 syntax is a subset of that accepted by [PCRE], roughly speaking, and with various [caveats]. Note that the RE2 `\C` escape sequence is not supported.
|
||||
Go's regular expression package implements the [RE2 syntax][]. The RE2 syntax is a subset of that accepted by [PCRE][], roughly speaking, and with various [caveats][]. Note that the RE2 `\C` escape sequence is not supported.
|
||||
|
||||
[caveats]: https://swtch.com/~rsc/regexp/regexp3.html#caveats
|
||||
[PCRE]: https://www.pcre.org/
|
||||
[RE2 syntax]: https://github.com/google/re2/wiki/Syntax/
|
||||
[caveats]: https://swtch.com/~rsc/regexp/regexp3.html#caveats
|
||||
[string literal]: https://go.dev/ref/spec#String_literals
|
||||
|
||||
@@ -2,10 +2,7 @@
|
||||
_comment: Do not remove front matter.
|
||||
---
|
||||
|
||||
The [`anchorize`] and [`urlize`] functions are similar:
|
||||
|
||||
[`anchorize`]: /functions/urls/anchorize/
|
||||
[`urlize`]: /functions/urls/urlize/
|
||||
The [`anchorize`][] and [`urlize`][] functions are similar:
|
||||
|
||||
- Use the `anchorize` function to generate an HTML `id` attribute value
|
||||
- Use the `urlize` function to sanitize a string for usage in a URL
|
||||
@@ -33,3 +30,6 @@ For example:
|
||||
{{ $s | anchorize }} → hugö
|
||||
{{ $s | urlize }} → hug%C3%B6
|
||||
```
|
||||
|
||||
[`anchorize`]: /functions/urls/anchorize/
|
||||
[`urlize`]: /functions/urls/urlize/
|
||||
|
||||
@@ -0,0 +1,8 @@
|
||||
---
|
||||
_comment: Do not remove front matter.
|
||||
---
|
||||
|
||||
> [!NOTE]
|
||||
> Do not commit the contents of the [`publishDir`][] directory to your repository. Hugo recreates this directory when you build your project.
|
||||
|
||||
[`publishDir`]: /configuration/all/#publishdir
|
||||
@@ -2,13 +2,15 @@
|
||||
_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.
|
||||
> [!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 module resources:
|
||||
>
|
||||
> - [go.dev/wiki/Modules](https://go.dev/wiki/Modules)
|
||||
> - [blog.golang.org/using-go-modules](https://go.dev/blog/using-go-modules)
|
||||
> - [go.dev/wiki/Modules][]
|
||||
> - [blog.golang.org/using-go-modules][]
|
||||
|
||||
[Git]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git
|
||||
[Go]: https://go.dev/doc/install
|
||||
[blog.golang.org/using-go-modules]: https://go.dev/blog/using-go-modules
|
||||
[go.dev/wiki/Modules]: https://go.dev/wiki/Modules
|
||||
|
||||
@@ -14,10 +14,10 @@ LibSass support (3)|:x:|:x:|:heavy_check_mark:|:heavy_check_mark:
|
||||
|
||||
(1) {{< new-in v0.159.2 />}}
|
||||
|
||||
(2) Deploy your site directly to a Google Cloud Storage bucket, an AWS S3 bucket, or an Azure Storage container. See [details].
|
||||
(2) Deploy your site directly to a Google Cloud Storage bucket, an AWS S3 bucket, or an Azure Storage container. See [details][].
|
||||
|
||||
(3) [Transpile Sass to CSS] via embedded LibSass. Note that embedded LibSass was deprecated in v0.153.0 and will be removed in a future release. Use the [Dart Sass] transpiler instead, which is compatible with any edition.
|
||||
(3) [Transpile Sass to CSS][] via embedded LibSass. Note that embedded LibSass was deprecated in v0.153.0 and will be removed in a future release. Use the [Dart Sass][] transpiler instead, which is compatible with any edition.
|
||||
|
||||
[dart sass]: /functions/css/sass/#dart-sass
|
||||
[transpile sass to css]: /functions/css/sass/
|
||||
[Dart Sass]: /functions/css/sass/#dart-sass
|
||||
[Transpile Sass to CSS]: /functions/css/sass/
|
||||
[details]: /host-and-deploy/deploy-with-hugo-deploy/
|
||||
|
||||
@@ -4,20 +4,20 @@ _comment: Do not remove front matter.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Although not required in all cases, [Git], [Go], and [Dart Sass] are commonly used when working with Hugo.
|
||||
Although not required in all cases, [Git][], [Go][], and [Dart Sass][] are commonly used when working with Hugo.
|
||||
|
||||
Git is required to:
|
||||
|
||||
- Build Hugo from source
|
||||
- Use the [Hugo Modules] feature
|
||||
- Use [Hugo modules][]
|
||||
- Install a theme as a Git submodule
|
||||
- Access [commit information] from a local Git repository
|
||||
- Access [commit information][] from a local Git repository
|
||||
- Host your site on [CI/CD](g) platforms such as [Cloudflare][], [GitHub Pages][], [GitLab Pages][], [Netlify][], [Render][], or [Vercel][]
|
||||
|
||||
Go is required to:
|
||||
|
||||
- Build Hugo from source
|
||||
- Use the Hugo Modules feature
|
||||
- Use Hugo modules
|
||||
|
||||
Dart Sass is required to transpile Sass to CSS when using the latest features of the Sass language.
|
||||
|
||||
@@ -28,16 +28,16 @@ Please refer to the relevant documentation for installation instructions:
|
||||
- [Dart Sass][dart sass install]
|
||||
|
||||
[Cloudflare]: /host-and-deploy/host-on-cloudflare/
|
||||
[commit information]: /methods/page/GitInfo
|
||||
[dart sass install]: /functions/css/sass/#dart-sass
|
||||
[dart sass]: https://sass-lang.com/dart-sass
|
||||
[git install]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git
|
||||
[git]: https://git-scm.com/
|
||||
[Dart Sass]: https://sass-lang.com/dart-sass
|
||||
[GitHub Pages]: /host-and-deploy/host-on-github-pages/
|
||||
[GitLab Pages]: /host-and-deploy/host-on-gitlab-pages/
|
||||
[go install]: https://go.dev/doc/install
|
||||
[go]: https://go.dev/
|
||||
[hugo modules]: /hugo-modules/
|
||||
[Git]: https://git-scm.com/
|
||||
[Go]: https://go.dev/
|
||||
[Hugo modules]: /hugo-modules/
|
||||
[Netlify]: /host-and-deploy/host-on-netlify/
|
||||
[Render]: /host-and-deploy/host-on-render/
|
||||
[Vercel]: /host-and-deploy/host-on-vercel/
|
||||
[commit information]: /methods/page/GitInfo/
|
||||
[dart sass install]: /functions/css/sass/#dart-sass
|
||||
[git install]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git
|
||||
[go install]: https://go.dev/doc/install
|
||||
|
||||
@@ -4,7 +4,7 @@ _comment: Do not remove front matter.
|
||||
|
||||
## Prebuilt binaries
|
||||
|
||||
Prebuilt binaries are available for a variety of operating systems and architectures. Visit the [latest release] page, and scroll down to the Assets section.
|
||||
Prebuilt binaries are available for a variety of operating systems and architectures. Visit the [latest release][] page, and scroll down to the Assets section.
|
||||
|
||||
1. Download the archive for the desired edition, operating system, and architecture
|
||||
1. Extract the archive
|
||||
|
||||
@@ -6,8 +6,8 @@ _comment: Do not remove front matter.
|
||||
|
||||
To build Hugo from source you must install:
|
||||
|
||||
1. [Git]
|
||||
1. [Go] version 1.25.0 or later
|
||||
1. [Git][]
|
||||
1. [Go][] version {{% current-go-version %}} or later
|
||||
|
||||
### Standard edition
|
||||
|
||||
@@ -29,7 +29,7 @@ CGO_ENABLED=0 go install -tags withdeploy github.com/gohugoio/hugo@latest
|
||||
|
||||
### Extended edition
|
||||
|
||||
To build and install the extended edition, first install a C compiler such as [GCC] or [Clang] and then run the following command:
|
||||
To build and install the extended edition, first install a C compiler such as [GCC][] or [Clang][] and then run the following command:
|
||||
|
||||
```sh
|
||||
CGO_ENABLED=1 go install -tags extended github.com/gohugoio/hugo@latest
|
||||
@@ -37,7 +37,7 @@ CGO_ENABLED=1 go install -tags extended github.com/gohugoio/hugo@latest
|
||||
|
||||
### Extended/deploy edition
|
||||
|
||||
To build and install the extended/deploy edition, first install a C compiler such as [GCC] or [Clang] and then run the following command:
|
||||
To build and install the extended/deploy edition, first install a C compiler such as [GCC][] or [Clang][] and then run the following command:
|
||||
|
||||
```sh
|
||||
CGO_ENABLED=1 go install -tags extended,withdeploy github.com/gohugoio/hugo@latest
|
||||
|
||||
@@ -4,7 +4,7 @@ _comment: Do not remove front matter.
|
||||
|
||||
### Homebrew
|
||||
|
||||
[Homebrew] is a free and open-source package manager for macOS and Linux. To install the extended/deploy edition of Hugo:
|
||||
[Homebrew][] is a free and open-source package manager for macOS and Linux. To install the extended/deploy edition of Hugo:
|
||||
|
||||
```sh
|
||||
brew install hugo
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
_comment: Do not remove front matter.
|
||||
---
|
||||
|
||||
In this project configuration we enable rendering of [emoji shortcodes], and add emoji shortcodes before (pre) and after (post) each menu entry:
|
||||
In this project configuration we enable rendering of [emoji shortcodes][], and add emoji shortcodes before (pre) and after (post) each menu entry:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
enableEmoji = true
|
||||
|
||||
@@ -6,26 +6,26 @@ _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
|
||||
`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
|
||||
`name`
|
||||
: (`string`) The text to display when rendering the menu entry.
|
||||
|
||||
params
|
||||
`params`
|
||||
: (`map`) User-defined properties for the menu entry.
|
||||
|
||||
parent
|
||||
`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
|
||||
`post`
|
||||
: (`string`) The HTML to append when rendering the menu entry.
|
||||
|
||||
pre
|
||||
`pre`
|
||||
: (`string`) The HTML to prepend when rendering the menu entry.
|
||||
|
||||
title
|
||||
`title`
|
||||
: (`string`) The HTML `title` attribute of the rendered menu entry.
|
||||
|
||||
weight
|
||||
`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.
|
||||
|
||||
@@ -0,0 +1,18 @@
|
||||
---
|
||||
_comment: Do not remove front matter.
|
||||
---
|
||||
|
||||
`Type`
|
||||
: (`string`) Returns the media type.
|
||||
|
||||
`MainType`
|
||||
: (`string`) Returns the main type of the media type.
|
||||
|
||||
`SubType`
|
||||
: (`string`) Returns the subtype of the media type.
|
||||
|
||||
`Suffixes`
|
||||
: (`slice`) Returns a slice of possible file suffixes for the media type.
|
||||
|
||||
`FirstSuffix.Suffix`
|
||||
: (`string`) Returns the first of the possible file suffixes for the media type.
|
||||
@@ -6,21 +6,16 @@ Hugo determines the _next_ and _previous_ page by sorting the site's collection
|
||||
|
||||
Field|Precedence|Sort direction
|
||||
:--|:--|:--
|
||||
[`weight`]|1|descending
|
||||
[`date`]|2|descending
|
||||
[`linkTitle`]|3|descending
|
||||
[`path`]|4|descending
|
||||
|
||||
[`date`]: /methods/page/date/
|
||||
[`weight`]: /methods/page/weight/
|
||||
[`linkTitle`]: /methods/page/linktitle/
|
||||
[`path`]: /methods/page/path/
|
||||
[`weight`][]|1|descending
|
||||
[`date`][]|2|descending
|
||||
[`linkTitle`][]|3|descending
|
||||
[`path`][]|4|descending
|
||||
|
||||
The sorted page collection used to determine the _next_ and _previous_ page is independent of other page collections, which may lead to unexpected behavior.
|
||||
|
||||
For example, with this content structure:
|
||||
|
||||
```text
|
||||
```tree
|
||||
content/
|
||||
├── pages/
|
||||
│ ├── _index.md
|
||||
@@ -53,8 +48,12 @@ When you visit page-2:
|
||||
- The `Prev` method points to page-3
|
||||
- The `Next` method points to page-1
|
||||
|
||||
To reverse the meaning of _next_ and _previous_ you can change the sort direction in your [project configuration], or use the [`Next`] and [`Prev`] methods on a `Pages` object for more flexibility.
|
||||
To reverse the meaning of _next_ and _previous_ you can change the sort direction in your [project configuration][], or use the [`Next`][] and [`Prev`][] methods on a `Pages` object for more flexibility.
|
||||
|
||||
[`Next`]: /methods/pages/next/
|
||||
[`Prev`]: /methods/pages/prev/
|
||||
[`date`]: /methods/page/date/
|
||||
[`linkTitle`]: /methods/page/linktitle/
|
||||
[`path`]: /methods/page/path/
|
||||
[`weight`]: /methods/page/weight/
|
||||
[project configuration]: /configuration/page/
|
||||
[`Next`]: /methods/pages/prev
|
||||
[`Prev`]: /methods/pages/prev
|
||||
|
||||
@@ -6,21 +6,16 @@ Hugo determines the _next_ and _previous_ page by sorting the current section's
|
||||
|
||||
Field|Precedence|Sort direction
|
||||
:--|:--|:--
|
||||
[`weight`]|1|descending
|
||||
[`date`]|2|descending
|
||||
[`linkTitle`]|3|descending
|
||||
[`path`]|4|descending
|
||||
|
||||
[`date`]: /methods/page/date/
|
||||
[`weight`]: /methods/page/weight/
|
||||
[`linkTitle`]: /methods/page/linktitle/
|
||||
[`path`]: /methods/page/path/
|
||||
[`weight`][]|1|descending
|
||||
[`date`][]|2|descending
|
||||
[`linkTitle`][]|3|descending
|
||||
[`path`][]|4|descending
|
||||
|
||||
The sorted page collection used to determine the _next_ and _previous_ page is independent of other page collections, which may lead to unexpected behavior.
|
||||
|
||||
For example, with this content structure:
|
||||
|
||||
```text
|
||||
```tree
|
||||
content/
|
||||
├── pages/
|
||||
│ ├── _index.md
|
||||
@@ -53,11 +48,7 @@ When you visit page-2:
|
||||
- The `PrevInSection` method points to page-3
|
||||
- The `NextInSection` method points to page-1
|
||||
|
||||
To reverse the meaning of _next_ and _previous_ you can change the sort direction in your [project configuration], or use the [`Next`] and [`Prev`] methods on a `Pages` object for more flexibility.
|
||||
|
||||
[project configuration]: /configuration/page/
|
||||
[`Next`]: /methods/pages/prev
|
||||
[`Prev`]: /methods/pages/prev
|
||||
To reverse the meaning of _next_ and _previous_ you can change the sort direction in your [project configuration][], or use the [`Next`][] and [`Prev`][] methods on a `Pages` object for more flexibility.
|
||||
|
||||
## Example
|
||||
|
||||
@@ -75,4 +66,12 @@ Code defensively by checking for page existence:
|
||||
|
||||
## Alternative
|
||||
|
||||
Use the [`Next`] and [`Prev`] methods on a `Pages` object for more flexibility.
|
||||
Use the [`Next`][] and [`Prev`][] methods on a `Pages` object for more flexibility.
|
||||
|
||||
[`Next`]: /methods/pages/next/
|
||||
[`Prev`]: /methods/pages/prev/
|
||||
[`date`]: /methods/page/date/
|
||||
[`linkTitle`]: /methods/page/linktitle/
|
||||
[`path`]: /methods/page/path/
|
||||
[`weight`]: /methods/page/weight/
|
||||
[project configuration]: /configuration/page/
|
||||
|
||||
@@ -6,21 +6,16 @@ Hugo determines the _next_ and _previous_ page by sorting the page collection ac
|
||||
|
||||
Field|Precedence|Sort direction
|
||||
:--|:--|:--
|
||||
[`weight`]|1|descending
|
||||
[`date`]|2|descending
|
||||
[`linkTitle`]|3|descending
|
||||
[`path`]|4|descending
|
||||
|
||||
[`date`]: /methods/page/date/
|
||||
[`weight`]: /methods/page/weight/
|
||||
[`linkTitle`]: /methods/page/linktitle/
|
||||
[`path`]: /methods/page/path/
|
||||
[`weight`][]|1|descending
|
||||
[`date`][]|2|descending
|
||||
[`linkTitle`][]|3|descending
|
||||
[`path`][]|4|descending
|
||||
|
||||
The sorted page collection used to determine the _next_ and _previous_ page is independent of other page collections, which may lead to unexpected behavior.
|
||||
|
||||
For example, with this content structure:
|
||||
|
||||
```text
|
||||
```tree
|
||||
content/
|
||||
├── pages/
|
||||
│ ├── _index.md
|
||||
@@ -55,7 +50,7 @@ When you visit page-2:
|
||||
- The `Prev` method points to page-3
|
||||
- The `Next` method points to page-1
|
||||
|
||||
To reverse the meaning of _next_ and _previous_ you can chain the [`Reverse`] method to the page collection definition:
|
||||
To reverse the meaning of _next_ and _previous_ you can chain the [`Reverse`][] method to the page collection definition:
|
||||
|
||||
```go-html-template {file="layouts/page.html"}
|
||||
{{ $pages := .CurrentSection.Pages.ByWeight.Reverse }}
|
||||
@@ -70,3 +65,7 @@ To reverse the meaning of _next_ and _previous_ you can chain the [`Reverse`] me
|
||||
```
|
||||
|
||||
[`Reverse`]: /methods/pages/reverse/
|
||||
[`date`]: /methods/page/date/
|
||||
[`linkTitle`]: /methods/page/linktitle/
|
||||
[`path`]: /methods/page/path/
|
||||
[`weight`]: /methods/page/weight/
|
||||
|
||||
@@ -2,5 +2,5 @@
|
||||
_comment: Do not remove front matter.
|
||||
---
|
||||
|
||||
> [!note]
|
||||
> [!NOTE]
|
||||
> Use this method with [global resources](g), [page resources](g), or [remote resources](g).
|
||||
|
||||
@@ -7,26 +7,26 @@ _comment: Do not remove front matter.
|
||||
The processing specification is a space-delimited, case-insensitive list containing one or more of the following options in any sequence:
|
||||
|
||||
action
|
||||
: Specify one of `crop`, `fill`, `fit`, or `resize`. This is applicable to the [`Process`][] method and the [`images.Process`][] filter. If you specify an action, you must also provide dimensions.
|
||||
: Specify one of `crop`, `fill`, `fit`, or `resize`. This is applicable to the [`Process`][] method and the [`images.Process`][] filter. If you specify an action, you must also provide [`dimensions`](#dimensions).
|
||||
|
||||
anchor
|
||||
: The focal point used when cropping or filling an image. Valid options include `TopLeft`, `Top`, `TopRight`, `Left`, `Center`, `Right`, `BottomLeft`, `Bottom`, `BottomRight`, or `Smart`. The `Smart` option utilizes the [`muesli/smartcrop`][] package to identify the most interesting area of the image. This defaults to the [`anchor`][] parameter in your project configuration.
|
||||
: The focal point used when cropping or filling an image. Valid options include `TopLeft`, `Top`, `TopRight`, `Left`, `Center`, `Right`, `BottomLeft`, `Bottom`, `BottomRight`, or `Smart`. The `Smart` option utilizes the [`muesli/smartcrop`][] package to identify the most interesting area of the image. This defaults to the `anchor` setting in your [imaging configuration][].
|
||||
|
||||
background color
|
||||
: The background color used when converting transparent images to formats that do not support transparency, such as PNG to JPEG. This color also fills the empty space created when rotating an image by a non-orthogonal angle if the space is not transparent and a background color is not specified in the processing specification. The value must be an RGB [hexadecimal color][]. This defaults to the [`bgColor`][] parameter in your project configuration.
|
||||
: The background color used when converting transparent images to formats that do not support transparency, such as PNG to JPEG. This color also fills the empty space created when rotating an image by a non-orthogonal angle if the space is not transparent and a background color is not specified in the processing specification. The value must be an RGB [hexadecimal color][]. This defaults to the `bgColor` setting in your [imaging configuration][].
|
||||
|
||||
compression
|
||||
: {{< new-in 0.153.5 />}}
|
||||
: The encoding strategy used for the image. Options are `lossy` or `lossless`. Note that `lossless` is only supported by the WebP format. This defaults to the [`compression`][] parameter in your project configuration.
|
||||
: The encoding strategy, applicable to AVIF and WebP images. Options are `lossy` or `lossless`. This defaults to the format-specific `compression` setting in your [imaging configuration][].
|
||||
|
||||
dimensions
|
||||
: The dimensions of the resulting image, in pixels. The format is `WIDTHxHEIGHT` where `WIDTH` and `HEIGHT` are whole numbers. When resizing an image, you may specify only the width (such as `600x`) or only the height (such as `x400`) for proportional scaling. Specifying both width and height when resizing an image may result in non-proportional scaling. When cropping, fitting, or filling, you must provide both width and height such as `600x400`.
|
||||
|
||||
format
|
||||
: The format of the resulting image. Valid options include `bmp`, `gif`, `jpeg`, `png`, `tiff`, or `webp`. This defaults to the format of the source image.
|
||||
: The format of the resulting image. Valid options include `avif`, `bmp`, `gif`, `jpeg`, `png`, `tiff`, or `webp`. This defaults to the format of the source image.
|
||||
|
||||
hint
|
||||
: The encoding preset used when processing WebP images, equivalent to the `-preset` flag for the [`cwebp`][] CLI. Valid options include `drawing`, `icon`, `photo`, `picture`, or `text`. This defaults to the [`hint`][] parameter in your project configuration.
|
||||
: The content hint, applicable to AVIF and WebP images. Valid options include `drawing`, `icon`, `photo`, `picture`, or `text`. This defaults to the format-specific `hint` setting in your [imaging configuration][].
|
||||
|
||||
Value|Example
|
||||
:--|:--
|
||||
@@ -37,10 +37,10 @@ hint
|
||||
`text`|Image that is primarily text
|
||||
|
||||
quality
|
||||
: The visual fidelity of the image, applicable to JPEG and WebP formats when using `lossy` compression. The format is `qQUALITY` where `QUALITY` is a whole number between `1` and `100`, inclusive. Lower numbers prioritize smaller file size, while higher numbers prioritize visual clarity. This defaults to the [`quality`][] parameter in your project configuration.
|
||||
: The visual fidelity, applicable to JPEG images and to AVIF and WebP images when using `lossy` compression. The format is `qQUALITY` where `QUALITY` is a whole number between `1` and `100`, inclusive. Lower numbers prioritize smaller file size, while higher numbers prioritize visual clarity. This defaults to the format-specific `quality` setting in your [imaging configuration][].
|
||||
|
||||
resampling filter
|
||||
: The algorithm used to calculate new pixels when resizing, fitting, or filling an image. Common options include `box`, `lanczos`, `catmullRom`, `mitchellNetravali`, `linear`, or `nearestNeighbor`. This defaults to the [`resampleFilter`][] parameter in your project configuration.
|
||||
: The algorithm used to calculate new pixels when resizing, fitting, or filling an image. Common options include `box`, `lanczos`, `catmullRom`, `mitchellNetravali`, `linear`, or `nearestNeighbor`. This defaults to the `resampleFilter` setting in your [imaging configuration][].
|
||||
|
||||
Filter|Description
|
||||
:--|:--
|
||||
@@ -56,18 +56,12 @@ resampling filter
|
||||
rotation
|
||||
: The number of whole degrees to rotate an image counter-clockwise. The format is `rDEGREES` where `DEGREES` is a whole number. Hugo performs rotation before any other transformations, so your [target dimensions](#dimensions) and any [anchor](#anchor) should refer to the image orientation after rotation. Use `r90`, `r180`, or `r270` for orthogonal rotations, or arbitrary angles such as `r45`. To rotate clockwise, use a negative number such as `r-45`. To automatically rotate an image based on its Exif orientation tag, use the [`images.AutoOrient`][] filter instead of manual rotation.
|
||||
|
||||
Rotating by non-orthogonal values increases the image extents to fit the rotated corners. For formats supporting alpha channels such as PNG or WebP, this resulting empty space is transparent by default. If the target format does not support transparency such as JPEG, or if you explicitly specify a [background color](#background-color) in the processing specification, the space is filled. If a color is required but not specified in the processing string, it defaults to the [`bgColor`][] parameter in your project configuration.
|
||||
Rotating by non-orthogonal values increases the image extents to fit the rotated corners. For formats supporting alpha channels such as AVIF, PNG, or WebP, this resulting empty space is transparent by default. If the target format does not support transparency such as JPEG, or if you explicitly specify a [background color](#background-color) in the processing specification, the space is filled. If a color is required but not specified in the processing string, it defaults to the `bgColor` setting in your [imaging configuration][].
|
||||
|
||||
[`anchor`]: /configuration/imaging/#anchor
|
||||
[`bgcolor`]: /configuration/imaging/#bgcolor
|
||||
[`compression`]: /configuration/imaging/#compression
|
||||
[`cwebp`]: https://developers.google.com/speed/webp/docs/cwebp
|
||||
[`muesli/smartcrop`]: https://github.com/muesli/smartcrop
|
||||
[`hint`]: /configuration/imaging/#hint
|
||||
[`Process`]: /methods/resource/process/
|
||||
[`images.AutoOrient`]: /functions/images/autoorient/
|
||||
[`images.Process`]: /functions/images/process/
|
||||
[`Process`]: /methods/resource/process
|
||||
[`quality`]: /configuration/imaging/#quality
|
||||
[`resampleFilter`]: /configuration/imaging/#resamplefilter
|
||||
[`muesli/smartcrop`]: https://github.com/muesli/smartcrop
|
||||
[hexadecimal color]: https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color
|
||||
[imaging configuration]: /configuration/imaging/
|
||||
[source documentation]: https://github.com/disintegration/imaging#image-resizing
|
||||
|
||||
@@ -16,7 +16,7 @@ author = 'authors'
|
||||
|
||||
And this content structure:
|
||||
|
||||
```text
|
||||
```tree
|
||||
content/
|
||||
├── books/
|
||||
│ ├── and-then-there-were-none.md --> genres: suspense
|
||||
@@ -26,13 +26,13 @@ content/
|
||||
└── _index.md
|
||||
```
|
||||
|
||||
To capture the "genres" `Taxonomy` object from within any template, use the [`Taxonomies`] method on a `Site` object.
|
||||
To capture the "genres" `Taxonomy` object from within any template, use the [`Taxonomies`][] method on a `Site` object.
|
||||
|
||||
```go-html-template
|
||||
{{ $taxonomyObject := .Site.Taxonomies.genres }}
|
||||
```
|
||||
|
||||
To capture the "genres" `Taxonomy` object when rendering its page with a _taxonomy_ template, use the [`Terms`] method on the page's [`Data`] object:
|
||||
To capture the "genres" `Taxonomy` object when rendering its page with a _taxonomy_ template, use the [`Terms`][] method on the page's [`Data`][] object:
|
||||
|
||||
```go-html-template {file="layouts/taxonomy.html"}
|
||||
{{ $taxonomyObject := .Data.Terms }}
|
||||
@@ -44,7 +44,7 @@ To inspect the data structure:
|
||||
<pre>{{ debug.Dump $taxonomyObject }}</pre>
|
||||
```
|
||||
|
||||
Although the [`Alphabetical`] and [`ByCount`] methods provide a better data structure for ranging through the taxonomy, you can render the weighted pages by term directly from the `Taxonomy` object:
|
||||
Although the [`Alphabetical`][] and [`ByCount`][] methods provide a better data structure for ranging through the taxonomy, you can render the weighted pages by term directly from the `Taxonomy` object:
|
||||
|
||||
```go-html-template
|
||||
{{ range $term, $weightedPages := $taxonomyObject }}
|
||||
@@ -61,7 +61,6 @@ In the example above, the first anchor element is a link to the term page.
|
||||
|
||||
[`Alphabetical`]: /methods/taxonomy/alphabetical/
|
||||
[`ByCount`]: /methods/taxonomy/bycount/
|
||||
|
||||
[`data`]: /methods/page/data/
|
||||
[`terms`]: /methods/page/data/#in-a-taxonomy-template
|
||||
[`taxonomies`]: /methods/site/taxonomies/
|
||||
[`Data`]: /methods/page/data/
|
||||
[`Taxonomies`]: /methods/site/taxonomies/
|
||||
[`Terms`]: /methods/page/data/#in-a-taxonomy-template
|
||||
|
||||
@@ -6,19 +6,19 @@ An ordered taxonomy is a slice, where each element is an object that contains th
|
||||
|
||||
Each element of the slice provides these methods:
|
||||
|
||||
Count
|
||||
`Count`
|
||||
: (`int`) Returns the number of pages to which the term is assigned.
|
||||
|
||||
Page
|
||||
`Page`
|
||||
: (`page.Page`) Returns the term's `Page` object, useful for linking to the term page.
|
||||
|
||||
Pages
|
||||
: (`page.Pages`) Returns a `Pages` object containing the `Page` objects to which the term is assigned, sorted by [taxonomic weight](g). To sort or group, use any of the [methods] available to the `Pages` object. For example, sort by the last modification date.
|
||||
`Pages`
|
||||
: (`page.Pages`) Returns a `Pages` object containing the `Page` objects to which the term is assigned, sorted by [taxonomic weight](g). To sort or group, use any of the [methods][] available to the `Pages` object. For example, sort by the last modification date.
|
||||
|
||||
Term
|
||||
`Term`
|
||||
: (`string`) Returns the term name.
|
||||
|
||||
WeightedPages
|
||||
`WeightedPages`
|
||||
: (`page.WeightedPages`) Returns a slice of weighted pages to which the term is assigned, sorted by taxonomic weight. The `Pages` method above is more flexible, allowing you to sort and group.
|
||||
|
||||
[methods]: /methods/pages/
|
||||
|
||||
@@ -45,27 +45,26 @@ _comment: Do not remove front matter.
|
||||
|
||||
`:filename`
|
||||
: {{< deprecated-in v0.144.0 />}}
|
||||
: Use `:contentbasename` instead.
|
||||
: Use the [`:contentbasename`](#contentbasename) token instead.
|
||||
|
||||
`:slugorfilename`
|
||||
: {{< deprecated-in v0.144.0 />}}
|
||||
: Use `:slugorcontentbasename` instead.
|
||||
: Use the [`:slugorcontentbasename`](#slugorcontentbasename) token instead.
|
||||
|
||||
`:contentbasename`
|
||||
: {{< new-in 0.144.0 />}}
|
||||
: The [content base name].
|
||||
|
||||
[content base name]: /methods/page/file/#contentbasename
|
||||
: The [content base name][].
|
||||
|
||||
`:slugorcontentbasename`
|
||||
: {{< new-in 0.144.0 />}}
|
||||
: The `slug` as defined in front matter, else the [content base name].
|
||||
: 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
|
||||
For time-related values, you can also use the layout string components defined in Go's [time package][]. For example:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
permalinks:
|
||||
posts: /:06/:1/:2/:title/
|
||||
{{< /code-toggle >}}
|
||||
|
||||
[content base name]: /methods/page/file/#contentbasename
|
||||
[time package]: https://pkg.go.dev/time#pkg-constants
|
||||
|
||||
@@ -2,11 +2,11 @@
|
||||
_comment: Do not remove front matter.
|
||||
---
|
||||
|
||||
path
|
||||
`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
|
||||
`lang`
|
||||
: (`string`) The language of the target page. Default is the current language. Optional.
|
||||
|
||||
outputFormat
|
||||
`outputFormat`
|
||||
: (`string`) The output format of the target page. Default is the current output format. Optional.
|
||||
|
||||
@@ -20,7 +20,7 @@ The primary use case for `PageInner` is to resolve links and [page resources](g)
|
||||
|
||||
Then call the shortcode in your Markdown:
|
||||
|
||||
```text {file="content/posts/post-1.md"}
|
||||
```md {file="content/posts/post-1.md"}
|
||||
{{%/* include "/posts/post-2" */%}}
|
||||
```
|
||||
|
||||
@@ -31,15 +31,15 @@ Any render hook triggered while rendering `/posts/post-2` 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 [Markdown notation].
|
||||
> [!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]
|
||||
- [Embedded image render hook]
|
||||
- [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 %}}>
|
||||
[Embedded link render hook]: <{{% eturl render-link %}}>
|
||||
[Markdown notation]: /content-management/shortcodes/#notation
|
||||
[`RenderShortcodes`]: /methods/page/rendershortcodes/
|
||||
|
||||
@@ -4,18 +4,18 @@ _comment: Do not remove front matter.
|
||||
|
||||
## Scope
|
||||
|
||||
The method or function used to create a scratch pad determines its scope. For example, use the `Store` method on a `Page` object to create a scratch pad scoped to the page.
|
||||
The method or function used to create the data structure determines its scope. For example, use the `Store` method on a `Page` object to create a data structure scoped to the page.
|
||||
|
||||
Scope|Method or function
|
||||
:--|:--
|
||||
page|[`PAGE.Store`]
|
||||
site|[`SITE.Store`]
|
||||
global|[`hugo.Store`]
|
||||
local|[`collections.NewScratch`]
|
||||
shortcode|[`SHORTCODE.Store`]
|
||||
page|[`PAGE.Store`][]
|
||||
site|[`SITE.Store`][]
|
||||
global|[`hugo.Store`][]
|
||||
local|[`collections.NewScratch`][]
|
||||
shortcode|[`SHORTCODE.Store`][]
|
||||
|
||||
[`page.store`]: /methods/page/store
|
||||
[`site.store`]: /methods/site/store
|
||||
[`hugo.store`]: /functions/hugo/store
|
||||
[`collections.newscratch`]: functions/collections/newscratch
|
||||
[`shortcode.store`]: /methods/shortcode/store
|
||||
[`PAGE.Store`]: /methods/page/store/
|
||||
[`SHORTCODE.Store`]: /methods/shortcode/store/
|
||||
[`SITE.Store`]: /methods/site/store/
|
||||
[`collections.NewScratch`]: /functions/collections/newscratch/
|
||||
[`hugo.Store`]: /functions/hugo/store/
|
||||
|
||||
@@ -4,83 +4,78 @@
|
||||
|
||||
## Methods
|
||||
|
||||
### Set
|
||||
Use these methods on the data structure.
|
||||
|
||||
Sets the value of the given key.
|
||||
`Set`
|
||||
: Sets the value of the given key.
|
||||
|
||||
```go-html-template
|
||||
{{ .Store.Set "greeting" "Hello" }}
|
||||
```
|
||||
|
||||
### Get
|
||||
|
||||
Gets the value of the given key.
|
||||
|
||||
```go-html-template
|
||||
{{ .Store.Set "greeting" "Hello" }}
|
||||
{{ .Store.Get "greeting" }} → Hello
|
||||
```
|
||||
|
||||
### Add
|
||||
|
||||
Adds the given value to the existing value(s) of the given key.
|
||||
|
||||
For single values, `Add` accepts values that support Go's `+` operator. If the first `Add` for a key is an array or slice, the following adds will be appended to that list.
|
||||
|
||||
```go-html-template
|
||||
{{ .Store.Set "greeting" "Hello" }}
|
||||
{{ .Store.Add "greeting" "Welcome" }}
|
||||
{{ .Store.Get "greeting" }} → HelloWelcome
|
||||
```
|
||||
|
||||
```go-html-template
|
||||
{{ .Store.Set "total" 3 }}
|
||||
{{ .Store.Add "total" 7 }}
|
||||
{{ .Store.Get "total" }} → 10
|
||||
```
|
||||
|
||||
```go-html-template
|
||||
{{ .Store.Set "greetings" (slice "Hello") }}
|
||||
{{ .Store.Add "greetings" (slice "Welcome" "Cheers") }}
|
||||
{{ .Store.Get "greetings" }} → [Hello Welcome Cheers]
|
||||
```
|
||||
|
||||
### SetInMap
|
||||
|
||||
Takes a `key`, `mapKey` and `value` and adds a map of `mapKey` and `value` to the given `key`.
|
||||
|
||||
```go-html-template
|
||||
{{ .Store.SetInMap "greetings" "english" "Hello" }}
|
||||
{{ .Store.SetInMap "greetings" "french" "Bonjour" }}
|
||||
{{ .Store.Get "greetings" }} → map[english:Hello french:Bonjour]
|
||||
```go-html-template
|
||||
{{ .Store.Set "greeting" "Hello" }}
|
||||
```
|
||||
|
||||
### DeleteInMap
|
||||
`Get`
|
||||
: (`any`) Gets the value of the given key.
|
||||
|
||||
Takes a `key` and `mapKey` and removes the map of `mapKey` from the given `key`.
|
||||
```go-html-template
|
||||
{{ .Store.Set "greeting" "Hello" }}
|
||||
{{ .Store.Get "greeting" }} → Hello
|
||||
```
|
||||
|
||||
```go-html-template
|
||||
{{ .Store.SetInMap "greetings" "english" "Hello" }}
|
||||
{{ .Store.SetInMap "greetings" "french" "Bonjour" }}
|
||||
{{ .Store.DeleteInMap "greetings" "english" }}
|
||||
{{ .Store.Get "greetings" }} → map[french:Bonjour]
|
||||
```
|
||||
`Add`
|
||||
: Adds the given value to the existing value(s) of the given key.
|
||||
|
||||
### GetSortedMapValues
|
||||
For single values, `Add` accepts values that support Go's `+` operator. If the first `Add` for a key is an array or slice, the following adds will be appended to that list.
|
||||
|
||||
Returns an array of values from `key` sorted by `mapKey`.
|
||||
```go-html-template
|
||||
{{ .Store.Set "greeting" "Hello" }}
|
||||
{{ .Store.Add "greeting" "Welcome" }}
|
||||
{{ .Store.Get "greeting" }} → HelloWelcome
|
||||
```
|
||||
|
||||
```go-html-template
|
||||
{{ .Store.SetInMap "greetings" "english" "Hello" }}
|
||||
{{ .Store.SetInMap "greetings" "french" "Bonjour" }}
|
||||
{{ .Store.GetSortedMapValues "greetings" }} → [Hello Bonjour]
|
||||
```
|
||||
```go-html-template
|
||||
{{ .Store.Set "total" 3 }}
|
||||
{{ .Store.Add "total" 7 }}
|
||||
{{ .Store.Get "total" }} → 10
|
||||
```
|
||||
|
||||
### Delete
|
||||
```go-html-template
|
||||
{{ .Store.Set "greetings" (slice "Hello") }}
|
||||
{{ .Store.Add "greetings" (slice "Welcome" "Cheers") }}
|
||||
{{ .Store.Get "greetings" }} → [Hello Welcome Cheers]
|
||||
```
|
||||
|
||||
Removes the given key.
|
||||
`SetInMap`
|
||||
: Takes a `key`, `mapKey` and `value` and adds a map of `mapKey` and `value` to the given `key`.
|
||||
|
||||
```go-html-template
|
||||
{{ .Store.Set "greeting" "Hello" }}
|
||||
{{ .Store.Delete "greeting" }}
|
||||
```
|
||||
```go-html-template
|
||||
{{ .Store.SetInMap "greetings" "english" "Hello" }}
|
||||
{{ .Store.SetInMap "greetings" "french" "Bonjour" }}
|
||||
{{ .Store.Get "greetings" }} → map[english:Hello french:Bonjour]
|
||||
```
|
||||
|
||||
`DeleteInMap`
|
||||
: Takes a `key` and `mapKey` and removes the map of `mapKey` from the given `key`.
|
||||
|
||||
```go-html-template
|
||||
{{ .Store.SetInMap "greetings" "english" "Hello" }}
|
||||
{{ .Store.SetInMap "greetings" "french" "Bonjour" }}
|
||||
{{ .Store.DeleteInMap "greetings" "english" }}
|
||||
{{ .Store.Get "greetings" }} → map[french:Bonjour]
|
||||
```
|
||||
|
||||
`GetSortedMapValues`
|
||||
: (`[]any`) Returns an array of values from `key` sorted by `mapKey`.
|
||||
|
||||
```go-html-template
|
||||
{{ .Store.SetInMap "greetings" "english" "Hello" }}
|
||||
{{ .Store.SetInMap "greetings" "french" "Bonjour" }}
|
||||
{{ .Store.GetSortedMapValues "greetings" }} → [Hello Bonjour]
|
||||
```
|
||||
|
||||
`Delete`
|
||||
: Removes the given key.
|
||||
|
||||
```go-html-template
|
||||
{{ .Store.Set "greeting" "Hello" }}
|
||||
{{ .Store.Delete "greeting" }}
|
||||
```
|
||||
|
||||
@@ -0,0 +1,21 @@
|
||||
---
|
||||
_comment: Do not remove front matter.
|
||||
---
|
||||
|
||||
## Scope
|
||||
|
||||
The method or function used to create the data structure determines its scope. For example, use the `Store` method on a `Page` object to create a data structure scoped to the page.
|
||||
|
||||
Scope|Method or function
|
||||
:--|:--
|
||||
page|[`PAGE.Store`][]
|
||||
site|[`SITE.Store`][]
|
||||
global|[`hugo.Store`][]
|
||||
local|[`collections.NewScratch`][]
|
||||
shortcode|[`SHORTCODE.Store`][]
|
||||
|
||||
[`PAGE.Store`]: /methods/page/store/
|
||||
[`SHORTCODE.Store`]: /methods/shortcode/store/
|
||||
[`SITE.Store`]: /methods/site/store/
|
||||
[`collections.NewScratch`]: /functions/collections/newscratch/
|
||||
[`hugo.Store`]: /functions/hugo/store/
|
||||
@@ -2,31 +2,31 @@
|
||||
_comment: Do not remove front matter.
|
||||
---
|
||||
|
||||
anchorLineNos
|
||||
`anchorLineNos`
|
||||
: (`bool`) Whether to render each line number as an HTML anchor element, setting the `id` attribute of the surrounding `span` element to the line number. Irrelevant if `lineNos` is `false`. Default is `false`.
|
||||
|
||||
codeFences
|
||||
`codeFences`
|
||||
: (`bool`) Whether to highlight fenced code blocks. Default is `true`.
|
||||
|
||||
guessSyntax
|
||||
`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]
|
||||
> [!NOTE]
|
||||
> The syntax highlighter includes lexers for approximately 300 languages, but only 5 of these have implemented automatic language detection.
|
||||
|
||||
hl_Lines
|
||||
`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.
|
||||
|
||||
hl_inline
|
||||
`hl_inline`
|
||||
: (`bool`) Whether to render the highlighted code without a wrapping container. Default is `false`.
|
||||
|
||||
lineAnchors
|
||||
`lineAnchors`
|
||||
: (`string`) When rendering a line number as an HTML anchor element, prepend this value to the `id` attribute of the surrounding `span` element. This provides unique `id` attributes when a page contains two or more code blocks. Irrelevant if `lineNos` or `anchorLineNos` is `false`.
|
||||
|
||||
lineNoStart
|
||||
`lineNoStart`
|
||||
: (`int`) The number to display at the beginning of the first line. Irrelevant if `lineNos` is `false`. Default is `1`.
|
||||
|
||||
lineNos
|
||||
`lineNos`
|
||||
: (`any`) Controls line number display. Default is `false`.
|
||||
|
||||
- `true`: Enable line numbers, controlled by `lineNumbersInTable`.
|
||||
@@ -34,23 +34,23 @@ lineNos
|
||||
- `inline`: Enable inline line numbers (sets `lineNumbersInTable` to `false`).
|
||||
- `table`: Enable table-based line numbers (sets `lineNumbersInTable` to `true`).
|
||||
|
||||
lineNumbersInTable
|
||||
`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
|
||||
`noClasses`
|
||||
: (`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
|
||||
```sh
|
||||
hugo gen chromastyles --style=monokai > syntax.css
|
||||
```
|
||||
|
||||
style
|
||||
`style`
|
||||
: (`string`) The CSS styles to apply to the highlighted code. This value is case-insensitive. Default is `monokai`. See [syntax highlighting styles][].
|
||||
|
||||
tabWidth
|
||||
`tabWidth`
|
||||
: (`int`) Substitute this number of spaces for each tab character in your highlighted code. Irrelevant if `noClasses` is `false`. Default is `4`.
|
||||
|
||||
wrapperClass
|
||||
`wrapperClass`
|
||||
: {{< new-in 0.140.2 />}}
|
||||
: (`string`) The class or classes to use for the outermost element of the highlighted code. Default is `highlight`.
|
||||
|
||||
|
||||
@@ -2,9 +2,7 @@
|
||||
_comment: Do not remove front matter.
|
||||
---
|
||||
|
||||
Format a `time.Time` value based on [Go's reference time]:
|
||||
|
||||
[Go's reference time]: https://pkg.go.dev/time#pkg-constants
|
||||
Format a `time.Time` value based on [Go's reference time][]:
|
||||
|
||||
```text
|
||||
Mon Jan 2 15:04:05 MST 2006
|
||||
@@ -44,3 +42,5 @@ Strings such as `PST` and `CET` are not time zones. They are time zone _abbrevia
|
||||
Strings such as `-07:00` and `+01:00` are not time zones. They are time zone _offsets_.
|
||||
|
||||
A time zone is a geographic area with the same local time. For example, the time zone abbreviated by `PST` and `PDT` (depending on Daylight Savings Time) is `America/Los_Angeles`.
|
||||
|
||||
[Go's reference time]: https://pkg.go.dev/time#pkg-constants
|
||||
|
||||
@@ -8,137 +8,133 @@ weight: 20
|
||||
|
||||
## Framework
|
||||
|
||||
[Multiplatform]
|
||||
[Multiplatform][]
|
||||
: Install Hugo's single executable on Linux, macOS, Windows, and more.
|
||||
|
||||
[Multilingual]
|
||||
[Multilingual][]
|
||||
: Localize your project for each language and region, including translations, images, dates, currencies, numbers, percentages, and collation sequence. Hugo's multilingual framework supports single-host and multihost configurations.
|
||||
|
||||
[Output formats]
|
||||
[Output formats][]
|
||||
: Render each page of your project to one or more output formats, with granular control by page kind, section, and path. While HTML is the default output format, you can add JSON, RSS, CSV, and more. For example, create a REST API to access content.
|
||||
|
||||
[Templates]
|
||||
[Templates][]
|
||||
: Create templates using variables, functions, and methods to transform your content, resources, and data into a published page. While HTML templates are the most common, you can create templates for any output format.
|
||||
|
||||
[Themes]
|
||||
[Themes][]
|
||||
: Reduce development time and cost by using one of the hundreds of themes contributed by the Hugo community. Themes are available for corporate sites, documentation projects, image portfolios, landing pages, personal and professional blogs, resumes, CVs, and more.
|
||||
|
||||
[Modules]
|
||||
[Modules][]
|
||||
: Reduce development time and cost by creating or importing packaged combinations of archetypes, assets, content, data, templates, translation tables, static files, or configuration settings. A module may serve as the basis for a new project, or to augment an existing project.
|
||||
|
||||
[Privacy]
|
||||
[Privacy][]
|
||||
: Configure your project to help comply with regional privacy regulations.
|
||||
|
||||
[Security]
|
||||
[Security][]
|
||||
: Hugo's security model is based on the premise that template and configuration authors are trusted, but content authors are not. This model enables generation of HTML output safe against code injection. Other protections prevent "shelling out" to arbitrary applications, limit access to specific environment variables, prevent connections to arbitrary remote data sources, and more.
|
||||
|
||||
## Content authoring
|
||||
|
||||
[Content formats]
|
||||
: Create your content using Markdown, HTML, AsciiDoc, Emacs Org Mode, Pandoc, or reStructuredText. Markdown is the default content format, conforming to the [CommonMark] and [GitHub Flavored Markdown] specifications.
|
||||
[Content formats][]
|
||||
: Create your content using Markdown, HTML, AsciiDoc, Emacs Org Mode, Pandoc, or reStructuredText. Markdown is the default content format, conforming to the [CommonMark][] and [GitHub Flavored Markdown][] specifications.
|
||||
|
||||
[Markdown attributes]
|
||||
[Markdown attributes][]
|
||||
: Apply HTML attributes such as `class` and `id` to Markdown images and block elements including blockquotes, fenced code blocks, headings, horizontal rules, lists, paragraphs, and tables.
|
||||
|
||||
[Markdown extensions]
|
||||
[Markdown extensions][]
|
||||
: Leverage the embedded Markdown extensions to create tables, definition lists, footnotes, task lists, inserted text, mark text, subscripts, superscripts, and more.
|
||||
|
||||
[Markdown render hooks]
|
||||
[Markdown render hooks][]
|
||||
: Override the conversion of Markdown to HTML when rendering blockquotes, fenced code blocks, headings, images, links, and tables. For example, render every standalone image as an HTML `figure` element.
|
||||
|
||||
[Diagrams]
|
||||
[Diagrams][]
|
||||
: Use fenced code blocks and Markdown render hooks to include diagrams in your content.
|
||||
|
||||
[Mathematics]
|
||||
[Mathematics][]
|
||||
: Include mathematical equations and expressions in Markdown using LaTeX markup.
|
||||
|
||||
[Syntax highlighting]
|
||||
[Syntax highlighting][]
|
||||
: 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]
|
||||
[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.
|
||||
|
||||
## Content management
|
||||
|
||||
[Multidimensional content model]
|
||||
[Multidimensional content model][]
|
||||
: Generate pages across any combination of language, version, and role from a single source. This allows a single piece of content to be published to multiple [sites](g) within your project, removing the need to duplicate files for different audiences or versions.
|
||||
|
||||
[Content adapters]
|
||||
[Content adapters][]
|
||||
: Create content adapters to dynamically add content when building your project. For example, use a content adapter to create pages from a remote data source such as JSON, TOML, YAML, or XML.
|
||||
|
||||
[Taxonomies]
|
||||
[Taxonomies][]
|
||||
: Classify content to establish simple or complex logical relationships between pages. For example, create an authors taxonomy, and assign one or more authors to each page. Among other uses, the taxonomy system provides an inverted, weighted index to render a list of related pages, ordered by relevance.
|
||||
|
||||
[Data]
|
||||
[Data][]
|
||||
: Augment your content using local or remote data sources including CSV, JSON, TOML, YAML, and XML. For example, create a shortcode to render an HTML table from a remote CSV file.
|
||||
|
||||
[Menus]
|
||||
[Menus][]
|
||||
: Provide rapid access to content via Hugo's menu system, configured automatically, globally, or on a page-by-page basis. The menu system is a key component of Hugo's multilingual architecture.
|
||||
|
||||
[URL management]
|
||||
[URL management][]
|
||||
: Serve any page from any path via global configuration or on a page-by-page basis.
|
||||
|
||||
## Asset pipelines
|
||||
|
||||
[CSS Processing]
|
||||
[CSS Processing][]
|
||||
: Bundle, transform, minify, create source maps, perform SRI hashing, and integrate with PostCSS.
|
||||
|
||||
[Image processing]
|
||||
[Image processing][]
|
||||
: Convert, resize, crop, rotate, adjust colors, apply filters, overlay text and images, and extract metadata.
|
||||
|
||||
[JavaScript bundling]
|
||||
[JavaScript bundling][]
|
||||
: Transpile TypeScript and JSX to JavaScript, bundle, tree shake, minify, create source maps, and perform SRI hashing.
|
||||
|
||||
[Sass processing]
|
||||
[Sass processing][]
|
||||
: Transpile Sass to CSS, bundle, tree shake, minify, create source maps, perform SRI hashing, and integrate with PostCSS.
|
||||
|
||||
[Tailwind CSS processing]
|
||||
[Tailwind CSS processing][]
|
||||
: Compile Tailwind CSS utility classes into standard CSS, bundle, tree shake, optimize, minify, perform SRI hashing, and integrate with PostCSS.
|
||||
|
||||
## Performance
|
||||
|
||||
[Caching]
|
||||
[Caching][]
|
||||
: Reduce build time and cost by rendering a _partial_ template once then cache the result, either globally or within a given context. For example, cache the result of an asset pipeline to prevent reprocessing on every rendered page.
|
||||
|
||||
[Segmentation]
|
||||
[Segmentation][]
|
||||
: Reduce build time and cost by partitioning your sites into segments. For example, render the home page and the "news section" every hour, and render the entire project once a week.
|
||||
|
||||
[Minification]
|
||||
[Minification][]
|
||||
: Minify HTML, CSS, and JavaScript to reduce file size, bandwidth consumption, and loading times.
|
||||
|
||||
[Multilingual]: /content-management/multilingual/
|
||||
[Multiplatform]: /installation/
|
||||
[Output formats]: /configuration/output-formats/
|
||||
[Templates]: /templates/introduction/
|
||||
[Themes]: https://themes.gohugo.io/
|
||||
[Modules]: /hugo-modules/
|
||||
[Privacy]: /configuration/privacy/
|
||||
[Security]: /about/security/
|
||||
|
||||
[Content formats]: /content-management/formats/
|
||||
[CSS Processing]: /functions/css/build/
|
||||
[Caching]: /functions/partials/includecached/
|
||||
[CommonMark]: https://spec.commonmark.org/current/
|
||||
[Content adapters]: /content-management/content-adapters/
|
||||
[Content formats]: /content-management/formats/
|
||||
[Data]: /content-management/data-sources/
|
||||
[Diagrams]: /content-management/diagrams/
|
||||
[GitHub Flavored Markdown]: https://github.github.com/gfm/
|
||||
[Image processing]: /content-management/image-processing/
|
||||
[JavaScript bundling]: /functions/js/build/
|
||||
[Markdown attributes]: /content-management/markdown-attributes/
|
||||
[Markdown extensions]: /configuration/markup/#extensions
|
||||
[Markdown render hooks]: /render-hooks/introduction/
|
||||
[Diagrams]: /content-management/diagrams/
|
||||
[Mathematics]: /content-management/mathematics/
|
||||
[Syntax highlighting]: /content-management/syntax-highlighting/
|
||||
[Shortcodes]: /content-management/shortcodes/
|
||||
|
||||
[Multidimensional content model]: /quick-reference/glossary/#sites-matrix
|
||||
[Content adapters]: /content-management/content-adapters/
|
||||
[Taxonomies]: /content-management/taxonomies/
|
||||
[Data]: /content-management/data-sources/
|
||||
[Menus]: /content-management/menus/
|
||||
[URL management]: /content-management/urls/
|
||||
|
||||
[CSS processing]: /functions/css/build/
|
||||
[Image processing]: /content-management/image-processing/
|
||||
[JavaScript bundling]: /functions/js/build/
|
||||
[Sass processing]: /functions/css/sass/
|
||||
[Tailwind CSS processing]: /functions/css/tailwindcss/
|
||||
|
||||
[Caching]: /functions/partials/includecached/
|
||||
[Segmentation]: /configuration/segments/
|
||||
[Minification]: /configuration/minify/
|
||||
[Modules]: /hugo-modules/
|
||||
[Multidimensional content model]: /quick-reference/glossary/#sites-matrix
|
||||
[Multilingual]: /content-management/multilingual/
|
||||
[Multiplatform]: /installation/
|
||||
[Output formats]: /configuration/output-formats/
|
||||
[Privacy]: /configuration/privacy/
|
||||
[Sass processing]: /functions/css/sass/
|
||||
[Security]: /about/security/
|
||||
[Segmentation]: /configuration/segments/
|
||||
[Shortcodes]: /content-management/shortcodes/
|
||||
[Syntax highlighting]: /content-management/syntax-highlighting/
|
||||
[Tailwind CSS processing]: /functions/css/tailwindcss/
|
||||
[Taxonomies]: /content-management/taxonomies/
|
||||
[Templates]: /templates/introduction/
|
||||
[Themes]: https://themes.gohugo.io/
|
||||
[URL management]: /content-management/urls/
|
||||
|
||||
@@ -7,7 +7,7 @@ weight: 10
|
||||
aliases: [/about/what-is-hugo/,/about/benefits/]
|
||||
---
|
||||
|
||||
Hugo is a [static site generator] written in [Go], optimized for speed and designed for flexibility. With its advanced templating system and fast asset pipelines, Hugo renders a complete site in seconds, often less.
|
||||
Hugo is a [static site generator][] written in [Go][], optimized for speed and designed for flexibility. With its advanced templating system and fast asset pipelines, Hugo renders a complete site in seconds, often less.
|
||||
|
||||
Due to its flexible framework, multilingual support, and powerful taxonomy system, Hugo is widely used to create:
|
||||
|
||||
@@ -20,15 +20,15 @@ Due to its flexible framework, multilingual support, and powerful taxonomy syste
|
||||
|
||||
Use Hugo's embedded web server during development to instantly see changes to content, structure, behavior, and presentation. Then deploy the site to your host, or push changes to your Git provider for automated builds and deployment.
|
||||
|
||||
And with [Hugo Modules], you can share content, assets, data, translations, themes, templates, and configuration with other projects via public or private Git repositories.
|
||||
And with [modules][] you can share content, assets, data, translations, themes, templates, and configuration with other projects via public or private Git repositories.
|
||||
|
||||
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]: /configuration/privacy
|
||||
Learn more about Hugo's [features][], [privacy protections][], and [security model][].
|
||||
|
||||
{{< youtube 0RKpf3rK57I >}}
|
||||
|
||||
[Go]: https://go.dev
|
||||
[features]: /about/features/
|
||||
[modules]: /hugo-modules/
|
||||
[privacy protections]: /configuration/privacy/
|
||||
[security model]: /about/security/
|
||||
[static site generator]: https://en.wikipedia.org/wiki/Static_site_generator
|
||||
|
||||
@@ -31,32 +31,33 @@ This combination of sandboxing and strict defaults effectively minimizes potenti
|
||||
|
||||
## Dependency security
|
||||
|
||||
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 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][], 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][].
|
||||
[Hugo modules][], which extend the functionality of Go modules, 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][].
|
||||
|
||||
## Web application security
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
To prevent unintended escaping of data that developers know is safe, Hugo provides [`safe`][] functions, such as [`safe.HTML`][]. 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.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
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 settings][], 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.
|
||||
|
||||
## Configuration
|
||||
|
||||
See [configure security](/configuration/security/).
|
||||
See [configure security][].
|
||||
|
||||
[`safe`]: /functions/safe
|
||||
[`safeHTML`]: /functions/safe/html/
|
||||
[content adapters]: /content-management/content-adapters/
|
||||
[configuration options]: /configuration/security
|
||||
[configured to sanitize]: /configuration/markup/#rendererunsafe
|
||||
[Go Modules]: https://go.dev/wiki/Modules#modules
|
||||
[Hugo Modules]: /hugo-modules/
|
||||
[inline shortcodes]: /content-management/shortcodes/#inline
|
||||
[Go modules]: https://go.dev/wiki/Modules#modules
|
||||
[Hugo modules]: /hugo-modules/
|
||||
[OWASP]: https://en.wikipedia.org/wiki/OWASP
|
||||
[`safe.HTML`]: /functions/safe/html/
|
||||
[`safe`]: /functions/safe/
|
||||
[configuration settings]: /configuration/security/
|
||||
[configure security]: /configuration/security/
|
||||
[configured to sanitize]: /configuration/markup/#rendererunsafe
|
||||
[content adapters]: /content-management/content-adapters/
|
||||
[inline shortcodes]: /content-management/shortcodes/#inline
|
||||
[security policy]: /configuration/security/
|
||||
[tamper with your project's dependencies]: https://julienrenaux.fr/2019/12/20/github-actions-security-risk/
|
||||
|
||||
@@ -9,320 +9,317 @@ aliases: [/getting-started/configuration/]
|
||||
|
||||
## Settings
|
||||
|
||||
archetypeDir
|
||||
`archetypeDir`
|
||||
: (`string`) The designated directory for [archetypes](g). Default is `archetypes`. {{% module-mounts-note %}}
|
||||
|
||||
assetDir
|
||||
`assetDir`
|
||||
: (`string`) The designated directory for [global resources](g). Default is `assets`. {{% module-mounts-note %}}
|
||||
|
||||
baseURL
|
||||
`baseURL`
|
||||
: (`string`) The absolute URL of your published site including the protocol, host, path, and a trailing slash.
|
||||
|
||||
build
|
||||
`build`
|
||||
: See [configure build][].
|
||||
|
||||
buildDrafts
|
||||
`buildDrafts`
|
||||
: (`bool`) Whether to include draft content when building a site. Default is `false`.
|
||||
|
||||
buildExpired
|
||||
`buildExpired`
|
||||
: (`bool`) Whether to include expired content when building a site. Default is `false`.
|
||||
|
||||
buildFuture
|
||||
`buildFuture`
|
||||
: (`bool`) Whether to include future content when building a site. Default is `false`.
|
||||
|
||||
cacheDir
|
||||
: (`string`) The designated cache directory. See [details](#cache-directory).
|
||||
`cacheDir`
|
||||
: (`string`) The designated cache directory. See [details](#cache-directory).
|
||||
|
||||
caches
|
||||
`caches`
|
||||
: See [configure file caches][].
|
||||
|
||||
canonifyURLs
|
||||
: (`bool`) See [details](/content-management/urls/#canonical-urls) before enabling this feature. Default is `false`.
|
||||
`canonifyURLs`
|
||||
: (`bool`) See [details][canonical-urls] before enabling this feature. Default is `false`.
|
||||
|
||||
capitalizeListTitles
|
||||
: (`bool`) Whether to capitalize automatic list titles. Applicable to section, taxonomy, and term pages. Use the [`titleCaseStyle`][] setting to configure capitalization rules. Default is `true`.
|
||||
`capitalizeListTitles`
|
||||
: (`bool`) Whether to capitalize automatic list titles. Applicable to section, taxonomy, and term pages. Use the [`titleCaseStyle`](#titlecasestyle) setting to configure capitalization rules. Default is `true`.
|
||||
|
||||
cascade
|
||||
`cascade`
|
||||
: See [configure cascade][].
|
||||
|
||||
cleanDestinationDir
|
||||
: (`bool`) Whether to remove files from the [`publishDir`][] that do not exist in the [`staticDir`][] when building the site. This setting will not take effect if the `staticDir` does not exist. Note that `.gitignore` and `.gitattributes` files, along with directories named `.git`, are always preserved in the `publishDir`. Default is `false`.
|
||||
`cleanDestinationDir`
|
||||
: (`bool`) Whether to remove files from the [`publishDir`](#publishdir) that do not exist in the [`staticDir`](#staticdir) when building the site. This setting will not take effect if the `staticDir` does not exist. Note that `.gitignore` and `.gitattributes` files, along with directories named `.git`, are always preserved in the `publishDir`. Default is `false`.
|
||||
|
||||
contentDir
|
||||
`contentDir`
|
||||
: (`string`) The designated directory for content files. Default is `content`. {{% module-mounts-note %}}
|
||||
|
||||
copyright
|
||||
`copyright`
|
||||
: (`string`) The copyright notice for a site, typically displayed in the footer.
|
||||
|
||||
dataDir
|
||||
`dataDir`
|
||||
: (`string`) The designated directory for data files. Default is `data`. {{% module-mounts-note %}}
|
||||
|
||||
defaultContentLanguage
|
||||
`defaultContentLanguage`
|
||||
: (`string`) The projects's [default language](g), conforming to the syntax described in [RFC 5646][].
|
||||
|
||||
defaultContentLanguageInSubdir
|
||||
: (`bool`) Whether to publish the default content language to a subdirectory matching the [`defaultContentLanguage`][]. Default is `false`.
|
||||
`defaultContentLanguageInSubdir`
|
||||
: (`bool`) Whether to publish the default content language to a subdirectory matching the [`defaultContentLanguage`](#defaultcontentlanguage). Default is `false`.
|
||||
|
||||
defaultContentRole
|
||||
`defaultContentRole`
|
||||
: {{< new-in 0.153.0 />}}
|
||||
: (`string`) The project's [default role](g).
|
||||
|
||||
defaultContentRoleInSubdir
|
||||
`defaultContentRoleInSubdir`
|
||||
: {{< new-in 0.153.0 />}}
|
||||
: (`bool`) Whether to publish the default content [role](g) to a subdirectory matching the [`defaultContentRole`][]. Default is `false`.
|
||||
: (`bool`) Whether to publish the default content [role](g) to a subdirectory matching the [`defaultContentRole`](#defaultcontentrole). Default is `false`.
|
||||
|
||||
defaultContentVersion
|
||||
`defaultContentVersion`
|
||||
: {{< new-in 0.153.0 />}}
|
||||
: (`string`) The project's [default version](g).
|
||||
|
||||
defaultContentVersionInSubdir
|
||||
`defaultContentVersionInSubdir`
|
||||
: {{< new-in 0.153.0 />}}
|
||||
: (`bool`) Whether to publish the default content version to a subdirectory matching the [`defaultContentVersion`][]. Default is `false`.
|
||||
: (`bool`) Whether to publish the default content version to a subdirectory matching the [`defaultContentVersion`](#defaultcontentversion). Default is `false`.
|
||||
|
||||
defaultOutputFormat
|
||||
`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
|
||||
`deployment`
|
||||
: See [configure deployment][].
|
||||
|
||||
disableAliases
|
||||
`disableAliases`
|
||||
: (`bool`) Whether to disable the generation of HTML redirect files for each path defined in the [`aliases`][aliases_front_matter] front matter field. When `true`, Hugo will not create physical files for [client-side redirection][], but the alias data remains available via the [`Aliases`][aliases_page_method] method on a `Page` object. Default is `false`.
|
||||
|
||||
disableDefaultLanguageRedirect
|
||||
`disableDefaultLanguageRedirect`
|
||||
: {{< new-in 0.140.0 />}}
|
||||
: (`bool`) Whether to disable generation of the alias redirect for the default content language. When [`defaultContentLanguageInSubdir`][] is `true`, this setting prevents the root directory from redirecting to the language subdirectory. Conversely, when `defaultContentLanguageInSubdir` is `false`, this setting prevents the language subdirectory from redirecting to the root directory. This is superseded by the more general [`disableDefaultSiteRedirect`][] setting. Default is `false`.
|
||||
: (`bool`) Whether to disable generation of the alias redirect for the default content language. When [`defaultContentLanguageInSubdir`](#defaultcontentlanguageinsubdir) is `true`, this setting prevents the root directory from redirecting to the language subdirectory. Conversely, when `defaultContentLanguageInSubdir` is `false`, this setting prevents the language subdirectory from redirecting to the root directory. This is superseded by the more general [`disableDefaultSiteRedirect`](#disabledefaultsiteredirect) setting. Default is `false`.
|
||||
|
||||
disableDefaultSiteRedirect
|
||||
`disableDefaultSiteRedirect`
|
||||
: {{< new-in 0.154.5 />}}
|
||||
: (`bool`) Whether to disable generation of the alias redirect to the [default site](g). When [`defaultContentLanguageInSubdir`][], [`defaultContentRoleInSubdir`][], or [`defaultContentVersionInSubdir`][] is `true`, this prevents the root directory from redirecting to the default site's subdirectory. Conversely, when these are `false`, it prevents the subdirectories from redirecting back to the root. Default is `false`.
|
||||
: (`bool`) Whether to disable generation of the alias redirect to the [default site](g). When [`defaultContentLanguageInSubdir`](#defaultcontentlanguageinsubdir), [`defaultContentRoleInSubdir`](#defaultcontentroleinsubdir), or [`defaultContentVersionInSubdir`](#defaultcontentversioninsubdir) is `true`, this prevents the root directory from redirecting to the default site's subdirectory. Conversely, when these are `false`, it prevents the subdirectories from redirecting back to the root. Default is `false`.
|
||||
|
||||
disableHugoGeneratorInject
|
||||
`disableHugoGeneratorInject`
|
||||
: (`bool`) Whether to disable injection of a `<meta name="generator">` tag into the home page. Default is `false`.
|
||||
|
||||
disableKinds
|
||||
`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
|
||||
`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
|
||||
`disableLiveReload`
|
||||
: (`bool`) Whether to disable automatic live reloading of the browser window. Default is `false`.
|
||||
|
||||
disablePathToLower
|
||||
`disablePathToLower`
|
||||
: (`bool`) Whether to disable transformation of page URLs to lower case. Default is `false`.
|
||||
|
||||
enableEmoji
|
||||
`enableEmoji`
|
||||
: (`bool`) Whether to allow emoji in Markdown. Default is `false`.
|
||||
|
||||
enableGitInfo
|
||||
`enableGitInfo`
|
||||
: (`bool`) Whether to retrieve commit metadata from the Git history of your local project and any [modules](g). This enables the [`GitInfo`][] method on a `Page` object. With the default front matter configuration, the [`Lastmod`][] method on a `Page` object returns the Git author date of the last commit for that file. Default is `false`.
|
||||
|
||||
enableMissingTranslationPlaceholders
|
||||
`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
|
||||
`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 build` and `development` when running `hugo server`.
|
||||
|
||||
frontmatter
|
||||
`frontmatter`
|
||||
: See [configure front matter][].
|
||||
|
||||
hasCJKLanguage
|
||||
`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
|
||||
`HTTPCache`
|
||||
: See [configure HTTP cache][].
|
||||
|
||||
i18nDir
|
||||
`i18nDir`
|
||||
: (`string`) The designated directory for translation tables. Default is `i18n`. {{% module-mounts-note %}}
|
||||
|
||||
ignoreCache
|
||||
`ignoreCache`
|
||||
: (`bool`) Whether to ignore the configured file caches. Default is `false`.
|
||||
|
||||
ignoreFiles
|
||||
`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
|
||||
`ignoreLogs`
|
||||
: (`[]string`) A slice of message identifiers corresponding to warnings and errors you wish to suppress. See [`erroridf`][] and [`warnidf`][].
|
||||
|
||||
ignoreVendorPaths
|
||||
`ignoreVendorPaths`
|
||||
: (`string`) A [glob pattern](g) matching the module paths to exclude from the `_vendor` directory.
|
||||
|
||||
imaging
|
||||
`imaging`
|
||||
: See [configure imaging][].
|
||||
|
||||
languageCode
|
||||
`languageCode`
|
||||
: {{<deprecated-in 0.158.0 />}}
|
||||
: Use [`locale`](#locale) instead.
|
||||
|
||||
languages
|
||||
`languages`
|
||||
: See [configure languages][].
|
||||
|
||||
layoutDir
|
||||
`layoutDir`
|
||||
: (`string`) The designated directory for templates. Default is `layouts`. {{% module-mounts-note %}}
|
||||
|
||||
{{% include "/_common/configuration/locale.md" %}}
|
||||
|
||||
For a multilingual project, specify this value independently for each language key. See [configure languages][].
|
||||
|
||||
mainSections
|
||||
`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
|
||||
`markup`
|
||||
: See [configure markup][].
|
||||
|
||||
mediaTypes
|
||||
`mediaTypes`
|
||||
: See [configure media types][].
|
||||
|
||||
menus
|
||||
`menus`
|
||||
: See [configure menus][].
|
||||
|
||||
minify
|
||||
`minify`
|
||||
: See [configure minify][].
|
||||
|
||||
module
|
||||
`module`
|
||||
: See [configure modules][].
|
||||
|
||||
newContentEditor
|
||||
`newContentEditor`
|
||||
: (`string`) The editor to use when creating new content.
|
||||
|
||||
noBuildLock
|
||||
`noBuildLock`
|
||||
: (`bool`) Whether to disable creation of the `.hugo_build.lock` file. Default is `false`.
|
||||
|
||||
noChmod
|
||||
`noChmod`
|
||||
: (`bool`) Whether to disable synchronization of file permission modes. Default is `false`.
|
||||
|
||||
noTimes
|
||||
`noTimes`
|
||||
: (`bool`) Whether to disable synchronization of file modification times. Default is `false`.
|
||||
|
||||
outputFormats
|
||||
`outputFormats`
|
||||
: See [configure output formats][].
|
||||
|
||||
outputs
|
||||
`outputs`
|
||||
: See [configure outputs][].
|
||||
|
||||
page
|
||||
`page`
|
||||
: See [configure page][].
|
||||
|
||||
pagination
|
||||
`pagination`
|
||||
: See [configure pagination][].
|
||||
|
||||
panicOnWarning
|
||||
`panicOnWarning`
|
||||
: (`bool`) Whether to panic on the first WARNING. Default is `false`.
|
||||
|
||||
params
|
||||
`params`
|
||||
: See [configure params][].
|
||||
|
||||
permalinks
|
||||
`permalinks`
|
||||
: See [configure permalinks][].
|
||||
|
||||
pluralizeListTitles
|
||||
`pluralizeListTitles`
|
||||
: (`bool`) Whether to pluralize automatic list titles. Applicable to section pages. Default is `true`.
|
||||
|
||||
printI18nWarnings
|
||||
`printI18nWarnings`
|
||||
: (`bool`) Whether to log WARNINGs for each missing translation. Default is `false`.
|
||||
|
||||
printPathWarnings
|
||||
`printPathWarnings`
|
||||
: (`bool`) Whether to log WARNINGs when Hugo publishes two or more files to the same path. Default is `false`.
|
||||
|
||||
printUnusedTemplates
|
||||
`printUnusedTemplates`
|
||||
: (`bool`) Whether to log WARNINGs for each unused template. Default is `false`.
|
||||
|
||||
privacy
|
||||
`privacy`
|
||||
: See [configure privacy][].
|
||||
|
||||
publishDir
|
||||
`publishDir`
|
||||
: (`string`) The designated directory for publishing the site. Default is `public`.
|
||||
|
||||
refLinksErrorLevel
|
||||
`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
|
||||
`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
|
||||
`related`
|
||||
: See [configure related content][].
|
||||
|
||||
relativeURLs
|
||||
: (`bool`) See [details](/content-management/urls/#relative-urls) before enabling this feature. Default is `false`.
|
||||
`relativeURLs`
|
||||
: (`bool`) See [details][relative-urls] before enabling this feature. Default is `false`.
|
||||
|
||||
removePathAccents
|
||||
`removePathAccents`
|
||||
: (`bool`) Whether to remove [non-spacing marks][] from [composite characters][] in content paths. Default is `false`.
|
||||
|
||||
renderSegments
|
||||
`renderSegments`
|
||||
: (`[]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 build --renderSegments segment1,segment2`. The provided segment names must correspond to those defined in the [`segments`][] configuration.
|
||||
|
||||
resourceDir
|
||||
`resourceDir`
|
||||
: (`string`) The designated directory for caching output from [asset pipelines](g). Default is `resources`.
|
||||
|
||||
roles
|
||||
`roles`
|
||||
: See [configure roles][].
|
||||
|
||||
security
|
||||
`security`
|
||||
: See [configure 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).
|
||||
`sectionPagesMenu`
|
||||
: (`string`) When set, each top-level section will be added to the menu identified by the provided value. See [details][define-automatically].
|
||||
|
||||
segments
|
||||
`segments`
|
||||
: See [configure segments][].
|
||||
|
||||
server
|
||||
`server`
|
||||
: See [configure server][].
|
||||
|
||||
services
|
||||
`services`
|
||||
: See [configure services][].
|
||||
|
||||
sitemap
|
||||
`sitemap`
|
||||
: See [configure sitemap][].
|
||||
|
||||
staticDir
|
||||
`staticDir`
|
||||
: (`string`) The designated directory for static files. Default is `static`. {{% module-mounts-note %}}
|
||||
|
||||
summaryLength
|
||||
`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. Default is `70`.
|
||||
|
||||
taxonomies
|
||||
`taxonomies`
|
||||
: See [configure taxonomies][].
|
||||
|
||||
templateMetrics
|
||||
: (`bool`) Whether to print template execution metrics to the console. Default is `false`. See [details](/troubleshooting/performance/#template-metrics).
|
||||
`templateMetrics`
|
||||
: (`bool`) Whether to print template execution metrics to the console. Default is `false`. See [details][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).
|
||||
`templateMetricsHints`
|
||||
: (`bool`) Whether to print template execution improvement hints to the console. Applicable when `templateMetrics` is `true`. Default is `false`. See [details][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/).
|
||||
`theme`
|
||||
: (`string` or `[]string`) The [theme](g) to use. Multiple themes can be listed, with precedence given from left to right. See [details][].
|
||||
|
||||
themesDir
|
||||
`themesDir`
|
||||
: (`string`) The designated directory for themes. Default is `themes`.
|
||||
|
||||
timeout
|
||||
`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 `60s`.
|
||||
|
||||
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.
|
||||
`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`][] 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
|
||||
`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).
|
||||
`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
|
||||
`uglyurls`
|
||||
: See [configure ugly URLs][].
|
||||
|
||||
versions
|
||||
`versions`
|
||||
: See [configure versions][].
|
||||
|
||||
## 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:
|
||||
Hugo's file cache directory is configurable via the [`cacheDir`](#cachedir) setting 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) platforms, please read their documentation. For a 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` 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`:
|
||||
@@ -333,21 +330,21 @@ 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.
|
||||
Hugo's [`titleCaseStyle`](#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
|
||||
`ap`
|
||||
: Use the capitalization rules published in the [Associated Press Stylebook][]. This is the default.
|
||||
|
||||
chicago
|
||||
`chicago`
|
||||
: Use the capitalization rules published in the [Chicago Manual of Style][].
|
||||
|
||||
go
|
||||
`go`
|
||||
: Capitalize the first letter of every word.
|
||||
|
||||
firstupper
|
||||
`firstupper`
|
||||
: Capitalize the first letter of the first word.
|
||||
|
||||
none
|
||||
`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
|
||||
@@ -365,27 +362,18 @@ Some configuration settings, such as menus and custom parameters, can be defined
|
||||
[`MainSections`]: /methods/site/mainsections/
|
||||
[`Summary`]: /methods/page/summary/
|
||||
[`WordCount`]: /methods/page/wordcount/
|
||||
[`cacheDir`]: #cachedir
|
||||
[`defaultContentLanguageInSubdir`]: #defaultcontentlanguageinsubdir
|
||||
[`defaultContentLanguage`]: #defaultcontentlanguage
|
||||
[`defaultContentRoleInSubdir`]: #defaultcontentroleinsubdir
|
||||
[`defaultContentRole`]: #defaultcontentrole
|
||||
[`defaultContentVersionInSubdir`]: #defaultcontentversioninsubdir
|
||||
[`defaultContentVersion`]: #defaultcontentversion
|
||||
[`disableDefaultSiteRedirect`]: #disabledefaultsiteredirect
|
||||
[`disabled`]: /configuration/languages/#disabled
|
||||
[`erroridf`]: /functions/fmt/erroridf/
|
||||
[`publishDir`]: #publishdir
|
||||
[`os.UserCacheDir`]: https://pkg.go.dev/os#UserCacheDir
|
||||
[`segments`]: /configuration/segments/
|
||||
[`staticDir`]: #staticdir
|
||||
[`strings.Title`]: /functions/strings/title/
|
||||
[`time.AsTime`]: /functions/time/astime/
|
||||
[`time.Format`]: /functions/time/format/
|
||||
[`titleCaseStyle`]: #titlecasestyle
|
||||
[`warnidf`]: /functions/fmt/warnidf/
|
||||
[aliases_front_matter]: /content-management/front-matter/#aliases
|
||||
[aliases_page_method]: /methods/page/aliases/
|
||||
[automatic summaries]: /content-management/summaries/#automatic-summary
|
||||
[canonical-urls]: /content-management/urls/#canonical-urls
|
||||
[client-side redirection]: /content-management/urls/#client-side-redirection
|
||||
[composite characters]: https://en.wikipedia.org/wiki/Precomposed_character
|
||||
[configure HTTP cache]: /configuration/http-cache/
|
||||
@@ -408,7 +396,7 @@ Some configuration settings, such as menus and custom parameters, can be defined
|
||||
[configure params]: /configuration/params/
|
||||
[configure permalinks]: /configuration/permalinks/
|
||||
[configure privacy]: /configuration/privacy/
|
||||
[configure related content]: /configuration/related-content
|
||||
[configure related content]: /configuration/related-content/
|
||||
[configure roles]: /configuration/roles/
|
||||
[configure security]: /configuration/security/
|
||||
[configure segments]: /configuration/segments/
|
||||
@@ -418,8 +406,11 @@ Some configuration settings, such as menus and custom parameters, can be defined
|
||||
[configure taxonomies]: /configuration/taxonomies/
|
||||
[configure ugly URLs]: /configuration/ugly-urls/
|
||||
[configure versions]: /configuration/versions/
|
||||
[define-automatically]: /content-management/menus/#define-automatically
|
||||
[details]: /hugo-modules/theme-components/
|
||||
[duration]: https://pkg.go.dev/time#Duration
|
||||
[module mounts]: /configuration/module/#mounts
|
||||
[non-spacing marks]: https://www.compart.com/en/unicode/category/Mn
|
||||
[os.UserCacheDir]: https://pkg.go.dev/os#UserCacheDir
|
||||
[relative-urls]: /content-management/urls/#relative-urls
|
||||
[template-metrics]: /troubleshooting/performance/#template-metrics
|
||||
[this configuration]: https://github.com/bep/hugo-sass-test/blob/6c3960a8f4b90e8938228688bc49bdcdd6b2d99e/.circleci/config.yml
|
||||
|
||||
@@ -7,25 +7,25 @@ keywords: []
|
||||
aliases: [/getting-started/configuration-build/]
|
||||
---
|
||||
|
||||
The `build` configuration section contains global build-related configuration options.
|
||||
This is the default configuration:
|
||||
|
||||
{{< code-toggle config=build />}}
|
||||
|
||||
buildStats
|
||||
`buildStats`
|
||||
: See the [build stats](#build-stats) section below.
|
||||
|
||||
cachebusters
|
||||
`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.
|
||||
`noJSConfigInAssets`
|
||||
: (`bool`) Whether to disable writing a `jsconfig.json` in your `assets` directory with mapping of imports from running [js.Build][]. This file is intended to help with intellisense/navigation inside code editors such as [VS Code][]. Note that if you do not use `js.Build`, no file will be written.
|
||||
|
||||
useResourceCacheWhen
|
||||
`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:
|
||||
The `build.cachebusters` setting was added to support development using Tailwind 3.x's JIT compiler where a `build` configuration may look like this:
|
||||
|
||||
<!-- markdownlint-disable MD049 -->
|
||||
{{< code-toggle file=hugo >}}
|
||||
@@ -47,37 +47,39 @@ The `build.cachebusters` configuration option was added to support development u
|
||||
{{< /code-toggle >}}
|
||||
<!-- markdownlint-enable MD049 -->
|
||||
|
||||
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.
|
||||
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][] for a running example.
|
||||
|
||||
source
|
||||
`source`
|
||||
: (`string`) A [regular expression](g) matching file(s) relative to one of the virtual component directories in Hugo, typically `assets/...`.
|
||||
|
||||
target
|
||||
`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`.
|
||||
`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
|
||||
`disableIDs`
|
||||
: (`bool`) Whether to exclude `id` attributes. Default is `false`.
|
||||
|
||||
disableTags
|
||||
`disableTags`
|
||||
: (`bool`) Whether to exclude element tags. Default is `false`.
|
||||
|
||||
disableClasses
|
||||
`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`].
|
||||
> [!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 `hugo build`.
|
||||
|
||||
[Hugo Starter Tailwind Basic]: https://github.com/bep/hugo-starter-tailwind-basic
|
||||
[VS Code]: https://code.visualstudio.com/
|
||||
[`config/production`]: /configuration/introduction/#configuration-directory
|
||||
[js.Build]: /functions/js/build/
|
||||
[removing unused CSS]: /functions/resources/postprocess/
|
||||
|
||||
@@ -14,48 +14,50 @@ This is the default configuration:
|
||||
|
||||
Hugo uses file caches to store data on disk, avoiding repeated operations within the same build and persisting data from one build to the next.
|
||||
|
||||
assets
|
||||
`assets`
|
||||
: Caches processed CSS and Sass resources.
|
||||
|
||||
getresource
|
||||
`getresource`
|
||||
: Caches files fetched from remote URLs via the [`resources.GetRemote`][] function.
|
||||
|
||||
images
|
||||
`images`
|
||||
: Caches processed images.
|
||||
|
||||
misc
|
||||
`misc`
|
||||
: Caches miscellaneous data.
|
||||
|
||||
modulegitinfo
|
||||
`modulegitinfo`
|
||||
: Caches Git information for modules.
|
||||
|
||||
modulequeries
|
||||
`modulequeries`
|
||||
: Caches the results of module resolution queries.
|
||||
|
||||
modules
|
||||
`modules`
|
||||
: Caches downloaded modules.
|
||||
|
||||
## Keys
|
||||
|
||||
dir
|
||||
`dir`
|
||||
: (`string`) The absolute file system path where Hugo stores the cached files. You can begin the path with the `:cacheDir` or `:resourceDir` [tokens](#tokens) to anchor the cache to specific system or project locations.
|
||||
|
||||
maxAge
|
||||
`maxAge`
|
||||
: (`string`) The duration a cached entry remains valid before being evicted, expressed as a [duration](g). A value of `0` disables the cache for that key, and a value of `-1` means the cache entry never expires. Default is `-1`.
|
||||
|
||||
## Tokens
|
||||
|
||||
`:cacheDir`
|
||||
: (`string`) The designated cache directory. See [details](/configuration/all/#cachedir).
|
||||
: (`string`) The designated cache directory. See [details][cachedir].
|
||||
|
||||
`:project`
|
||||
: (`string`) The base directory name of the current Hugo project. This ensures isolated file caches for each project, preventing the `hugo build --gc` command from affecting other projects on the same machine.
|
||||
|
||||
`:resourceDir`
|
||||
: (`string`) The designated directory for caching output from [asset pipelines](g). See [details](/configuration/all/#resourcedir).
|
||||
: (`string`) The designated directory for caching output from [asset pipelines](g). See [details][resourcedir].
|
||||
|
||||
## Garbage collection
|
||||
|
||||
As you modify your site or change your configuration, cached files from previous builds may remain on disk, consuming unnecessary space. Use the `hugo build --gc` command to remove these expired or unused entries from the file cache.
|
||||
|
||||
[`resources.GetRemote`]: /functions/resources/getremote/
|
||||
[cachedir]: /configuration/all/#cachedir
|
||||
[resourcedir]: /configuration/all/#resourcedir
|
||||
|
||||
@@ -6,10 +6,10 @@ 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.
|
||||
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 [branch](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][].
|
||||
> [!NOTE]
|
||||
> You can also configure cascading behavior within a page's front matter. See [details][].
|
||||
|
||||
For example, to cascade the `color` page parameter to all pages:
|
||||
|
||||
@@ -21,7 +21,8 @@ color = 'red'
|
||||
## Target
|
||||
|
||||
<!-- TODO
|
||||
We deprecated the `_target` front matter key in favor of `target` in v0.156.0 on 2026-02-17. Remove footnote #1 on or after 2027-05-17 (15 months after deprecation).
|
||||
We deprecated the `_target` front matter key in favor of `target` in v0.156.0 on 2026-02-17. Remove footnote #1 somewhere after v0.171.0, 15 minor releases
|
||||
after deprecation.
|
||||
-->
|
||||
|
||||
The `target` key accepts a [page matcher](g) to limit cascaded values to a subset of pages.[^1] If a target is omitted, values cascade to all pages.
|
||||
|
||||
@@ -16,7 +16,7 @@ These can be used as either page content or [page resources](g). When used as pa
|
||||
|
||||
Consider this example of a [page bundle](g):
|
||||
|
||||
```text
|
||||
```tree
|
||||
content/
|
||||
└── example/
|
||||
├── index.md <-- content
|
||||
@@ -34,7 +34,7 @@ The `index.md` file is the page's content, while the other files are page resour
|
||||
|
||||
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
|
||||
```tree
|
||||
public/
|
||||
├── example/
|
||||
│ ├── g.jpg
|
||||
|
||||
@@ -6,68 +6,68 @@ categories: []
|
||||
keywords: []
|
||||
---
|
||||
|
||||
> [!note]
|
||||
> This configuration is only relevant when running `hugo deploy`. See [details](/host-and-deploy/deploy-with-hugo-deploy/).
|
||||
> [!NOTE]
|
||||
> This configuration is only relevant when running `hugo deploy`. See [details][hugo deploy].
|
||||
|
||||
## Top-level options
|
||||
## Top-level settings
|
||||
|
||||
These settings control the overall behavior of the deployment process. This is the default configuration:
|
||||
|
||||
{{< code-toggle file=hugo config=deployment />}}
|
||||
|
||||
confirm
|
||||
`confirm`
|
||||
: (`bool`) Whether to prompt for confirmation before deploying. Default is `false`.
|
||||
|
||||
dryRun
|
||||
`dryRun`
|
||||
: (`bool`) Whether to simulate the deployment without any remote changes. Default is `false`.
|
||||
|
||||
force
|
||||
`force`
|
||||
: (`bool`) Whether to re-upload all files. Default is `false`.
|
||||
|
||||
invalidateCDN
|
||||
`invalidateCDN`
|
||||
: (`bool`) Whether to invalidate the CDN cache listed in the deployment target. Default is `true`.
|
||||
|
||||
maxDeletes
|
||||
`maxDeletes`
|
||||
: (`int`) The maximum number of files to delete, or `-1` to disable. Default is `256`.
|
||||
|
||||
matchers
|
||||
`matchers`
|
||||
: (`[]*Matcher`) A slice of [matchers](#matchers-1).
|
||||
|
||||
order
|
||||
`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
|
||||
`target`
|
||||
: (`string`) The target deployment [`name`](#name). Defaults to the first target.
|
||||
|
||||
targets
|
||||
`targets`
|
||||
: (`[]*Target`) A slice of [targets](#targets-1).
|
||||
|
||||
workers
|
||||
`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
|
||||
`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
|
||||
`exclude`
|
||||
: (`string`) A [glob pattern](g) 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
|
||||
`googleCloudCDNOrigin`
|
||||
: (`string`) The Google Cloud project and CDN origin to invalidate when deploying this target, specified as `<project>/<origin>`.
|
||||
|
||||
include
|
||||
`include`
|
||||
: (`string`) A [glob pattern](g) 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
|
||||
`name`
|
||||
: (`string`) An arbitrary name for this target.
|
||||
|
||||
stripIndexHTML
|
||||
`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
|
||||
`url`
|
||||
: (`string`) The [destination URL](#destination-urls) for deployment.
|
||||
|
||||
## Matchers
|
||||
@@ -75,28 +75,24 @@ url
|
||||
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].
|
||||
`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].
|
||||
`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].
|
||||
`contentType`
|
||||
: (`string`) The media type of the blob being written. See [details][contentType].
|
||||
|
||||
force
|
||||
`force`
|
||||
: (`bool`) Whether matching files should be re-uploaded. Useful when other route-determined metadata (e.g., `contentType`) has changed. Default is `false`.
|
||||
|
||||
gzip
|
||||
`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
|
||||
`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
|
||||
@@ -113,13 +109,9 @@ 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
|
||||
- [Ceph][]
|
||||
- [MinIO][]
|
||||
- [SeaweedFS][]
|
||||
|
||||
For example, the `url` for a MinIO deployment target might resemble this:
|
||||
|
||||
@@ -157,3 +149,11 @@ s3://my-bucket?endpoint=https://my.minio.instance&awssdk=v2&use_path_style=true&
|
||||
exclude = '**.{heic,psd}'
|
||||
name = 'staging'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
[Ceph]: https://ceph.com/
|
||||
[MinIO]: https://www.minio.io/
|
||||
[SeaweedFS]: https://github.com/chrislusf/seaweedfs
|
||||
[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
|
||||
[hugo deploy]: /host-and-deploy/deploy-with-hugo-deploy/
|
||||
|
||||
@@ -17,11 +17,6 @@ Method|Description
|
||||
[`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 />}}
|
||||
@@ -76,7 +71,9 @@ Hugo provides the following [tokens](g) to help you configure your front matter:
|
||||
|
||||
Within the `YYYY-MM-DD-HH-MM-SS` format, the date and time values may be separated by any character including a space (e.g., `2025-02-01T14-30-00`).
|
||||
|
||||
Hugo resolves the extracted date to the [`timeZone`][] defined in your project configuration, falling back to the system time zone. After extracting the date, Hugo uses the remaining part of the file name to generate the page's [`slug`][], but only if you haven't already specified a slug in the page's front matter.
|
||||
Hugo resolves the extracted date to the [`timeZone`][] defined in your project configuration, falling back to the system time zone. Hugo also derives the page [`slug`][] from the remaining file name, unless the page already defines a `slug` in its front matter.
|
||||
|
||||
Slug inference only occurs when `:filename` is the winning date source. If an earlier entry in the list provides a valid date, Hugo skips `:filename` entirely. For example, with `date = ["date", ":filename"]`, a page that defines `date` in its front matter will use that value, and the slug will not be inferred from the file name.
|
||||
|
||||
For example, if you name your file `2025-02-01-article.md`, Hugo will set the date to `2025-02-01` and the slug to `article`.
|
||||
|
||||
@@ -98,6 +95,10 @@ To determine `date` and `publishDate`, Hugo tries to extract the value from the
|
||||
|
||||
To determine `lastmod`, Hugo looks for a `lastmod` field in front matter, falling back to the file's last modification timestamp.
|
||||
|
||||
[`Date`]: /methods/page/date/
|
||||
[`ExpiryDate`]: /methods/page/expirydate/
|
||||
[`Lastmod`]: /methods/page/lastmod/
|
||||
[`PublishDate`]: /methods/page/publishdate/
|
||||
[`enableGitInfo`]: /configuration/all/#enablegitinfo
|
||||
[`slug`]: /content-management/front-matter/#slug
|
||||
[`timeZone`]: /configuration/all/#timezone
|
||||
|
||||
@@ -6,8 +6,8 @@ categories: []
|
||||
keywords: []
|
||||
---
|
||||
|
||||
> [!note]
|
||||
> This configuration is only relevant when using the [`resources.GetRemote`] function.
|
||||
> [!NOTE]
|
||||
> This configuration is only relevant when using the [`resources.GetRemote`][] function.
|
||||
|
||||
## Layered caching
|
||||
|
||||
@@ -30,13 +30,13 @@ Hugo employs a layered caching system.
|
||||
```
|
||||
|
||||
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.
|
||||
: 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.
|
||||
: 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].
|
||||
: 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).
|
||||
|
||||
@@ -48,36 +48,36 @@ This is the default configuration for HTTP caching:
|
||||
|
||||
{{< code-toggle config=HTTPCache />}}
|
||||
|
||||
respectCacheControlNoStoreInRequest
|
||||
`respectCacheControlNoStoreInRequest`
|
||||
: {{< new-in 0.151.0 />}}
|
||||
: (`bool`) Whether to respect the `no-store` directive in the server's `Cache-Control` request header when fetching remote resources via the [`resources.GetRemote`][] function. Default is `true`.
|
||||
|
||||
respectCacheControlNoStoreInResponse
|
||||
`respectCacheControlNoStoreInResponse`
|
||||
: {{< new-in 0.151.0 />}}
|
||||
: (`bool`) Whether to respect the `no-store` directive in the server's `Cache-Control` response header when fetching remote resources via the [`resources.GetRemote`][] function. Default is `false`.
|
||||
|
||||
cache.for.excludes
|
||||
`cache.for.excludes`
|
||||
: (`[]string`) A slice of [glob patterns](g) to exclude from caching. In its default configuration HTTP caching excludes all files.
|
||||
|
||||
cache.for.includes
|
||||
`cache.for.includes`
|
||||
: (`[]string`) A slice of [glob patterns](g) to cache.
|
||||
|
||||
polls
|
||||
: A slice of polling configurations.
|
||||
`polls`
|
||||
: (`[]PollConfig`) A slice of polling configurations.
|
||||
|
||||
polls.disable
|
||||
`polls.disable`
|
||||
: (`bool`) Whether to disable polling for this configuration. Default is `true`.
|
||||
|
||||
polls.high
|
||||
`polls.high`
|
||||
: (`string`) The maximum polling interval expressed as a [duration](g). This is used when the resource is considered stable. Default is `0s`.
|
||||
|
||||
polls.low
|
||||
`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`. Default is `0s`.
|
||||
|
||||
polls.for.excludes
|
||||
`polls.for.excludes`
|
||||
: (`[]string`) A slice of [glob patterns](g) to exclude from polling for this configuration.
|
||||
|
||||
polls.for.includes
|
||||
`polls.for.includes`
|
||||
: (`[]string`) A slice of [glob patterns](g) to include in polling for this configuration.
|
||||
|
||||
## HTTP polling
|
||||
@@ -96,22 +96,22 @@ includes = ['**']
|
||||
excludes = []
|
||||
{{< /code-toggle >}}
|
||||
|
||||
polls
|
||||
: A slice of polling configurations.
|
||||
`polls`
|
||||
: (`[]PollConfig`) A slice of polling configurations.
|
||||
|
||||
polls.disable
|
||||
`polls.disable`
|
||||
: (`bool`) Whether to disable polling for this configuration. Default is `true`.
|
||||
|
||||
polls.high
|
||||
`polls.high`
|
||||
: (`string`) The maximum polling interval expressed as a [duration](g). This is used when the resource is considered stable. Default is `0s`.
|
||||
|
||||
polls.low
|
||||
`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`. Default is `0s`.
|
||||
|
||||
polls.for.excludes
|
||||
`polls.for.excludes`
|
||||
: (`[]string`) A list of [glob patterns](g) to exclude from polling for this configuration.
|
||||
|
||||
polls.for.includes
|
||||
`polls.for.includes`
|
||||
: (`[]string`) A list of [glob patterns](g) to include in polling for this configuration.
|
||||
|
||||
## Behavior
|
||||
@@ -120,10 +120,10 @@ 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].
|
||||
- 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
|
||||
[RFC 9111]: https://datatracker.ietf.org/doc/html/rfc9111
|
||||
[`resources.GetRemote`]: /functions/resources/getremote/
|
||||
[cache-busting]: /configuration/build/#cache-busters
|
||||
[configure file caches]: /configuration/caches/
|
||||
[RFC 9111]: https://datatracker.ietf.org/doc/html/rfc9111
|
||||
|
||||
@@ -10,25 +10,30 @@ These are the default settings for processing images:
|
||||
|
||||
{{< code-toggle config=imaging />}}
|
||||
|
||||
## Top-level options
|
||||
## Top-level settings
|
||||
|
||||
These global settings define how Hugo handles the fundamental aspects of image manipulation, such as cropping logic, background colors, and general output quality.
|
||||
These settings apply to all image formats.
|
||||
|
||||
anchor
|
||||
`anchor`
|
||||
: (`string`) The focal point used when cropping or filling an image. Valid case-insensitive options include `TopLeft`, `Top`, `TopRight`, `Left`, `Center`, `Right`, `BottomLeft`, `Bottom`, `BottomRight`, or `Smart`. The `Smart` option utilizes the [`muesli/smartcrop`][] package to identify the most interesting area of the image. Default is `smart`.
|
||||
|
||||
bgColor
|
||||
: (string) The background color used when converting transparent images to formats that do not support transparency, such as PNG to JPEG. This color also fills the empty space created when rotating an image by a non-orthogonal angle if the space is not transparent and a background color is not specified in the processing specification. The value must be an RGB [hexadecimal color][]. Default is `#ffffff`.
|
||||
`bgColor`
|
||||
: (`string`) The background color used when converting transparent images to formats that do not support transparency, such as PNG to JPEG. This color also fills the empty space created when rotating an image by a non-orthogonal angle if the space is not transparent and a background color is not specified in the processing specification. The value must be an RGB [hexadecimal color][]. Default is `#ffffff`.
|
||||
|
||||
compression
|
||||
: {{< new-in 0.153.5 />}}
|
||||
: (`string`) The encoding strategy used for the image. Options are `lossy` or `lossless`. Note that `lossless` is only supported by the WebP format. Default is `lossy`.
|
||||
`compression`
|
||||
: {{< deprecated-in 0.163.0 />}}
|
||||
: Use the format-specific `compression` setting instead, applicable to [AVIF](#avif) and [WebP](#webp) images.
|
||||
|
||||
quality
|
||||
: (`int`) The visual fidelity of the image, applicable to JPEG and WebP formats when using `lossy` compression. Expressed as a whole number from `1` to `100`, inclusive. Lower numbers prioritize smaller file size, while higher numbers prioritize visual clarity. Default is `75`.
|
||||
`hint`
|
||||
: {{< deprecated-in 0.163.0 />}}
|
||||
: Use the format-specific `hint` setting instead, applicable to [AVIF](#avif) and [WebP](#webp) images.
|
||||
|
||||
resampleFilter
|
||||
: (`string`) The algorithm used to calculate new pixels when resizing, fitting, or filling an image. Common options include `box`, `lanczos`, `catmullRom`, `mitchellNetravali`, `linear`, or `nearestNeighbor`. Default is `box`.
|
||||
`quality`
|
||||
: {{< deprecated-in 0.163.0 />}}
|
||||
: Use the format-specific `quality` setting instead, applicable to [AVIF](#avif), [JPEG](#jpeg), and [WebP](#webp) images.
|
||||
|
||||
`resampleFilter`
|
||||
: (`string`) The algorithm used to calculate new pixels when resizing, fitting, or filling an image. Common case-insensitive options include `box`, `lanczos`, `catmullRom`, `mitchellNetravali`, `linear`, or `nearestNeighbor`. Default is `box`.
|
||||
|
||||
Filter|Description
|
||||
:--|:--
|
||||
@@ -41,35 +46,30 @@ resampleFilter
|
||||
|
||||
Refer to the [source documentation][] for a complete list of available resampling filters. If you wish to improve image quality at the expense of performance, you may wish to experiment with the alternative filters.
|
||||
|
||||
## Exif method
|
||||
## AVIF
|
||||
|
||||
{{< deprecated-in 0.155.0 >}}
|
||||
Use [`Meta`](/methods/resource/meta/) instead.
|
||||
{{< /deprecated-in >}}
|
||||
{{< new-in 0.162.0 />}}
|
||||
|
||||
## Meta method
|
||||
These settings apply when encoding AVIF images.
|
||||
|
||||
{{< new-in 0.155.0 />}}
|
||||
> [!NOTE]
|
||||
> When exporting HDR AVIF images from Lightroom, in the Export dialog under File Settings, uncheck Maximize Compatibility to improve Hugo's AVIF decoding speed.
|
||||
|
||||
The following parameters allow you to control how Hugo extracts and filters metadata when using the [`Meta`][] method, helping you balance data granularity with build performance.
|
||||
> [!NOTE]
|
||||
> Encoding animated images to AVIF produces a single-frame (static) image. Converting an animated AVIF to another format such as GIF works as expected.
|
||||
|
||||
fields
|
||||
: (`[]string`) A [glob slice](g) matching the fields to include when extracting metadata. If empty, a default set excluding technical metadata is used. Set to `['**']` to include all fields.
|
||||
{{< code-toggle config=imaging.avif />}}
|
||||
|
||||
> [!note]
|
||||
> By default, to improve performance and decrease cache size, Hugo excludes the following fields: `ColorSpace`, `Contrast`, `Exif`, `ExposureBias`, `ExposureMode`, `ExposureProgram`, `Flash`, `GPS`, `JPEG`, `Metering`, `Resolution`, `Saturation`, `Sensing`, `Sharp`, and `WhiteBalance`.
|
||||
`compression`
|
||||
: {{< new-in 0.163.0 />}}
|
||||
: (`string`) The encoding strategy. Options are `lossy` or `lossless`. Default is `lossy`.
|
||||
|
||||
sources
|
||||
: (`[]string`) The metadata sources to include, one or more of `exif`, `iptc`, or `xmp`. Default is `['exif', 'iptc']`. The XMP metadata is excluded by default to improve performance.
|
||||
`encoderSpeed`
|
||||
: (`int`) The encoder speed. Expressed as a whole number from `1` to `10`, inclusive, equivalent to the `-s` flag for the [`avifenc`][] CLI. Lower numbers reduce file size at the cost of build time. At typical web image sizes, quality is indistinguishable across settings. Values below `5` may cause significantly longer build times. Default is `10`.
|
||||
|
||||
## WebP images
|
||||
|
||||
{{< new-in 0.155.0 />}}
|
||||
|
||||
These specialized settings provide granular control over the WebP encoding process, allowing you to optimize compression based on the specific visual characteristics of your imagery.
|
||||
|
||||
hint
|
||||
: (`string`) The encoding preset used when processing WebP images, equivalent to the `-preset` flag for the [`cwebp`][] CLI. Valid options include `drawing`, `icon`, `photo`, `picture`, or `text`. Default is `photo`.
|
||||
`hint`
|
||||
: {{< new-in 0.163.0 />}}
|
||||
: (`string`) The content hint. Valid options include `drawing`, `icon`, `photo`, `picture`, or `text`. Hugo uses the `4:2:0` chroma subsampling format with `photo` and `picture`, and `4:4:4` with the remaining options. Default is `photo`.
|
||||
|
||||
Value|Example
|
||||
:--|:--
|
||||
@@ -79,12 +79,76 @@ hint
|
||||
`picture`|Indoor photograph such as a portrait
|
||||
`text`|Image that is primarily text
|
||||
|
||||
method
|
||||
: (`int`) The effort level of the compression algorithm. Expressed as a whole number from `0` to `6`, inclusive, equivalent to the `-m` flag for the [`cwebp`][] CLI. Lower numbers prioritize processing speed, while higher numbers prioritize compression efficiency. Default is `2`.
|
||||
`quality`
|
||||
: {{< new-in 0.163.0 />}}
|
||||
: (`int`) The visual fidelity when using `lossy` compression. Expressed as a whole number from `1` to `100`, inclusive. Lower numbers prioritize smaller file size, while higher numbers prioritize visual clarity. Default is `60`. Quality values are encoder-specific and not directly comparable across formats; a value of `60` for AVIF is perceptually similar to `75` for JPEG.
|
||||
|
||||
useSharpYuv
|
||||
## JPEG
|
||||
|
||||
{{< new-in 0.163.0 />}}
|
||||
|
||||
These settings apply when encoding JPEG images.
|
||||
|
||||
{{< code-toggle config=imaging.jpeg />}}
|
||||
|
||||
`quality`
|
||||
: (`int`) The visual fidelity. Expressed as a whole number from `1` to `100`, inclusive. Lower numbers prioritize smaller file size, while higher numbers prioritize visual clarity. Default is `75`.
|
||||
|
||||
## WebP
|
||||
|
||||
{{< new-in 0.155.0 />}}
|
||||
|
||||
These settings apply when encoding WebP images.
|
||||
|
||||
{{< code-toggle config=imaging.webp />}}
|
||||
|
||||
`compression`
|
||||
: {{< new-in 0.163.0 />}}
|
||||
: (`string`) The encoding strategy. Options are `lossy` or `lossless`. Default is `lossy`.
|
||||
|
||||
`hint`
|
||||
: (`string`) The content hint, equivalent to the `-preset` flag for the [`cwebp`][] CLI. Valid options include `drawing`, `icon`, `photo`, `picture`, or `text`. Default is `photo`.
|
||||
|
||||
Value|Example
|
||||
:--|:--
|
||||
`drawing`|Hand or line drawing with high-contrast details
|
||||
`icon`|Small colorful image
|
||||
`photo`|Outdoor photograph with natural lighting
|
||||
`picture`|Indoor photograph such as a portrait
|
||||
`text`|Image that is primarily text
|
||||
|
||||
`method`
|
||||
: (`int`) The effort level of the compression algorithm. Expressed as a whole number from `0` to `6`, inclusive, equivalent to the `-m` flag for the [`cwebp`][] CLI. Lower numbers prioritize processing speed, while higher numbers prioritize compression efficiency and image quality. Default is `2`.
|
||||
|
||||
`quality`
|
||||
: {{< new-in 0.163.0 />}}
|
||||
: (`int`) The visual fidelity when using `lossy` compression. Expressed as a whole number from `1` to `100`, inclusive. Lower numbers prioritize smaller file size, while higher numbers prioritize visual clarity. Default is `75`.
|
||||
|
||||
`useSharpYuv`
|
||||
: (`bool`) The conversion method used for RGB-to-YUV encoding, equivalent to the `-sharp_yuv` flag for the [`cwebp`][] CLI. Enabling this prioritizes image sharpness at the expense of processing speed. Default is `false`.
|
||||
|
||||
## Exif method
|
||||
|
||||
{{< deprecated-in 0.155.0 >}}
|
||||
Use the [`Meta`](#meta-method) method instead.
|
||||
{{< /deprecated-in >}}
|
||||
|
||||
## Meta method
|
||||
|
||||
{{< new-in 0.155.0 />}}
|
||||
|
||||
The following parameters allow you to control how Hugo extracts and filters metadata when using the [`Meta`][] method, helping you balance data granularity with build performance.
|
||||
|
||||
`fields`
|
||||
: (`[]string`) A [glob slice](g) matching the fields to include when extracting metadata. If empty, a default set excluding technical metadata is used. Set to `['**']` to include all fields.
|
||||
|
||||
> [!NOTE]
|
||||
> By default, to improve performance and decrease cache size, Hugo excludes the following fields: `ColorSpace`, `Contrast`, `Exif`, `ExposureBias`, `ExposureMode`, `ExposureProgram`, `Flash`, `GPS`, `JPEG`, `Metering`, `Resolution`, `Saturation`, `Sensing`, `Sharp`, and `WhiteBalance`.
|
||||
|
||||
`sources`
|
||||
: (`[]string`) The metadata sources to include, one or more of `exif`, `iptc`, or `xmp`. Default is `['exif', 'iptc']`. The XMP metadata is excluded by default to improve performance.
|
||||
|
||||
[`avifenc`]: https://github.com/aomediacodec/libavif
|
||||
[`cwebp`]: https://developers.google.com/speed/webp/docs/cwebp
|
||||
[`muesli/smartcrop`]: https://github.com/muesli/smartcrop
|
||||
[hexadecimal color]: https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color
|
||||
|
||||
@@ -8,7 +8,7 @@ weight: 10
|
||||
|
||||
## Sensible defaults
|
||||
|
||||
Hugo offers many configuration options, but its defaults are often sufficient. A new project requires only these settings:
|
||||
Hugo offers many configuration settings, but its defaults are often sufficient. A new project requires only these settings:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
baseURL = 'https://example.org/'
|
||||
@@ -18,21 +18,18 @@ title = 'My New Hugo Site'
|
||||
|
||||
Only define settings that deviate from the defaults. A smaller configuration file is easier to read, understand, and debug. Keep your configuration concise.
|
||||
|
||||
> [!note]
|
||||
> [!NOTE]
|
||||
> The best configuration file is a short configuration file.
|
||||
|
||||
## Configuration file
|
||||
|
||||
Create a project configuration file in the root of your project directory, naming it `hugo.toml`, `hugo.yaml`, or `hugo.json`, with that order of precedence.
|
||||
|
||||
```text
|
||||
```tree
|
||||
my-project/
|
||||
└── hugo.toml
|
||||
```
|
||||
|
||||
> [!note]
|
||||
> For versions v0.109.0 and earlier, the project 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 >}}
|
||||
@@ -58,14 +55,14 @@ Combine two or more configuration files, with left-to-right precedence:
|
||||
hugo build --config a.toml,b.yaml,c.json
|
||||
```
|
||||
|
||||
> [!note]
|
||||
> See the specifications for each file format: [TOML], [YAML], and [JSON].
|
||||
> [!NOTE]
|
||||
> See the specifications for each file format: [TOML][], [YAML][], and [JSON][].
|
||||
|
||||
## Configuration directory
|
||||
|
||||
Instead of a single project configuration file, split your configuration by [environment](g), root configuration key, and language. For example:
|
||||
|
||||
```text
|
||||
```tree
|
||||
my-project/
|
||||
└── config/
|
||||
├── _default/
|
||||
@@ -79,14 +76,11 @@ my-project/
|
||||
|
||||
The root configuration keys are {{< root-configuration-keys >}}.
|
||||
|
||||
> [!note]
|
||||
> You must define `cascade` tables in the root configuration file. You cannot define `cascade` tables in a dedicated file. See issue [#12899] for details.
|
||||
### Root key
|
||||
|
||||
[#12899]: https://github.com/gohugoio/hugo/issues/12899
|
||||
{{< new-in 0.162.0 />}}
|
||||
|
||||
### Omit the root key
|
||||
|
||||
When splitting the configuration by root key, omit the root key in the component file. For example, these are equivalent:
|
||||
When splitting the configuration by root key, you may omit or include the root key in the component file. For example, these are equivalent:
|
||||
|
||||
{{< code-toggle file=config/_default/hugo >}}
|
||||
[params]
|
||||
@@ -97,11 +91,40 @@ foo = 'bar'
|
||||
foo = 'bar'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
This also applies to keys whose values are maps of slices, such as `menus`. For example, these are equivalent:
|
||||
|
||||
{{< code-toggle file=config/_default/menus >}}
|
||||
[[main]]
|
||||
name = 'Home'
|
||||
pageRef = '/'
|
||||
weight = 10
|
||||
{{< /code-toggle >}}
|
||||
|
||||
{{< code-toggle file=config/_default/menus >}}
|
||||
[[menus.main]]
|
||||
name = 'Home'
|
||||
pageRef = '/'
|
||||
weight = 10
|
||||
{{< /code-toggle >}}
|
||||
|
||||
For pure slice-typed keys such as `cascade` and `permalinks`, including the root key is required. For example:
|
||||
|
||||
{{< code-toggle file=config/_default/cascade >}}
|
||||
[[cascade]]
|
||||
[cascade.params]
|
||||
color = 'red'
|
||||
[cascade.target]
|
||||
path = '/articles/**'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
> [!NOTE]
|
||||
> Hugo unwraps the root key only when it is the sole top-level key in the file and matches the file's basename.
|
||||
|
||||
### Recursive parsing
|
||||
|
||||
Hugo parses the `config` directory recursively, allowing you to organize the files into subdirectories. For example:
|
||||
|
||||
```text
|
||||
```tree
|
||||
my-project/
|
||||
└── config/
|
||||
└── _default/
|
||||
@@ -113,7 +136,7 @@ my-project/
|
||||
|
||||
### Example
|
||||
|
||||
```text
|
||||
```tree
|
||||
my-project/
|
||||
└── config/
|
||||
├── _default/
|
||||
@@ -131,7 +154,7 @@ my-project/
|
||||
|
||||
Considering the structure above, when running `hugo build --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 project configuration:
|
||||
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 project configuration:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[services.googleAnalytics]
|
||||
@@ -177,7 +200,7 @@ To satisfy these requirements, configure your site as follows:
|
||||
|
||||
Hugo merges configuration settings from themes and modules, prioritizing the project's own settings. Given this simplified project structure with two themes:
|
||||
|
||||
```text
|
||||
```tree
|
||||
project/
|
||||
├── themes/
|
||||
│ ├── theme-a/
|
||||
@@ -206,20 +229,20 @@ The `_merge` setting within each top-level configuration key controls _which_ se
|
||||
|
||||
The value for `_merge` can be one of:
|
||||
|
||||
none
|
||||
`none`
|
||||
: No merge.
|
||||
|
||||
shallow
|
||||
`shallow`
|
||||
: Only add values for new keys.
|
||||
|
||||
deep
|
||||
`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 />}}
|
||||
|
||||
> [!note]
|
||||
> [!NOTE]
|
||||
> Hugo can merge map configuration values from modules and themes into the project configuration, but cannot merge slice values. This applies to top-level slice keys such as `menus`, as well as to map keys whose values are slices, such as the per-kind format lists in `outputs`.
|
||||
|
||||
## Environment variables
|
||||
@@ -229,36 +252,38 @@ 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.
|
||||
The above configures the [`baseURL`][] and [`enableGitInfo`][] settings and then builds your site.
|
||||
|
||||
> [!note]
|
||||
> [!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) platforms by allowing you to set values directly within their respective configuration and workflow files.
|
||||
|
||||
> [!note]
|
||||
> [!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].
|
||||
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
|
||||
`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
|
||||
`HUGO_ENVIRONMENT`
|
||||
: (`string`) The build environment. Default is `production` when running `hugo build` and `development` when running `hugo server`.
|
||||
|
||||
`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
|
||||
`HUGO_MEMORYLIMIT`
|
||||
: (`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 `HUGO_MEMORYLIMIT` is a "best effort" setting. Don't expect Hugo to build a million pages with only 1 GB of memory. You can get more information about how this behaves during the build by running `hugo build --logLevel info` and look for the `dynacache` label.
|
||||
|
||||
HUGO_NUMWORKERMULTIPLIER
|
||||
`HUGO_NUMWORKERMULTIPLIER`
|
||||
: (`int`) The number of workers used in parallel processing. Default is the number of logical CPUs.
|
||||
|
||||
## Current configuration
|
||||
@@ -281,11 +306,10 @@ Display the configured file mounts with:
|
||||
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/
|
||||
[`baseURL`]: /configuration/all#baseurl
|
||||
[`enableGitInfo`]: /configuration/all#enablegitinfo
|
||||
[permitted delimiter]: https://pubs.opengroup.org/onlinepubs/000095399/basedefs/xbd_chap08.html
|
||||
|
||||
@@ -17,17 +17,17 @@ disableDefaultLanguageRedirect = false
|
||||
disableLanguages = []
|
||||
{{< /code-toggle >}}
|
||||
|
||||
defaultContentLanguage
|
||||
`defaultContentLanguage`
|
||||
: (`string`) The projects's default content language, 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 content language to a subdirectory matching the [`defaultContentLanguage`][]. Default is `false`.
|
||||
`defaultContentLanguageInSubdir`
|
||||
: (`bool`) Whether to publish the default content language to a subdirectory matching the [`defaultContentLanguage`](#defaultcontentlanguage). Default is `false`.
|
||||
|
||||
disableDefaultLanguageRedirect
|
||||
`disableDefaultLanguageRedirect`
|
||||
: {{< new-in 0.140.0 />}}
|
||||
: (`bool`) Whether to disable generation of the alias redirect for the default content language. When [`defaultContentLanguageInSubdir`][] is `true`, this setting prevents the root directory from redirecting to the language subdirectory. Conversely, when `defaultContentLanguageInSubdir` is `false`, this setting prevents the language subdirectory from redirecting to the root directory. This is superseded by the more general [`disableDefaultSiteRedirect`][] setting. Default is `false`.
|
||||
: (`bool`) Whether to disable generation of the alias redirect for the default content language. When [`defaultContentLanguageInSubdir`](#defaultcontentlanguageinsubdir) is `true`, this setting prevents the root directory from redirecting to the language subdirectory. Conversely, when `defaultContentLanguageInSubdir` is `false`, this setting prevents the language subdirectory from redirecting to the root directory. This is superseded by the more general [`disableDefaultSiteRedirect`][] setting. Default is `false`.
|
||||
|
||||
disableLanguages
|
||||
`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
|
||||
@@ -38,33 +38,33 @@ Configure each language under the `languages` key:
|
||||
|
||||
In the above, `en` is the [language key](#language-keys).
|
||||
|
||||
direction
|
||||
`direction`
|
||||
: (`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.Direction`][] method on a `Site` or `Page` object. Default is `ltr`.
|
||||
|
||||
disabled
|
||||
`disabled`
|
||||
: (`bool`) Whether to disable this language when building the site. Default is `false`.
|
||||
|
||||
label
|
||||
`label`
|
||||
: (`string`) The language name, typically used when rendering a language switcher. Access this value from a template using the [`Language.Label`][] method on a `Site` or `Page` object.
|
||||
|
||||
languageCode
|
||||
`languageCode`
|
||||
: {{<deprecated-in 0.158.0 />}}
|
||||
: Use [`locale`](#locale) instead.
|
||||
|
||||
languageDirection
|
||||
`languageDirection`
|
||||
: {{<deprecated-in 0.158.0 />}}
|
||||
: Use [`direction`](#direction) instead.
|
||||
|
||||
languageName
|
||||
`languageName`
|
||||
: {{<deprecated-in 0.158.0 />}}
|
||||
: Use [`label`](#label) instead.
|
||||
|
||||
{{% include "/_common/configuration/locale.md" %}}
|
||||
|
||||
title
|
||||
`title`
|
||||
: (`string`) The site title for this language. Access this value from a template using the [`Title`][] method on a `Site` object.
|
||||
|
||||
weight
|
||||
`weight`
|
||||
: (`int`) The language [weight](g). When set to a non-zero value, this is the primary sort criteria for this language.
|
||||
|
||||
## Sort order
|
||||
@@ -118,7 +118,7 @@ weight = 1
|
||||
weight = 2
|
||||
{{< /code-toggle >}}
|
||||
|
||||
> [!note]
|
||||
> [!NOTE]
|
||||
> Private use subtags must not exceed 8 alphanumeric characters.
|
||||
|
||||
## Example
|
||||
@@ -153,14 +153,14 @@ weight = 2
|
||||
subtitle = 'Reference, Tutorials, and Explanations'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
> [!note]
|
||||
> [!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]
|
||||
> [!NOTE]
|
||||
> If you define a `baseURL` for one language, you must define a unique `baseURL` for all languages.
|
||||
|
||||
For example:
|
||||
@@ -181,7 +181,7 @@ weight = 1
|
||||
|
||||
With the above, Hugo publishes two sites, each with their own root:
|
||||
|
||||
```text
|
||||
```tree
|
||||
public
|
||||
├── en
|
||||
└── fr
|
||||
@@ -192,8 +192,6 @@ public
|
||||
[`Language.Direction`]: /methods/site/language/#direction
|
||||
[`Language.Label`]: /methods/site/language/#label
|
||||
[`Title`]: /methods/site/title/
|
||||
[`defaultContentLanguageInSubdir`]: #defaultcontentlanguageinsubdir
|
||||
[`defaultContentLanguage`]: #defaultcontentlanguage
|
||||
[`dir`]: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/dir
|
||||
[`disableDefaultSiteRedirect`]: /configuration/all/#disabledefaultsiteredirect
|
||||
[language keys]: /configuration/languages/#language-keys
|
||||
|
||||
@@ -9,7 +9,7 @@ aliases: [/getting-started/configuration-markup/]
|
||||
|
||||
## Default handler
|
||||
|
||||
In its default configuration, Hugo uses [Goldmark] to render Markdown to HTML.
|
||||
In its default configuration, Hugo uses [Goldmark][] to render Markdown to HTML.
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[markup]
|
||||
@@ -20,18 +20,18 @@ Files with ending with `.md`, `.mdown`, or `.markdown` are processed as Markdown
|
||||
|
||||
To use a different renderer for Markdown files, specify one of `asciidocext`, `org`, `pandoc`, or `rst` in your project configuration.
|
||||
|
||||
`defaultMarkdownHandler`|Renderer
|
||||
:--|:--
|
||||
`asciidocext`|[AsciiDoc]
|
||||
`goldmark`|[Goldmark]
|
||||
`org`|[Emacs Org Mode]
|
||||
`pandoc`|[Pandoc]
|
||||
`rst`|[reStructuredText]
|
||||
`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].
|
||||
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).
|
||||
> [!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
|
||||
|
||||
@@ -43,35 +43,33 @@ This is the default configuration for the Goldmark Markdown renderer:
|
||||
|
||||
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:
|
||||
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
|
||||
|
||||
Enable [deleted text], [inserted text], [mark text], [subscript], and [superscript] elements in Markdown.
|
||||
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>`
|
||||
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[^1], if you enable the "subscript" feature of the Extras extension, you must disable the Strikethrough extension:
|
||||
|
||||
[^1]: See [details](https://github.com/gohugoio/hugo-goldmark-extensions/commit/4d4fcd022fe45a9b51483df001c9e5f4e632d5a9).
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[markup.goldmark.extensions]
|
||||
strikethrough = false
|
||||
@@ -96,21 +94,21 @@ With this configuration, to format text as deleted, wrap it with double-tildes.
|
||||
|
||||
Enabled by default, the Footnote extension enables inclusion of footnotes in Markdown.
|
||||
|
||||
enable
|
||||
`enable`
|
||||
: {{< new-in 0.151.0 />}}
|
||||
: (`bool`) Whether to enable the Footnotes extension. Default is `true`.
|
||||
|
||||
backlinkHTML
|
||||
`backlinkHTML`
|
||||
: {{< new-in 0.151.0 />}}
|
||||
: (`string`) The HTML to be displayed at the end of a footnote that links the user back to the corresponding reference in the main text. The default is ↩︎ (a return arrow symbol).
|
||||
|
||||
enableAutoIDPrefix
|
||||
`enableAutoIDPrefix`
|
||||
: {{< new-in 0.151.0 />}}
|
||||
: (`bool`) Whether to prepend a unique prefix to footnote IDs, preventing clashes when multiple documents are rendered together. This prefix is unique to each logical path, which means that the prefix is not unique across content dimensions such as language. Default is `false`.
|
||||
|
||||
#### Passthrough
|
||||
|
||||
Enable the Passthrough extension to include mathematical equations and expressions in Markdown using LaTeX markup. See [mathematics in Markdown] for details.
|
||||
Enable the Passthrough extension to include mathematical equations and expressions in Markdown using LaTeX markup. See [mathematics in Markdown][] for details.
|
||||
|
||||
#### Typographer
|
||||
|
||||
@@ -133,66 +131,66 @@ Markdown|Replaced by|Description
|
||||
|
||||
Most of the Goldmark settings above are self-explanatory, but some require explanation.
|
||||
|
||||
duplicateResourceFiles
|
||||
: (`bool`) Whether to duplicate shared page resources for each language on multilingual single-host projects. See [multilingual page resources] for details. Default is `false`.
|
||||
`duplicateResourceFiles`
|
||||
: (`bool`) Whether to duplicate shared page resources for each language on multilingual single-host projects. See [multilingual page resources][] for details. Default is `false`.
|
||||
|
||||
> [!note]
|
||||
> With multilingual single-host projects, 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 projects.
|
||||
> [!NOTE]
|
||||
> With multilingual single-host projects, 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 projects.
|
||||
|
||||
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.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
|
||||
`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.
|
||||
: (`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
|
||||
`parser.autoHeadingID`
|
||||
: (`bool`) Whether to automatically add `id` attributes to headings (i.e., `h1`, `h2`, `h3`, `h4`, `h5`, and `h6` elements).
|
||||
|
||||
parser.autoIDType
|
||||
`parser.autoIDType`
|
||||
: (`string`) The strategy used to automatically generate `id` attributes, one of `github`, `github-ascii` or `blackfriday`. Default is `github`.
|
||||
|
||||
- `github`: Generate GitHub-compatible `id` attributes
|
||||
- `github-ascii`: Drop any non-ASCII characters after accent normalization
|
||||
- `blackfriday`: Generate `id` attributes compatible with the Blackfriday Markdown renderer
|
||||
|
||||
This is also the strategy used by the [anchorize] template function.
|
||||
This is also the strategy used by the [`urls.Anchorize`][] function.
|
||||
|
||||
parser.attribute.block
|
||||
: (`bool`) Whether to enable [Markdown attributes] for block elements. Default is `false`.
|
||||
`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`.
|
||||
`parser.attribute.title`
|
||||
: (`bool`) Whether to enable [Markdown attributes][] for headings. Default is `true`.
|
||||
|
||||
<!-- TODO: delete this on or after July 1, 2027. -->
|
||||
renderHooks.image.enableDefault
|
||||
: Deprecated in v0.148.0. Use `renderHooks.image.useEmbedded` instead.
|
||||
`renderHooks.image.enableDefault`
|
||||
: {{< deprecated-in 0.148.0 />}}
|
||||
: Use the `renderHooks.image.useEmbedded` setting instead.
|
||||
|
||||
renderHooks.image.useEmbedded
|
||||
`renderHooks.image.useEmbedded`
|
||||
: {{< new-in 0.148.0 />}}
|
||||
: (`string`) When to use the [embedded image render hook]. One of `auto`, `never`, `always`, or `fallback`. Default is `auto`.
|
||||
: (`string`) When to use the [embedded image render hook][]. One of `auto`, `never`, `always`, or `fallback`. Default is `auto`.
|
||||
|
||||
- `auto`: Use the embedded image render hook only for multilingual single-host projects where the [duplication of shared page resources] feature is disabled. If custom image render hooks are defined by your project, modules, or themes, these will be used instead.
|
||||
- `auto`: Use the embedded image render hook only for multilingual single-host projects where the [duplication of shared page resources][] feature is disabled. If custom image render hooks are defined by your project, modules, or themes, these will be used instead.
|
||||
- `never`: Never use the embedded image render hook. If custom image render hooks are defined by your project, modules, or themes, these will be used instead.
|
||||
- `always`: Always use the embedded image render hook, even if custom image render hooks are provided by your project, modules, or themes.
|
||||
- `fallback`: Use the embedded image render hook only if custom image render hooks are not provided by your project, modules, or themes. If custom image render hooks exist, these will be used instead.
|
||||
|
||||
<!-- TODO: delete this on or after July 1, 2027. -->
|
||||
renderHooks.link.enableDefault
|
||||
: Deprecated in v0.148.0. Use `renderHooks.link.useEmbedded` instead.
|
||||
`renderHooks.link.enableDefault`
|
||||
: {{< deprecated-in 0.148.0 />}}
|
||||
: Use the `renderHooks.link.useEmbedded` setting instead.
|
||||
|
||||
renderHooks.link.useEmbedded
|
||||
: (`string`) When to use the [embedded link render hook]. One of `auto`, `never`, `always`, or `fallback`. Default is `auto`.
|
||||
`renderHooks.link.useEmbedded`
|
||||
: (`string`) When to use the [embedded link render hook][]. One of `auto`, `never`, `always`, or `fallback`. Default is `auto`.
|
||||
|
||||
- `auto`: Use the embedded link render hook only for multilingual single-host projects where the [duplication of shared page resources] feature is disabled. If custom link render hooks are defined by your project, modules, or themes, these will be used instead.
|
||||
- `auto`: Use the embedded link render hook only for multilingual single-host projects where the [duplication of shared page resources][] feature is disabled. If custom link render hooks are defined by your project, modules, or themes, these will be used instead.
|
||||
- `never`: Never use the embedded link render hook. If custom link render hooks are defined by your project, modules, or themes, these will be used instead.
|
||||
- `always`: Always use the embedded link render hook, even if custom link render hooks are provided by your project, modules, or themes.
|
||||
- `fallback`: Use the embedded link render hook only if custom link render hooks are not provided by your project, modules, or themes. If custom link render hooks exist, these will be used instead.
|
||||
|
||||
renderer.hardWraps
|
||||
`renderer.hardWraps`
|
||||
: (`bool`) Whether to replace newline characters within a paragraph with `br` elements. Default is `false`.
|
||||
|
||||
renderer.unsafe
|
||||
`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
|
||||
@@ -203,41 +201,41 @@ This is the default configuration for the AsciiDoc renderer:
|
||||
|
||||
### AsciiDoc settings explained
|
||||
|
||||
attributes
|
||||
: (`map`) A map of key-value pairs, each a document attribute. See Asciidoctor's [attributes].
|
||||
`attributes`
|
||||
: (`map`) A map of key-value pairs, each a document attribute. See Asciidoctor's [attributes][].
|
||||
|
||||
backend
|
||||
`backend`
|
||||
: (`string`) The backend output file format. Default is `html5`.
|
||||
|
||||
extensions
|
||||
`extensions`
|
||||
: (`[]string`) An array of enabled extensions, such as `asciidoctor-html5s`, `asciidoctor-bibtex`, or `asciidoctor-diagram`.
|
||||
|
||||
> [!note]
|
||||
> [!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
|
||||
`failureLevel`
|
||||
: (`string`) The minimum logging level that triggers a non-zero exit code (failure). Default is `fatal`.
|
||||
|
||||
noHeaderOrFooter
|
||||
`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`.
|
||||
`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
|
||||
`safeMode`
|
||||
: (`string`) The safe mode level, one of `unsafe`, `safe`, `server`, or `secure`. Default is `unsafe`.
|
||||
|
||||
sectionNumbers
|
||||
`sectionNumbers`
|
||||
: (`bool`) Whether to number each section title. Default is `false`.
|
||||
|
||||
trace
|
||||
`trace`
|
||||
: (`bool`) Whether to include backtrace information on errors. Default is `false`.
|
||||
|
||||
verbose
|
||||
`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`.
|
||||
`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
|
||||
|
||||
@@ -265,7 +263,7 @@ Step 1
|
||||
Step 2
|
||||
: Generate the highlighter CSS. For example:
|
||||
|
||||
```text
|
||||
```sh
|
||||
rougify style monokai.sublime > assets/css/syntax.css
|
||||
```
|
||||
|
||||
@@ -318,27 +316,20 @@ This is the default configuration for the table of contents, applicable to Goldm
|
||||
|
||||
{{< code-toggle config=markup.tableOfContents />}}
|
||||
|
||||
startLevel
|
||||
`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
|
||||
`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
|
||||
`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/
|
||||
[anchorize]: /functions/urls/anchorize
|
||||
[^1]: See [details](https://github.com/gohugoio/hugo-goldmark-extensions/commit/4d4fcd022fe45a9b51483df001c9e5f4e632d5a9).
|
||||
|
||||
[AsciiDoc]: https://asciidoc.org/
|
||||
[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
|
||||
[Emacs Org Mode]: https://orgmode.org/
|
||||
[embedded image render hook]: /render-hooks/images/#embedded
|
||||
[embedded link render hook]: /render-hooks/links/#embedded
|
||||
[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-
|
||||
@@ -349,16 +340,25 @@ ordered
|
||||
[Goldmark]: https://github.com/yuin/goldmark/
|
||||
[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
|
||||
[Markdown attributes]: /content-management/markdown-attributes/
|
||||
[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
|
||||
[Pandoc]: https://pandoc.org/
|
||||
[`Fragments.Identifiers`]: /methods/page/fragments/#identifiers
|
||||
[`TableOfContents`]: /methods/page/tableofcontents/
|
||||
[`urls.Anchorize`]: /functions/urls/anchorize/
|
||||
[asciidoctor-diagram]: https://asciidoctor.org/docs/asciidoctor-diagram/
|
||||
[attributes]: https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#attributes-and-substitutions
|
||||
[deleted text]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/del
|
||||
[duplication of shared page resources]: /configuration/markup/#duplicateresourcefiles
|
||||
[embedded image render hook]: /render-hooks/images/#embedded
|
||||
[embedded link render hook]: /render-hooks/links/#embedded
|
||||
[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/
|
||||
[mathematics in Markdown]: /content-management/mathematics/
|
||||
[multilingual page resources]: /content-management/page-resources/#multilingual
|
||||
[Pandoc]: https://pandoc.org/
|
||||
[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
|
||||
[reStructuredText]: https://docutils.sourceforge.io/rst.html
|
||||
[security policy]: /configuration/security/
|
||||
[subscript]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/sub
|
||||
|
||||
@@ -14,7 +14,7 @@ Configured media types serve multiple purposes in Hugo, including the definition
|
||||
|
||||
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]
|
||||
> [!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
|
||||
@@ -23,10 +23,10 @@ The following is the default configuration that matches the table above:
|
||||
|
||||
{{< code-toggle file=hugo config=mediaTypes />}}
|
||||
|
||||
delimiter
|
||||
`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
|
||||
`suffixes`
|
||||
: (`[]string`) The suffixes associated with this media type. The first suffix is the primary suffix.
|
||||
|
||||
## Modify a media type
|
||||
@@ -56,7 +56,7 @@ suffixes = ['atom']
|
||||
|
||||
## 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).
|
||||
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:
|
||||
|
||||
|
||||
@@ -6,13 +6,13 @@ categories: []
|
||||
keywords: []
|
||||
---
|
||||
|
||||
> [!note]
|
||||
> To understand Hugo's menu system, please refer to the [menus] page.
|
||||
> [!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. [Automatically][]
|
||||
1. In [front matter][]
|
||||
1. In your project configuration
|
||||
|
||||
This page covers the project configuration method.
|
||||
@@ -38,7 +38,7 @@ pageRef = '/services'
|
||||
weight = 30
|
||||
{{< /code-toggle >}}
|
||||
|
||||
This creates a menu structure that you can access with [`Menus`] method on a `Site` object:
|
||||
This creates a menu structure that you can access with [`Menus`][] method on a `Site` object:
|
||||
|
||||
```go-html-template
|
||||
{{ range .Site.Menus.main }}
|
||||
@@ -46,7 +46,7 @@ This creates a menu structure that you can access with [`Menus`] method on a `Si
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
See [menu templates] for a detailed example.
|
||||
See [menu templates][] for a detailed example.
|
||||
|
||||
To define entries for a "footer" menu:
|
||||
|
||||
@@ -78,7 +78,7 @@ These are the available menu entry properties:
|
||||
|
||||
{{% include "/_common/menu-entry-properties.md" %}}
|
||||
|
||||
pageRef
|
||||
`pageRef`
|
||||
: (`string`) The [logical path](g) of the target page. For example:
|
||||
|
||||
page kind|pageRef
|
||||
@@ -89,7 +89,7 @@ pageRef
|
||||
taxonomy|`/tags`
|
||||
term|`/tags/foo`
|
||||
|
||||
url
|
||||
`url`
|
||||
: (`string`) The destination URL. Use this for external destinations only.
|
||||
|
||||
## Nested menu
|
||||
@@ -130,8 +130,8 @@ rel = 'external'
|
||||
{{< /code-toggle >}}
|
||||
<!-- markdownlint-enable MD033 -->
|
||||
|
||||
[`Menus`]: /methods/site/menus/
|
||||
[Automatically]: /content-management/menus/#define-automatically
|
||||
[`Menus`]: /methods/site/menus/
|
||||
[front matter]: /content-management/menus/#define-in-front-matter
|
||||
[menu templates]: /templates/menu/
|
||||
[menus]: /content-management/menus/
|
||||
|
||||
@@ -9,7 +9,7 @@ aliases: [/hugo-modules/configuration/]
|
||||
|
||||
{{% include "/_common/gomodules-info.md" %}}
|
||||
|
||||
## Top-level options
|
||||
## Top-level settings
|
||||
|
||||
This is the default configuration:
|
||||
|
||||
@@ -25,23 +25,23 @@ workspace = 'off'
|
||||
{{< /code-toggle >}}
|
||||
<!-- markdownlint-enable MD049 -->
|
||||
|
||||
auth
|
||||
`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
|
||||
`noProxy`
|
||||
: (`string`) A comma-separated list of [glob patterns](g), matching paths that should not use the [configured proxy server](#proxy).
|
||||
|
||||
noVendor
|
||||
`noVendor`
|
||||
: (`string`) A [glob pattern](g) matching module paths to skip when vendoring.
|
||||
|
||||
private
|
||||
`private`
|
||||
: (`string`) A comma-separated list of [glob patterns](g), matching paths that should be treated as private.
|
||||
|
||||
proxy
|
||||
`proxy`
|
||||
: (`string`) The proxy server to use to download remote modules. Default is `direct`, which means `git clone` and similar.
|
||||
|
||||
replacements
|
||||
`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 >}}
|
||||
@@ -49,10 +49,10 @@ replacements
|
||||
replacements = 'github.com/bep/my-theme -> ../..,github.com/bep/shortcodes -> /some/path'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
vendorClosest
|
||||
`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
|
||||
`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:
|
||||
@@ -73,10 +73,11 @@ This is the default configuration:
|
||||
|
||||
You can omit any of the settings above.
|
||||
|
||||
extended
|
||||
`extended`
|
||||
: {{< deprecated-in v0.153.0 />}}
|
||||
: (`bool`) Whether the extended edition of Hugo is required, satisfied by installing either the extended or extended/deploy edition.
|
||||
|
||||
> [!note]
|
||||
> [!NOTE]
|
||||
> The extended version check is disabled in v0.153.2 and later.
|
||||
>
|
||||
> Historically, certain features—specifically WebP encoding and LibSass—required the Hugo Extended binary. However, as of v0.153.0:
|
||||
@@ -86,10 +87,10 @@ extended
|
||||
>
|
||||
> Because these dependencies no longer require a specialized binary, the internal enforcement check for the extended version has been removed. Site and theme authors are encouraged to use Dart Sass to ensure cross-edition compatibility.
|
||||
|
||||
max
|
||||
`max`
|
||||
: (`string`) The maximum Hugo version supported, for example `0.153.0`.
|
||||
|
||||
min
|
||||
`min`
|
||||
: (`string`) The minimum Hugo version supported, for example `0.102.0`.
|
||||
|
||||
## Imports
|
||||
@@ -104,37 +105,37 @@ path = 'github.com/gohugoio/hugoTestModules1_linux/modh1_2_1v'
|
||||
path = 'my-shortcodes'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
disable
|
||||
`disable`
|
||||
: (`bool`) Whether to disable the module but keep version information in the `go.*` files. Default is `false`.
|
||||
|
||||
ignoreConfig
|
||||
`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
|
||||
`ignoreImports`
|
||||
: (`bool`) Whether to ignore module imports. Default is `false`.
|
||||
|
||||
noMounts
|
||||
`noMounts`
|
||||
: (`bool`) Whether to disable directory mounting for this import. Default is `false`.
|
||||
|
||||
noVendor
|
||||
`noVendor`
|
||||
: (`bool`) Whether to disable vendoring for this import. This setting is restricted to the main project. Default is `false`.
|
||||
|
||||
usePackageJSON
|
||||
`usePackageJSON`
|
||||
: {{< new-in 0.159.0 />}}
|
||||
: (`string`) Whether to use the import's npm dependencies in [hugo mod npm pack](commands/hugo_mod_npm_pack/). One of `auto` (default), `always` or `never`. When set to `auto`, Hugo will enable this if either there is a Hugo config file (e.g. `hugo.toml`) or a `package.hugo.json` file in the module root.
|
||||
|
||||
path
|
||||
`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`][].
|
||||
|
||||
version
|
||||
`version`
|
||||
: {{< new-in 0.150.0 />}}
|
||||
: If set to a [version query](https://go.dev/ref/mod#version-queries), this import becomes a direct dependency, in contrast to dependencies managed by Go Modules. See [this issue](https://github.com/gohugoio/hugo/pull/13966) for more information.
|
||||
: (`string`) If set to a [version query][], this import becomes a direct dependency, in contrast to dependencies managed by Go modules. See [this issue][] for more information.
|
||||
|
||||
## Mounts
|
||||
|
||||
{{% glossary-term mount %}}
|
||||
|
||||
> [!important]
|
||||
> [!IMPORTANT]
|
||||
> If you define one or more mounts to map a file system path to a component path, do not use these legacy configuration settings: [`archetypeDir`][], [`assetDir`][], [`contentDir`][], [`dataDir`][], [`i18nDir`][], [`layoutDir`][], or [`staticDir`][].
|
||||
|
||||
### Default mounts
|
||||
@@ -149,32 +150,32 @@ These are the default mounts:
|
||||
|
||||
{{< code-toggle config=module.mounts />}}
|
||||
|
||||
source
|
||||
`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
|
||||
`target`
|
||||
: (`string`) Where the mount will reside within Hugo's [unified file system](g). It must begin with one of Hugo's [component](g) directories: archetypes, assets, content, data, i18n, layouts, or static. For example, content/blog.
|
||||
|
||||
disableWatch
|
||||
`disableWatch`
|
||||
: (`bool`) Whether to disable watching in watch mode for this mount. Default is `false`.
|
||||
|
||||
excludeFiles
|
||||
`excludeFiles`
|
||||
: {{< deprecated-in 0.153.0 />}}
|
||||
: Use [`files`](#files) instead.
|
||||
: Use the [`files`](#files) setting instead.
|
||||
|
||||
files
|
||||
`files`
|
||||
: {{< new-in 0.153.0 />}}
|
||||
: (`[]string`) A [glob slice](g) defining the files to include or exclude.
|
||||
|
||||
includeFiles
|
||||
`includeFiles`
|
||||
: {{< deprecated-in 0.153.0 />}}
|
||||
: Use [`files`](#files) instead.
|
||||
: Use the [`files`](#files) setting instead.
|
||||
|
||||
lang
|
||||
`lang`
|
||||
: {{< deprecated-in 0.153.0 />}}
|
||||
: Use [`sites`](#sites) instead.
|
||||
: Use the [`sites`](#sites) setting instead.
|
||||
|
||||
sites
|
||||
`sites`
|
||||
: {{< new-in 0.153.0 />}}
|
||||
: (`map`) A map to define [sites matrix](g) and [sites complements](g) for the mount. Relevant for `content` and `layouts` mounts, and `static` mounts when in multihost mode. For `static` and `layouts`, only the `matrix` keyword is supported.
|
||||
|
||||
@@ -194,6 +195,7 @@ source = 'assets'
|
||||
target = 'assets'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
[Dart Sass]: /functions/css/sass/#dart-sass
|
||||
[`archetypeDir`]: /configuration/all/#archetypedir
|
||||
[`assetDir`]: /configuration/all/#assetdir
|
||||
[`contentDir`]: /configuration/all/#contentdir
|
||||
@@ -202,4 +204,5 @@ target = 'assets'
|
||||
[`layoutDir`]: /configuration/all/#layoutdir
|
||||
[`staticDir`]: /configuration/all/#staticdir
|
||||
[`themesDir`]: /configuration/all/#themesdir
|
||||
[Dart Sass]: /functions/css/sass/#dart-sass
|
||||
[this issue]: https://github.com/gohugoio/hugo/pull/13966
|
||||
[version query]: https://go.dev/ref/mod#version-queries
|
||||
|
||||
@@ -37,43 +37,43 @@ The following is the default configuration that matches the table above:
|
||||
|
||||
{{< code-toggle config=outputFormats />}}
|
||||
|
||||
baseName
|
||||
`baseName`
|
||||
: (`string`) The base name of the published file. Default is `index`.
|
||||
|
||||
isHTML
|
||||
`isHTML`
|
||||
: (`bool`) Whether to classify the output format as HTML. This value determines when the LiveReload script is injected and, in conjunction with [`permalinkable`](#permalinkable), whether [alias redirects][] are generated. Default is `false`.
|
||||
|
||||
isPlainText
|
||||
`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
|
||||
`mediaType`
|
||||
: (`string`) The [media type](g) of the published file. This must match one of the [configured media types][].
|
||||
|
||||
notAlternative
|
||||
`notAlternative`
|
||||
: (`bool`) Whether to exclude this output format from the values returned by the [`AlternativeOutputFormats`][] method on a `Page` object. Default is `false`.
|
||||
|
||||
noUgly
|
||||
`noUgly`
|
||||
: (`bool`) Whether to disable ugly URLs for this output format when [`uglyURLs`][] are enabled in your project configuration. Default is `false`.
|
||||
|
||||
path
|
||||
`path`
|
||||
: (`string`) The first segment of the publication path for this output format. This path segment is relative to the root of your [`publishDir`][]. If omitted, Hugo will use the file's original content path for publishing.
|
||||
|
||||
permalinkable
|
||||
`permalinkable`
|
||||
: (`bool`) Whether to return the rendering output format rather than the main output format when invoking the [`Permalink`][] and [`RelPermalink`][] methods on a `Page` object. Along with [`isHTML`](#ishtml), this must be `true` to create [alias redirects][]. Enabled by default for the `html` and `amp` output formats. Default is `false`.
|
||||
|
||||
protocol
|
||||
`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 project configuration, typically `https://`.
|
||||
|
||||
rel
|
||||
`rel`
|
||||
: (`string`) The relationship of the output format to the current page. Hugo uses this property to determine the [canonical output format](g) of the current page. For the predefined `html` output format, the default value is `canonical`; for all other predefined output formats, the default value is `alternate`.
|
||||
|
||||
root
|
||||
`root`
|
||||
: (`bool`) Whether to publish files to the root of the publish directory. Default is `false`.
|
||||
|
||||
ugly
|
||||
`ugly`
|
||||
: (`bool`) Whether to enable uglyURLs for this output format when `uglyURLs` is `false` in your project configuration. Default is `false`.
|
||||
|
||||
weight
|
||||
`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
|
||||
@@ -159,7 +159,7 @@ For example, in `page.json.json`, you'll see:
|
||||
{{ 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.
|
||||
To make these methods return the URL of the _current_ template's output format, you must set the [`permalinkable`](#permalinkable) setting to `true` for that format.
|
||||
|
||||
With `permalinkable` set to true for `json` in the same `page.json.json` template:
|
||||
|
||||
@@ -189,12 +189,13 @@ Output format|Template path
|
||||
`rss`|`layouts/section.rss.xml`
|
||||
|
||||
[`AlternativeOutputFormats`]: /methods/page/alternativeoutputformats/
|
||||
[`baseURL`]: /configuration/all/#baseurl
|
||||
[`OutputFormats`]: /methods/page/outputformats/
|
||||
[`Permalink`]: /methods/page/permalink/
|
||||
[`permalinkable`]: #permalinkable
|
||||
[`publishDir`]: /configuration/all/#publishdir
|
||||
[`RelPermalink`]: /methods/page/relpermalink/
|
||||
[`baseURL`]: /configuration/all/#baseurl
|
||||
[`html/template`]: https://pkg.go.dev/html/template
|
||||
[`publishDir`]: /configuration/all/#publishdir
|
||||
[`text/template`]: https://pkg.go.dev/text/template
|
||||
[`uglyURLs`]: /configuration/ugly-urls/
|
||||
[alias redirects]: /content-management/urls/#aliases
|
||||
[configure media types]: /configuration/media-types/
|
||||
@@ -202,6 +203,4 @@ Output format|Template path
|
||||
[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
|
||||
|
||||
@@ -8,7 +8,7 @@ keywords: []
|
||||
|
||||
{{% glossary-term "output format" %}}
|
||||
|
||||
Learn more about creating and configuring output formats in the [configure output formats] section.
|
||||
Learn more about creating and configuring output formats in the [configure output formats][] section.
|
||||
|
||||
## Outputs per page kind
|
||||
|
||||
@@ -25,12 +25,12 @@ home = ['html','rss','json']
|
||||
|
||||
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]
|
||||
> [!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.
|
||||
> 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.
|
||||
> See the [link to output formats][] section for details.
|
||||
|
||||
## Outputs per page
|
||||
|
||||
|
||||
@@ -6,19 +6,23 @@ 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/)
|
||||
- [`Next`][] and [`Prev`][]
|
||||
- [`NextInSection`][] and [`PrevInSection`][]
|
||||
|
||||
This is based on this default project configuration:
|
||||
|
||||
{{< code-toggle config=page />}}
|
||||
|
||||
`nextPrevInSectionSortOrder`
|
||||
: (`string`) The sort order used to determine the _next_ and _previous_ page within the same section when calling [`NextInSection`][] or [`PrevInSection`][] on a `Page` object. Valid values are `asc` (ascending) or `desc` (descending). Default is `desc`.
|
||||
|
||||
`nextPrevSortOrder`
|
||||
: (`string`) The sort order used to determine the _next_ and _previous_ page when calling [`Next`][] or [`Prev`][] on a `Page` object. Valid values are `asc` (ascending) or `desc` (descending). Default is `desc`.
|
||||
|
||||
To reverse the meaning of _next_ and _previous_:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
@@ -27,8 +31,12 @@ To reverse the meaning of _next_ and _previous_:
|
||||
nextPrevSortOrder = 'asc'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
> [!note]
|
||||
> These settings do not apply to the [`Next`] or [`Prev`] methods on a `Pages` object.
|
||||
> [!NOTE]
|
||||
> These settings do not apply to the [`Next`][next-pages] or [`Prev`][prev-pages] methods on a `Pages` object.
|
||||
|
||||
[`Next`]: /methods/pages/next
|
||||
[`Prev`]: /methods/pages/next
|
||||
[`NextInSection`]: /methods/page/nextinsection/
|
||||
[`Next`]: /methods/page/next/
|
||||
[`PrevInSection`]: /methods/page/previnsection/
|
||||
[`Prev`]: /methods/page/prev/
|
||||
[next-pages]: /methods/pages/next/
|
||||
[prev-pages]: /methods/pages/prev/
|
||||
|
||||
@@ -10,13 +10,13 @@ This is the default configuration:
|
||||
|
||||
{{< code-toggle config=pagination />}}
|
||||
|
||||
disableAliases
|
||||
`disableAliases`
|
||||
: (`bool`) Whether to disable alias generation for the first pager. Default is `false`.
|
||||
|
||||
pagerSize
|
||||
`pagerSize`
|
||||
: (`int`) The number of pages per pager. Default is `10`.
|
||||
|
||||
path
|
||||
`path`
|
||||
: (`string`) The segment of each pager URL indicating that the target page is a pager. Default is `page`.
|
||||
|
||||
With multilingual projects you can define the pagination behavior for each language:
|
||||
|
||||
@@ -19,9 +19,7 @@ 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/
|
||||
Access the custom parameters from your templates using the [`Params`][] method on a `Site` object:
|
||||
|
||||
```go-html-template
|
||||
{{ .Site.Params.subtitle }} → Reference, Tutorials, and Explanations
|
||||
@@ -98,3 +96,5 @@ To access the module/theme settings:
|
||||
{{ $cfg.colors.background }} → #efefef
|
||||
{{ $cfg.colors.font }} → #222222
|
||||
```
|
||||
|
||||
[`Params`]: /methods/site/params/
|
||||
|
||||
@@ -8,8 +8,8 @@ keywords: []
|
||||
|
||||
Use the `permalinks` configuration to define custom URL patterns for your pages. Hugo supports two forms: a map form for simple section-based patterns, and an array form that supports [page matchers](g) for more precise targeting.
|
||||
|
||||
> [!note]
|
||||
> The [`url`] front matter field overrides any matching permalink pattern.
|
||||
> [!NOTE]
|
||||
> The [`url`][] front matter field overrides any matching permalink pattern.
|
||||
|
||||
## Map form
|
||||
|
||||
|
||||
@@ -26,7 +26,7 @@ Some of these templates include settings to enhance privacy.
|
||||
|
||||
## Configuration
|
||||
|
||||
> [!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:
|
||||
@@ -35,9 +35,16 @@ These are the default privacy settings for Hugo's embedded templates:
|
||||
|
||||
See each template's documentation for a description of its privacy settings:
|
||||
|
||||
- [Disqus partial](/templates/embedded/#privacy-disqus)
|
||||
- [Google Analytics partial](/templates/embedded/#privacy-google-analytics)
|
||||
- [Instagram shortcode](/shortcodes/instagram/#privacy)
|
||||
- [Vimeo shortcode](/shortcodes/vimeo/#privacy)
|
||||
- [X shortcode](/shortcodes/x/#privacy)
|
||||
- [YouTube shortcode](/shortcodes/youtube/#privacy)
|
||||
- [Disqus partial][]
|
||||
- [Google Analytics partial][]
|
||||
- [Instagram shortcode][]
|
||||
- [Vimeo shortcode][]
|
||||
- [X shortcode][]
|
||||
- [YouTube shortcode][]
|
||||
|
||||
[Disqus partial]: /templates/embedded/#privacy-disqus
|
||||
[Google Analytics partial]: /templates/embedded/#privacy-google-analytics
|
||||
[Instagram shortcode]: /shortcodes/instagram/#privacy
|
||||
[Vimeo shortcode]: /shortcodes/vimeo/#privacy
|
||||
[X shortcode]: /shortcodes/x/#privacy
|
||||
[YouTube shortcode]: /shortcodes/youtube/#privacy
|
||||
|
||||
@@ -6,8 +6,8 @@ categories: []
|
||||
keywords: []
|
||||
---
|
||||
|
||||
> [!note]
|
||||
> To understand Hugo's related content identification, please refer to the [related content] page.
|
||||
> [!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 project configuration, either globally or per language.
|
||||
|
||||
@@ -17,50 +17,50 @@ This is the default configuration:
|
||||
|
||||
{{< code-toggle config=related />}}
|
||||
|
||||
> [!note]
|
||||
> [!NOTE]
|
||||
> Adding a `related` section to your project configuration requires you to provide a full configuration. You cannot override individual default values without specifying all related settings.
|
||||
|
||||
## Top-level options
|
||||
## Top-level settings
|
||||
|
||||
threshold
|
||||
`threshold`
|
||||
: (`int`) A value between 0-100, inclusive. A lower value will return more, but maybe not so relevant, matches.
|
||||
|
||||
includeNewer
|
||||
`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
|
||||
`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
|
||||
## Per-index settings
|
||||
|
||||
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.
|
||||
`applyFilter`
|
||||
: (`string`) Apply a `type` specific filter to the result of a search. This is only used for the `fragments` type.
|
||||
|
||||
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
|
||||
`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
|
||||
`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.
|
||||
|
||||
`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
|
||||
`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`.
|
||||
|
||||
`type`
|
||||
: (`string`) One of `basic` or `fragments`. Default is `basic`.
|
||||
|
||||
`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`.
|
||||
|
||||
## 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
|
||||
```tree
|
||||
content/
|
||||
└── book-reviews/
|
||||
├── book-review-1.md
|
||||
|
||||
@@ -16,7 +16,7 @@ This is the default configuration:
|
||||
|
||||
Use the following setting to define how Hugo orders roles.
|
||||
|
||||
weight
|
||||
`weight`
|
||||
: (`int`) The role [weight](g).
|
||||
|
||||
## Sort order
|
||||
|
||||
@@ -12,48 +12,52 @@ This is the default security configuration:
|
||||
|
||||
{{< code-toggle config=security />}}
|
||||
|
||||
enableInlineShortcodes
|
||||
: (`bool`) Whether to enable [inline shortcodes]. Default is `false`.
|
||||
`allowContent`
|
||||
: {{< new-in 0.162.0 />}}
|
||||
: (`[]string`) A slice of [regular expressions](g) matching the [media type](g) of [content formats](g) allowed in the `content` directory. By default, the HTML content format (media type `text/html`) is denied. Hugo emits HTML file content verbatim, which could allow arbitrary JavaScript execution. See the [classification][] table for a mapping of content formats to media types.
|
||||
|
||||
exec.allow
|
||||
`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
|
||||
`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.
|
||||
`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.methods`
|
||||
: (`[]string`) A slice of [regular expressions](g) matching the HTTP methods that the [`resources.GetRemote`][] function is allowed to use.
|
||||
|
||||
http.mediaTypes
|
||||
`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
|
||||
`http.urls`
|
||||
: (`[]string`) A slice of [regular expressions](g) matching the URLs that the `resources.GetRemote` function is allowed to access.
|
||||
|
||||
node.permissions.disable
|
||||
`node.permissions.disable`
|
||||
: {{< new-in 0.161.0 />}}
|
||||
: (`bool`) Whether to disable the Node.js [permission model]. When `false`, Hugo runs Node.js tools with the `--permission` flag, restricting their file system and resource access to what is explicitly allowed below. Default is `false`.
|
||||
: (`bool`) Whether to disable the Node.js [permission model][]. When `false`, Hugo runs Node.js tools with the `--permission` flag, restricting their file system and resource access to what is explicitly allowed below. Default is `false`.
|
||||
|
||||
node.permissions.allowAddons
|
||||
`node.permissions.allowAddons`
|
||||
: {{< new-in 0.161.0 />}}
|
||||
: (`[]string`) A slice of Node.js tool names permitted to load native addons (`--allow-addons`).
|
||||
|
||||
node.permissions.allowChildProcess
|
||||
`node.permissions.allowChildProcess`
|
||||
: {{< new-in 0.161.0 />}}
|
||||
: (`[]string`) A slice of Node.js tool names permitted to spawn child processes (`--allow-child-process`).
|
||||
|
||||
node.permissions.allowRead
|
||||
`node.permissions.allowRead`
|
||||
: {{< new-in 0.161.0 />}}
|
||||
: (`[]string`) A slice of file system paths that Node.js tools are allowed to read (`--allow-fs-read`). Paths are relative to the working directory; `"."` means the working directory itself. Use `"*"` to allow all paths.
|
||||
|
||||
node.permissions.allowWorker
|
||||
`node.permissions.allowWorker`
|
||||
: {{< new-in 0.161.0 />}}
|
||||
: (`[]string`) A slice of Node.js tool names permitted to spawn worker threads (`--allow-worker`).
|
||||
|
||||
node.permissions.allowWrite
|
||||
`node.permissions.allowWrite`
|
||||
: {{< new-in 0.161.0 />}}
|
||||
: (`[]string`) A slice of file system paths that Node.js tools are allowed to write (`--allow-fs-write`). Paths are relative to the working directory; `"."` means the working directory itself. Use `"*"` to allow all paths.
|
||||
|
||||
@@ -80,10 +84,11 @@ You can also override your project configuration with environment variables. For
|
||||
export HUGO_SECURITY_HTTP_URLS=none
|
||||
```
|
||||
|
||||
Learn more about [using environment variables] to configure your site.
|
||||
Learn more about [using environment variables][] to configure your site.
|
||||
|
||||
[`os.Getenv`]: /functions/os/getenv
|
||||
[`resources.GetRemote`]: /functions/resources/getremote
|
||||
[`os.Getenv`]: /functions/os/getenv/
|
||||
[`resources.GetRemote`]: /functions/resources/getremote/
|
||||
[classification]: /content-management/formats/#classification
|
||||
[inline shortcodes]: /content-management/shortcodes/#inline
|
||||
[permission model]: https://nodejs.org/api/permissions.html#permission-model
|
||||
[using environment variables]: /configuration/introduction/#environment-variables
|
||||
|
||||
@@ -6,7 +6,7 @@ categories: []
|
||||
keywords: []
|
||||
---
|
||||
|
||||
> [!note]
|
||||
> [!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:
|
||||
@@ -18,58 +18,179 @@ Segmented rendering offers several advantages:
|
||||
|
||||
## Segment definition
|
||||
|
||||
Each segment is defined by include and exclude filters:
|
||||
Each segment is defined by an `includes` key and an `excludes` key, both of which accept an array of 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 pattern](g) matchers.
|
||||
- Logic: Matchers within a filter use AND logic. Filters within a section (include or exclude) use OR logic.
|
||||
A _filter_ is a collection of one or more conditions, represented as an item in the configuration array. A _condition_ compares a specific page [field](#fields) to a given [glob pattern](g).
|
||||
|
||||
## Filter fields
|
||||
### Evaluation rules
|
||||
|
||||
Available fields for filtering:
|
||||
The evaluation logic adheres to three rules:
|
||||
|
||||
kind
|
||||
- All conditions within a single filter item must match for that filter to evaluate as true, creating an AND relationship.
|
||||
- If the `includes` or `excludes` array contains multiple filters, only one filter needs to evaluate as true for the entire array to match, creating an OR relationship.
|
||||
- The `excludes` array takes absolute precedence. If a page matches any filter in the `excludes` array, Hugo omits it from the segment regardless of whether it matches the `includes` array.
|
||||
|
||||
### Performance optimization
|
||||
|
||||
Using the `excludes` array to target sites or output formats allows Hugo to skip entire groups of pages during evaluation instead of checking every page. This optimization helps with performance in larger setups.
|
||||
|
||||
For example, excluding unwanted output formats is faster:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[segments]
|
||||
[segments.segment1]
|
||||
[[segments.segment1.excludes]]
|
||||
output = '! json'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
Including only the desired output format is slower:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[segments]
|
||||
[segments.segment1]
|
||||
[[segments.segment1.includes]]
|
||||
output = 'json'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
## Fields
|
||||
|
||||
`kind`
|
||||
: (`string`) A [glob pattern](g) matching the [page kind](g). For example: `{taxonomy,term}`.
|
||||
|
||||
sites
|
||||
`lang`
|
||||
: {{< deprecated-in 0.153.0 />}}
|
||||
: Use [`sites`](#sites) instead.
|
||||
|
||||
`output`
|
||||
: (`string`) A [glob pattern](g) matching the [output format](g) of the page. For example: `{html,json}`.
|
||||
|
||||
`path`
|
||||
: (`string`) A [glob pattern](g) matching the page's [logical path](g). For example: `{/books,/books/**}`.
|
||||
|
||||
`sites`
|
||||
: {{< new-in 0.153.0 />}}
|
||||
: (`map`) A map to define [sites matrix](g).
|
||||
|
||||
output
|
||||
: (`string`) A [glob pattern](g) matching the [output format](g) of the page. For example: `{html,json}`.
|
||||
## Targeting segments
|
||||
|
||||
path
|
||||
: (`string`) A [glob pattern](g) 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:
|
||||
To specify which segments Hugo builds, add the [`renderSegments`][] setting to your project configuration:
|
||||
|
||||
{{< 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/**}'
|
||||
renderSegments = ['segment1','segment2']
|
||||
{{< /code-toggle >}}
|
||||
|
||||
## Rendering segments
|
||||
|
||||
Render specific segments using the [`renderSegments`] configuration or the `--renderSegments` flag:
|
||||
Alternatively, pass the segment names directly to the `--renderSegments` command-line flag during a build:
|
||||
|
||||
```sh
|
||||
hugo build --renderSegments segment1
|
||||
```
|
||||
|
||||
You can configure multiple segments and use a comma-separated list with `--renderSegments` to render them all.
|
||||
You can target multiple segments by providing a comma-separated list:
|
||||
|
||||
```sh
|
||||
hugo build --renderSegments segment1,segment2
|
||||
```
|
||||
|
||||
## Example
|
||||
|
||||
<!--
|
||||
To test the example below:
|
||||
|
||||
git clone --single-branch -b segmentation-test https://github.com/jmooring/hugo-testing segmentation-test
|
||||
cd segmentation-test
|
||||
rm -rf public/ && hugo build --renderSegments segment1 && tree public
|
||||
-->
|
||||
|
||||
Consider a project with this content structure:
|
||||
|
||||
```tree
|
||||
content/
|
||||
├── books/
|
||||
│ ├── _index.en.md
|
||||
│ ├── _index.nb.md
|
||||
│ ├── _index.nn.md
|
||||
│ ├── book-1.en.md
|
||||
│ ├── book-1.nb.md
|
||||
│ └── book-1.nn.md
|
||||
├── films/
|
||||
│ ├── _index.en.md
|
||||
│ ├── _index.nb.md
|
||||
│ ├── _index.nn.md
|
||||
│ ├── film-1.en.md
|
||||
│ ├── film-1.nb.md
|
||||
│ └── film-1.nn.md
|
||||
├── _index.en.md
|
||||
├── _index.nb.md
|
||||
└── _index.nn.md
|
||||
```
|
||||
|
||||
And this project configuration:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
baseURL = 'https://example.org/'
|
||||
title = 'Segmentation'
|
||||
defaultContentLanguage = 'en'
|
||||
defaultContentLanguageInSubdir = true
|
||||
|
||||
[languages.en]
|
||||
direction = 'ltr'
|
||||
label = 'English'
|
||||
locale = 'en-US'
|
||||
weight = 1
|
||||
|
||||
[languages.nb]
|
||||
locale = 'nb-NO'
|
||||
direction = 'ltr'
|
||||
label = 'Bokmål'
|
||||
weight = 2
|
||||
|
||||
[languages.nn]
|
||||
locale = 'nn-NO'
|
||||
direction = 'ltr'
|
||||
label = 'Norsk'
|
||||
weight = 3
|
||||
|
||||
[segments]
|
||||
[segments.segment1]
|
||||
[[segments.segment1.excludes]]
|
||||
[segments.segment1.excludes.sites.matrix]
|
||||
languages = ['n*']
|
||||
[[segments.segment1.excludes]]
|
||||
output = 'rss'
|
||||
[segments.segment1.excludes.sites.matrix]
|
||||
languages = ['en']
|
||||
[[segments.segment1.includes]]
|
||||
kind = '{home,term,taxonomy}'
|
||||
[[segments.segment1.includes]]
|
||||
path = '{/books,/books/**}'
|
||||
|
||||
[taxonomies]
|
||||
tag = 'tags'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
When you run this command:
|
||||
|
||||
```sh
|
||||
hugo build --renderSegments segment1
|
||||
```
|
||||
|
||||
The published project has this structure:
|
||||
|
||||
```tree
|
||||
public/
|
||||
├── en/
|
||||
│ ├── books/
|
||||
│ │ ├── book-1/
|
||||
│ │ │ └── index.html
|
||||
│ │ └── index.html
|
||||
│ ├── tags/
|
||||
│ │ ├── tag-a/
|
||||
│ │ │ └── index.html
|
||||
│ │ ├── tag-b/
|
||||
│ │ │ └── index.html
|
||||
│ │ └── index.html
|
||||
│ └── index.html
|
||||
└── index.html
|
||||
```
|
||||
|
||||
[`renderSegments`]: /configuration/all/#rendersegments
|
||||
|
||||
@@ -6,11 +6,9 @@ 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.
|
||||
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
|
||||
```tree
|
||||
project/
|
||||
└── config/
|
||||
├── _default/
|
||||
@@ -25,31 +23,29 @@ The development server defaults to redirecting to `/404.html` for any requests t
|
||||
|
||||
{{< code-toggle config=server />}}
|
||||
|
||||
force
|
||||
`force`
|
||||
: (`bool`) Whether to force a redirect even if there is existing content in the path.
|
||||
|
||||
from
|
||||
`from`
|
||||
: (`string`) A [glob pattern](g) 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
|
||||
`fromHeaders`
|
||||
: {{< new-in 0.144.0 />}}
|
||||
: (`map[string][string]`) Headers to match for the redirect. This maps the HTTP header name to a [glob pattern](g) with values to match. If the map is empty, the redirect will always be triggered.
|
||||
|
||||
fromRe
|
||||
`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
|
||||
`status`
|
||||
: (`string`) The HTTP status code to use for the redirect. A status code of 200 will trigger a URL rewrite.
|
||||
|
||||
to
|
||||
`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
|
||||
Include headers in every server response to facilitate testing, particularly for features like [Content Security Policies][].
|
||||
|
||||
{{< code-toggle file=config/development/server >}}
|
||||
[[headers]]
|
||||
@@ -75,9 +71,7 @@ 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
|
||||
The `200` status code in this example triggers a URL rewrite, which is typically the desired behavior for [single-page applications][].
|
||||
|
||||
## 404 errors
|
||||
|
||||
@@ -126,3 +120,7 @@ from = '/**'
|
||||
to = '/en/404.html'
|
||||
status = 404
|
||||
{{< /code-toggle >}}
|
||||
|
||||
[Content Security Policies]: https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP
|
||||
[configuration directory]: /configuration/introduction/#configuration-directory
|
||||
[single-page applications]: https://en.wikipedia.org/wiki/Single-page_application
|
||||
|
||||
@@ -12,32 +12,35 @@ This is the default configuration:
|
||||
|
||||
{{< code-toggle config=services />}}
|
||||
|
||||
disqus.shortname
|
||||
: (`string`) The `shortname` used with the Disqus commenting system. See [details](/templates/embedded/#disqus). To access this value from a template:
|
||||
`disqus.shortname`
|
||||
: (`string`) The `shortname` used with the Disqus commenting system. See [details][disqus]. To access this value from a template:
|
||||
|
||||
```go-html-template
|
||||
{{ .Site.Config.Services.Disqus.Shortname }}
|
||||
```
|
||||
|
||||
googleAnalytics.id
|
||||
: (`string`) The Google tag ID for Google Analytics 4 properties. See [details](/templates/embedded/#google-analytics). To access this value from a template:
|
||||
`googleAnalytics.id`
|
||||
: (`string`) The Google tag ID for Google Analytics 4 properties. See [details][google-analytics]. To access this value from a template:
|
||||
|
||||
```go-html-template
|
||||
{{ .Site.Config.Services.GoogleAnalytics.ID }}
|
||||
```
|
||||
|
||||
rss.limit
|
||||
: (`int`) The maximum number of items to include in an RSS feed. Set to `-1` for no limit. Default is `-1`. See [details](/templates/rss/). To access this value from a template:
|
||||
`rss.limit`
|
||||
: (`int`) The maximum number of items to include in an RSS feed. Set to `-1` for no limit. Default is `-1`. See [details][rss]. To access this value from a template:
|
||||
|
||||
```go-html-template
|
||||
{{ .Site.Config.Services.RSS.Limit }}
|
||||
```
|
||||
|
||||
x.disableInlineCSS
|
||||
: (`bool`) Whether to disable the inline CSS rendered by the embedded `x` shortode. See [details](/shortcodes/x/#privacy). Default is `false`. To access this value from a template:
|
||||
`x.disableInlineCSS`
|
||||
: (`bool`) Whether to disable the inline CSS rendered by the embedded `x` shortode. See [details][privacy]. Default is `false`. To access this value from a template:
|
||||
|
||||
```go-html-template
|
||||
{{ .Site.Config.Services.X.DisableInlineCSS }}
|
||||
```
|
||||
|
||||
[v0.141.0]: https://github.com/gohugoio/hugo/releases/tag/v0.141.0
|
||||
[v0.123.0]: https://github.com/gohugoio/hugo/releases/tag/v0.123.0
|
||||
[disqus]: /templates/embedded/#disqus
|
||||
[google-analytics]: /templates/embedded/#google-analytics
|
||||
[privacy]: /shortcodes/x/#privacy
|
||||
[rss]: /templates/rss/
|
||||
|
||||
@@ -10,14 +10,17 @@ These are the default sitemap configuration values. They apply to all pages unle
|
||||
|
||||
{{< code-toggle config=sitemap />}}
|
||||
|
||||
changefreq
|
||||
: (`string`) How frequently a page is likely to change. Valid values are `always`, `hourly`, `daily`, `weekly`, `monthly`, `yearly`, and `never`. With the default value of `""` Hugo will omit this field from the sitemap. See [details](https://www.sitemaps.org/protocol.html#changefreqdef).
|
||||
`changefreq`
|
||||
: (`string`) How frequently a page is likely to change. Valid values are `always`, `hourly`, `daily`, `weekly`, `monthly`, `yearly`, and `never`. With the default value of `""` Hugo will omit this field from the sitemap. See [details][changefreqdef].
|
||||
|
||||
disable
|
||||
`disable`
|
||||
: (`bool`) Whether to disable page inclusion. Default is `false`. Set to `true` in front matter to exclude the page.
|
||||
|
||||
filename
|
||||
`filename`
|
||||
: (`string`) The name of the generated file. Default is `sitemap.xml`.
|
||||
|
||||
priority
|
||||
: (`float`) The priority of a page relative to any other page on the site. Valid values range from 0.0 to 1.0. With the default value of `-1` Hugo will omit this field from the sitemap. See [details](https://www.sitemaps.org/protocol.html#prioritydef).
|
||||
`priority`
|
||||
: (`float`) The priority of a page relative to any other page on the site. Valid values range from 0.0 to 1.0. With the default value of `-1` Hugo will omit this field from the sitemap. See [details][prioritydef].
|
||||
|
||||
[changefreqdef]: https://www.sitemaps.org/protocol.html#changefreqdef
|
||||
[prioritydef]: https://www.sitemaps.org/protocol.html#prioritydef
|
||||
|
||||
@@ -56,14 +56,13 @@ taxonomies:
|
||||
tag: tags
|
||||
{{< /code-toggle >}}
|
||||
|
||||
To disable the taxonomy system, use the [`disableKinds`] setting in the root of your project configuration to disable the `taxonomy` and `term` page [kinds](g).
|
||||
To disable the taxonomy system, use the [`disableKinds`][] setting in the root of your project configuration to disable the `taxonomy` and `term` page [kinds](g).
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
disableKinds = ['taxonomy','term']
|
||||
{{< /code-toggle >}}
|
||||
|
||||
See the [taxonomies][] section for more information.
|
||||
|
||||
[`disableKinds`]: /configuration/all/#disablekinds
|
||||
|
||||
See the [taxonomies] section for more information.
|
||||
|
||||
[taxonomies]: /content-management/taxonomies/
|
||||
|
||||
@@ -16,7 +16,7 @@ This is the default configuration:
|
||||
|
||||
Use the following setting to define how Hugo orders versions.
|
||||
|
||||
weight
|
||||
`weight`
|
||||
: (`int`) The language [weight](g).
|
||||
|
||||
## Sort order
|
||||
|
||||
@@ -34,7 +34,7 @@ draft = true
|
||||
|
||||
You can create an archetype for one or more [content types](g). For example, use one archetype for posts, and use the default archetype for everything else:
|
||||
|
||||
```text
|
||||
```tree
|
||||
archetypes/
|
||||
├── default.md
|
||||
└── posts.md
|
||||
@@ -61,27 +61,25 @@ If none of these exists, Hugo uses a built-in default archetype.
|
||||
|
||||
## Functions and context
|
||||
|
||||
You can use any template [function](g) within an archetype. As shown above, the default archetype uses the [`replace`](/functions/strings/replace) function to replace hyphens with spaces when populating the title in front matter.
|
||||
You can use any template [function](g) within an archetype. As shown above, the default archetype uses the [`strings.Replace`][] function to replace hyphens with spaces when populating the title in front matter.
|
||||
|
||||
Archetypes receive the following [context](g):
|
||||
|
||||
Date
|
||||
`Date`
|
||||
: (`string`) The current date and time, formatted in compliance with RFC3339.
|
||||
|
||||
File
|
||||
: (`hugolib.fileInfo`) Returns file information for the current page. See [details](/methods/page/file).
|
||||
`File`
|
||||
: (`hugolib.fileInfo`) Returns [file information][] for the current page.
|
||||
|
||||
Type
|
||||
`Type`
|
||||
: (`string`) The [content type](g) inferred from the top-level directory name, or as specified by the `--kind` flag passed to the `hugo new content` command.
|
||||
|
||||
Site
|
||||
: (`page.Site`) The current site object. See [details](/methods/site/).
|
||||
`Site`
|
||||
: (`page.Site`) The current `Site` object.
|
||||
|
||||
## Date format
|
||||
|
||||
To insert date and time with a different format, use the [`time.Now`] function:
|
||||
|
||||
[`time.Now`]: /functions/time/now/
|
||||
To insert date and time with a different format, use the [`time.Now`][] function:
|
||||
|
||||
{{< code-toggle file=archetypes/default.md fm=true >}}
|
||||
title = '{{ replace .File.ContentBaseName `-` ` ` | title }}'
|
||||
@@ -95,7 +93,7 @@ Although typically used as a front matter template, you can also use an archetyp
|
||||
|
||||
For example, in a documentation site you might have a section (content type) for functions. Every page within this section should follow the same format: a brief description, the function signature, examples, and notes. We can pre-populate the page to remind content authors of the standard format.
|
||||
|
||||
````text {file="archetypes/functions.md"}
|
||||
````md {file="archetypes/functions.md"}
|
||||
---
|
||||
date: '{{ .Date }}'
|
||||
draft: true
|
||||
@@ -131,7 +129,7 @@ For example, in a photography site you might have a section (content type) for g
|
||||
|
||||
Create an archetype for galleries:
|
||||
|
||||
```text
|
||||
```tree
|
||||
archetypes/
|
||||
├── galleries/
|
||||
│ ├── images/
|
||||
@@ -150,7 +148,7 @@ hugo new galleries/bryce-canyon
|
||||
|
||||
This produces:
|
||||
|
||||
```text
|
||||
```tree
|
||||
content/
|
||||
├── galleries/
|
||||
│ └── bryce-canyon/
|
||||
@@ -166,7 +164,7 @@ Use the `--kind` command line flag to specify an archetype when creating content
|
||||
|
||||
For example, let's say your site has two sections: articles and tutorials. Create an archetype for each content type:
|
||||
|
||||
```text
|
||||
```tree
|
||||
archetypes/
|
||||
├── articles.md
|
||||
├── default.md
|
||||
@@ -184,3 +182,7 @@ To create an article using the tutorials archetype:
|
||||
```sh
|
||||
hugo new content --kind tutorials articles/something.md
|
||||
```
|
||||
|
||||
[`strings.Replace`]: /functions/strings/replace/
|
||||
[`time.Now`]: /functions/time/now/
|
||||
[file information]: /methods/page/file/
|
||||
|
||||
@@ -6,13 +6,7 @@ keywords: []
|
||||
aliases: [/content/build-options/]
|
||||
---
|
||||
|
||||
<!-- TODO
|
||||
We deprecated the `_build` front matter key in favor of `build` in v0.145.0 on 2025-02-26. Remove footnote #1 on or after 2026-05-26 (15 months after deprecation).
|
||||
-->
|
||||
|
||||
Build options are stored in a reserved front matter object named `build`[^1] with these defaults:
|
||||
|
||||
[^1]: The `_build` alias for `build` is deprecated and will be removed in a future release.
|
||||
Build options are stored in a reserved front matter object named `build` with these defaults:
|
||||
|
||||
{{< code-toggle file=content/example/index.md fm=true >}}
|
||||
[build]
|
||||
@@ -21,34 +15,34 @@ publishResources = true
|
||||
render = 'always'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
list
|
||||
`list`
|
||||
: When to include the page within page collections. Specify one of:
|
||||
|
||||
- `always`: Include the page in _all_ page collections. For example, `site.RegularPages`, `.Pages`, etc. This is the default value.
|
||||
- `local`: Include the page in _local_ page collections. For example, `.RegularPages`, `.Pages`, etc. Use this option to create fully navigable but headless content sections.
|
||||
- `never`: Do not include the page in _any_ page collection.
|
||||
|
||||
publishResources
|
||||
: Applicable to [page bundles], determines whether to publish the associated [page resources]. Specify one of:
|
||||
`publishResources`
|
||||
: Applicable to [page bundles][], determines whether to publish the associated [page resources][]. Specify one of:
|
||||
|
||||
- `true`: Always publish resources. This is the default value.
|
||||
- `false`: Only publish a resource when invoking its [`Permalink`], [`RelPermalink`], or [`Publish`] method within a template.
|
||||
- `false`: Only publish a resource when invoking its [`Permalink`][], [`RelPermalink`][], or [`Publish`][] method within a template.
|
||||
|
||||
render
|
||||
`render`
|
||||
: When to render the page. Specify one of:
|
||||
|
||||
- `always`: Always render the page to disk. This is the default value.
|
||||
- `link`: Do not render the page to disk, but assign `Permalink` and `RelPermalink` values.
|
||||
- `never`: Never render the page to disk, and exclude it from all page collections.
|
||||
|
||||
> [!note]
|
||||
> Any page, regardless of its build options, will always be available by using the [`.Page.GetPage`] or [`.Site.GetPage`] method.
|
||||
> [!NOTE]
|
||||
> Any page, regardless of its build options, will always be available by using the [`.Page.GetPage`][] or [`.Site.GetPage`][] method.
|
||||
|
||||
## Example -- headless page
|
||||
|
||||
Create a unpublished page whose content and resources can be included in other pages.
|
||||
|
||||
```text
|
||||
```tree
|
||||
content/
|
||||
├── headless/
|
||||
│ ├── a.jpg
|
||||
@@ -80,7 +74,7 @@ To include the content and images on the home page:
|
||||
|
||||
The published site will have this structure:
|
||||
|
||||
```text
|
||||
```tree
|
||||
public/
|
||||
├── headless/
|
||||
│ ├── a.jpg
|
||||
@@ -91,13 +85,13 @@ public/
|
||||
In the example above, note that:
|
||||
|
||||
1. Hugo did not publish an HTML file for the page.
|
||||
1. Despite setting `publishResources` to `false` in front matter, Hugo published the [page resources] because we invoked the [`RelPermalink`] method on each resource. This is the expected behavior.
|
||||
1. Despite setting `publishResources` to `false` in front matter, Hugo published the [page resources][] because we invoked the [`RelPermalink`][] method on each resource. This is the expected behavior.
|
||||
|
||||
## Example -- headless section
|
||||
|
||||
Create a unpublished section whose content and resources can be included in other pages.
|
||||
|
||||
```text
|
||||
```tree
|
||||
content/
|
||||
├── headless/
|
||||
│ ├── note-1/
|
||||
@@ -140,7 +134,7 @@ To include the content and images on the home page:
|
||||
|
||||
The published site will have this structure:
|
||||
|
||||
```text
|
||||
```tree
|
||||
public/
|
||||
├── headless/
|
||||
│ ├── note-1/
|
||||
@@ -155,13 +149,13 @@ public/
|
||||
In the example above, note that:
|
||||
|
||||
1. Hugo did not publish an HTML file for the page.
|
||||
1. Despite setting `publishResources` to `false` in front matter, Hugo correctly published the [page resources] because we invoked the [`RelPermalink`] method on each resource. This is the expected behavior.
|
||||
1. Despite setting `publishResources` to `false` in front matter, Hugo correctly published the [page resources][] because we invoked the [`RelPermalink`][] method on each resource. This is the expected behavior.
|
||||
|
||||
## Example -- list without publishing
|
||||
|
||||
Publish a section page without publishing the descendant pages. For example, to create a glossary:
|
||||
|
||||
```text
|
||||
```tree
|
||||
content/
|
||||
├── glossary/
|
||||
│ ├── _index.md
|
||||
@@ -197,7 +191,7 @@ To render the glossary:
|
||||
|
||||
The published site will have this structure:
|
||||
|
||||
```text
|
||||
```tree
|
||||
public/
|
||||
├── glossary/
|
||||
│ └── index.html
|
||||
@@ -208,7 +202,7 @@ public/
|
||||
|
||||
Publish a section's descendant pages without publishing the section page itself.
|
||||
|
||||
```text
|
||||
```tree
|
||||
content/
|
||||
├── books/
|
||||
│ ├── _index.md
|
||||
@@ -228,7 +222,7 @@ list = 'never'
|
||||
|
||||
The published site will have this structure:
|
||||
|
||||
```text
|
||||
```tree
|
||||
public/
|
||||
├── books/
|
||||
│ ├── book-1/
|
||||
@@ -244,7 +238,7 @@ Consider this example. A documentation site has a team of contributors with acce
|
||||
|
||||
Instead of external documentation for the shortcodes, include an `internal` section that is hidden when building the production site.
|
||||
|
||||
```text
|
||||
```tree
|
||||
content/
|
||||
├── internal/
|
||||
│ ├── shortcodes/
|
||||
@@ -277,7 +271,7 @@ environment = 'production'
|
||||
|
||||
The production site will have this structure:
|
||||
|
||||
```text
|
||||
```tree
|
||||
public/
|
||||
├── reference/
|
||||
│ ├── reference-1/
|
||||
|
||||
@@ -1,37 +1,37 @@
|
||||
---
|
||||
title: Comments
|
||||
description: Hugo ships with an internal Disqus template, but this isn't the only commenting system that will work with your new Hugo website.
|
||||
description: Hugo ships with an embedded Disqus partial, but this isn't the only commenting system that will work with your new Hugo website.
|
||||
categories: []
|
||||
keywords: []
|
||||
aliases: [/extras/comments/]
|
||||
---
|
||||
|
||||
Hugo ships with support for [Disqus](https://disqus.com/), a third-party service that provides comment and community capabilities to websites via JavaScript.
|
||||
Hugo ships with support for [Disqus][], a third-party service that provides comment and community capabilities to websites via JavaScript.
|
||||
|
||||
Your theme may already support Disqus, but if not, it is easy to add to your templates via [Hugo's built-in Disqus partial][disquspartial].
|
||||
Your theme may already support Disqus, but if not, it is easy to add to your templates via Hugo's [embedded partial][].
|
||||
|
||||
## Add Disqus
|
||||
|
||||
Hugo comes with all the code you need to load Disqus into your templates. Before adding Disqus to your site, you'll need to [set up an account][disqussetup].
|
||||
Hugo comes with all the code you need to load Disqus into your templates. Before adding Disqus to your site, you'll need to [set up an account][].
|
||||
|
||||
### Configure Disqus
|
||||
|
||||
Disqus comments require you set a single value in your [project configuration][configuration]:
|
||||
Disqus comments require you set a single value in your project configuration:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[services.disqus]
|
||||
shortname = 'your-disqus-shortname'
|
||||
{{</ code-toggle >}}
|
||||
|
||||
For many websites, this is enough configuration. However, you also have the option to set the following in the [front matter] of a single content file:
|
||||
For many websites, this is enough configuration. However, you also have the option to set the following in the front matter of a single content file:
|
||||
|
||||
- `disqus_identifier`
|
||||
- `disqus_title`
|
||||
- `disqus_url`
|
||||
- `params.disqus_identifier`
|
||||
- `params.disqus_title`
|
||||
- `params.disqus_url`
|
||||
|
||||
### Render Hugo's built-in Disqus partial template
|
||||
### Render Hugo's embedded Disqus partial
|
||||
|
||||
Disqus has its own [internal template](/templates/embedded/#disqus) available, to render it add the following code where you want comments to appear:
|
||||
To render it, add the following code where you want comments to appear:
|
||||
|
||||
```go-html-template
|
||||
{{ partial "disqus.html" . }}
|
||||
@@ -41,29 +41,46 @@ Disqus has its own [internal template](/templates/embedded/#disqus) available, t
|
||||
|
||||
Commercial commenting systems:
|
||||
|
||||
- [Commentix](https://www.commentix.com/)
|
||||
- [Emote](https://emote.com/)
|
||||
- [Graph Comment](https://graphcomment.com/)
|
||||
- [Hyvor Talk](https://talk.hyvor.com/)
|
||||
- [IntenseDebate](https://intensedebate.com/)
|
||||
- [ReplyBox](https://getreplybox.com/)
|
||||
- [Commentix][]
|
||||
- [Emote][]
|
||||
- [FastComments][]
|
||||
- [Graph Comment][]
|
||||
- [Hyvor Talk][]
|
||||
- [IntenseDebate][]
|
||||
- [ReplyBox][]
|
||||
|
||||
Open-source commenting systems:
|
||||
|
||||
- [Cactus Comments](https://cactus.chat/docs/integrations/hugo/)
|
||||
- [Comentario](https://gitlab.com/comentario/comentario/)
|
||||
- [Comma](https://github.com/Dieterbe/comma/)
|
||||
- [Commento](https://commento.io/)
|
||||
- [Discourse](https://meta.discourse.org/t/embed-discourse-comments-on-another-website-via-javascript/31963)
|
||||
- [Giscus](https://giscus.app/)
|
||||
- [Isso](https://isso-comments.de/)
|
||||
- [Remark42](https://remark42.com/)
|
||||
- [Staticman](https://staticman.net/)
|
||||
- [Talkyard](https://blog-comments.talkyard.io/)
|
||||
- [Utterances](https://utteranc.es/)
|
||||
- [Zoomment](https://zoomment.com/)
|
||||
- [Cactus Comments][]
|
||||
- [Comentario][]
|
||||
- [Comma][]
|
||||
- [Discourse][]
|
||||
- [Giscus][]
|
||||
- [Isso][]
|
||||
- [Remark42][]
|
||||
- [Staticman][]
|
||||
- [Talkyard][]
|
||||
- [Utterances][]
|
||||
- [Zoomment][]
|
||||
|
||||
[configuration]: /configuration/
|
||||
[disquspartial]: /templates/embedded/#disqus
|
||||
[disqussetup]: https://disqus.com/profile/signup/
|
||||
[front matter]: /content-management/front-matter/
|
||||
[Cactus Comments]: https://cactus.chat/docs/integrations/hugo/
|
||||
[Comentario]: https://gitlab.com/comentario/comentario/
|
||||
[Comma]: https://github.com/Dieterbe/comma/
|
||||
[Commentix]: https://www.commentix.com/
|
||||
[Discourse]: https://meta.discourse.org/t/embed-discourse-comments-on-another-website-via-javascript/31963
|
||||
[Disqus]: https://disqus.com/
|
||||
[Emote]: https://emote.com/
|
||||
[FastComments]: https://fastcomments.com/commenting-system-for-hugo
|
||||
[Giscus]: https://giscus.app/
|
||||
[Graph Comment]: https://graphcomment.com/
|
||||
[Hyvor Talk]: https://talk.hyvor.com/
|
||||
[IntenseDebate]: https://intensedebate.com/
|
||||
[Isso]: https://isso-comments.de/
|
||||
[Remark42]: https://remark42.com/
|
||||
[ReplyBox]: https://getreplybox.com/
|
||||
[Staticman]: https://staticman.net/
|
||||
[Talkyard]: https://blog-comments.talkyard.io/
|
||||
[Utterances]: https://utteranc.es/
|
||||
[Zoomment]: https://zoomment.com/
|
||||
[embedded partial]: /templates/embedded/#disqus
|
||||
[set up an account]: https://disqus.com/profile/signup/
|
||||
|
||||
@@ -11,7 +11,7 @@ A content adapter is a template that dynamically creates pages when building a s
|
||||
|
||||
Unlike templates that reside in the `layouts` directory, content adapters reside in the `content` directory, no more than one per directory per language. When a content adapter creates a page, the page's [logical path](g) will be relative to the content adapter.
|
||||
|
||||
```text
|
||||
```tree
|
||||
content/
|
||||
├── articles/
|
||||
│ ├── _index.md
|
||||
@@ -25,114 +25,107 @@ content/
|
||||
└── _index.md
|
||||
```
|
||||
|
||||
Each content adapter is named `_content.gotmpl` and uses the same [syntax] as templates in the `layouts` directory. You can use any of the [template functions] within a content adapter, as well as the methods described below.
|
||||
Each content adapter is named `_content.gotmpl` and uses the same [syntax][] as templates in the `layouts` directory. You can use any of the [template functions][] within a content adapter, as well as the methods described below.
|
||||
|
||||
## Methods
|
||||
|
||||
Use these methods within a content adapter.
|
||||
|
||||
### AddPage
|
||||
`AddPage`
|
||||
: Adds a page to the site.
|
||||
|
||||
Adds a page to the site.
|
||||
|
||||
```go-html-template {file="content/books/_content.gotmpl"}
|
||||
{{ $content := dict
|
||||
"mediaType" "text/markdown"
|
||||
"value" "The _Hunchback of Notre Dame_ was written by Victor Hugo."
|
||||
}}
|
||||
{{ $page := dict
|
||||
"content" $content
|
||||
"kind" "page"
|
||||
"path" "the-hunchback-of-notre-dame"
|
||||
"title" "The Hunchback of Notre Dame"
|
||||
}}
|
||||
{{ .AddPage $page }}
|
||||
```
|
||||
|
||||
### AddResource
|
||||
|
||||
Adds a page resource to the site.
|
||||
|
||||
```go-html-template {file="content/books/_content.gotmpl"}
|
||||
{{ with resources.Get "images/a.jpg" }}
|
||||
```go-html-template {file="content/books/_content.gotmpl"}
|
||||
{{ $content := dict
|
||||
"mediaType" .MediaType.Type
|
||||
"value" .
|
||||
"mediaType" "text/markdown"
|
||||
"value" "The _Hunchback of Notre Dame_ was written by Victor Hugo."
|
||||
}}
|
||||
{{ $resource := dict
|
||||
{{ $page := dict
|
||||
"content" $content
|
||||
"path" "the-hunchback-of-notre-dame/cover.jpg"
|
||||
"kind" "page"
|
||||
"path" "the-hunchback-of-notre-dame"
|
||||
"title" "The Hunchback of Notre Dame"
|
||||
}}
|
||||
{{ $.AddResource $resource }}
|
||||
{{ end }}
|
||||
```
|
||||
{{ .AddPage $page }}
|
||||
```
|
||||
|
||||
Then retrieve the new page resource with something like:
|
||||
`AddResource`
|
||||
: Adds a page resource to the site.
|
||||
|
||||
```go-html-template {file="layouts/page.html"}
|
||||
{{ with .Resources.Get "cover.jpg" }}
|
||||
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
|
||||
{{ end }}
|
||||
```
|
||||
```go-html-template {file="content/books/_content.gotmpl"}
|
||||
{{ with resources.Get "images/a.jpg" }}
|
||||
{{ $content := dict
|
||||
"mediaType" .MediaType.Type
|
||||
"value" .
|
||||
}}
|
||||
{{ $resource := dict
|
||||
"content" $content
|
||||
"path" "the-hunchback-of-notre-dame/cover.jpg"
|
||||
}}
|
||||
{{ $.AddResource $resource }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
### Site
|
||||
Then retrieve the new page resource with something like:
|
||||
|
||||
Returns the `Site` to which the pages will be added.
|
||||
```go-html-template {file="layouts/page.html"}
|
||||
{{ with .Resources.Get "cover.jpg" }}
|
||||
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
```go-html-template {file="content/books/_content.gotmpl"}
|
||||
{{ .Site.Title }}
|
||||
```
|
||||
`Site`
|
||||
: (`Site`) Returns the site to which the pages will be added.
|
||||
|
||||
> [!note]
|
||||
> Note that the `Site` returned isn't fully built when invoked from the content adapters; if you try to call methods that depends on pages, e.g. `.Site.Pages`, you will get an error saying "this method cannot be called before the site is fully initialized".
|
||||
```go-html-template {file="content/books/_content.gotmpl"}
|
||||
{{ .Site.Title }}
|
||||
```
|
||||
|
||||
### Store
|
||||
> [!NOTE]
|
||||
> The `Site` object is not fully initialized while Hugo executes a content adapter.
|
||||
> Methods that depend on built pages, such as `Site.Pages`, are unavailable at this stage and return an error.
|
||||
|
||||
Returns a persistent "scratch pad" to store and manipulate data. The main use case for this is to transfer values between executions when [EnableAllLanguages](#enablealllanguages) is set. See [examples](/methods/page/store/).
|
||||
`Store`
|
||||
: (`maps.Scratch`) Returns a persistent data structure for storing and manipulating keyed values. The main use case for this is to transfer values between executions when [EnableAllLanguages](#enablealllanguages) is set. See [examples][].
|
||||
|
||||
```go-html-template {file="content/books/_content.gotmpl"}
|
||||
{{ .Store.Set "key" "value" }}
|
||||
{{ .Store.Get "key" }}
|
||||
```
|
||||
```go-html-template {file="content/books/_content.gotmpl"}
|
||||
{{ .Store.Set "key" "value" }}
|
||||
{{ .Store.Get "key" }}
|
||||
```
|
||||
|
||||
### EnableAllLanguages
|
||||
`EnableAllLanguages`
|
||||
: By default, Hugo executes the content adapter only once for the first matching site in the [sites matrix](g). Use this method to expand execution to all languages while maintaining the current role and version.
|
||||
|
||||
By default, Hugo executes the content adapter only once for the first matching site in the [sites matrix](g). Use this method to expand execution to all languages while maintaining the current role and version.
|
||||
For more fine-grained control, define a `sites.matrix` in front matter or in a content mount.
|
||||
|
||||
For more fine-grained control, define a `sites.matrix` in front matter or in a content mount.
|
||||
```go-html-template {file="content/books/_content.gotmpl"}
|
||||
{{ .EnableAllLanguages }}
|
||||
{{ $content := dict
|
||||
"mediaType" "text/markdown"
|
||||
"value" "The _Hunchback of Notre Dame_ was written by Victor Hugo."
|
||||
}}
|
||||
{{ $page := dict
|
||||
"content" $content
|
||||
"kind" "page"
|
||||
"path" "the-hunchback-of-notre-dame"
|
||||
"title" "The Hunchback of Notre Dame"
|
||||
}}
|
||||
{{ .AddPage $page }}
|
||||
```
|
||||
|
||||
```go-html-template {file="content/books/_content.gotmpl"}
|
||||
{{ .EnableAllLanguages }}
|
||||
{{ $content := dict
|
||||
"mediaType" "text/markdown"
|
||||
"value" "The _Hunchback of Notre Dame_ was written by Victor Hugo."
|
||||
}}
|
||||
{{ $page := dict
|
||||
"content" $content
|
||||
"kind" "page"
|
||||
"path" "the-hunchback-of-notre-dame"
|
||||
"title" "The Hunchback of Notre Dame"
|
||||
}}
|
||||
{{ .AddPage $page }}
|
||||
```
|
||||
`EnableAllDimensions`
|
||||
: By default, Hugo executes the content adapter only once for the first matching site in the [sites matrix](g). Use this method to expand execution to every possible combination of language, version, and role.
|
||||
|
||||
### EnableAllDimensions
|
||||
|
||||
By default, Hugo executes the content adapter only once for the first matching site in the [sites matrix](g). Use this method to expand execution to every possible combination of language, version, and role.
|
||||
|
||||
For more fine-grained control, define a `sites.matrix` in front matter or in a content mount.
|
||||
|
||||
{{< new-in v0.153.0 />}}
|
||||
For more fine-grained control, define a `sites.matrix` in front matter or in a content mount.
|
||||
|
||||
## Page map
|
||||
|
||||
Set any [front matter field] in the map passed to the [`AddPage`](#addpage) method, excluding `markup`. Instead of setting the `markup` field, specify the `content.mediaType` as described below.
|
||||
Set any [front matter field][] in the map passed to the [`AddPage`](#addpage) method, excluding `markup`. Instead of setting the `markup` field, specify the `content.mediaType` as described below.
|
||||
|
||||
This table describes the fields most commonly passed to the `AddPage` method.
|
||||
|
||||
Key|Description|Required
|
||||
:--|:--|:-:
|
||||
`content.mediaType`|The content [media type]. Default is `text/markdown`. See [content formats] for examples.|
|
||||
`content.mediaType`|The content [media type][]. Default is `text/markdown`. See [content formats][] for examples.|
|
||||
`content.value`|The content value as a string.|
|
||||
`dates.date`|The page creation date as a `time.Time` value.|
|
||||
`dates.expiryDate`|The page expiry date as a `time.Time` value.|
|
||||
@@ -142,7 +135,7 @@ Key|Description|Required
|
||||
`path`|The page's [logical path](g) relative to the content adapter. Do not include a leading slash or file extension.|:heavy_check_mark:
|
||||
`title`|The page title.|
|
||||
|
||||
> [!note]
|
||||
> [!NOTE]
|
||||
> While `path` is the only required field, we recommend setting `title` as well.
|
||||
>
|
||||
> When setting the `path`, Hugo transforms the given string to a logical path. For example, setting `path` to `A B C` produces a logical path of `/section/a-b-c`.
|
||||
@@ -153,14 +146,14 @@ Construct the map passed to the [`AddResource`](#addresource) method using the f
|
||||
|
||||
Key|Description|Required
|
||||
:--|:--|:-:
|
||||
`content.mediaType`|The content [media type].|:heavy_check_mark:
|
||||
`content.mediaType`|The content [media type][].|:heavy_check_mark:
|
||||
`content.value`|The content value as a string or resource.|:heavy_check_mark:
|
||||
`name`|The resource name.|
|
||||
`params`|A map of resource parameters.|
|
||||
`path`|The resources's [logical path](g) relative to the content adapter. Do not include a leading slash.|:heavy_check_mark:
|
||||
`title`|The resource title.|
|
||||
|
||||
> [!note]
|
||||
> [!NOTE]
|
||||
> When `content.value` is a string, Hugo generates a new resource with a publication path relative to the page. However, if `content.value` is already a resource, Hugo directly uses its value and publishes it relative to the site root. This latter method is more efficient.
|
||||
>
|
||||
> When setting the `path`, Hugo transforms the given string to a logical path. For example, setting `path` to `A B C/cover.jpg` produces a logical path of `/section/a-b-c/cover.jpg`.
|
||||
@@ -172,7 +165,7 @@ Create pages from remote data, where each page represents a book review.
|
||||
Step 1
|
||||
: Create the content structure.
|
||||
|
||||
```text
|
||||
```tree
|
||||
content/
|
||||
└── books/
|
||||
├── _content.gotmpl <-- content adapter
|
||||
@@ -294,7 +287,7 @@ weight = 2
|
||||
|
||||
Include a language designator in the content adapter's file name.
|
||||
|
||||
```text
|
||||
```tree
|
||||
content/
|
||||
└── books/
|
||||
├── _content.de.gotmpl
|
||||
@@ -319,7 +312,7 @@ weight = 2
|
||||
|
||||
Create a single content adapter in each directory:
|
||||
|
||||
```text
|
||||
```tree
|
||||
content/
|
||||
├── de/
|
||||
│ └── books/
|
||||
@@ -335,7 +328,7 @@ content/
|
||||
|
||||
Two or more pages collide when they have the same publication path. Due to concurrency, the content of the published page is indeterminate. Consider this example:
|
||||
|
||||
```text
|
||||
```tree
|
||||
content/
|
||||
└── books/
|
||||
├── _content.gotmpl <-- content adapter
|
||||
@@ -348,6 +341,7 @@ If the content adapter also creates `books/the-hunchback-of-notre-dame`, the con
|
||||
To detect page collisions, use the `--printPathWarnings` flag when building your project.
|
||||
|
||||
[content formats]: /content-management/formats/#classification
|
||||
[examples]: /methods/page/store/
|
||||
[front matter field]: /content-management/front-matter/#fields
|
||||
[media type]: https://en.wikipedia.org/wiki/Media_type
|
||||
[syntax]: /templates/introduction/
|
||||
|
||||
@@ -16,40 +16,40 @@ The `data` directory in the root of your project may contain one or more data fi
|
||||
|
||||
Hugo also merges data directories from themes and modules into this single data structure, where the `data` directory in the root of your project takes precedence.
|
||||
|
||||
> [!note]
|
||||
> [!NOTE]
|
||||
> Hugo reads the combined data structure into memory and keeps it there for the entire build. For data that is infrequently accessed, use global or page resources instead.
|
||||
|
||||
Theme and module authors may wish to namespace their data files to prevent collisions. For example:
|
||||
|
||||
```text
|
||||
```tree
|
||||
project/
|
||||
└── data/
|
||||
└── mytheme/
|
||||
└── foo.json
|
||||
```
|
||||
|
||||
> [!note]
|
||||
> [!NOTE]
|
||||
> Do not place CSV files in the `data` directory. Access CSV files as page, global, or remote resources.
|
||||
|
||||
See the documentation for the [`Data`] method on a `Site` object for details and examples.
|
||||
See the documentation for the [`Data`][] method on a `Site` object for details and examples.
|
||||
|
||||
## Global resources
|
||||
|
||||
Use the `resources.Get` and `transform.Unmarshal` functions to access data files that exist as global resources.
|
||||
|
||||
See the [`transform.Unmarshal`](/functions/transform/unmarshal/#global-resource) documentation for details and examples.
|
||||
See the [`transform.Unmarshal`][global-resource] documentation for details and examples.
|
||||
|
||||
## Page resources
|
||||
|
||||
Use the `Resources.Get` method on a `Page` object combined with the `transform.Unmarshal` function to access data files that exist as page resources.
|
||||
|
||||
See the [`transform.Unmarshal`](/functions/transform/unmarshal/#page-resource) documentation for details and examples.
|
||||
See the [`transform.Unmarshal`][page-resource] documentation for details and examples.
|
||||
|
||||
## Remote resources
|
||||
|
||||
Use the `resources.GetRemote` and `transform.Unmarshal` functions to access remote data.
|
||||
|
||||
See the [`transform.Unmarshal`](/functions/transform/unmarshal/#remote-resource) documentation for details and examples.
|
||||
See the [`transform.Unmarshal`][remote-resource] documentation for details and examples.
|
||||
|
||||
## Augment existing content
|
||||
|
||||
@@ -61,7 +61,7 @@ Use data sources to augment existing content. For example, create a shortcode to
|
||||
"Felix","cat","Malicious","7"
|
||||
```
|
||||
|
||||
```text {file="content/example.md"}
|
||||
```md {file="content/example.md"}
|
||||
{{</* csv-to-table "pets.csv" */>}}
|
||||
```
|
||||
|
||||
@@ -105,7 +105,10 @@ Felix|cat|Malicious|7
|
||||
|
||||
## Create new content
|
||||
|
||||
Use [content adapters] to create new content.
|
||||
Use [content adapters][] to create new content.
|
||||
|
||||
[`Data`]: /methods/site/data/
|
||||
[content adapters]: /content-management/content-adapters/
|
||||
[global-resource]: /functions/transform/unmarshal/#global-resource
|
||||
[page-resource]: /functions/transform/unmarshal/#page-resource
|
||||
[remote-resource]: /functions/transform/unmarshal/#remote-resource
|
||||
|
||||
@@ -7,7 +7,7 @@ keywords: []
|
||||
|
||||
## GoAT diagrams (ASCII)
|
||||
|
||||
Hugo natively supports [GoAT] diagrams with an [embedded code block render hook]. This means that this code block:
|
||||
Hugo natively supports [GoAT][] diagrams with an [embedded code block render hook][]. This means that this code block:
|
||||
|
||||
````txt
|
||||
```goat
|
||||
@@ -37,7 +37,7 @@ Will be rendered as:
|
||||
|
||||
## Mermaid diagrams
|
||||
|
||||
Hugo does not provide a built-in template for Mermaid diagrams. Create your own using a [code block render hook]:
|
||||
Hugo does not provide a built-in template for Mermaid diagrams. Create your own using a [code block render hook][]:
|
||||
|
||||
```go-html-template {file="layouts/_markup/render-codeblock-mermaid.html" copy=true}
|
||||
<pre class="mermaid">
|
||||
@@ -59,7 +59,7 @@ Then include this snippet at the _bottom_ of your base template, before the clos
|
||||
|
||||
With that you can use the `mermaid` language in Markdown code blocks:
|
||||
|
||||
````text {copy=true}
|
||||
````md {file="content/example.md" copy=true}
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Alice
|
||||
@@ -255,6 +255,6 @@ Created from <https://arthursonzogni.com/Diagon/#Tree>
|
||||
└────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
[GoAT]: https://github.com/bep/goat
|
||||
[code block render hook]: /render-hooks/code-blocks/
|
||||
[embedded code block render hook]: <{{% eturl render-codeblock-goat %}}>
|
||||
[GoAT]: https://github.com/bep/goat
|
||||
|
||||
@@ -10,7 +10,7 @@ aliases: [/content/markdown-extras/,/content/supported-formats/,/doc/supported-f
|
||||
|
||||
You may mix content formats throughout your site. For example:
|
||||
|
||||
```text
|
||||
```tree
|
||||
content/
|
||||
└── posts/
|
||||
├── post-1.md
|
||||
@@ -21,106 +21,81 @@ content/
|
||||
└── post-6.html
|
||||
```
|
||||
|
||||
Regardless of content format, all content must have [front matter], preferably including both `title` and `date`.
|
||||
Regardless of content format, all content must have [front matter][], preferably including both `title` and `date`.
|
||||
|
||||
Hugo selects the content renderer based on the `markup` identifier in front matter, falling back to the file extension. See the [classification] table below for a list of markup identifiers and recognized file extensions.
|
||||
|
||||
[classification]: #classification
|
||||
[front matter]: /content-management/front-matter/
|
||||
Hugo selects the content renderer based on the `markup` identifier in front matter, falling back to the file extension. See the [classification](#classification) table below for a list of markup identifiers and recognized file extensions.
|
||||
|
||||
## Formats
|
||||
|
||||
### Markdown
|
||||
|
||||
Create your content in [Markdown] preceded by front matter.
|
||||
Create your content in [Markdown][] preceded by front matter.
|
||||
|
||||
Markdown is Hugo's default content format. Hugo natively renders Markdown to HTML using [Goldmark]. Goldmark is fast and conforms to the [CommonMark] and [GitHub Flavored Markdown] specifications. You can configure Goldmark in your [project configuration][configure goldmark].
|
||||
Markdown is Hugo's default content format. Hugo natively renders Markdown to HTML using [Goldmark][]. Goldmark is fast and conforms to the [CommonMark][] and [GitHub Flavored Markdown][] specifications. You can configure Goldmark in your [project configuration][configure goldmark].
|
||||
|
||||
Hugo provides custom Markdown features including:
|
||||
|
||||
[Attributes]
|
||||
[Attributes][]
|
||||
: Apply HTML attributes such as `class` and `id` to Markdown images and block elements including blockquotes, fenced code blocks, headings, horizontal rules, lists, paragraphs, and tables.
|
||||
|
||||
[Extensions]
|
||||
[Extensions][]
|
||||
: Leverage the embedded Markdown extensions to create tables, definition lists, footnotes, task lists, inserted text, mark text, subscripts, superscripts, and more.
|
||||
|
||||
[Mathematics]
|
||||
[Mathematics][]
|
||||
: Include mathematical equations and expressions in Markdown using LaTeX markup.
|
||||
|
||||
[Render hooks]
|
||||
[Render hooks][]
|
||||
: Override the conversion of Markdown to HTML when rendering fenced code blocks, headings, images, and links. For example, render every standalone image as an HTML `figure` element.
|
||||
|
||||
[Attributes]: /content-management/markdown-attributes/
|
||||
[CommonMark]: https://spec.commonmark.org/current/
|
||||
[Extensions]: /configuration/markup/#extensions
|
||||
[GitHub Flavored Markdown]: https://github.github.com/gfm/
|
||||
[Goldmark]: https://github.com/yuin/goldmark
|
||||
[Markdown]: https://daringfireball.net/projects/markdown/
|
||||
[Mathematics]: /content-management/mathematics/
|
||||
[Render hooks]: /render-hooks/introduction/
|
||||
[configure goldmark]: /configuration/markup/#goldmark
|
||||
|
||||
### HTML
|
||||
|
||||
Create your content in [HTML] preceded by front matter. The content is typically what you would place within an HTML document's `body` or `main` element.
|
||||
Create your content in [HTML][] preceded by front matter. The content is typically what you would place within an HTML document's `body` or `main` element.
|
||||
|
||||
[HTML]: https://developer.mozilla.org/en-US/docs/Learn_web_development/Getting_started/Your_first_website/Creating_the_content
|
||||
> [!NOTE]
|
||||
> The HTML content format is denied by default. See [`security.allowContent`][].
|
||||
|
||||
### Emacs Org Mode
|
||||
|
||||
Create your content in the [Emacs Org Mode] format preceded by front matter. You can use Org Mode keywords for front matter. See [details].
|
||||
|
||||
[details]: /content-management/front-matter/#emacs-org-mode
|
||||
[Emacs Org Mode]: https://orgmode.org/
|
||||
Create your content in the [Emacs Org Mode][] format preceded by front matter. You can use Org Mode keywords for front matter. See [details][].
|
||||
|
||||
### AsciiDoc
|
||||
|
||||
Create your content in the [AsciiDoc] format preceded by front matter. Hugo renders AsciiDoc content to HTML using the Asciidoctor executable. You must install Asciidoctor and its dependencies (Ruby) to render the AsciiDoc content format.
|
||||
Create your content in the [AsciiDoc][] format preceded by front matter. Hugo renders AsciiDoc content to HTML using the Asciidoctor executable. You must install Asciidoctor and its dependencies (Ruby) to render the AsciiDoc content format.
|
||||
|
||||
You can configure the AsciiDoc renderer in your [project configuration][configure asciidoc].
|
||||
|
||||
In its default configuration, Hugo passes these CLI flags when calling the Asciidoctor executable:
|
||||
|
||||
```text
|
||||
```sh
|
||||
--no-header-footer
|
||||
```
|
||||
|
||||
The CLI flags passed to the Asciidoctor executable depend on configuration. You may inspect the flags when building your project:
|
||||
|
||||
```text
|
||||
```sh
|
||||
hugo build --logLevel info
|
||||
```
|
||||
|
||||
[AsciiDoc]: https://asciidoc.org/
|
||||
[configure asciidoc]: /configuration/markup/#asciidoc
|
||||
|
||||
### Pandoc
|
||||
|
||||
Create your content in the [Pandoc] format[^1] preceded by front matter. Hugo renders Pandoc content to HTML using the Pandoc executable. You must install Pandoc to render the Pandoc content format.
|
||||
|
||||
[^1]: This is a derivation of the Markdown format as described by the CommonMark specification.
|
||||
Create your content in the [Pandoc][] format preceded by front matter. Hugo renders Pandoc content to HTML using the Pandoc executable. You must install Pandoc to render the Pandoc content format.
|
||||
|
||||
Hugo passes these CLI flags when calling the Pandoc executable:
|
||||
|
||||
```text
|
||||
```sh
|
||||
--mathjax
|
||||
```
|
||||
|
||||
[Pandoc]: https://pandoc.org/MANUAL.html#pandocs-markdown
|
||||
|
||||
### reStructuredText
|
||||
|
||||
Create your content in the [reStructuredText] format preceded by front matter. Hugo renders reStructuredText content to HTML using [Docutils], specifically rst2html. You must install Docutils and its dependencies (Python) to render the reStructuredText content format.
|
||||
Create your content in the [reStructuredText][] format preceded by front matter. Hugo renders reStructuredText content to HTML using [Docutils][], specifically rst2html. You must install Docutils and its dependencies (Python) to render the reStructuredText content format.
|
||||
|
||||
Hugo passes these CLI flags when calling the rst2html executable:
|
||||
|
||||
```text
|
||||
```sh
|
||||
--leave-comments --initial-header-level=2
|
||||
```
|
||||
|
||||
[Docutils]: https://docutils.sourceforge.io/
|
||||
[reStructuredText]: https://docutils.sourceforge.io/rst.html
|
||||
|
||||
## Classification
|
||||
|
||||
{{% include "/_common/content-format-table.md" %}}
|
||||
@@ -131,3 +106,23 @@ When converting content to HTML, Hugo uses:
|
||||
- External renderers for AsciiDoc, Pandoc, and reStructuredText
|
||||
|
||||
Native renderers are faster than external renderers.
|
||||
|
||||
[AsciiDoc]: https://asciidoc.org/
|
||||
[Attributes]: /content-management/markdown-attributes/
|
||||
[CommonMark]: https://spec.commonmark.org/current/
|
||||
[Docutils]: https://docutils.sourceforge.io/
|
||||
[Emacs Org Mode]: https://orgmode.org/
|
||||
[Extensions]: /configuration/markup/#extensions
|
||||
[GitHub Flavored Markdown]: https://github.github.com/gfm/
|
||||
[Goldmark]: https://github.com/yuin/goldmark
|
||||
[HTML]: https://developer.mozilla.org/en-US/docs/Learn_web_development/Getting_started/Your_first_website/Creating_the_content
|
||||
[Markdown]: https://daringfireball.net/projects/markdown/
|
||||
[Mathematics]: /content-management/mathematics/
|
||||
[Pandoc]: https://pandoc.org/MANUAL.html#pandocs-markdown
|
||||
[Render hooks]: /render-hooks/introduction/
|
||||
[`security.allowContent`]: /configuration/security/#allowcontent
|
||||
[configure asciidoc]: /configuration/markup/#asciidoc
|
||||
[configure goldmark]: /configuration/markup/#goldmark
|
||||
[details]: /content-management/front-matter/#emacs-org-mode
|
||||
[front matter]: /content-management/front-matter/
|
||||
[reStructuredText]: https://docutils.sourceforge.io/rst.html
|
||||
|
||||
@@ -35,79 +35,79 @@ Front matter fields may be [boolean](g), [integer](g), [float](g), [string](g),
|
||||
|
||||
The most common front matter fields are `date`, `draft`, `title`, and `weight`, but you can specify metadata using any of fields below.
|
||||
|
||||
> [!note]
|
||||
> [!NOTE]
|
||||
> The field names below are reserved. For example, you cannot create a custom field named `type`. Create custom fields under the `params` key. See the [parameters](#parameters) section for details.
|
||||
|
||||
aliases
|
||||
`aliases`
|
||||
: (`[]string`) An array of one or more [page-relative](g) or [site-relative](g) paths that should redirect to the current page. Hugo resolves these to [server-relative](g) URLs during the build process. Access these values from a template using the [`Aliases`][] method on a `Page` object. See the [aliases][] section for details.
|
||||
|
||||
build
|
||||
`build`
|
||||
: (`map`) A map of [build options][].
|
||||
|
||||
cascade
|
||||
: (`map`) A map (or array of maps) of front matter keys whose values are passed down to the page's descendants unless overwritten by self or a closer ancestor's cascade. See the [cascade][] section for details.
|
||||
`cascade`
|
||||
: (`map`) A map (or array of maps) of front matter keys whose values are passed down to the page's descendants unless overwritten by self or a closer ancestor's cascade. See the [cascade](#cascade-1) section for details.
|
||||
|
||||
date
|
||||
`date`
|
||||
: (`string`) The date associated with the page, typically the creation date. Note that the TOML format also supports unquoted date/time values. See the [dates](#dates) section for examples. Access this value from a template using the [`Date`][] method on a `Page` object.
|
||||
|
||||
description
|
||||
`description`
|
||||
: (`string`) Conceptually different than the page `summary`, the description is typically rendered within a `meta` element within the `head` element of the published HTML file. Access this value from a template using the [`Description`][] method on a `Page` object.
|
||||
|
||||
draft
|
||||
`draft`
|
||||
: (`bool`) Whether to disable rendering unless you pass the `--buildDrafts` flag to the `hugo` command. Access this value from a template using the [`Draft`][] method on a `Page` object.
|
||||
|
||||
expiryDate
|
||||
`expiryDate`
|
||||
: (`string`) The page expiration date. On or after the expiration date, the page will not be rendered unless you pass the `--buildExpired` flag to the `hugo` command. Note that the TOML format also supports unquoted date/time values. See the [dates](#dates) section for examples. Access this value from a template using the [`ExpiryDate`][] method on a `Page` object.
|
||||
|
||||
headless
|
||||
`headless`
|
||||
: (`bool`) Applicable to [leaf bundles][], whether to set the `render` and `list` [build options][] to `never`, creating a headless bundle of [page resources][].
|
||||
|
||||
isCJKLanguage
|
||||
`isCJKLanguage`
|
||||
: (`bool`) Whether the content language is in the [CJK](g) family. This value determines how Hugo calculates word count, and affects the values returned by the [`WordCount`][], [`FuzzyWordCount`][], [`ReadingTime`][], and [`Summary`][] methods on a `Page` object.
|
||||
|
||||
keywords
|
||||
`keywords`
|
||||
: (`[]string`) An array of keywords, typically rendered within a `meta` element within the `head` element of the published HTML file, or used as a [taxonomy](g) to classify content. Access these values from a template using the [`Keywords`][] method on a `Page` object.
|
||||
|
||||
lastmod
|
||||
`lastmod`
|
||||
: (`string`) The date that the page was last modified. Note that the TOML format also supports unquoted date/time values. See the [dates](#dates) section for examples. Access this value from a template using the [`Lastmod`][] method on a `Page` object.
|
||||
|
||||
layout
|
||||
`layout`
|
||||
: (`string`) Provide a template name to [target a specific template][], overriding the default [template lookup order][]. Set the value to the base file name of the template, excluding its extension. Access this value from a template using the [`Layout`][] method on a `Page` object.
|
||||
|
||||
linkTitle
|
||||
`linkTitle`
|
||||
: (`string`) Typically a shorter version of the `title`. Access this value from a template using the [`LinkTitle`][] method on a `Page` object.
|
||||
|
||||
markup
|
||||
`markup`
|
||||
: (`string`) An identifier corresponding to one of the supported [content formats][]. If not provided, Hugo determines the content renderer based on the file extension.
|
||||
|
||||
menus
|
||||
`menus`
|
||||
: (`string`, `[]string`, or `map`) If set, Hugo adds the page to the given menu or menus. See the [menus][] page for details.
|
||||
|
||||
modified
|
||||
`modified`
|
||||
: Alias to [lastmod](#lastmod).
|
||||
|
||||
outputs
|
||||
`outputs`
|
||||
: (`[]string`) The [output formats][] to render. See [configure outputs][] for more information.
|
||||
|
||||
params
|
||||
: (`map`) A map of custom [page parameters][].
|
||||
`params`
|
||||
: (`map`) A map of custom [page parameters](#parameters).
|
||||
|
||||
pubdate
|
||||
`pubdate`
|
||||
: Alias to [publishDate](#publishdate).
|
||||
|
||||
publishDate
|
||||
`publishDate`
|
||||
: (`string`) The page publication date. Before the publication date, the page will not be rendered unless you pass the `--buildFuture` flag to the `hugo` command. Note that the TOML format also supports unquoted date/time values. See the [dates](#dates) section for examples. Access this value from a template using the [`PublishDate`][] method on a `Page` object.
|
||||
|
||||
published
|
||||
`published`
|
||||
: Alias to [publishDate](#publishdate).
|
||||
|
||||
resources
|
||||
: (`map array`) An array of maps to provide metadata for [page resources]. Each element supports the `src`, `name`, `title`, and `params` keys.
|
||||
`resources`
|
||||
: (`map array`) An array of maps to provide metadata for [page resources][]. Each element supports the `src`, `name`, `title`, and `params` keys.
|
||||
|
||||
sitemap
|
||||
`sitemap`
|
||||
: (`map`) A map of sitemap options. See the [sitemap templates][] page for details. Access these values from a template using the [`Sitemap`][] method on a `Page` object.
|
||||
|
||||
sites
|
||||
`sites`
|
||||
: {{< new-in 0.153.0 />}}
|
||||
: (`map`) A map to define [sites matrix](g) and [sites complements](g) for the page.
|
||||
|
||||
@@ -125,28 +125,28 @@ sites
|
||||
|
||||
<!-- markdownlint-enable MD049 -->
|
||||
|
||||
slug
|
||||
`slug`
|
||||
: (`string`) Overrides the last segment of the URL path. Not applicable to `home`, `section`, `taxonomy`, or `term` pages. See the [URL management][] page for details. Access this value from a template using the [`Slug`][] method on a `Page` object.
|
||||
|
||||
summary
|
||||
`summary`
|
||||
: (`string`) Conceptually different than the page `description`, the summary either summarizes the content or serves as a teaser to encourage readers to visit the page. Access this value from a template using the [`Summary`][] method on a `Page` object.
|
||||
|
||||
title
|
||||
`title`
|
||||
: (`string`) The page title. Access this value from a template using the [`Title`][] method on a `Page` object.
|
||||
|
||||
translationKey
|
||||
`translationKey`
|
||||
: (`string`) An arbitrary value used to relate two or more translations of the same page, useful when the translated pages do not share a common path. Access this value from a template using the [`TranslationKey`][] method on a `Page` object.
|
||||
|
||||
type
|
||||
`type`
|
||||
: (`string`) The [content type](g), overriding the value derived from the top-level section in which the page resides. Access this value from a template using the [`Type`][] method on a `Page` object.
|
||||
|
||||
unpublishdate
|
||||
`unpublishdate`
|
||||
: Alias to [expirydate](#expirydate).
|
||||
|
||||
url
|
||||
`url`
|
||||
: (`string`) Overrides the entire URL path. Applicable to regular pages and section pages. See the [URL management][] page for details.
|
||||
|
||||
weight
|
||||
`weight`
|
||||
: (`int`) The page [weight](g), used to order the page within a [page collection](g). Access this value from a template using the [`Weight`][] method on a `Page` object.
|
||||
|
||||
## Parameters
|
||||
@@ -164,16 +164,6 @@ author = 'John Smith'
|
||||
|
||||
Access these values from a template using the [`Params`][] or [`Param`][] method on a `Page` object.
|
||||
|
||||
Hugo provides [embedded templates][] to optionally insert meta data within the `head` element of your rendered pages. These embedded templates expect the following front matter parameters:
|
||||
|
||||
Parameter|Data type|Used by these embedded templates
|
||||
:--|:--|:--
|
||||
`audio`|`[]string`|[`opengraph.html`][]
|
||||
`images`|`[]string`|[`opengraph.html`][], [`schema.html`][], [`twitter_cards.html`][]
|
||||
`videos`|`[]string`|[`opengraph.html`][]
|
||||
|
||||
The embedded templates will skip a parameter if not provided in front matter, but will throw an error if the data type is unexpected.
|
||||
|
||||
## Taxonomies
|
||||
|
||||
Classify content by adding taxonomy terms to front matter. For example, with this project configuration:
|
||||
@@ -220,10 +210,10 @@ Access taxonomy terms from a template using the [`Params`][] or [`GetTerms`][] m
|
||||
|
||||
## Cascade
|
||||
|
||||
> [!note]
|
||||
> For multilingual projects, defining cascade values in your project configuration is often more efficient. This avoids repeating the same cascade values for each language. See [details](/configuration/cascade/).
|
||||
> [!NOTE]
|
||||
> For multilingual projects, defining cascade values in your project configuration is often more efficient. This avoids repeating the same cascade values for each language. See [details][].
|
||||
|
||||
A [node](g) can cascade front matter values to its descendants. However, this cascading will be prevented if the descendant already defines the field, or if a closer ancestor node has already cascaded a value for that same field.
|
||||
A [branch](g) can cascade front matter values to its descendants. However, this cascading will be prevented if the descendant already defines the field, or if a closer ancestor branch has already cascaded a value for that same field.
|
||||
|
||||
For example, to cascade the `color` page parameter from the home page to all its descendants:
|
||||
|
||||
@@ -236,7 +226,8 @@ color = 'red'
|
||||
### Target
|
||||
|
||||
<!-- TODO
|
||||
We deprecated the `_target` front matter key in favor of `target` in v0.156.0 on 2026-02-17. Remove footnote #1 on or after 2027-05-17 (15 months after deprecation).
|
||||
We deprecated the `_target` front matter key in favor of `target` in v0.156.0 on 2026-02-17. Remove footnote #1 somewhere after v0.171.0, 15 minor releases
|
||||
after deprecation.
|
||||
-->
|
||||
|
||||
The `target` key accepts a [page matcher](g) to limit cascaded values to a subset of pages.[^1] If a target is not specified, values cascade to all descendant pages.
|
||||
@@ -298,7 +289,7 @@ When populating a date field, whether a [custom page parameter](#parameters) or
|
||||
|
||||
{{% include "/_common/parsable-date-time-strings.md" %}}
|
||||
|
||||
To override the default time zone, set the [`timeZone`](/configuration/all/#timezone) in your project configuration. The order of precedence for determining the time zone is:
|
||||
To override the default time zone, set the [`timeZone`][] in your project configuration. The order of precedence for determining the time zone is:
|
||||
|
||||
1. The time zone offset in the date/time string
|
||||
1. The time zone specified in your project configuration
|
||||
@@ -306,49 +297,45 @@ To override the default time zone, set the [`timeZone`](/configuration/all/#time
|
||||
|
||||
[^1]: The `_target` alias for `target` is deprecated and will be removed in a future release.
|
||||
|
||||
[Emacs Org Mode]: https://orgmode.org/
|
||||
[JSON]: https://www.json.org/
|
||||
[TOML]: https://toml.io/
|
||||
[URL management]: /content-management/urls/#slug
|
||||
[YAML]: https://yaml.org/
|
||||
[`Aliases`]: /methods/page/aliases/
|
||||
[`Date`]: /methods/page/date/
|
||||
[`Description`]: /methods/page/description/
|
||||
[`Draft`]: /methods/page/draft/
|
||||
[`ExpiryDate`]: /methods/page/expirydate/
|
||||
[`FuzzyWordCount`]: /methods/page/wordcount/
|
||||
[`GetTerms`]: /methods/page/getterms/
|
||||
[`Keywords`]: /methods/page/keywords/
|
||||
[`Lastmod`]: /methods/page/date/
|
||||
[`Layout`]: /methods/page/layout/
|
||||
[`LinkTitle`]: /methods/page/linktitle/
|
||||
[`Param`]: /methods/page/param/
|
||||
[`Params`]: /methods/page/params/
|
||||
[`PublishDate`]: /methods/page/publishdate/
|
||||
[`ReadingTime`]: /methods/page/readingtime/
|
||||
[`Sitemap`]: /methods/page/sitemap/
|
||||
[`Slug`]: /methods/page/slug/
|
||||
[`Summary`]: /methods/page/summary/
|
||||
[`aliases`]: /methods/page/aliases/
|
||||
[`date`]: /methods/page/date/
|
||||
[`description`]: /methods/page/description/
|
||||
[`draft`]: /methods/page/draft/
|
||||
[`expirydate`]: /methods/page/expirydate/
|
||||
[`fuzzywordcount`]: /methods/page/wordcount/
|
||||
[`keywords`]: /methods/page/keywords/
|
||||
[`lastmod`]: /methods/page/date/
|
||||
[`layout`]: /methods/page/layout/
|
||||
[`linktitle`]: /methods/page/linktitle/
|
||||
[`opengraph.html`]: <{{% eturl opengraph %}}>
|
||||
[`publishdate`]: /methods/page/publishdate/
|
||||
[`readingtime`]: /methods/page/readingtime/
|
||||
[`schema.html`]: <{{% eturl schema %}}>
|
||||
[`sitemap`]: /methods/page/sitemap/
|
||||
[`slug`]: /methods/page/slug/
|
||||
[`title`]: /methods/page/title/
|
||||
[`translationkey`]: /methods/page/translationkey/
|
||||
[`twitter_cards.html`]: <{{% eturl twitter_cards %}}>
|
||||
[`type`]: /methods/page/type/
|
||||
[`weight`]: /methods/page/weight/
|
||||
[`wordcount`]: /methods/page/wordcount/
|
||||
[`Title`]: /methods/page/title/
|
||||
[`TranslationKey`]: /methods/page/translationkey/
|
||||
[`Type`]: /methods/page/type/
|
||||
[`Weight`]: /methods/page/weight/
|
||||
[`WordCount`]: /methods/page/wordcount/
|
||||
[`timeZone`]: /configuration/all/#timezone
|
||||
[aliases]: /content-management/urls/#aliases
|
||||
[build options]: /content-management/build-options/
|
||||
[cascade]: #cascade-1
|
||||
[configure outputs]: /configuration/outputs/#outputs-per-page
|
||||
[content format]: /content-management/formats/
|
||||
[content formats]: /content-management/formats/#classification
|
||||
[emacs org mode]: https://orgmode.org/
|
||||
[embedded templates]: /templates/embedded/
|
||||
[json]: https://www.json.org/
|
||||
[details]: /configuration/cascade/
|
||||
[leaf bundles]: /content-management/page-bundles/#leaf-bundles
|
||||
[menus]: /content-management/menus/#define-in-front-matter
|
||||
[output formats]: /configuration/output-formats/
|
||||
[page parameters]: #parameters
|
||||
[page resources]: /content-management/page-resources/#metadata
|
||||
[sitemap templates]: /templates/sitemap/
|
||||
[target a specific template]: /templates/lookup-order/#target-a-template
|
||||
[template lookup order]: /templates/lookup-order/
|
||||
[toml]: https://toml.io/
|
||||
[yaml]: https://yaml.org/
|
||||
|
||||
@@ -7,7 +7,7 @@ keywords: []
|
||||
|
||||
Hugo provides methods to transform and analyze images during the build process. While Hugo can manage any image format as a resource, only [processable images](g) can be transformed using the methods below. The results are cached to ensure subsequent builds remain fast.
|
||||
|
||||
> [!note]
|
||||
> [!NOTE]
|
||||
> Use the [`reflect.IsImageResourceProcessable`][] function to verify that an image can be processed.
|
||||
|
||||
## Resources
|
||||
@@ -18,7 +18,7 @@ To process an image you must capture the file as a page resource, a global resou
|
||||
|
||||
{{% glossary-term "page resource" %}}
|
||||
|
||||
```text
|
||||
```tree
|
||||
content/
|
||||
└── posts/
|
||||
└── post-1/ <-- page bundle
|
||||
@@ -36,7 +36,7 @@ To capture an image as a page resource:
|
||||
|
||||
{{% glossary-term "global resource" %}}
|
||||
|
||||
```text
|
||||
```tree
|
||||
assets/
|
||||
└── images/
|
||||
└── sunset.jpg <-- global resource
|
||||
@@ -115,7 +115,7 @@ To transform an image, apply a processing method to the image resource. Hugo gen
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
> [!note]
|
||||
> [!NOTE]
|
||||
> Metadata is not preserved during image transformation. Use the [`Meta`][] method with the original image resource to extract metadata from supported formats.
|
||||
|
||||
Select a method from the table below for syntax and usage examples, depending on your specific transformation or metadata requirements:
|
||||
@@ -146,7 +146,7 @@ If you host your site with Netlify, include the following in your project config
|
||||
|
||||
If you change image processing methods, or rename/remove images, the cache will eventually contain unused files. To remove them and reclaim disk space, run Hugo's garbage collection:
|
||||
|
||||
```text
|
||||
```sh
|
||||
hugo build --gc
|
||||
```
|
||||
|
||||
@@ -158,7 +158,7 @@ If your source images are much larger than the maximum size you intend to publis
|
||||
|
||||
## Configuration
|
||||
|
||||
See [configure imaging](/configuration/imaging).
|
||||
See [configure imaging][].
|
||||
|
||||
[`Height`]: /methods/resource/height/
|
||||
[`Meta`]: /methods/resource/meta/
|
||||
@@ -166,4 +166,5 @@ See [configure imaging](/configuration/imaging).
|
||||
[`RelPermalink`]: /methods/resource/relpermalink/
|
||||
[`Width`]: /methods/resource/width/
|
||||
[`reflect.IsImageResourceProcessable`]: /functions/reflect/isimageresourceprocessable/
|
||||
[configure imaging]: /configuration/imaging/
|
||||
[file cache]: /configuration/caches/
|
||||
|
||||
@@ -11,14 +11,14 @@ Hugo supports Markdown attributes on images and block elements including blockqu
|
||||
|
||||
For example:
|
||||
|
||||
```text
|
||||
```md
|
||||
This is a paragraph.
|
||||
{class="foo bar" id="baz"}
|
||||
```
|
||||
|
||||
With `class` and `id` attributes you can also use short-form notation:
|
||||
|
||||
```text
|
||||
```md
|
||||
This is a paragraph.
|
||||
{.foo .bar #baz}
|
||||
```
|
||||
@@ -48,7 +48,7 @@ block = true # default is false
|
||||
|
||||
## Standalone images
|
||||
|
||||
By default, when the [Goldmark][] Markdown renderer encounters a standalone image element (no other elements or text on the same line), it wraps the image element within a paragraph element per the [CommonMark specification][].
|
||||
By default, when the [Goldmark][] Markdown renderer encounters a standalone image element (no other elements or text on the same line), it wraps the image element within a paragraph element per the [CommonMark][] specification.
|
||||
|
||||
If you were to place an attribute list beneath an image element, Hugo would apply the attributes to the surrounding paragraph, not the image.
|
||||
|
||||
@@ -63,14 +63,14 @@ wrapStandAloneImageWithinParagraph = false # default is true
|
||||
|
||||
You may add [global HTML attributes][], or HTML attributes specific to the current element type. Consistent with its content security model, Hugo removes HTML event attributes such as `onclick` and `onmouseover`.
|
||||
|
||||
> [!note]
|
||||
> [!NOTE]
|
||||
> Within fenced code blocks, Hugo interprets the `style` attribute as a syntax highlighting [option][option] rather than a global HTML attribute.
|
||||
|
||||
The attribute list consists of one or more key-value pairs, separated by spaces or commas, wrapped by braces. You must quote string values that contain spaces. Unlike HTML, boolean attributes must have both key and value.
|
||||
|
||||
For example:
|
||||
|
||||
```text
|
||||
```md
|
||||
> This is a blockquote.
|
||||
{class="foo bar" hidden=hidden}
|
||||
```
|
||||
@@ -85,20 +85,20 @@ Hugo renders this to:
|
||||
|
||||
In most cases, place the attribute list beneath the markup element. For headings and fenced code blocks, place the attribute list on the right.
|
||||
|
||||
Element|Position of attribute list
|
||||
:--|:--
|
||||
blockquote|bottom
|
||||
fenced code block|right
|
||||
heading|right
|
||||
horizontal rule|bottom
|
||||
image|bottom
|
||||
list|bottom
|
||||
paragraph|bottom
|
||||
table|bottom
|
||||
Element | Position of attribute list
|
||||
:-----------------|:--------------------------
|
||||
blockquote | bottom
|
||||
fenced code block | right
|
||||
heading | right
|
||||
horizontal rule | bottom
|
||||
image | bottom
|
||||
list | bottom
|
||||
paragraph | bottom
|
||||
table | bottom
|
||||
|
||||
For example:
|
||||
|
||||
````text
|
||||
````md
|
||||
## Section 1 {class=foo}
|
||||
|
||||
```sh {class=foo linenos=inline}
|
||||
@@ -112,8 +112,8 @@ This is a paragraph.
|
||||
|
||||
As shown above, the attribute list for fenced code blocks is not limited to HTML attributes. You can also configure syntax highlighting by passing one or more of [these options][option].
|
||||
|
||||
[CommonMark specification]: https://spec.commonmark.org/current/
|
||||
[global HTML attributes]: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes
|
||||
[CommonMark]: https://spec.commonmark.org/current/
|
||||
[Goldmark]: https://github.com/yuin/goldmark
|
||||
[render hook templates]: /render-hooks/introduction/
|
||||
[global HTML attributes]: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes
|
||||
[option]: /functions/transform/highlight/#options
|
||||
[render hook templates]: /render-hooks/introduction/
|
||||
|
||||
@@ -12,7 +12,7 @@ Mathematical equations and expressions written in [LaTeX][] are common in academ
|
||||
|
||||
For example, this LaTeX markup:
|
||||
|
||||
```text
|
||||
```md
|
||||
\[
|
||||
\begin{aligned}
|
||||
KL(\hat{y} || y) &= \sum_{c=1}^{M}\hat{y}_c \log{\frac{\hat{y}_c}{y_c}} \\
|
||||
@@ -34,7 +34,7 @@ Equations and expressions can be displayed inline with other text, or as standal
|
||||
|
||||
Whether an equation or expression appears inline, or as a block, depends on the delimiters that surround the mathematical markup. Delimiters are defined in pairs, where each pair consists of an opening and closing delimiter. The opening and closing delimiters may be the same, or different.
|
||||
|
||||
> [!note]
|
||||
> [!NOTE]
|
||||
> You can configure Hugo to render mathematical markup on the client side using the MathJax or KaTeX display engine, or you can render the markup with the [`transform.ToMath`][] function while building your project.
|
||||
>
|
||||
> The first approach is described below.
|
||||
@@ -58,12 +58,12 @@ Step 1
|
||||
math = true
|
||||
{{< /code-toggle >}}
|
||||
|
||||
The configuration above enables mathematical rendering on every page unless you set the `math` parameter to `false` in front matter. To enable mathematical rendering as needed, set the `math` parameter to `false` in your project configuration, and set the `math` parameter to `true` in front matter. Use this parameter in your base template as shown in [Step 3][].
|
||||
The configuration above enables mathematical rendering on every page unless you set the `math` parameter to `false` in front matter. To enable mathematical rendering as needed, set the `math` parameter to `false` in your project configuration, and set the `math` parameter to `true` in front matter. Use this parameter in your base template as shown in [Step 3](#step-3).
|
||||
|
||||
> [!note]
|
||||
> [!NOTE]
|
||||
> The configuration above precludes the use of the `$...$` delimiter pair for inline equations. Although you can add this delimiter pair to the configuration and JavaScript, you must double-escape the `$` symbol when used outside of math contexts to avoid unintended formatting.
|
||||
>
|
||||
> See the [inline delimiters][] section for details.
|
||||
> See the [inline delimiters](#inline-delimiters) section for details.
|
||||
|
||||
To disable passthrough of inline snippets, omit the `inline` key from the configuration:
|
||||
|
||||
@@ -72,7 +72,7 @@ Step 1
|
||||
block = [['\[', '\]'], ['$$', '$$']]
|
||||
{{< /code-toggle >}}
|
||||
|
||||
You can define your own opening and closing delimiters, provided they match the delimiters that you set in [Step 2][].
|
||||
You can define your own opening and closing delimiters, provided they match the delimiters that you set in [Step 2](#step-2).
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[markup.goldmark.extensions.passthrough.delimiters]
|
||||
@@ -81,7 +81,7 @@ Step 1
|
||||
{{< /code-toggle >}}
|
||||
|
||||
Step 2
|
||||
: Create a _partial_ template to load MathJax or KaTeX. The example below loads MathJax, or you can use KaTeX as described in the [engines][] section.
|
||||
: Create a _partial_ template to load MathJax or KaTeX. The example below loads MathJax, or you can use KaTeX as described in the [engines](#engines) section.
|
||||
|
||||
```go-html-template {file="layouts/_partials/math.html" copy=true}
|
||||
<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@4/tex-mml-chtml.js"></script>
|
||||
@@ -129,7 +129,7 @@ Step 4
|
||||
Step 5
|
||||
: Include mathematical equations and expressions in Markdown using LaTeX markup.
|
||||
|
||||
```text {file="content/math-examples.md" copy=true}
|
||||
```md {file="content/math-examples.md" copy=true}
|
||||
This is an inline \(a^*=x-b^*\) equation.
|
||||
|
||||
These are block equations:
|
||||
@@ -159,44 +159,33 @@ The configuration, JavaScript, and examples above use the `\(...\)` delimiter pa
|
||||
|
||||
If you add the `$...$` delimiter pair to your configuration and JavaScript, you must double-escape the `$` symbol when used outside of math contexts to avoid unintended formatting. For example:
|
||||
|
||||
```text
|
||||
```md
|
||||
I will give you \\$2 if you can solve $y = x^2$.
|
||||
```
|
||||
|
||||
> [!note]
|
||||
> [!NOTE]
|
||||
> If you use the `$...$` delimiter pair for inline equations, and occasionally use the `$` symbol outside of math contexts, you must use MathJax instead of KaTeX to avoid unintended formatting caused by [this KaTeX limitation][].
|
||||
|
||||
## Engines
|
||||
|
||||
MathJax and KaTeX are open-source JavaScript display engines.
|
||||
|
||||
> [!note]
|
||||
> [!NOTE]
|
||||
> If you use the `$...$` delimiter pair for inline equations, and occasionally use the `$` symbol outside of math contexts, you must use MathJax instead of KaTeX to avoid unintended formatting caused by [this KaTeX limitation][].
|
||||
>
|
||||
>See the [inline delimiters][] section for details.
|
||||
>See the [inline delimiters](#inline-delimiters) section for details.
|
||||
|
||||
To use KaTeX instead of MathJax, replace the _partial_ template from [Step 2][] with this:
|
||||
To use KaTeX instead of MathJax, replace the _partial_ template from [Step 2](#step-2) with this:
|
||||
|
||||
```go-html-template {file="layouts/_partials/math.html" copy=true}
|
||||
<link
|
||||
rel="stylesheet"
|
||||
href="https://cdn.jsdelivr.net/npm/katex@0.16.25/dist/katex.min.css"
|
||||
integrity="sha384-WcoG4HRXMzYzfCgiyfrySxx90XSl2rxY5mnVY5TwtWE6KLrArNKn0T/mOgNL0Mmi"
|
||||
crossorigin="anonymous"
|
||||
>
|
||||
<script
|
||||
defer
|
||||
src="https://cdn.jsdelivr.net/npm/katex@0.16.25/dist/katex.min.js"
|
||||
integrity="sha384-J+9dG2KMoiR9hqcFao0IBLwxt6zpcyN68IgwzsCSkbreXUjmNVRhPFTssqdSGjwQ"
|
||||
crossorigin="anonymous">
|
||||
</script>
|
||||
<script
|
||||
defer
|
||||
src="https://cdn.jsdelivr.net/npm/katex@0.16.25/dist/contrib/auto-render.min.js"
|
||||
integrity="sha384-hCXGrW6PitJEwbkoStFjeJxv+fSOOQKOPbJxSfM6G5sWZjAyWhXiTIIAmQqnlLlh"
|
||||
crossorigin="anonymous"
|
||||
onload="renderMathInElement(document.body);">
|
||||
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.17.0/dist/katex.min.css" integrity="sha384-vlBdW0r3AcZO/HboRPznQNowvexd3fY8qHOWkBi5q7KGgqJ+F48+DceybYmrVbmB" crossorigin="anonymous">
|
||||
|
||||
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.17.0/dist/katex.min.js" integrity="sha384-AtrdNsnxl/75rvBneBVH7DtOvCxSVahR2zWqle1coBKd8DEmLoviqNeJSx64gNAs" crossorigin="anonymous"></script>
|
||||
|
||||
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.17.0/dist/contrib/auto-render.min.js" integrity="sha384-bjyGPfbij8/NDKJhSGZNP/khQVgtHUE5exjm4Ydllo42FwIgYsdLO2lXGmRBf5Mz" crossorigin="anonymous"
|
||||
onload="renderMathInElement(document.body);">
|
||||
</script>
|
||||
|
||||
<script>
|
||||
document.addEventListener("DOMContentLoaded", function() {
|
||||
renderMathInElement(document.body, {
|
||||
@@ -217,21 +206,18 @@ The delimiters above must match the delimiters in your project configuration.
|
||||
|
||||
Both MathJax and KaTeX provide support for chemical equations. For example:
|
||||
|
||||
```text
|
||||
```md
|
||||
$$C_p[\ce{H2O(l)}] = \pu{75.3 J // mol K}$$
|
||||
```
|
||||
|
||||
$$C_p[\ce{H2O(l)}] = \pu{75.3 J // mol K}$$
|
||||
|
||||
As shown in [Step 2][] above, MathJax supports chemical equations without additional configuration. To add chemistry support to KaTeX, enable the mhchem extension as described in the KaTeX [documentation](https://katex.org/docs/libs).
|
||||
As shown in [Step 2](#step-2) above, MathJax supports chemical equations without additional configuration. To add chemistry support to KaTeX, enable the mhchem extension as described in the KaTeX [documentation][].
|
||||
|
||||
[`transform.ToMath`]: /functions/transform/tomath/
|
||||
[engines]: #engines
|
||||
[inline delimiters]: #inline-delimiters
|
||||
[KaTeX]: https://katex.org/
|
||||
[LaTeX]: https://www.latex-project.org/
|
||||
[MathJax]: https://www.mathjax.org/
|
||||
[`transform.ToMath`]: /functions/transform/tomath/
|
||||
[documentation]: https://katex.org/docs/libs
|
||||
[passthrough extension]: /configuration/markup/#passthrough
|
||||
[Step 2]: #step-2
|
||||
[Step 3]: #step-3
|
||||
[this KaTeX limitation]: https://github.com/KaTeX/KaTeX/issues/437
|
||||
|
||||
@@ -12,7 +12,7 @@ To create a menu for your site:
|
||||
|
||||
1. Define the menu entries
|
||||
1. [Localize](multilingual/#menus) each entry
|
||||
1. Render the menu with a [template]
|
||||
1. Render the menu with a [template][]
|
||||
|
||||
Create multiple menus, either flat or nested. For example, create a main menu for the header, and a separate menu for the footer.
|
||||
|
||||
@@ -22,7 +22,7 @@ There are three ways to define menu entries:
|
||||
1. In front matter
|
||||
1. In your project configuration
|
||||
|
||||
> [!note]
|
||||
> [!NOTE]
|
||||
> Although you can use these methods in combination when defining a menu, the menu will be easier to conceptualize and maintain if you use one method throughout the site.
|
||||
|
||||
## Define automatically
|
||||
@@ -33,7 +33,7 @@ To automatically define a menu entry for each top-level [section](g) of your sit
|
||||
sectionPagesMenu = 'main'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
This creates a menu structure that you can access with `site.Menus.main` in your templates. See [menu templates] for details.
|
||||
This creates a menu structure that you can access with `site.Menus.main` in your templates. See [menu templates][] for details.
|
||||
|
||||
## Define in front matter
|
||||
|
||||
@@ -44,7 +44,7 @@ title = 'About'
|
||||
menus = 'main'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
Access the entry with `site.Menus.main` in your templates. See [menu templates] for details.
|
||||
Access the entry with `site.Menus.main` in your templates. See [menu templates][] for details.
|
||||
|
||||
To add a page to the "main" and "footer" menus:
|
||||
|
||||
@@ -53,9 +53,9 @@ title = 'Contact'
|
||||
menus = ['main','footer']
|
||||
{{< /code-toggle >}}
|
||||
|
||||
Access the entry with `site.Menus.main` and `site.Menus.footer` in your templates. See [menu templates] for details.
|
||||
Access the entry with `site.Menus.main` and `site.Menus.footer` in your templates. See [menu templates][] for details.
|
||||
|
||||
> [!note]
|
||||
> [!NOTE]
|
||||
> The configuration key in the examples above is `menus`. The `menu` (singular) configuration key is an alias for `menus`.
|
||||
|
||||
### Properties
|
||||
@@ -80,20 +80,21 @@ class = 'center'
|
||||
{{< /code-toggle >}}
|
||||
<!-- markdownlint-enable MD033 -->
|
||||
|
||||
Access the entry with `site.Menus.main` in your templates. See [menu templates] for details.
|
||||
Access the entry with `site.Menus.main` in your templates. See [menu templates][] for details.
|
||||
|
||||
## Define in project configuration
|
||||
|
||||
See [configure menus](/configuration/menus/).
|
||||
See [configure menus][].
|
||||
|
||||
## Localize
|
||||
|
||||
Hugo provides two methods to localize your menu entries. See [multilingual].
|
||||
Hugo provides two methods to localize your menu entries. See [multilingual][].
|
||||
|
||||
## Render
|
||||
|
||||
See [menu templates].
|
||||
See [menu templates][].
|
||||
|
||||
[configure menus]: /configuration/menus/
|
||||
[menu templates]: /templates/menu/
|
||||
[multilingual]: /content-management/multilingual/#menus
|
||||
[template]: /templates/menu/
|
||||
|
||||
@@ -9,7 +9,7 @@ aliases: [/content/multilingual/,/tutorials/create-a-multilingual-site/]
|
||||
|
||||
## Configuration
|
||||
|
||||
See [configure languages](/configuration/languages/).
|
||||
See [configure languages][].
|
||||
|
||||
## Translate your content
|
||||
|
||||
@@ -29,10 +29,10 @@ Their language is assigned according to the language code added as a suffix to t
|
||||
|
||||
By having the same path and base file name, the content pieces are linked together as translated pages.
|
||||
|
||||
> [!note]
|
||||
> [!NOTE]
|
||||
> The language code in a file name must be lowercase. For example, use `about.en-us.md` instead of `about.en-US.md`.
|
||||
|
||||
> [!note]
|
||||
> [!NOTE]
|
||||
> If a file has no language code, it will be assigned the default language.
|
||||
|
||||
### Translation by content directory
|
||||
@@ -87,8 +87,8 @@ Because paths and file names are used to handle linking, all translated pages wi
|
||||
|
||||
To localize URLs:
|
||||
|
||||
- For a regular page, set either [`slug`] or [`url`] in front matter
|
||||
- For a section page, set [`url`] in front matter
|
||||
- For a regular page, set either [`slug`][] or [`url`][] in front matter
|
||||
- For a section page, set [`url`][] in front matter
|
||||
|
||||
For example, a French translation can have its own localized slug.
|
||||
|
||||
@@ -110,12 +110,12 @@ If, across the linked bundles, two or more files share the same basename, only o
|
||||
- File from current language bundle, if present.
|
||||
- First file found across bundles by order of language `Weight`.
|
||||
|
||||
> [!note]
|
||||
> [!NOTE]
|
||||
> Page Bundle resources follow the same language assignment logic as content files, both by file name (`image.jpg`, `image.fr.jpg`) and by directory (`english/about/header.jpg`, `french/about/header.jpg`).
|
||||
|
||||
## Translation of strings
|
||||
|
||||
See the [`lang.Translate`] template function.
|
||||
See the [`lang.Translate`][] function.
|
||||
|
||||
## Localization
|
||||
|
||||
@@ -162,7 +162,7 @@ English|Wednesday, November 3, 2021
|
||||
Français|mercredi 3 novembre 2021
|
||||
Deutsch|Mittwoch, 3. November 2021
|
||||
|
||||
See [`time.Format`] for details.
|
||||
See [`time.Format`][] for details.
|
||||
|
||||
### Currency
|
||||
|
||||
@@ -180,7 +180,7 @@ English|$512.50
|
||||
Français|512,50 $US
|
||||
Deutsch|512,50 $
|
||||
|
||||
See [lang.FormatCurrency] and [lang.FormatAccounting] for details.
|
||||
See [lang.FormatCurrency][] and [lang.FormatAccounting][] for details.
|
||||
|
||||
### Numbers
|
||||
|
||||
@@ -198,7 +198,7 @@ English|512.50
|
||||
Français|512,50
|
||||
Deutsch|512,50
|
||||
|
||||
See [lang.FormatNumber] and [lang.FormatNumberCustom] for details.
|
||||
See [lang.FormatNumber][] and [lang.FormatNumberCustom][] for details.
|
||||
|
||||
### Percentages
|
||||
|
||||
@@ -216,15 +216,15 @@ English|512.50%
|
||||
Français|512,50 %
|
||||
Deutsch|512,50 %
|
||||
|
||||
See [lang.FormatPercent] for details.
|
||||
See [lang.FormatPercent][] for details.
|
||||
|
||||
## Menus
|
||||
|
||||
Localization of menu entries depends on how you define them:
|
||||
|
||||
- When you define menu entries [automatically] using the section pages menu, you must use translation tables to localize each entry.
|
||||
- When you define menu entries in [front matter], they are already localized based on the front matter itself. If the front matter values are insufficient, use translation tables to localize each entry.
|
||||
- When you define menu entries in your [project configuration], you must create language-specific menu entries under each language key. If the names of the menu entries are insufficient, use translation tables to localize each entry.
|
||||
- When you define menu entries [automatically][] using the section pages menu, you must use translation tables to localize each entry.
|
||||
- When you define menu entries in [front matter][], they are already localized based on the front matter itself. If the front matter values are insufficient, use translation tables to localize each entry.
|
||||
- When you define menu entries in your [project configuration][], you must create language-specific menu entries under each language key. If the names of the menu entries are insufficient, use translation tables to localize each entry.
|
||||
|
||||
### Create language-specific menu entries
|
||||
|
||||
@@ -266,9 +266,9 @@ weight = 20
|
||||
|
||||
#### Method 2 -- Use a configuration directory
|
||||
|
||||
With a more complex menu structure, create a [configuration directory] and split the menu entries into multiple files, one file per language. For example:
|
||||
With a more complex menu structure, create a [configuration directory][] and split the menu entries into multiple files, one file per language. For example:
|
||||
|
||||
```text
|
||||
```tree
|
||||
config/
|
||||
└── _default/
|
||||
├── menus.de.toml
|
||||
@@ -300,7 +300,7 @@ weight = 20
|
||||
|
||||
### Use translation tables
|
||||
|
||||
When rendering the text that appears in menu each entry, the [example menu template] does this:
|
||||
When rendering the text that appears in menu each entry, the [example menu template][] does this:
|
||||
|
||||
```go-html-template
|
||||
{{ or (T .Identifier) .Name | safeHTML }}
|
||||
@@ -310,8 +310,8 @@ It queries the translation table for the current language using the menu entry's
|
||||
|
||||
The `identifier` depends on how you define menu entries:
|
||||
|
||||
- If you define the menu entry [automatically] using the section pages menu, the `identifier` is the page's `.Section`.
|
||||
- If you define the menu entry in your [project configuration] or in [front matter], set the `identifier` property to the desired value.
|
||||
- If you define the menu entry [automatically][] using the section pages menu, the `identifier` is the page's `.Section`.
|
||||
- If you define the menu entry in your [project configuration][] or in [front matter][], set the `identifier` property to the desired value.
|
||||
|
||||
For example, if you define menu entries in project configuration:
|
||||
|
||||
@@ -339,9 +339,9 @@ services = 'Leistungen'
|
||||
|
||||
If a string does not have a translation for the current language, Hugo will use the value from the default language. If no default value is set, an empty string will be shown.
|
||||
|
||||
While translating a Hugo website, it can be handy to have a visual indicator of missing translations. The [`enableMissingTranslationPlaceholders` configuration option][config] will flag all untranslated strings with the placeholder `[i18n] identifier`, where `identifier` is the id of the missing translation.
|
||||
While translating a Hugo website, it can be helpful to have a visual indicator of missing translations. The [`enableMissingTranslationPlaceholders`][] configuration setting will flag all untranslated strings with the placeholder `[i18n] identifier`, where `identifier` is the id of the missing translation.
|
||||
|
||||
> [!note]
|
||||
> [!NOTE]
|
||||
> Hugo will generate your website with these missing translation placeholders. It might not be suitable for production environments.
|
||||
|
||||
For merging of content from other languages (i.e. missing content translations), see [lang.Merge].
|
||||
@@ -358,7 +358,7 @@ i18n|MISSING_TRANSLATION|en|wordCount
|
||||
To support Multilingual mode in your themes, some considerations must be taken for the URLs in the templates. If there is more than one language, URLs must meet the following criteria:
|
||||
|
||||
- Come from the built-in `.Permalink` or `.RelPermalink`
|
||||
- Be constructed with the [`relLangURL`] or [`absLangURL`] template function, or be prefixed with `{{ .LanguagePrefix }}`
|
||||
- Be constructed with the [`urls.RelLangURL`][] or [`urls.AbsLangURL`][] function, or be prefixed with `{{ .LanguagePrefix }}`
|
||||
|
||||
If there is more than one language defined, the `LanguagePrefix` method will return `/en` (or whatever the current language is). If not enabled, it will be an empty string (and is therefore harmless for single-language Hugo websites).
|
||||
|
||||
@@ -378,15 +378,16 @@ hugo new content content/en/post/test.md
|
||||
hugo new content content/de/post/test.md
|
||||
```
|
||||
|
||||
[`absLangURL`]: /functions/urls/abslangurl/
|
||||
[`lang.Translate`]: /functions/lang/translate
|
||||
[`relLangURL`]: /functions/urls/rellangurl/
|
||||
[`enableMissingTranslationPlaceholders`]: /configuration/all/#enablemissingtranslationplaceholders
|
||||
[`lang.Translate`]: /functions/lang/translate/
|
||||
[`slug`]: /content-management/urls/#slug
|
||||
[`time.Format`]: /functions/time/format/
|
||||
[`url`]: /content-management/urls/#url
|
||||
[`urls.AbsLangURL`]: /functions/urls/abslangurl/
|
||||
[`urls.RelLangURL`]: /functions/urls/rellangurl/
|
||||
[automatically]: /content-management/menus/#define-automatically
|
||||
[config]: /configuration/
|
||||
[configuration directory]: /configuration/introduction/#configuration-directory
|
||||
[configure languages]: /configuration/languages/
|
||||
[example menu template]: /templates/menu/#example
|
||||
[front matter]: /content-management/menus/#define-in-front-matter
|
||||
[lang.FormatAccounting]: /functions/lang/formataccounting/
|
||||
|
||||
@@ -11,9 +11,9 @@ aliases: [/content/sections/]
|
||||
|
||||
Hugo supports page-relative images and other resources packaged into `Page Bundles`.
|
||||
|
||||
These terms are connected, and you also need to read about [Page Resources](/content-management/page-resources) and [Image Processing](/content-management/image-processing) to get the full picture.
|
||||
These terms are connected, and you also need to read about [page resources][] and [image processing][] to get the full picture.
|
||||
|
||||
```text
|
||||
```tree
|
||||
content/
|
||||
├── blog/
|
||||
│ ├── hugo-is-cool/
|
||||
@@ -40,7 +40,7 @@ The file tree above shows three bundles. Note that the home page bundle cannot c
|
||||
|
||||
In Hugo, your content should be organized in a manner that reflects the rendered website.
|
||||
|
||||
While Hugo supports content nested at any level, the top levels (i.e. `content/<DIRECTORIES>`) are special in Hugo and are considered the content type used to determine layouts etc. To read more about sections, including how to nest them, see [sections].
|
||||
While Hugo supports content nested at any level, the top levels (i.e. `content/<DIRECTORIES>`) are special in Hugo and are considered the content type used to determine layouts etc. To read more about sections, including how to nest them, see [sections][].
|
||||
|
||||
Without any additional configuration, the following will automatically work:
|
||||
|
||||
@@ -61,13 +61,13 @@ Without any additional configuration, the following will automatically work:
|
||||
|
||||
## Path breakdown in Hugo
|
||||
|
||||
The following demonstrates the relationships between your content organization and the output URL structure for your Hugo website when it renders. These examples assume you are [using pretty URLs][pretty], which is the default behavior for Hugo. The examples also assume a key-value of `baseURL = "https://example.org/"` in your [project configuration][config].
|
||||
The following demonstrates the relationships between your content organization and the output URL structure for your Hugo website when it renders. These examples assume you are [using pretty URLs][pretty], which is the default behavior for Hugo. The examples also assume a key-value of `baseURL = "https://example.org/"` in your [project configuration][].
|
||||
|
||||
### Index pages: `_index.md`
|
||||
|
||||
`_index.md` has a special role in Hugo. It allows you to add front matter and content to `home`, `section`, `taxonomy`, and `term` pages.
|
||||
|
||||
> [!note]
|
||||
> [!NOTE]
|
||||
> Access the content and metadata within an `_index.md` file by invoking the `GetPage` method on a `Site` or `Page` object.
|
||||
|
||||
You can create one `_index.md` for your home page and one in each of your content sections, taxonomies, and terms. The following shows typical placement of an `_index.md` that would contain content and front matter for a `posts` section list page on a Hugo website:
|
||||
@@ -95,11 +95,11 @@ At build, this will output to the following destination with the associated valu
|
||||
https://example.org/posts/index.html
|
||||
```
|
||||
|
||||
The [sections] can be nested as deeply as you want. The important thing to understand is that to make the section tree fully navigational, at least the lower-most section must include a content file. (i.e. `_index.md`).
|
||||
The [sections][] can be nested as deeply as you want. The important thing to understand is that to make the section tree fully navigational, at least the lower-most section must include a content file. (i.e. `_index.md`).
|
||||
|
||||
### Single pages in sections
|
||||
|
||||
Single content files in each of your sections will be rendered by a [page template]. Here is an example of a single `post` within `posts`:
|
||||
Single content files in each of your sections will be rendered by a [page template][]. Here is an example of a single `post` within `posts`:
|
||||
|
||||
```txt
|
||||
path ("posts/my-first-hugo-post.md")
|
||||
@@ -132,7 +132,7 @@ A default content type is determined by the section in which a content item is s
|
||||
|
||||
### `slug`
|
||||
|
||||
The `slug` is the last segment of the URL path, defined by the file name and optionally overridden by a `slug` value in front matter. See [URL Management](/content-management/urls/#slug) for details.
|
||||
The `slug` is the last segment of the URL path, defined by the file name and optionally overridden by a `slug` value in front matter. See [URL management][slug] for details.
|
||||
|
||||
### `path`
|
||||
|
||||
@@ -143,9 +143,13 @@ A content's `path` is determined by the section's path to the file. The file `pa
|
||||
|
||||
### `url`
|
||||
|
||||
The `url` is the entire URL path, defined by the file path and optionally overridden by a `url` value in front matter. See [URL Management](/content-management/urls/#slug) for details.
|
||||
The `url` is the entire URL path, defined by the file path and optionally overridden by a `url` value in front matter. See [URL management][url] for details.
|
||||
|
||||
[config]: /configuration/
|
||||
[pretty]: /content-management/urls/#appearance
|
||||
[sections]: /content-management/sections/
|
||||
[image processing]: /content-management/image-processing/
|
||||
[page resources]: /content-management/page-resources/
|
||||
[page template]: /templates/types/#page
|
||||
[pretty]: /content-management/urls/#appearance
|
||||
[project configuration]: /configuration/
|
||||
[sections]: /content-management/sections/
|
||||
[slug]: /content-management/urls/#slug
|
||||
[url]: /content-management/urls/#url
|
||||
|
||||
@@ -11,7 +11,7 @@ A page bundle is a directory that encapsulates both content and associated resou
|
||||
|
||||
By way of example, this site has an `about` page and a `privacy` page:
|
||||
|
||||
```text
|
||||
```tree
|
||||
content/
|
||||
├── about/
|
||||
│ ├── index.md
|
||||
@@ -19,7 +19,7 @@ content/
|
||||
└── privacy.md
|
||||
```
|
||||
|
||||
The `about` page is a page bundle. It logically associates a resource with content by bundling them together. Resources within a page bundle are [page resources], accessible with the [`Resources`] method on the `Page` object.
|
||||
The `about` page is a page bundle. It logically associates a resource with content by bundling them together. Resources within a page bundle are [page resources][], accessible with the [`Resources`][] method on the `Page` object.
|
||||
|
||||
Page bundles are either _leaf bundles_ or _branch bundles_.
|
||||
|
||||
@@ -29,22 +29,22 @@ leaf bundle
|
||||
branch bundle
|
||||
: A _branch bundle_ is a directory that contains an `_index.md` file and zero or more resources. Analogous to a physical branch, a branch bundle may have descendants including leaf bundles and other branch bundles. Top-level directories with or without `_index.md` files are also branch bundles. This includes the home page.
|
||||
|
||||
> [!note]
|
||||
> [!NOTE]
|
||||
> In the definitions above and the examples below, the extension of the index file depends on the [content format](g). For example, use `index.md` for Markdown content, `index.html` for HTML content, `index.adoc` for AsciiDoc content, etc.
|
||||
|
||||
## Comparison
|
||||
|
||||
Page bundle characteristics vary by bundle type.
|
||||
|
||||
| | Leaf bundle | Branch bundle |
|
||||
|---------------------|---------------------------------------------------------|---------------------------------------------------------|
|
||||
| Index file | `index.md` | `_index.md` |
|
||||
| Example | `content/about/index.md` | `content/posts/_index.md` |
|
||||
| [Page kinds](g) | `page` | `home`, `section`, `taxonomy`, or `term` |
|
||||
| Template types | [single] | [home], [section], [taxonomy], or [term] |
|
||||
| Descendant pages | None | Zero or more |
|
||||
| Resource location | Adjacent to the index file or in a nested subdirectory | Same as a leaf bundles, but excludes descendant bundles |
|
||||
| [Resource types](g) | `page`, `image`, `video`, etc. | all but `page` |
|
||||
| | Leaf bundle | Branch bundle |
|
||||
|---------------------|--------------------------------------------------------|---------------------------------------------------------|
|
||||
| Index file | `index.md` | `_index.md` |
|
||||
| Example | `content/about/index.md` | `content/posts/_index.md` |
|
||||
| [Page kinds](g) | `page` | `home`, `section`, `taxonomy`, or `term` |
|
||||
| Template types | [single][] | [home][], [section][], [taxonomy][], or [term][] |
|
||||
| Descendant pages | None | Zero or more |
|
||||
| Resource location | Adjacent to the index file or in a nested subdirectory | Same as a leaf bundles, but excludes descendant bundles |
|
||||
| [Resource types](g) | `page`, `image`, `video`, etc. | all but `page` |
|
||||
|
||||
Files with [resource type](g) `page` include content written in Markdown, HTML, AsciiDoc, Pandoc, reStructuredText, and Emacs Org Mode. In a leaf bundle, excluding the index file, these files are only accessible as page resources. In a branch bundle, these files are only accessible as content pages.
|
||||
|
||||
@@ -52,7 +52,7 @@ Files with [resource type](g) `page` include content written in Markdown, HTML,
|
||||
|
||||
A _leaf bundle_ is a directory that contains an `index.md` file and zero or more resources. Analogous to a physical leaf, a leaf bundle is at the end of a branch. It has no descendants.
|
||||
|
||||
```text
|
||||
```tree
|
||||
content/
|
||||
├── about
|
||||
│ └── index.md
|
||||
@@ -83,7 +83,7 @@ my-post
|
||||
|
||||
- content-1, content-2
|
||||
|
||||
These are resources of resource type `page`, accessible via the [`Resources`] method on the `Page` object. Hugo will not render these as individual pages.
|
||||
These are resources of resource type `page`, accessible via the [`Resources`][] method on the `Page` object. Hugo will not render these as individual pages.
|
||||
|
||||
- image-1, image-2
|
||||
|
||||
@@ -95,14 +95,14 @@ my-other-post
|
||||
another-leaf-bundle
|
||||
: This leaf bundle does not contain any page resources.
|
||||
|
||||
> [!note]
|
||||
> [!NOTE]
|
||||
> Create leaf bundles at any depth within the `content` directory, but a leaf bundle may not contain another bundle. Leaf bundles do not have descendants.
|
||||
|
||||
## Branch bundles
|
||||
|
||||
A _branch bundle_ is a directory that contains an `_index.md` file and zero or more resources. Analogous to a physical branch, a branch bundle may have descendants including leaf bundles and other branch bundles. Top-level directories with or without `_index.md` files are also branch bundles. This includes the home page.
|
||||
|
||||
```text
|
||||
```tree
|
||||
content/
|
||||
├── branch-bundle-1/
|
||||
│ ├── _index.md
|
||||
@@ -128,12 +128,12 @@ branch-bundle-1
|
||||
branch-bundle-2
|
||||
: This branch bundle contains an index file and a leaf bundle.
|
||||
|
||||
> [!note]
|
||||
> [!NOTE]
|
||||
> Create branch bundles at any depth within the `content` directory. Branch bundles may have descendants.
|
||||
|
||||
## Headless bundles
|
||||
|
||||
Use [build options] in front matter to create an unpublished leaf or branch bundle whose content and resources you can include in other pages.
|
||||
Use [build options][] in front matter to create an unpublished leaf or branch bundle whose content and resources you can include in other pages.
|
||||
|
||||
[`Resources`]: /methods/page/resources/
|
||||
[build options]: /content-management/build-options/
|
||||
|
||||
@@ -9,7 +9,7 @@ Page resources are only accessible from [page bundles][], those directories with
|
||||
|
||||
In this example, `first-post` is a page bundle with access to 10 page resources including audio, data, documents, images, and video. Although `second-post` is also a page bundle, it has no page resources and is unable to directly access the page resources associated with `first-post`.
|
||||
|
||||
```text
|
||||
```tree
|
||||
content
|
||||
└── post
|
||||
├── first-post
|
||||
@@ -33,16 +33,16 @@ content
|
||||
|
||||
Use any of these methods on a `Page` object to capture page resources:
|
||||
|
||||
- [`Resources.ByType`]
|
||||
- [`Resources.Get`]
|
||||
- [`Resources.GetMatch`]
|
||||
- [`Resources.Match`]
|
||||
- [`Resources.ByType`][]
|
||||
- [`Resources.Get`][]
|
||||
- [`Resources.GetMatch`][]
|
||||
- [`Resources.Match`][]
|
||||
|
||||
Once you have captured a resource, use any of the applicable [`Resource`][] methods to return a value or perform an action.
|
||||
|
||||
The following examples assume this content structure:
|
||||
|
||||
```text
|
||||
```tree
|
||||
content/
|
||||
└── example/
|
||||
├── data/
|
||||
@@ -106,19 +106,19 @@ List the titles in the data file, and throw an error if the file does not exist.
|
||||
|
||||
The page resources' metadata is managed from the corresponding page's front matter with an array parameter named `resources`.
|
||||
|
||||
> [!note]
|
||||
> [!NOTE]
|
||||
> Resources of type `page` get `Title` etc. from their own front matter.
|
||||
|
||||
src
|
||||
`src`
|
||||
: (`string`) Required. A [glob pattern](g) matching one or more page resources by file path, relative to the page bundle. Matching is case-insensitive. When the pattern matches multiple resources, the same metadata is applied to each.
|
||||
|
||||
name
|
||||
: (`string`) Sets the value returned by [`Name`]. Supports the [`:counter`][] placeholder. After assignment, use `name`, not the original file path, with [`Resources.Get`][], [`Resources.Match`][], and [`Resources.GetMatch`][].
|
||||
`name`
|
||||
: (`string`) Sets the value returned by [`Name`][]. Supports the [`:counter`](#the-counter-placeholder-in-name-and-title) placeholder. After assignment, use `name`, not the original file path, with [`Resources.Get`][], [`Resources.Match`][], and [`Resources.GetMatch`][].
|
||||
|
||||
title
|
||||
: (`string`) Sets the value returned by [`Title`][]. Supports the [`:counter`][] placeholder.
|
||||
`title`
|
||||
: (`string`) Sets the value returned by [`Title`][]. Supports the [`:counter`](#the-counter-placeholder-in-name-and-title) placeholder.
|
||||
|
||||
params
|
||||
`params`
|
||||
: (`map`) A map of custom key-value pairs. When multiple array entries match the same resource, their `params` maps are merged; later entries take precedence for duplicate keys.
|
||||
|
||||
### Resources metadata example
|
||||
@@ -155,7 +155,7 @@ From the example above:
|
||||
- All `PDF` files will get the `pdf` icon and a new `Name`. The `name` parameter contains a special placeholder [`:counter`](#the-counter-placeholder-in-name-and-title), so the `Name` will be `pdf-file-1`, `pdf-file-2`, `pdf-file-3`.
|
||||
- All `.docx` files will get the `word` icon.
|
||||
|
||||
> [!note]
|
||||
> [!NOTE]
|
||||
> For `name` and `title`, the first matching array entry wins; later matches are ignored. For `params`, all matching entries contribute; later entries take precedence for duplicate keys. Place more specific `src` patterns before broader wildcards to control which `name` and `title` values are applied.
|
||||
|
||||
### The `:counter` placeholder in `name` and `title`
|
||||
@@ -189,7 +189,7 @@ the `Name` and `Title` will be assigned to the resource files as follows:
|
||||
|
||||
By default, with a multilingual single-host project, Hugo does not duplicate shared page during the build.
|
||||
|
||||
> [!note]
|
||||
> [!NOTE]
|
||||
> This behavior is limited to Markdown content. Shared page resources for other [content formats][] are copied into each language bundle.
|
||||
|
||||
Consider this project configuration:
|
||||
@@ -211,7 +211,7 @@ weight = 2
|
||||
|
||||
And this content:
|
||||
|
||||
```text
|
||||
```tree
|
||||
content/
|
||||
└── my-bundle/
|
||||
├── a.jpg <-- shared page resource
|
||||
@@ -222,31 +222,9 @@ content/
|
||||
└── index.en.md
|
||||
```
|
||||
|
||||
With v0.122.0 and earlier, Hugo duplicated the shared page resources, creating copies for each language:
|
||||
Hugo places the shared resources in the page bundle for the default content language:
|
||||
|
||||
```text
|
||||
public/
|
||||
├── de/
|
||||
│ ├── my-bundle/
|
||||
│ │ ├── a.jpg <-- shared page resource
|
||||
│ │ ├── b.jpg <-- shared page resource
|
||||
│ │ ├── c.de.jpg
|
||||
│ │ └── index.html
|
||||
│ └── index.html
|
||||
├── en/
|
||||
│ ├── my-bundle/
|
||||
│ │ ├── a.jpg <-- shared page resource (duplicate)
|
||||
│ │ ├── b.jpg <-- shared page resource (duplicate)
|
||||
│ │ ├── c.en.jpg
|
||||
│ │ └── index.html
|
||||
│ └── index.html
|
||||
└── index.html
|
||||
|
||||
```
|
||||
|
||||
With v0.123.0 and later, Hugo places the shared resources in the page bundle for the default content language:
|
||||
|
||||
```text
|
||||
```tree
|
||||
public/
|
||||
├── de/
|
||||
│ ├── my-bundle/
|
||||
@@ -265,12 +243,12 @@ public/
|
||||
|
||||
This approach reduces build times, storage requirements, bandwidth consumption, and deployment times, ultimately reducing cost.
|
||||
|
||||
> [!important]
|
||||
> [!IMPORTANT]
|
||||
> To resolve Markdown link and image destinations to the correct location, you must use link and image render hooks that capture the page resource with the [`Resources.Get`][] method, and then invoke its [`RelPermalink`][] method.
|
||||
>
|
||||
> In its default configuration, Hugo automatically uses the [embedded link render hook][] and the [embedded image render hook][] for multilingual single-host projects, specifically when the [duplication of shared page resources][] feature is disabled. This is the default behavior for such projects. If custom link or image render hooks are defined by your project, modules, or themes, these will be used instead.
|
||||
>
|
||||
> You can also configure Hugo to `always` use the embedded link or image render hook, use it only as a `fallback`, or `never` use it. See [details][].
|
||||
> You can also configure Hugo to `always` use the embedded link or image render hook, use it only as a `fallback`, or `never` use it. See [details][].
|
||||
|
||||
Although duplicating shared page resources is inefficient, you can enable this feature in your project configuration if desired:
|
||||
|
||||
@@ -279,10 +257,9 @@ Although duplicating shared page resources is inefficient, you can enable this f
|
||||
duplicateResourceFiles = true
|
||||
{{< /code-toggle >}}
|
||||
|
||||
[`:counter`]: #the-counter-placeholder-in-name-and-title
|
||||
[`Name`]: /methods/resource/name/
|
||||
[`RelPermalink`]: /methods/resource/relpermalink/
|
||||
[`Resource`]: /methods/resource
|
||||
[`Resource`]: /methods/resource/
|
||||
[`Resources.ByType`]: /methods/page/resources#bytype
|
||||
[`Resources.GetMatch`]: /methods/page/resources#getmatch
|
||||
[`Resources.Get`]: /methods/page/resources/#get
|
||||
@@ -293,4 +270,4 @@ duplicateResourceFiles = true
|
||||
[duplication of shared page resources]: /configuration/markup/#duplicateresourcefiles
|
||||
[embedded image render hook]: /render-hooks/images/#embedded
|
||||
[embedded link render hook]: /render-hooks/links/#embedded
|
||||
[page bundles]: /content-management/page-bundles
|
||||
[page bundles]: /content-management/page-bundles/
|
||||
|
||||
@@ -6,7 +6,7 @@ keywords: []
|
||||
aliases: [/content/related/,/related/,/content-management/related/]
|
||||
---
|
||||
|
||||
Hugo uses a set of factors to identify a page's related content based on front matter parameters. This can be tuned to the desired set of indices and parameters or left to Hugo's default [related content configuration](/configuration/related-content/).
|
||||
Hugo uses a set of factors to identify a page's related content based on front matter parameters. This can be tuned to the desired set of indices and parameters.
|
||||
|
||||
## List related content
|
||||
|
||||
@@ -25,16 +25,16 @@ To list up to 5 related pages (which share the same _date_ or _keyword_ paramete
|
||||
|
||||
The `Related` method takes one argument which may be a `Page` or an options map. The options map has these options:
|
||||
|
||||
indices
|
||||
`indices`
|
||||
: (`slice`) The indices to search within.
|
||||
|
||||
document
|
||||
`document`
|
||||
: (`page`) The page for which to find related content. Required when specifying an options map.
|
||||
|
||||
namedSlices
|
||||
: (`slice`) The keywords to search for, expressed as a slice of `KeyValues` using the [`keyVals`] function.
|
||||
`namedSlices`
|
||||
: (`slice`) The keywords to search for, expressed as a slice of `KeyValues` using the [`keyVals`][] function.
|
||||
|
||||
fragments
|
||||
`fragments`
|
||||
: (`slice`) A list of special keywords that is used for indices configured as type "fragments". This will match the [fragment](g) identifiers of the documents.
|
||||
|
||||
A fictional example using all of the above options:
|
||||
@@ -49,8 +49,8 @@ A fictional example using all of the above options:
|
||||
}}
|
||||
```
|
||||
|
||||
> [!note]
|
||||
> We improved and simplified this feature in Hugo 0.111.0. Before this we had 3 different methods: `Related`, `RelatedTo` and `RelatedIndices`. Now we have only one method: `Related`. The old methods are still available but deprecated. Also see [this blog article](https://regisphilibert.com/blog/2018/04/hugo-optmized-relashionships-with-related-content/) for a great explanation of more advanced usage of this feature.
|
||||
> [!NOTE]
|
||||
> We improved and simplified this feature in Hugo 0.111.0. Before this we had 3 different methods: `Related`, `RelatedTo` and `RelatedIndices`. Now we have only one method: `Related`. The old methods are still available but deprecated. Also see [this blog article][] for a great explanation of more advanced usage of this feature.
|
||||
|
||||
## Index content headings
|
||||
|
||||
@@ -97,6 +97,8 @@ weight = 80
|
||||
|
||||
## Configuration
|
||||
|
||||
See [configure related content](/configuration/related-content/).
|
||||
See [configure related content][].
|
||||
|
||||
[`keyVals`]: /functions/collections/keyvals/
|
||||
[configure related content]: /configuration/related-content/
|
||||
[this blog article]: https://regisphilibert.com/blog/2018/04/hugo-optmized-relashionships-with-related-content/
|
||||
|
||||
@@ -11,7 +11,7 @@ aliases: [/content/sections/]
|
||||
|
||||
{{% glossary-term "section" %}}
|
||||
|
||||
```text
|
||||
```tree
|
||||
content/
|
||||
├── articles/ <-- section (top-level directory)
|
||||
│ ├── 2022/
|
||||
@@ -68,7 +68,7 @@ With the file structure from the [example above](#overview):
|
||||
|
||||
## Template selection
|
||||
|
||||
Hugo has a defined [lookup order] to determine which template to use when rendering a page. The [lookup rules] consider the top-level section name; subsection names are not considered when selecting a template.
|
||||
Hugo has a defined [lookup order][] to determine which template to use when rendering a page. The [lookup rules][] consider the top-level section name; subsection names are not considered when selecting a template.
|
||||
|
||||
With the file structure from the [example above](#overview):
|
||||
|
||||
|
||||
@@ -30,7 +30,7 @@ Create custom shortcodes to simplify and standardize content creation. For examp
|
||||
|
||||
Then call the shortcode from within markup:
|
||||
|
||||
```text {file="content/example.md"}
|
||||
```md {file="content/example.md"}
|
||||
{{</* audio src=/audio/test.mp3 */>}}
|
||||
```
|
||||
|
||||
@@ -49,11 +49,11 @@ To conform with this security model, creating _shortcode_ templates within conte
|
||||
enableInlineShortcodes = true
|
||||
{{< /code-toggle >}}
|
||||
|
||||
For more information see [configure security](/configuration/security).
|
||||
For more information see [configure security][].
|
||||
|
||||
The following example demonstrates an inline shortcode, `date.inline`, that accepts a single positional argument: a date/time [layout string][].
|
||||
|
||||
```text {file="content/example.md"}
|
||||
```md {file="content/example.md"}
|
||||
Today is
|
||||
{{</* date.inline ":date_medium" */>}}
|
||||
{{- now | time.Format (.Get 0) -}}
|
||||
@@ -71,7 +71,7 @@ In the example above, the inline shortcode is executed twice: once upon definiti
|
||||
|
||||
Inline shortcodes process their inner content within the same context as regular _shortcode_ templates, allowing you to use any available [shortcode method][].
|
||||
|
||||
> [!note]
|
||||
> [!NOTE]
|
||||
> You cannot [nest](#nesting) inline shortcodes.
|
||||
|
||||
Learn more about creating shortcodes in the [shortcode templates][] section.
|
||||
@@ -84,7 +84,7 @@ Shortcode calls involve three syntactical elements: tags, arguments, and notatio
|
||||
|
||||
Some shortcodes expect content between opening and closing tags. For example, the embedded [`details`][] shortcode requires an opening and closing tag:
|
||||
|
||||
```text
|
||||
```md
|
||||
{{</* details summary="See the details" */>}}
|
||||
This is a **bold** word.
|
||||
{{</* /details */>}}
|
||||
@@ -92,13 +92,13 @@ This is a **bold** word.
|
||||
|
||||
Some shortcodes do not accept content. For example, the embedded [`instagram`][] shortcode requires a single _positional_ argument:
|
||||
|
||||
```text
|
||||
```md
|
||||
{{</* instagram CxOWiQNP2MO */>}}
|
||||
```
|
||||
|
||||
Some shortcodes optionally accept content. For example, you can call the embedded [`qr`][] shortcode with content:
|
||||
|
||||
```text
|
||||
```md
|
||||
{{</* qr */>}}
|
||||
https://gohugo.io
|
||||
{{</* /qr */>}}
|
||||
@@ -106,7 +106,7 @@ https://gohugo.io
|
||||
|
||||
Or use the self-closing syntax with a trailing slash to pass the text as an argument:
|
||||
|
||||
```text
|
||||
```md
|
||||
{{</* qr text=https://gohugo.io /*/>}}
|
||||
```
|
||||
|
||||
@@ -118,31 +118,31 @@ Shortcode arguments can be either _named_ or _positional_.
|
||||
|
||||
Named arguments are passed as case-sensitive key-value pairs, as seen in this example with the embedded [`figure`][] shortcode. The `src` argument, for instance, is required.
|
||||
|
||||
```text
|
||||
```md
|
||||
{{</* figure src=/images/kitten.jpg */>}}
|
||||
```
|
||||
|
||||
Positional arguments, on the other hand, are determined by their position. The embedded `instagram` shortcode, for example, expects the first argument to be the Instagram post ID.
|
||||
|
||||
```text
|
||||
```md
|
||||
{{</* instagram CxOWiQNP2MO */>}}
|
||||
```
|
||||
|
||||
Shortcode arguments are space-delimited, and arguments with internal spaces must be quoted.
|
||||
|
||||
```text
|
||||
```md
|
||||
{{</* figure src=/images/kitten.jpg alt="A white kitten" */>}}
|
||||
```
|
||||
|
||||
Shortcodes accept [scalar](g) arguments, one of [string](g), [integer](g), [floating point](g), or [boolean](g).
|
||||
|
||||
```text
|
||||
```md
|
||||
{{</* my-shortcode name="John Smith" age=24 married=false */>}}
|
||||
```
|
||||
|
||||
You can optionally use multiple lines when providing several arguments to a shortcode for better readability:
|
||||
|
||||
```text
|
||||
```md
|
||||
{{</* figure
|
||||
src=/images/kitten.jpg
|
||||
alt="A white kitten"
|
||||
@@ -153,7 +153,7 @@ You can optionally use multiple lines when providing several arguments to a shor
|
||||
|
||||
Use a [raw string literal](g) if you need to pass a multiline string:
|
||||
|
||||
```text
|
||||
```md
|
||||
{{</* myshortcode `This is some <b>HTML</b>,
|
||||
and a new line with a "quoted string".` */>}}
|
||||
```
|
||||
@@ -187,7 +187,7 @@ By way of example, with this _shortcode_ template:
|
||||
|
||||
And this markdown:
|
||||
|
||||
```text {file="content/example.md"}
|
||||
```md {file="content/example.md"}
|
||||
{{%/* foo */%}} ## Section 1 {{%/* /foo */%}}
|
||||
|
||||
{{</* foo */>}} ## Section 2 {{</* /foo */>}}
|
||||
@@ -203,14 +203,14 @@ Hugo renders this HTML:
|
||||
|
||||
In the above, "Section 1" will be included when invoking the `TableOfContents` method, while "Section 2" will not.
|
||||
|
||||
> [!note]
|
||||
> [!NOTE]
|
||||
> The shortcode author determines which notation to use. Consult each shortcode's documentation for specific usage instructions and available arguments.
|
||||
|
||||
## Nesting
|
||||
|
||||
Shortcodes (excluding [inline](#inline) shortcodes) can be nested, creating parent-child relationships. For example, a gallery shortcode might contain several image shortcodes:
|
||||
|
||||
```text {file="content/example.md"}
|
||||
```md {file="content/example.md"}
|
||||
{{</* gallery class="content-gallery" */>}}
|
||||
{{</* image src="/images/a.jpg" */>}}
|
||||
{{</* image src="/images/b.jpg" */>}}
|
||||
@@ -220,11 +220,12 @@ Shortcodes (excluding [inline](#inline) shortcodes) can be nested, creating pare
|
||||
|
||||
The [shortcode templates][nesting] section provides a detailed explanation and examples.
|
||||
|
||||
[`details`]: /shortcodes/details
|
||||
[`figure`]: /shortcodes/figure
|
||||
[`instagram`]: /shortcodes/instagram
|
||||
[`qr`]: /shortcodes/qr
|
||||
[`TableOfContents`]: /methods/page/tableofcontents/
|
||||
[`details`]: /shortcodes/details/
|
||||
[`figure`]: /shortcodes/figure/
|
||||
[`instagram`]: /shortcodes/instagram/
|
||||
[`qr`]: /shortcodes/qr/
|
||||
[configure security]: /configuration/security/
|
||||
[layout string]: /functions/time/format/#layout-string
|
||||
[nesting]: /templates/shortcode/#nesting
|
||||
[shortcode method]: /templates/shortcode/#methods
|
||||
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user