From: Bjørn Erik Pedersen Date: Sat, 27 May 2023 15:02:23 +0000 (+0200) Subject: Merge commit 'd3927310d5b2404c3238f9b899db3329ea516490' X-Git-Url: http://git.maquefel.me/?a=commitdiff_plain;h=a838a27e4;p=brevno-suite%2Fhugo Merge commit 'd3927310d5b2404c3238f9b899db3329ea516490' --- a838a27e4c82626f9b3227e02a157119673e5dcf diff --cc docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/index.headers index fedd73525,000000000..1216e42d4 mode 100644,000000..100644 --- a/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/index.headers +++ b/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/index.headers @@@ -1,8 -1,0 +1,5 @@@ +/* + X-Frame-Options: DENY + X-XSS-Protection: 1; mode=block + X-Content-Type-Options: nosniff + Referrer-Policy: origin-when-cross-origin - /* - Link: <{{ "dist/app.bundle.js" | relURL }}>; rel=preload; as=script - Link: <{{ "dist/main.css" | relURL }}>; rel=preload; as=style diff --cc docs/_vendor/modules.txt index 5c4b53271,000000000..1c7cac307 mode 100644,000000..100644 --- a/docs/_vendor/modules.txt +++ b/docs/_vendor/modules.txt @@@ -1,1 -1,0 +1,1 @@@ - # github.com/gohugoio/gohugoioTheme v0.0.0-20230418063032-99f9185b8e11 ++# github.com/gohugoio/gohugoioTheme v0.0.0-20230527124826-78bc315d7b8a diff --cc docs/content/en/about/hugo-and-gdpr.md index 3e0a160c7,000000000..b028c4543 mode 100644,000000..100644 --- a/docs/content/en/about/hugo-and-gdpr.md +++ b/docs/content/en/about/hugo-and-gdpr.md @@@ -1,134 -1,0 +1,134 @@@ +--- +title: Hugo and the General Data Protection Regulation (GDPR) +linktitle: Hugo and GDPR +description: About how to configure your Hugo site to meet the new regulations. +layout: single +keywords: ["GDPR", "Privacy", "Data Protection"] +menu: + docs: + parent: about + weight: 5 +weight: 5 +aliases: [/privacy/,/gdpr/] +toc: true +--- + + General Data Protection Regulation ([GDPR](https://en.wikipedia.org/wiki/General_Data_Protection_Regulation)) is a regulation in EU law on data protection and privacy for all individuals within the European Union and the European Economic Area. It became enforceable on 25 May 2018. + + **Hugo is a static site generator. By using Hugo you are already standing on very solid ground. Static HTML files on disk are much easier to reason about compared to server and database driven web sites.** + + But even static websites can integrate with external services, so from version `0.41`, Hugo provides a **Privacy Config** that covers the relevant built-in templates. + + Note that: + + * These settings have their defaults setting set to _off_, i.e. how it worked before Hugo `0.41`. You must do your own evaluation of your site and apply the appropriate settings. + * These settings work with the [internal templates](/templates/internal/). Some theme may contain custom templates for embedding services like Google Analytics. In that case these options have no effect. + * We will continue this work and improve this further in future Hugo versions. + +## All Privacy Settings + - Below are all privacy settings and their default value. These settings need to be put in your site config (e.g. `config.toml`). ++Below are all privacy settings and their default value. These settings need to be put in your site config (e.g. `hugo.toml`). + - {{< code-toggle file="config">}} ++{{< code-toggle file="hugo" >}} +[privacy] +[privacy.disqus] +disable = false +[privacy.googleAnalytics] +disable = false +respectDoNotTrack = false +anonymizeIP = false +useSessionStorage = false +[privacy.instagram] +disable = false +simple = false +[privacy.twitter] +disable = false +enableDNT = false +simple = false +[privacy.vimeo] +disable = false +enableDNT = false +simple = false +[privacy.youtube] +disable = false +privacyEnhanced = false +{{< /code-toggle >}} + +## Disable All Services + +An example Privacy Config that disables all the relevant services in Hugo. With this configuration, the other settings will not matter. + - {{< code-toggle file="config">}} ++ {{< code-toggle file="hugo" >}} +[privacy] +[privacy.disqus] +disable = true +[privacy.googleAnalytics] +disable = true +[privacy.instagram] +disable = true +[privacy.twitter] +disable = true +[privacy.vimeo] +disable = true +[privacy.youtube] +disable = true +{{< /code-toggle >}} + +## The Privacy Settings Explained + +### GoogleAnalytics + +anonymizeIP +: Enabling this will make it so the users' IP addresses are anonymized within Google Analytics. + +respectDoNotTrack +: Enabling this will make the GA templates respect the "Do Not Track" HTTP header. + +useSessionStorage +: Enabling this will disable the use of Cookies and use Session Storage to Store the GA Client ID. + +{{% note %}} +`useSessionStorage` is not supported when using Google Analytics v4 (gtag.js). +{{% /note %}} + +### Instagram + +simple +: If simple mode is enabled, a static and no-JS version of the Instagram image card will be built. Note that this only supports image cards and the image itself will be fetched from Instagram's servers. + +**Note:** If you use the _simple mode_ for Instagram and a site styled with Bootstrap 4, you may want to disable the inline styles provided by Hugo: + - {{< code-toggle file="config">}} ++ {{< code-toggle file="hugo" >}} +[services] +[services.instagram] +disableInlineCSS = true +{{< /code-toggle >}} + +### Twitter + +enableDNT +: Enabling this for the twitter/tweet shortcode, the tweet and its embedded page on your site are not used for purposes that include personalized suggestions and personalized ads. + +simple +: If simple mode is enabled, a static and no-JS version of a tweet will be built. + +**Note:** If you use the _simple mode_ for Twitter, you may want to disable the inline styles provided by Hugo: + - {{< code-toggle file="config">}} ++ {{< code-toggle file="hugo" >}} +[services] +[services.twitter] +disableInlineCSS = true +{{< /code-toggle >}} + +### YouTube + +privacyEnhanced +: When you turn on privacy-enhanced mode, YouTube won’t store information about visitors on your website unless the user plays the embedded video. + +### Vimeo + +enableDNT +: Enabling this for the vimeo shortcode, the Vimeo player will be blocked from tracking any session data, including all cookies and stats. + +simple +: If simple mode is enabled, the video thumbnail is fetched from Vimeo's servers and it is overlayed with a play button. If the user clicks to play the video, it will open in a new tab directly on Vimeo's website. diff --cc docs/content/en/commands/hugo.md index 73d443169,000000000..8dbdd6231 mode 100644,000000..100644 --- a/docs/content/en/commands/hugo.md +++ b/docs/content/en/commands/hugo.md @@@ -1,86 -1,0 +1,87 @@@ +--- +title: "hugo" +slug: hugo +url: /commands/hugo/ +--- +## hugo + +hugo builds your site + +### Synopsis + +hugo is the main command, used to build your Hugo site. + +Hugo is a Fast and Flexible Static Site Generator +built with love by spf13 and friends in Go. + +Complete documentation is available at https://gohugo.io/. + +``` +hugo [flags] +``` + +### Options + +``` + -b, --baseURL string hostname (and path) to the root, e.g. https://spf13.com/ + -D, --buildDrafts include content marked as draft + -E, --buildExpired include expired content + -F, --buildFuture include content with publishdate in the future + --cacheDir string filesystem path to cache directory. Defaults: $TMPDIR/hugo_cache/ + --cleanDestinationDir remove files from destination not found in static directories + --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00 + --config string config file (default is hugo.yaml|json|toml) + --configDir string config dir (default "config") + -c, --contentDir string filesystem path to content directory + --debug debug output + -d, --destination string filesystem path to write files to + --disableKinds strings disable different kind of pages (home, RSS etc.) + --enableGitInfo add Git revision, date, author, and CODEOWNERS info to the pages + -e, --environment string build environment + --forceSyncStatic copy all files when static is changed. ++ --format string preferred file format (toml, yaml or json) (default "toml") + --gc enable to run some cleanup tasks (remove unused cache files) after the build + -h, --help help for hugo + --ignoreCache ignores the cache directory + --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern + -l, --layoutDir string filesystem path to layout directory + --log enable Logging + --logFile string log File path (if set, logging enabled automatically) + --minify minify any supported output format (HTML, XML etc.) + --noBuildLock don't create .hugo_build.lock file + --noChmod don't sync permission mode of files + --noTimes don't sync modification time of files + --panicOnWarning panic on first WARNING log + --poll string set this to a poll interval, e.g --poll 700ms, to use a poll based approach to watch for file system changes + --printI18nWarnings print missing translations + --printMemoryUsage print memory usage to screen at intervals + --printPathWarnings print warnings on duplicate target paths etc. + --printUnusedTemplates print warnings on unused templates. + --quiet build in quiet mode + --renderToMemory render to memory (only useful for benchmark testing) + -s, --source string filesystem path to read files relative from + --templateMetrics display metrics about template executions + --templateMetricsHints calculate some improvement hints when combined with --templateMetrics + -t, --theme strings themes to use (located in /themes/THEMENAME/) + --themesDir string filesystem path to themes directory + --trace file write trace to file (not useful in general) + -v, --verbose verbose output + --verboseLog verbose logging + -w, --watch watch filesystem for changes and recreate as needed +``` + +### SEE ALSO + +* [hugo completion](/commands/hugo_completion/) - Generate the autocompletion script for the specified shell +* [hugo config](/commands/hugo_config/) - Print the site configuration +* [hugo convert](/commands/hugo_convert/) - Convert your content to different formats +* [hugo deploy](/commands/hugo_deploy/) - Deploy your site to a Cloud provider. +* [hugo env](/commands/hugo_env/) - Print Hugo version and environment info +* [hugo gen](/commands/hugo_gen/) - A collection of several useful generators. +* [hugo import](/commands/hugo_import/) - Import your site from others. +* [hugo list](/commands/hugo_list/) - Listing out various types of content +* [hugo mod](/commands/hugo_mod/) - Various Hugo Modules helpers. +* [hugo new](/commands/hugo_new/) - Create new content for your site +* [hugo server](/commands/hugo_server/) - A high performance webserver +* [hugo version](/commands/hugo_version/) - Print Hugo version and environment info + diff --cc docs/content/en/commands/hugo_completion.md index d7cc64cc2,000000000..7ab87f800 mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_completion.md +++ b/docs/content/en/commands/hugo_completion.md @@@ -1,48 -1,0 +1,49 @@@ +--- +title: "hugo completion" +slug: hugo_completion +url: /commands/hugo_completion/ +--- +## hugo completion + +Generate the autocompletion script for the specified shell + +### Synopsis + +Generate the autocompletion script for hugo for the specified shell. +See each sub-command's help for details on how to use the generated script. + + +### Options + +``` + -h, --help help for completion +``` + +### Options inherited from parent commands + +``` + --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00 + --config string config file (default is hugo.yaml|json|toml) + --configDir string config dir (default "config") + --debug debug output + -d, --destination string filesystem path to write files to + -e, --environment string build environment ++ --format string preferred file format (toml, yaml or json) (default "toml") + --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern + --log enable Logging + --logFile string log File path (if set, logging enabled automatically) + --quiet build in quiet mode + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output + --verboseLog verbose logging +``` + +### SEE ALSO + +* [hugo](/commands/hugo/) - hugo builds your site +* [hugo completion bash](/commands/hugo_completion_bash/) - Generate the autocompletion script for bash +* [hugo completion fish](/commands/hugo_completion_fish/) - Generate the autocompletion script for fish +* [hugo completion powershell](/commands/hugo_completion_powershell/) - Generate the autocompletion script for powershell +* [hugo completion zsh](/commands/hugo_completion_zsh/) - Generate the autocompletion script for zsh + diff --cc docs/content/en/commands/hugo_completion_bash.md index eb6fdd8d4,000000000..a4d4d6f11 mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_completion_bash.md +++ b/docs/content/en/commands/hugo_completion_bash.md @@@ -1,67 -1,0 +1,68 @@@ +--- +title: "hugo completion bash" +slug: hugo_completion_bash +url: /commands/hugo_completion_bash/ +--- +## hugo completion bash + +Generate the autocompletion script for bash + +### Synopsis + +Generate the autocompletion script for the bash shell. + +This script depends on the 'bash-completion' package. +If it is not installed already, you can install it via your OS's package manager. + +To load completions in your current shell session: + + source <(hugo completion bash) + +To load completions for every new session, execute once: + +#### Linux: + + hugo completion bash > /etc/bash_completion.d/hugo + +#### macOS: + + hugo completion bash > $(brew --prefix)/etc/bash_completion.d/hugo + +You will need to start a new shell for this setup to take effect. + + +``` +hugo completion bash +``` + +### Options + +``` + -h, --help help for bash + --no-descriptions disable completion descriptions +``` + +### Options inherited from parent commands + +``` + --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00 + --config string config file (default is hugo.yaml|json|toml) + --configDir string config dir (default "config") + --debug debug output + -d, --destination string filesystem path to write files to + -e, --environment string build environment ++ --format string preferred file format (toml, yaml or json) (default "toml") + --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern + --log enable Logging + --logFile string log File path (if set, logging enabled automatically) + --quiet build in quiet mode + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output + --verboseLog verbose logging +``` + +### SEE ALSO + +* [hugo completion](/commands/hugo_completion/) - Generate the autocompletion script for the specified shell + diff --cc docs/content/en/commands/hugo_completion_fish.md index f81acb8af,000000000..6fe2d7f16 mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_completion_fish.md +++ b/docs/content/en/commands/hugo_completion_fish.md @@@ -1,58 -1,0 +1,59 @@@ +--- +title: "hugo completion fish" +slug: hugo_completion_fish +url: /commands/hugo_completion_fish/ +--- +## hugo completion fish + +Generate the autocompletion script for fish + +### Synopsis + +Generate the autocompletion script for the fish shell. + +To load completions in your current shell session: + + hugo completion fish | source + +To load completions for every new session, execute once: + + hugo completion fish > ~/.config/fish/completions/hugo.fish + +You will need to start a new shell for this setup to take effect. + + +``` +hugo completion fish [flags] +``` + +### Options + +``` + -h, --help help for fish + --no-descriptions disable completion descriptions +``` + +### Options inherited from parent commands + +``` + --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00 + --config string config file (default is hugo.yaml|json|toml) + --configDir string config dir (default "config") + --debug debug output + -d, --destination string filesystem path to write files to + -e, --environment string build environment ++ --format string preferred file format (toml, yaml or json) (default "toml") + --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern + --log enable Logging + --logFile string log File path (if set, logging enabled automatically) + --quiet build in quiet mode + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output + --verboseLog verbose logging +``` + +### SEE ALSO + +* [hugo completion](/commands/hugo_completion/) - Generate the autocompletion script for the specified shell + diff --cc docs/content/en/commands/hugo_completion_powershell.md index 5f900ec59,000000000..614023dbb mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_completion_powershell.md +++ b/docs/content/en/commands/hugo_completion_powershell.md @@@ -1,55 -1,0 +1,56 @@@ +--- +title: "hugo completion powershell" +slug: hugo_completion_powershell +url: /commands/hugo_completion_powershell/ +--- +## hugo completion powershell + +Generate the autocompletion script for powershell + +### Synopsis + +Generate the autocompletion script for powershell. + +To load completions in your current shell session: + + hugo completion powershell | Out-String | Invoke-Expression + +To load completions for every new session, add the output of the above command +to your powershell profile. + + +``` +hugo completion powershell [flags] +``` + +### Options + +``` + -h, --help help for powershell + --no-descriptions disable completion descriptions +``` + +### Options inherited from parent commands + +``` + --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00 + --config string config file (default is hugo.yaml|json|toml) + --configDir string config dir (default "config") + --debug debug output + -d, --destination string filesystem path to write files to + -e, --environment string build environment ++ --format string preferred file format (toml, yaml or json) (default "toml") + --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern + --log enable Logging + --logFile string log File path (if set, logging enabled automatically) + --quiet build in quiet mode + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output + --verboseLog verbose logging +``` + +### SEE ALSO + +* [hugo completion](/commands/hugo_completion/) - Generate the autocompletion script for the specified shell + diff --cc docs/content/en/commands/hugo_completion_zsh.md index fbe5c6ad4,000000000..7e17bc96d mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_completion_zsh.md +++ b/docs/content/en/commands/hugo_completion_zsh.md @@@ -1,69 -1,0 +1,70 @@@ +--- +title: "hugo completion zsh" +slug: hugo_completion_zsh +url: /commands/hugo_completion_zsh/ +--- +## hugo completion zsh + +Generate the autocompletion script for zsh + +### Synopsis + +Generate the autocompletion script for the zsh shell. + +If shell completion is not already enabled in your environment you will need +to enable it. You can execute the following once: + + echo "autoload -U compinit; compinit" >> ~/.zshrc + +To load completions in your current shell session: + + source <(hugo completion zsh) + +To load completions for every new session, execute once: + +#### Linux: + + hugo completion zsh > "${fpath[1]}/_hugo" + +#### macOS: + + hugo completion zsh > $(brew --prefix)/share/zsh/site-functions/_hugo + +You will need to start a new shell for this setup to take effect. + + +``` +hugo completion zsh [flags] +``` + +### Options + +``` + -h, --help help for zsh + --no-descriptions disable completion descriptions +``` + +### Options inherited from parent commands + +``` + --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00 + --config string config file (default is hugo.yaml|json|toml) + --configDir string config dir (default "config") + --debug debug output + -d, --destination string filesystem path to write files to + -e, --environment string build environment ++ --format string preferred file format (toml, yaml or json) (default "toml") + --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern + --log enable Logging + --logFile string log File path (if set, logging enabled automatically) + --quiet build in quiet mode + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output + --verboseLog verbose logging +``` + +### SEE ALSO + +* [hugo completion](/commands/hugo_completion/) - Generate the autocompletion script for the specified shell + diff --cc docs/content/en/commands/hugo_config_mounts.md index 9ec0a5e7f,000000000..1019f5102 mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_config_mounts.md +++ b/docs/content/en/commands/hugo_config_mounts.md @@@ -1,42 -1,0 +1,43 @@@ +--- +title: "hugo config mounts" +slug: hugo_config_mounts +url: /commands/hugo_config_mounts/ +--- +## hugo config mounts + +Print the configured file mounts + +``` +hugo config mounts [flags] [args] +``` + +### Options + +``` + -h, --help help for mounts +``` + +### Options inherited from parent commands + +``` + --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00 + --config string config file (default is hugo.yaml|json|toml) + --configDir string config dir (default "config") + --debug debug output + -d, --destination string filesystem path to write files to + -e, --environment string build environment ++ --format string preferred file format (toml, yaml or json) (default "toml") + --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern + --log enable Logging + --logFile string log File path (if set, logging enabled automatically) + --quiet build in quiet mode + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output + --verboseLog verbose logging +``` + +### SEE ALSO + +* [hugo config](/commands/hugo_config/) - Print the site configuration + diff --cc docs/content/en/commands/hugo_convert_toJSON.md index 4b811f49e,000000000..73c2fc303 mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_convert_toJSON.md +++ b/docs/content/en/commands/hugo_convert_toJSON.md @@@ -1,49 -1,0 +1,50 @@@ +--- +title: "hugo convert toJSON" +slug: hugo_convert_toJSON +url: /commands/hugo_convert_tojson/ +--- +## hugo convert toJSON + +Convert front matter to JSON + +### Synopsis + +toJSON converts all front matter in the content directory +to use JSON for the front matter. + +``` +hugo convert toJSON [flags] [args] +``` + +### Options + +``` + -h, --help help for toJSON +``` + +### Options inherited from parent commands + +``` + --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00 + --config string config file (default is hugo.yaml|json|toml) + --configDir string config dir (default "config") + --debug debug output + -d, --destination string filesystem path to write files to + -e, --environment string build environment ++ --format string preferred file format (toml, yaml or json) (default "toml") + --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern + --log enable Logging + --logFile string log File path (if set, logging enabled automatically) + -o, --output string filesystem path to write files to + --quiet build in quiet mode + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + --unsafe enable less safe operations, please backup first + -v, --verbose verbose output + --verboseLog verbose logging +``` + +### SEE ALSO + +* [hugo convert](/commands/hugo_convert/) - Convert your content to different formats + diff --cc docs/content/en/commands/hugo_convert_toTOML.md index 19d847e90,000000000..9141eb1a2 mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_convert_toTOML.md +++ b/docs/content/en/commands/hugo_convert_toTOML.md @@@ -1,49 -1,0 +1,50 @@@ +--- +title: "hugo convert toTOML" +slug: hugo_convert_toTOML +url: /commands/hugo_convert_totoml/ +--- +## hugo convert toTOML + +Convert front matter to TOML + +### Synopsis + +toTOML converts all front matter in the content directory +to use TOML for the front matter. + +``` +hugo convert toTOML [flags] [args] +``` + +### Options + +``` + -h, --help help for toTOML +``` + +### Options inherited from parent commands + +``` + --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00 + --config string config file (default is hugo.yaml|json|toml) + --configDir string config dir (default "config") + --debug debug output + -d, --destination string filesystem path to write files to + -e, --environment string build environment ++ --format string preferred file format (toml, yaml or json) (default "toml") + --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern + --log enable Logging + --logFile string log File path (if set, logging enabled automatically) + -o, --output string filesystem path to write files to + --quiet build in quiet mode + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + --unsafe enable less safe operations, please backup first + -v, --verbose verbose output + --verboseLog verbose logging +``` + +### SEE ALSO + +* [hugo convert](/commands/hugo_convert/) - Convert your content to different formats + diff --cc docs/content/en/commands/hugo_convert_toYAML.md index 1785d3ad8,000000000..a932921cf mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_convert_toYAML.md +++ b/docs/content/en/commands/hugo_convert_toYAML.md @@@ -1,49 -1,0 +1,50 @@@ +--- +title: "hugo convert toYAML" +slug: hugo_convert_toYAML +url: /commands/hugo_convert_toyaml/ +--- +## hugo convert toYAML + +Convert front matter to YAML + +### Synopsis + +toYAML converts all front matter in the content directory +to use YAML for the front matter. + +``` +hugo convert toYAML [flags] [args] +``` + +### Options + +``` + -h, --help help for toYAML +``` + +### Options inherited from parent commands + +``` + --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00 + --config string config file (default is hugo.yaml|json|toml) + --configDir string config dir (default "config") + --debug debug output + -d, --destination string filesystem path to write files to + -e, --environment string build environment ++ --format string preferred file format (toml, yaml or json) (default "toml") + --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern + --log enable Logging + --logFile string log File path (if set, logging enabled automatically) + -o, --output string filesystem path to write files to + --quiet build in quiet mode + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + --unsafe enable less safe operations, please backup first + -v, --verbose verbose output + --verboseLog verbose logging +``` + +### SEE ALSO + +* [hugo convert](/commands/hugo_convert/) - Convert your content to different formats + diff --cc docs/content/en/commands/hugo_env.md index 296e6e002,000000000..e001c6098 mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_env.md +++ b/docs/content/en/commands/hugo_env.md @@@ -1,46 -1,0 +1,47 @@@ +--- +title: "hugo env" +slug: hugo_env +url: /commands/hugo_env/ +--- +## hugo env + +Print Hugo version and environment info + +### Synopsis + +Print Hugo version and environment info. This is useful in Hugo bug reports + +``` +hugo env [flags] [args] +``` + +### Options + +``` + -h, --help help for env +``` + +### Options inherited from parent commands + +``` + --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00 + --config string config file (default is hugo.yaml|json|toml) + --configDir string config dir (default "config") + --debug debug output + -d, --destination string filesystem path to write files to + -e, --environment string build environment ++ --format string preferred file format (toml, yaml or json) (default "toml") + --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern + --log enable Logging + --logFile string log File path (if set, logging enabled automatically) + --quiet build in quiet mode + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output + --verboseLog verbose logging +``` + +### SEE ALSO + +* [hugo](/commands/hugo/) - hugo builds your site + diff --cc docs/content/en/commands/hugo_gen.md index 71c6dfe42,000000000..b589e2e0f mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_gen.md +++ b/docs/content/en/commands/hugo_gen.md @@@ -1,45 -1,0 +1,46 @@@ +--- +title: "hugo gen" +slug: hugo_gen +url: /commands/hugo_gen/ +--- +## hugo gen + +A collection of several useful generators. + +``` +hugo gen [command] [flags] +``` + +### Options + +``` + -h, --help help for gen +``` + +### Options inherited from parent commands + +``` + --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00 + --config string config file (default is hugo.yaml|json|toml) + --configDir string config dir (default "config") + --debug debug output + -d, --destination string filesystem path to write files to + -e, --environment string build environment ++ --format string preferred file format (toml, yaml or json) (default "toml") + --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern + --log enable Logging + --logFile string log File path (if set, logging enabled automatically) + --quiet build in quiet mode + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output + --verboseLog verbose logging +``` + +### SEE ALSO + +* [hugo](/commands/hugo/) - hugo builds your site +* [hugo gen chromastyles](/commands/hugo_gen_chromastyles/) - Generate CSS stylesheet for the Chroma code highlighter +* [hugo gen doc](/commands/hugo_gen_doc/) - Generate Markdown documentation for the Hugo CLI. +* [hugo gen man](/commands/hugo_gen_man/) - Generate man pages for the Hugo CLI + diff --cc docs/content/en/commands/hugo_gen_chromastyles.md index 9c41f7174,000000000..5ea23381d mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_gen_chromastyles.md +++ b/docs/content/en/commands/hugo_gen_chromastyles.md @@@ -1,51 -1,0 +1,52 @@@ +--- +title: "hugo gen chromastyles" +slug: hugo_gen_chromastyles +url: /commands/hugo_gen_chromastyles/ +--- +## hugo gen chromastyles + +Generate CSS stylesheet for the Chroma code highlighter + +### Synopsis + +Generate CSS stylesheet for the Chroma code highlighter for a given style. This stylesheet is needed if markup.highlight.noClasses is disabled in config. + +See https://xyproto.github.io/splash/docs/all.html for a preview of the available styles + +``` +hugo gen chromastyles [flags] [args] +``` + +### Options + +``` + -h, --help help for chromastyles + --highlightStyle string style used for highlighting lines (see https://github.com/alecthomas/chroma) (default "bg:#ffffcc") + --linesStyle string style used for line numbers (see https://github.com/alecthomas/chroma) + --style string highlighter style (see https://xyproto.github.io/splash/docs/) (default "friendly") +``` + +### Options inherited from parent commands + +``` + --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00 + --config string config file (default is hugo.yaml|json|toml) + --configDir string config dir (default "config") + --debug debug output + -d, --destination string filesystem path to write files to + -e, --environment string build environment ++ --format string preferred file format (toml, yaml or json) (default "toml") + --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern + --log enable Logging + --logFile string log File path (if set, logging enabled automatically) + --quiet build in quiet mode + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output + --verboseLog verbose logging +``` + +### SEE ALSO + +* [hugo gen](/commands/hugo_gen/) - A collection of several useful generators. + diff --cc docs/content/en/commands/hugo_gen_doc.md index 59999fb7b,000000000..16593400a mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_gen_doc.md +++ b/docs/content/en/commands/hugo_gen_doc.md @@@ -1,52 -1,0 +1,53 @@@ +--- +title: "hugo gen doc" +slug: hugo_gen_doc +url: /commands/hugo_gen_doc/ +--- +## hugo gen doc + +Generate Markdown documentation for the Hugo CLI. + +### Synopsis + +Generate Markdown documentation for the Hugo CLI. + This command is, mostly, used to create up-to-date documentation + of Hugo's command-line interface for https://gohugo.io/. + + It creates one Markdown file per command with front matter suitable + for rendering in Hugo. + +``` +hugo gen doc [flags] [args] +``` + +### Options + +``` + --dir string the directory to write the doc. (default "/tmp/hugodoc/") + -h, --help help for doc +``` + +### Options inherited from parent commands + +``` + --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00 + --config string config file (default is hugo.yaml|json|toml) + --configDir string config dir (default "config") + --debug debug output + -d, --destination string filesystem path to write files to + -e, --environment string build environment ++ --format string preferred file format (toml, yaml or json) (default "toml") + --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern + --log enable Logging + --logFile string log File path (if set, logging enabled automatically) + --quiet build in quiet mode + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output + --verboseLog verbose logging +``` + +### SEE ALSO + +* [hugo gen](/commands/hugo_gen/) - A collection of several useful generators. + diff --cc docs/content/en/commands/hugo_gen_man.md index f2c40d71d,000000000..3602dcc93 mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_gen_man.md +++ b/docs/content/en/commands/hugo_gen_man.md @@@ -1,49 -1,0 +1,50 @@@ +--- +title: "hugo gen man" +slug: hugo_gen_man +url: /commands/hugo_gen_man/ +--- +## hugo gen man + +Generate man pages for the Hugo CLI + +### Synopsis + +This command automatically generates up-to-date man pages of Hugo's + command-line interface. By default, it creates the man page files + in the "man" directory under the current directory. + +``` +hugo gen man [flags] [args] +``` + +### Options + +``` + --dir string the directory to write the man pages. (default "man/") + -h, --help help for man +``` + +### Options inherited from parent commands + +``` + --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00 + --config string config file (default is hugo.yaml|json|toml) + --configDir string config dir (default "config") + --debug debug output + -d, --destination string filesystem path to write files to + -e, --environment string build environment ++ --format string preferred file format (toml, yaml or json) (default "toml") + --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern + --log enable Logging + --logFile string log File path (if set, logging enabled automatically) + --quiet build in quiet mode + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output + --verboseLog verbose logging +``` + +### SEE ALSO + +* [hugo gen](/commands/hugo_gen/) - A collection of several useful generators. + diff --cc docs/content/en/commands/hugo_import.md index c9774f466,000000000..ad4907d58 mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_import.md +++ b/docs/content/en/commands/hugo_import.md @@@ -1,49 -1,0 +1,50 @@@ +--- +title: "hugo import" +slug: hugo_import +url: /commands/hugo_import/ +--- +## hugo import + +Import your site from others. + +### Synopsis + +Import your site from other web site generators like Jekyll. + +Import requires a subcommand, e.g. `hugo import jekyll jekyll_root_path target_path`. + +``` +hugo import [command] [flags] +``` + +### Options + +``` + -h, --help help for import +``` + +### Options inherited from parent commands + +``` + --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00 + --config string config file (default is hugo.yaml|json|toml) + --configDir string config dir (default "config") + --debug debug output + -d, --destination string filesystem path to write files to + -e, --environment string build environment ++ --format string preferred file format (toml, yaml or json) (default "toml") + --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern + --log enable Logging + --logFile string log File path (if set, logging enabled automatically) + --quiet build in quiet mode + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output + --verboseLog verbose logging +``` + +### SEE ALSO + +* [hugo](/commands/hugo/) - hugo builds your site +* [hugo import jekyll](/commands/hugo_import_jekyll/) - hugo import from Jekyll + diff --cc docs/content/en/commands/hugo_import_jekyll.md index 4e4876d90,000000000..10d603bdf mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_import_jekyll.md +++ b/docs/content/en/commands/hugo_import_jekyll.md @@@ -1,49 -1,0 +1,50 @@@ +--- +title: "hugo import jekyll" +slug: hugo_import_jekyll +url: /commands/hugo_import_jekyll/ +--- +## hugo import jekyll + +hugo import from Jekyll + +### Synopsis + +hugo import from Jekyll. + +Import from Jekyll requires two paths, e.g. `hugo import jekyll jekyll_root_path target_path`. + +``` +hugo import jekyll [flags] [args] +``` + +### Options + +``` + --force allow import into non-empty target directory + -h, --help help for jekyll +``` + +### Options inherited from parent commands + +``` + --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00 + --config string config file (default is hugo.yaml|json|toml) + --configDir string config dir (default "config") + --debug debug output + -d, --destination string filesystem path to write files to + -e, --environment string build environment ++ --format string preferred file format (toml, yaml or json) (default "toml") + --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern + --log enable Logging + --logFile string log File path (if set, logging enabled automatically) + --quiet build in quiet mode + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output + --verboseLog verbose logging +``` + +### SEE ALSO + +* [hugo import](/commands/hugo_import/) - Import your site from others. + diff --cc docs/content/en/commands/hugo_list_all.md index 5ac8a7c35,000000000..8edd0a4d9 mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_list_all.md +++ b/docs/content/en/commands/hugo_list_all.md @@@ -1,46 -1,0 +1,47 @@@ +--- +title: "hugo list all" +slug: hugo_list_all +url: /commands/hugo_list_all/ +--- +## hugo list all + +List all posts + +### Synopsis + +List all of the posts in your content directory, include drafts, future and expired pages. + +``` +hugo list all [flags] [args] +``` + +### Options + +``` + -h, --help help for all +``` + +### Options inherited from parent commands + +``` + --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00 + --config string config file (default is hugo.yaml|json|toml) + --configDir string config dir (default "config") + --debug debug output + -d, --destination string filesystem path to write files to + -e, --environment string build environment ++ --format string preferred file format (toml, yaml or json) (default "toml") + --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern + --log enable Logging + --logFile string log File path (if set, logging enabled automatically) + --quiet build in quiet mode + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output + --verboseLog verbose logging +``` + +### SEE ALSO + +* [hugo list](/commands/hugo_list/) - Listing out various types of content + diff --cc docs/content/en/commands/hugo_list_drafts.md index 601c7648f,000000000..5ec870a5d mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_list_drafts.md +++ b/docs/content/en/commands/hugo_list_drafts.md @@@ -1,46 -1,0 +1,47 @@@ +--- +title: "hugo list drafts" +slug: hugo_list_drafts +url: /commands/hugo_list_drafts/ +--- +## hugo list drafts + +List all drafts + +### Synopsis + +List all of the drafts in your content directory. + +``` +hugo list drafts [flags] [args] +``` + +### Options + +``` + -h, --help help for drafts +``` + +### Options inherited from parent commands + +``` + --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00 + --config string config file (default is hugo.yaml|json|toml) + --configDir string config dir (default "config") + --debug debug output + -d, --destination string filesystem path to write files to + -e, --environment string build environment ++ --format string preferred file format (toml, yaml or json) (default "toml") + --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern + --log enable Logging + --logFile string log File path (if set, logging enabled automatically) + --quiet build in quiet mode + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output + --verboseLog verbose logging +``` + +### SEE ALSO + +* [hugo list](/commands/hugo_list/) - Listing out various types of content + diff --cc docs/content/en/commands/hugo_list_expired.md index 47a9cc369,000000000..3feae5640 mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_list_expired.md +++ b/docs/content/en/commands/hugo_list_expired.md @@@ -1,46 -1,0 +1,47 @@@ +--- +title: "hugo list expired" +slug: hugo_list_expired +url: /commands/hugo_list_expired/ +--- +## hugo list expired + +List all posts already expired + +### Synopsis + +List all of the posts in your content directory which has already expired. + +``` +hugo list expired [flags] [args] +``` + +### Options + +``` + -h, --help help for expired +``` + +### Options inherited from parent commands + +``` + --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00 + --config string config file (default is hugo.yaml|json|toml) + --configDir string config dir (default "config") + --debug debug output + -d, --destination string filesystem path to write files to + -e, --environment string build environment ++ --format string preferred file format (toml, yaml or json) (default "toml") + --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern + --log enable Logging + --logFile string log File path (if set, logging enabled automatically) + --quiet build in quiet mode + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output + --verboseLog verbose logging +``` + +### SEE ALSO + +* [hugo list](/commands/hugo_list/) - Listing out various types of content + diff --cc docs/content/en/commands/hugo_list_future.md index 5cbb86c74,000000000..5b331b90b mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_list_future.md +++ b/docs/content/en/commands/hugo_list_future.md @@@ -1,46 -1,0 +1,47 @@@ +--- +title: "hugo list future" +slug: hugo_list_future +url: /commands/hugo_list_future/ +--- +## hugo list future + +List all posts dated in the future + +### Synopsis + +List all of the posts in your content directory which will be posted in the future. + +``` +hugo list future [flags] [args] +``` + +### Options + +``` + -h, --help help for future +``` + +### Options inherited from parent commands + +``` + --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00 + --config string config file (default is hugo.yaml|json|toml) + --configDir string config dir (default "config") + --debug debug output + -d, --destination string filesystem path to write files to + -e, --environment string build environment ++ --format string preferred file format (toml, yaml or json) (default "toml") + --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern + --log enable Logging + --logFile string log File path (if set, logging enabled automatically) + --quiet build in quiet mode + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output + --verboseLog verbose logging +``` + +### SEE ALSO + +* [hugo list](/commands/hugo_list/) - Listing out various types of content + diff --cc docs/content/en/commands/hugo_mod_clean.md index ad97610cd,000000000..922fab2ab mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_mod_clean.md +++ b/docs/content/en/commands/hugo_mod_clean.md @@@ -1,48 -1,0 +1,49 @@@ +--- +title: "hugo mod clean" +slug: hugo_mod_clean +url: /commands/hugo_mod_clean/ +--- +## hugo mod clean + +Delete the Hugo Module cache for the current project. + +### Synopsis + +Delete the Hugo Module cache for the current project. + +``` +hugo mod clean [flags] [args] +``` + +### Options + +``` + --all clean entire module cache + -h, --help help for clean + --pattern string pattern matching module paths to clean (all if not set), e.g. "**hugo*" +``` + +### Options inherited from parent commands + +``` + --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00 + --config string config file (default is hugo.yaml|json|toml) + --configDir string config dir (default "config") + --debug debug output + -d, --destination string filesystem path to write files to + -e, --environment string build environment ++ --format string preferred file format (toml, yaml or json) (default "toml") + --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern + --log enable Logging + --logFile string log File path (if set, logging enabled automatically) + --quiet build in quiet mode + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output + --verboseLog verbose logging +``` + +### SEE ALSO + +* [hugo mod](/commands/hugo_mod/) - Various Hugo Modules helpers. + diff --cc docs/content/en/commands/hugo_mod_get.md index 21fa1f967,000000000..d0d0f85d3 mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_mod_get.md +++ b/docs/content/en/commands/hugo_mod_get.md @@@ -1,72 -1,0 +1,73 @@@ +--- +title: "hugo mod get" +slug: hugo_mod_get +url: /commands/hugo_mod_get/ +--- +## hugo mod get + +Resolves dependencies in your current Hugo Project. + +### Synopsis + + +Resolves dependencies in your current Hugo Project. + +Some examples: + +Install the latest version possible for a given module: + + hugo mod get github.com/gohugoio/testshortcodes + +Install a specific version: + + hugo mod get github.com/gohugoio/testshortcodes@v0.3.0 + +Install the latest versions of all module dependencies: + + hugo mod get -u + hugo mod get -u ./... (recursive) + +Run "go help get" for more information. All flags available for "go get" is also relevant here. + +Note that Hugo will always start out by resolving the components defined in the site +configuration, provided by a _vendor directory (if no --ignoreVendorPaths flag provided), +Go Modules, or a folder inside the themes directory, in that order. + +See https://gohugo.io/hugo-modules/ for more information. + + + +``` +hugo mod get [flags] [args] +``` + +### Options + +``` + -h, --help help for get +``` + +### Options inherited from parent commands + +``` + --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00 + --config string config file (default is hugo.yaml|json|toml) + --configDir string config dir (default "config") + --debug debug output + -d, --destination string filesystem path to write files to + -e, --environment string build environment ++ --format string preferred file format (toml, yaml or json) (default "toml") + --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern + --log enable Logging + --logFile string log File path (if set, logging enabled automatically) + --quiet build in quiet mode + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output + --verboseLog verbose logging +``` + +### SEE ALSO + +* [hugo mod](/commands/hugo_mod/) - Various Hugo Modules helpers. + diff --cc docs/content/en/commands/hugo_mod_graph.md index 79ff3170f,000000000..da72a2a31 mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_mod_graph.md +++ b/docs/content/en/commands/hugo_mod_graph.md @@@ -1,49 -1,0 +1,50 @@@ +--- +title: "hugo mod graph" +slug: hugo_mod_graph +url: /commands/hugo_mod_graph/ +--- +## hugo mod graph + +Print a module dependency graph. + +### Synopsis + +Print a module dependency graph with information about module status (disabled, vendored). +Note that for vendored modules, that is the version listed and not the one from go.mod. + + +``` +hugo mod graph [flags] [args] +``` + +### Options + +``` + --clean delete module cache for dependencies that fail verification + -h, --help help for graph +``` + +### Options inherited from parent commands + +``` + --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00 + --config string config file (default is hugo.yaml|json|toml) + --configDir string config dir (default "config") + --debug debug output + -d, --destination string filesystem path to write files to + -e, --environment string build environment ++ --format string preferred file format (toml, yaml or json) (default "toml") + --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern + --log enable Logging + --logFile string log File path (if set, logging enabled automatically) + --quiet build in quiet mode + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output + --verboseLog verbose logging +``` + +### SEE ALSO + +* [hugo mod](/commands/hugo_mod/) - Various Hugo Modules helpers. + diff --cc docs/content/en/commands/hugo_mod_init.md index ad4501b64,000000000..7d5f77aa7 mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_mod_init.md +++ b/docs/content/en/commands/hugo_mod_init.md @@@ -1,53 -1,0 +1,54 @@@ +--- +title: "hugo mod init" +slug: hugo_mod_init +url: /commands/hugo_mod_init/ +--- +## hugo mod init + +Initialize this project as a Hugo Module. + +### Synopsis + +Initialize this project as a Hugo Module. + It will try to guess the module path, but you may help by passing it as an argument, e.g: + + hugo mod init github.com/gohugoio/testshortcodes + + Note that Hugo Modules supports multi-module projects, so you can initialize a Hugo Module + inside a subfolder on GitHub, as one example. + + +``` +hugo mod init [flags] [args] +``` + +### Options + +``` + -h, --help help for init +``` + +### Options inherited from parent commands + +``` + --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00 + --config string config file (default is hugo.yaml|json|toml) + --configDir string config dir (default "config") + --debug debug output + -d, --destination string filesystem path to write files to + -e, --environment string build environment ++ --format string preferred file format (toml, yaml or json) (default "toml") + --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern + --log enable Logging + --logFile string log File path (if set, logging enabled automatically) + --quiet build in quiet mode + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output + --verboseLog verbose logging +``` + +### SEE ALSO + +* [hugo mod](/commands/hugo_mod/) - Various Hugo Modules helpers. + diff --cc docs/content/en/commands/hugo_mod_npm.md index 8e13a7294,000000000..12ec71b77 mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_mod_npm.md +++ b/docs/content/en/commands/hugo_mod_npm.md @@@ -1,47 -1,0 +1,48 @@@ +--- +title: "hugo mod npm" +slug: hugo_mod_npm +url: /commands/hugo_mod_npm/ +--- +## hugo mod npm + +Various npm helpers. + +### Synopsis + +Various npm (Node package manager) helpers. + +``` +hugo mod npm [command] [flags] +``` + +### Options + +``` + -h, --help help for npm +``` + +### Options inherited from parent commands + +``` + --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00 + --config string config file (default is hugo.yaml|json|toml) + --configDir string config dir (default "config") + --debug debug output + -d, --destination string filesystem path to write files to + -e, --environment string build environment ++ --format string preferred file format (toml, yaml or json) (default "toml") + --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern + --log enable Logging + --logFile string log File path (if set, logging enabled automatically) + --quiet build in quiet mode + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output + --verboseLog verbose logging +``` + +### SEE ALSO + +* [hugo mod](/commands/hugo_mod/) - Various Hugo Modules helpers. +* [hugo mod npm pack](/commands/hugo_mod_npm_pack/) - Experimental: Prepares and writes a composite package.json file for your project. + diff --cc docs/content/en/commands/hugo_mod_npm_pack.md index aadac772b,000000000..b923db82c mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_mod_npm_pack.md +++ b/docs/content/en/commands/hugo_mod_npm_pack.md @@@ -1,56 -1,0 +1,57 @@@ +--- +title: "hugo mod npm pack" +slug: hugo_mod_npm_pack +url: /commands/hugo_mod_npm_pack/ +--- +## hugo mod npm pack + +Experimental: Prepares and writes a composite package.json file for your project. + +### Synopsis + +Prepares and writes a composite package.json file for your project. + +On first run it creates a "package.hugo.json" in the project root if not already there. This file will be used as a template file +with the base dependency set. + +This set will be merged with all "package.hugo.json" files found in the dependency tree, picking the version closest to the project. + +This command is marked as 'Experimental'. We think it's a great idea, so it's not likely to be +removed from Hugo, but we need to test this out in "real life" to get a feel of it, +so this may/will change in future versions of Hugo. + + +``` +hugo mod npm pack [flags] [args] +``` + +### Options + +``` + -h, --help help for pack +``` + +### Options inherited from parent commands + +``` + --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00 + --config string config file (default is hugo.yaml|json|toml) + --configDir string config dir (default "config") + --debug debug output + -d, --destination string filesystem path to write files to + -e, --environment string build environment ++ --format string preferred file format (toml, yaml or json) (default "toml") + --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern + --log enable Logging + --logFile string log File path (if set, logging enabled automatically) + --quiet build in quiet mode + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output + --verboseLog verbose logging +``` + +### SEE ALSO + +* [hugo mod npm](/commands/hugo_mod_npm/) - Various npm helpers. + diff --cc docs/content/en/commands/hugo_mod_tidy.md index 9c665f1c5,000000000..63cb52ca6 mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_mod_tidy.md +++ b/docs/content/en/commands/hugo_mod_tidy.md @@@ -1,42 -1,0 +1,43 @@@ +--- +title: "hugo mod tidy" +slug: hugo_mod_tidy +url: /commands/hugo_mod_tidy/ +--- +## hugo mod tidy + +Remove unused entries in go.mod and go.sum. + +``` +hugo mod tidy [flags] [args] +``` + +### Options + +``` + -h, --help help for tidy +``` + +### Options inherited from parent commands + +``` + --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00 + --config string config file (default is hugo.yaml|json|toml) + --configDir string config dir (default "config") + --debug debug output + -d, --destination string filesystem path to write files to + -e, --environment string build environment ++ --format string preferred file format (toml, yaml or json) (default "toml") + --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern + --log enable Logging + --logFile string log File path (if set, logging enabled automatically) + --quiet build in quiet mode + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output + --verboseLog verbose logging +``` + +### SEE ALSO + +* [hugo mod](/commands/hugo_mod/) - Various Hugo Modules helpers. + diff --cc docs/content/en/commands/hugo_mod_vendor.md index 42c04609a,000000000..9d9943c8a mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_mod_vendor.md +++ b/docs/content/en/commands/hugo_mod_vendor.md @@@ -1,48 -1,0 +1,49 @@@ +--- +title: "hugo mod vendor" +slug: hugo_mod_vendor +url: /commands/hugo_mod_vendor/ +--- +## hugo mod vendor + +Vendor all module dependencies into the _vendor directory. + +### Synopsis + +Vendor all module dependencies into the _vendor directory. + If a module is vendored, that is where Hugo will look for it's dependencies. + + +``` +hugo mod vendor [flags] [args] +``` + +### Options + +``` + -h, --help help for vendor +``` + +### Options inherited from parent commands + +``` + --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00 + --config string config file (default is hugo.yaml|json|toml) + --configDir string config dir (default "config") + --debug debug output + -d, --destination string filesystem path to write files to + -e, --environment string build environment ++ --format string preferred file format (toml, yaml or json) (default "toml") + --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern + --log enable Logging + --logFile string log File path (if set, logging enabled automatically) + --quiet build in quiet mode + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output + --verboseLog verbose logging +``` + +### SEE ALSO + +* [hugo mod](/commands/hugo_mod/) - Various Hugo Modules helpers. + diff --cc docs/content/en/commands/hugo_mod_verify.md index 9cddcbc25,000000000..dd41f29fd mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_mod_verify.md +++ b/docs/content/en/commands/hugo_mod_verify.md @@@ -1,47 -1,0 +1,48 @@@ +--- +title: "hugo mod verify" +slug: hugo_mod_verify +url: /commands/hugo_mod_verify/ +--- +## hugo mod verify + +Verify dependencies. + +### Synopsis + +Verify checks that the dependencies of the current module, which are stored in a local downloaded source cache, have not been modified since being downloaded. + +``` +hugo mod verify [flags] [args] +``` + +### Options + +``` + --clean delete module cache for dependencies that fail verification + -h, --help help for verify +``` + +### Options inherited from parent commands + +``` + --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00 + --config string config file (default is hugo.yaml|json|toml) + --configDir string config dir (default "config") + --debug debug output + -d, --destination string filesystem path to write files to + -e, --environment string build environment ++ --format string preferred file format (toml, yaml or json) (default "toml") + --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern + --log enable Logging + --logFile string log File path (if set, logging enabled automatically) + --quiet build in quiet mode + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output + --verboseLog verbose logging +``` + +### SEE ALSO + +* [hugo mod](/commands/hugo_mod/) - Various Hugo Modules helpers. + diff --cc docs/content/en/commands/hugo_version.md index b78237bb7,000000000..35b720153 mode 100644,000000..100644 --- a/docs/content/en/commands/hugo_version.md +++ b/docs/content/en/commands/hugo_version.md @@@ -1,46 -1,0 +1,47 @@@ +--- +title: "hugo version" +slug: hugo_version +url: /commands/hugo_version/ +--- +## hugo version + +Print Hugo version and environment info + +### Synopsis + +Print Hugo version and environment info. This is useful in Hugo bug reports. + +``` +hugo version [flags] [args] +``` + +### Options + +``` + -h, --help help for version +``` + +### Options inherited from parent commands + +``` + --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00 + --config string config file (default is hugo.yaml|json|toml) + --configDir string config dir (default "config") + --debug debug output + -d, --destination string filesystem path to write files to + -e, --environment string build environment ++ --format string preferred file format (toml, yaml or json) (default "toml") + --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern + --log enable Logging + --logFile string log File path (if set, logging enabled automatically) + --quiet build in quiet mode + -s, --source string filesystem path to read files relative from + --themesDir string filesystem path to themes directory + -v, --verbose verbose output + --verboseLog verbose logging +``` + +### SEE ALSO + +* [hugo](/commands/hugo/) - hugo builds your site + diff --cc docs/content/en/content-management/cross-references.md index 00fb2d973,000000000..a2b3f8e1c mode 100644,000000..100644 --- a/docs/content/en/content-management/cross-references.md +++ b/docs/content/en/content-management/cross-references.md @@@ -1,153 -1,0 +1,153 @@@ +--- +title: Links and Cross References +linkTitle: Links and Cross References +description: Shortcodes for creating links to documents. +categories: [content management] +keywords: ["cross references","references", "anchors", "urls"] +menu: + docs: + parent: content-management + weight: 170 +toc: true +weight: 170 +aliases: [/extras/crossreferences/] +--- + +The `ref` and `relref` shortcodes display the absolute and relative permalinks to a document, respectively. + +## Use of `ref` and `relref` + +The `ref` and `relref` shortcodes require a single parameter: the path to a content document, with or without a file extension, with or without an anchor. Paths without a leading `/` are first resolved relative to the current page, then to the remainder of the site. + +``` +. +└── content + ├── about + | ├── _index.md + | └── credits.md + ├── pages + | ├── document1.md + | └── document2.md // has anchor #anchor + ├── products + | └── index.md + └── blog + └── my-post.md +``` + +The pages can be referenced as follows: + + +```text +{{}} // <- From pages/document1.md, relative path +{{}} +{{}} +{{}} +{{}} // <- From pages/document2.md +{{}} // <- From anywhere, absolute path +{{}} +{{}} +{{}} +{{}} +{{}} +``` + +index.md can be reference either by its path or by its containing folder without the ending `/`. \_index.md can be referenced only by its containing folder: + +```text +{{}} // <- References /about/_index.md +{{}} // Raises REF_NOT_FOUND error +{{}} // <- References /about/credits.md + +{{}} // <- References /products/index.md +{{}} // <- References /products/index.md +``` + +To generate a hyperlink using `ref` or `relref` in markdown: + +```text +[About]({{}} "About Us") +``` + +Hugo emits an error or warning if a document cannot be uniquely resolved. The error behavior is configurable; see below. + +### Link to another language version + +To link to another language version of a document, use this syntax: + +```go-html-template +{{}} +``` + +### Get another Output Format + +To link to another Output Format of a document, use this syntax: + +```go-html-template +{{}} +``` + +### Heading IDs + +When using Markdown document types, Hugo generates element IDs for every heading on a page. For example: + +```md +## Reference +``` + +produces this HTML: + +```html +

Reference

+``` + +Get the permalink to a heading by appending the ID to the path when using the `ref` or `relref` shortcodes: + +```go-html-template +{{}} +{{}} +``` + +Generate a custom heading ID by including an attribute. For example: + +```md +## Reference A {#foo} +## Reference B {id="bar"} +``` + +produces this HTML: + +```html +

Reference A

+

Reference B

+``` + +Hugo will generate unique element IDs if the same heading appears more than once on a page. For example: + +```md +## Reference +## Reference +## Reference +``` + +produces this HTML: + +```html +

Reference

+

Reference

+

Reference

+``` + +## Ref and RelRef Configuration + - The behavior can, since Hugo 0.45, be configured in `config.toml`: ++The behavior can, since Hugo 0.45, be configured in `hugo.toml`: + +refLinksErrorLevel ("ERROR") +: When using `ref` or `relref` to resolve page links and a link cannot resolved, it will be logged with this log level. Valid values are `ERROR` (default) or `WARNING`. Any `ERROR` will fail the build (`exit -1`). + +refLinksNotFoundURL +: URL to be used as a placeholder when a page reference cannot be found in `ref` or `relref`. Is used as-is. + + +[lists]: /templates/lists/ +[output formats]: /templates/output-formats/ +[shortcode]: /content-management/shortcodes/ diff --cc docs/content/en/content-management/front-matter.md index 78d3323dd,000000000..062288320 mode 100644,000000..100644 --- a/docs/content/en/content-management/front-matter.md +++ b/docs/content/en/content-management/front-matter.md @@@ -1,239 -1,0 +1,239 @@@ +--- +title: Front Matter +description: Hugo allows you to add front matter in yaml, toml, or json to your content files. +categories: [content management] +keywords: ["front matter", "yaml", "toml", "json", "metadata", "archetypes"] +menu: + docs: + parent: content-management + weight: 60 +toc: true +weight: 60 +aliases: [/content/front-matter/] +--- + +**Front matter** allows you to keep metadata attached to an instance of a [content type]---i.e., embedded inside a content file---and is one of the many features that gives Hugo its strength. + +{{< youtube Yh2xKRJGff4 >}} + +## Front Matter Formats + +Hugo supports four formats for front matter, each with their own identifying tokens. + +TOML +: identified by opening and closing `+++`. + +YAML +: identified by opening and closing `---`. + +JSON +: a single JSON object surrounded by '`{`' and '`}`', followed by a new line. + +ORG +: a group of Org mode keywords in the format '`#+KEY: VALUE`'. Any line that does not start with `#+` ends the front matter section. + Keyword values can be either strings (`#+KEY: VALUE`) or a whitespace separated list of strings (`#+KEY[]: VALUE_1 VALUE_2`). + +### Example + +{{< code-toggle >}} +title = "spf13-vim 3.0 release and new website" +description = "spf13-vim is a cross platform distribution of vim plugins and resources for Vim." +tags = [ ".vimrc", "plugins", "spf13-vim", "vim" ] +date = "2012-04-06" +categories = [ + "Development", + "VIM" +] +slug = "spf13-vim-3-0-release-and-new-website" +{{< /code-toggle >}} + +## Front Matter Variables + +### Predefined + +There are a few predefined variables that Hugo is aware of. See [Page Variables][pagevars] for how to call many of these predefined variables in your templates. + +aliases +: An array of one or more aliases (e.g., old published paths of renamed content) that will be created in the output directory structure . See [Aliases][aliases] for details. + +audio +: An array of paths to audio files related to the page; used by the `opengraph` [internal template](/templates/internal) to populate `og:audio`. + +cascade +: A map of front matter keys whose values are passed down to the page's descendants unless overwritten by self or a closer ancestor's cascade. See [Front Matter Cascade](#front-matter-cascade) for details. + +date +: The datetime assigned to this page. This is usually fetched from the `date` field in front matter, but this behavior is configurable. + +description +: The description for the content. + +draft +: If `true`, the content will not be rendered unless the `--buildDrafts` flag is passed to the `hugo` command. + +expiryDate +: The datetime at which the content should no longer be published by Hugo; expired content will not be rendered unless the `--buildExpired` flag is passed to the `hugo` command. + +headless +: If `true`, sets a leaf bundle to be [headless][headless-bundle]. + +images +: An array of paths to images related to the page; used by [internal templates](/templates/internal) such as `_internal/twitter_cards.html`. + +isCJKLanguage +: If `true`, Hugo will explicitly treat the content as a CJK language; both `.Summary` and `.WordCount` work properly in CJK languages. + +keywords +: The meta keywords for the content. + +layout +: The layout Hugo should select from the [lookup order][lookup] when rendering the content. If a `type` is not specified in the front matter, Hugo will look for the layout of the same name in the layout directory that corresponds with a content's section. See [Content Types][content type]. + +lastmod +: The datetime at which the content was last modified. + +linkTitle +: Used for creating links to content; if set, Hugo defaults to using the `linktitle` before the `title`. Hugo can also [order lists of content by `linktitle`][bylinktitle]. + +markup +: **experimental**; specify `"rst"` for reStructuredText (requires`rst2html`) or `"md"` (default) for Markdown. + +outputs +: Allows you to specify output formats specific to the content. See [output formats][outputs]. + +publishDate +: If in the future, content will not be rendered unless the `--buildFuture` flag is passed to `hugo`. + +resources +: Used for configuring page bundle resources. See [Page Resources][page-resources]. + +series +: An array of series this page belongs to, as a subset of the `series` [taxonomy](/content-management/taxonomies/); used by the `opengraph` [internal template](/templates/internal) to populate `og:see_also`. + +slug +: Overrides the last segment of the URL path. Not applicable to section pages. See [URL Management](/content-management/urls/#slug) for details. + +summary +: Text used when providing a summary of the article in the `.Summary` page variable; details available in the [content-summaries](/content-management/summaries/) section. + +title +: The title for the content. + +type +: The type of the content; this value will be automatically derived from the directory (i.e., the [section]) if not specified in front matter. + +url +: Overrides the entire URL path. Applicable to regular pages and section pages. See [URL Management](/content-management/urls/#url) for details. + +videos +: An array of paths to videos related to the page; used by the `opengraph` [internal template](/templates/internal) to populate `og:video`. + +weight +: used for [ordering your content in lists][ordering]. Lower weight gets higher precedence. So content with lower weight will come first. If set, weights should be non-zero, as 0 is interpreted as an *unset* weight. + +\ +: Field name of the *plural* form of the index. See `tags` and `categories` in the above front matter examples. *Note that the plural form of user-defined taxonomies cannot be the same as any of the predefined front matter variables.* + +{{% note %}} - If neither `slug` nor `url` is present and [permalinks are not configured otherwise in your site `config` file](/content-management/urls/#permalinks), Hugo will use the filename of your content to create the output URL. See [Content Organization](/content-management/organization) for an explanation of paths in Hugo and [URL Management](/content-management/urls/) for ways to customize Hugo's default behaviors. ++If neither `slug` nor `url` is present and [permalinks are not configured otherwise in your site configuration file](/content-management/urls/#permalinks), Hugo will use the filename of your content to create the output URL. See [Content Organization](/content-management/organization) for an explanation of paths in Hugo and [URL Management](/content-management/urls/) for ways to customize Hugo's default behaviors. +{{% /note %}} + +### User-Defined + +You can add fields to your front matter arbitrarily to meet your needs. These user-defined key-values are placed into a single `.Params` variable for use in your templates. + +The following fields can be accessed via `.Params.include_toc` and `.Params.show_comments`, respectively. The [Variables] section provides more information on using Hugo's page- and site-level variables in your templates. + +{{< code-toggle copy=false >}} +include_toc: true +show_comments: false +{{}} + +## Front Matter Cascade + +Any node or section can pass down to descendants a set of Front Matter values as long as defined underneath the reserved `cascade` Front Matter key. + +### Target Specific Pages + +The `cascade` block can be a slice with a optional `_target` keyword, allowing for multiple `cascade` values targeting different page sets. + +{{< code-toggle copy=false >}} +title ="Blog" +[[cascade]] +background = "yosemite.jpg" +[cascade._target] +path="/blog/**" +lang="en" +kind="page" +[[cascade]] +background = "goldenbridge.jpg" +[cascade._target] +kind="section" +{{}} + +Keywords available for `_target`: + +path +: A [Glob](https://github.com/gobwas/glob) pattern matching the content path below /content. Expects Unix-styled slashes. Note that this is the virtual path, so it starts at the mount root. The matching supports double-asterisks so you can match for patterns like `/blog/*/**` to match anything from the third level and down. + +kind +: A Glob pattern matching the Page's Kind(s), e.g. "{home,section}". + +lang +: A Glob pattern matching the Page's language, e.g. "{en,sv}". + +environment +: A Glob pattern matching the build environment, e.g. "{production,development}" + +Any of the above can be omitted. + +### Example + +In `content/blog/_index.md` + +{{< code-toggle copy=false >}} +title: Blog +cascade: + banner: images/typewriter.jpg +{{}} + +With the above example the Blog section page and its descendants will return `images/typewriter.jpg` when `.Params.banner` is invoked unless: + +- Said descendant has its own `banner` value set +- Or a closer ancestor node has its own `cascade.banner` value set. + +## Order Content Through Front Matter + +You can assign content-specific `weight` in the front matter of your content. These values are especially useful for [ordering][ordering] in list views. You can use `weight` for ordering of content and the convention of [`_weight`][taxweight] for ordering content within a taxonomy. See [Ordering and Grouping Hugo Lists][lists] to see how `weight` can be used to organize your content in list views. + +## Override Global Markdown Configuration + +It's possible to set some options for Markdown rendering in a content's front matter as an override to the [Rendering options set in your project configuration][config]. + +## Front Matter Format Specs + +- [TOML Spec][toml] +- [YAML Spec][yaml] +- [JSON Spec][json] + +[variables]: /variables/ +[aliases]: /content-management/urls/#aliases +[archetype]: /content-management/archetypes/ +[bylinktitle]: /templates/lists/#by-link-title +[config]: /getting-started/configuration/ "Hugo documentation for site configuration" +[content type]: /content-management/types/ +[contentorg]: /content-management/organization/ +[headless-bundle]: /content-management/page-bundles/#headless-bundle +[json]: https://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf "Specification for JSON, JavaScript Object Notation" +[lists]: /templates/lists/#order-content "See how to order content in list pages; for example, templates that look to specific _index.md for content and front matter." +[lookup]: /templates/lookup-order/ "Hugo traverses your templates in a specific order when rendering content to allow for DRYer templating." +[ordering]: /templates/lists/ "Hugo provides multiple ways to sort and order your content in list templates" +[outputs]: /templates/output-formats/ "With the release of v22, you can output your content to any text format using Hugo's familiar templating" +[page-resources]: /content-management/page-resources/ +[pagevars]: /variables/page/ +[section]: /content-management/sections/ +[taxweight]: /content-management/taxonomies/ +[toml]: https://github.com/toml-lang/toml "Specification for TOML, Tom's Obvious Minimal Language" +[urls]: /content-management/urls/ +[variables]: /variables/ +[yaml]: https://yaml.org/spec/ "Specification for YAML, YAML Ain't Markup Language" diff --cc docs/content/en/content-management/image-processing/index.md index 0043f97b0,000000000..3d70951b3 mode 100644,000000..100644 --- a/docs/content/en/content-management/image-processing/index.md +++ b/docs/content/en/content-management/image-processing/index.md @@@ -1,476 -1,0 +1,476 @@@ +--- +title: Image Processing +description: Resize, crop, rotate, filter, and convert images. +categories: [content management] +keywords: [resources, images] +menu: + docs: + parent: content-management + weight: 90 +toc: true +weight: 90 +--- +## Image Resources + +To process an image, you must access the image as either a page resource or a global resource. + +### Page Resources + +A page resource is a file within a [page bundle]. A page bundle is a directory with an `index.md` or `_index.md` file at its root. + +```text +content/ +└── posts/ + └── post-1/ <-- page bundle + ├── index.md + └── sunset.jpg <-- page resource +``` + +### Global Resources + +A global resource is a file: + +- Within the `assets` directory, or +- Within any directory [mounted] to the `assets` directory, or +- Located on a remote server accessible via `http` or `https` + +```text +assets/ +└── images/ + └── sunset.jpg <-- global resource +``` + +To access a local image as a global resource: + +```go-html-template +{{ $image := resources.Get "images/sunset.jpg" }} +``` + +To access a remote image as a global resource: + +```go-html-template +{{ $image := resources.GetRemote "https://gohugo.io/img/hugo-logo.png" }} +``` + +## Image Rendering + +Once you have accessed an image as either a page resource or a global resource, render it in your templates using the `Permalink`, `RelPermalink`, `Width`, and `Height` properties. + +Example 1: Throws an error if the resource is not found. + +```go-html-template +{{ $image := .Resources.GetMatch "sunset.jpg" }} + +``` + +Example 2: Skips image rendering if the resource is not found. + +```go-html-template +{{ $image := .Resources.GetMatch "sunset.jpg" }} +{{ with $image }} + +{{ end }} +``` + +Example 3: A more concise way to skip image rendering if the resource is not found. + +```go-html-template +{{ with .Resources.GetMatch "sunset.jpg" }} + +{{ end }} +``` + +## Image Processing Methods + +The `image` resource implements the [`Resize`], [`Fit`], [`Fill`], [`Crop`], [`Filter`], [`Colors`] and [`Exif`] methods. + +{{% note %}} +Metadata (Exif, IPTC, XMP, etc.) is not preserved during image transformation. Use the [`Exif`] method with the _original_ image to extract Exif metadata from JPEG or TIFF images. +{{% /note %}} + +### Resize + +Resize an image to the specified width and/or height. + +If you specify both width and height, the resulting image will be disproportionally scaled unless the original image has the same aspect ratio. + +```go-html-template +{{/* Resize to a width of 600px and preserve aspect ratio */}} +{{ $image := $image.Resize "600x" }} + +{{/* Resize to a height of 400px and preserve aspect ratio */}} +{{ $image := $image.Resize "x400" }} + +{{/* Resize to a width of 600px and a height of 400px */}} +{{ $image := $image.Resize "600x400" }} +``` + +### Fit + +Downscale an image to fit the given dimensions while maintaining aspect ratio. You must provide both width and height. + +```go-html-template +{{ $image := $image.Fit "600x400" }} +``` + +### Fill + +Crop and resize an image to match the given dimensions. You must provide both width and height. Use the [`anchor`] option to change the crop box anchor point. + +```go-html-template +{{ $image := $image.Fill "600x400" }} +``` + +### Crop + +Crop an image to match the given dimensions without resizing. You must provide both width and height. Use the [`anchor`] option to change the crop box anchor point. + +```go-html-template +{{ $image := $image.Crop "600x400" }} +``` + +### Filter + +Apply one or more [filters] to an image. + +```go-html-template +{{ $image := $image.Filter (images.GaussianBlur 6) (images.Pixelate 8) }} +``` + +Write this in a more functional style using pipes. Hugo applies the filters in the order given. + +```go-html-template +{{ $image := $image | images.Filter (images.GaussianBlur 6) (images.Pixelate 8) }} +``` + +Sometimes it can be useful to create the filter chain once and then reuse it. + +```go-html-template +{{ $filters := slice (images.GaussianBlur 6) (images.Pixelate 8) }} +{{ $image1 := $image1.Filter $filters }} +{{ $image2 := $image2.Filter $filters }} +``` + +### Colors + +{{< new-in "0.104.0" >}} + +`.Colors` returns a slice of hex strings with the dominant colors in the image using a simple histogram method. + +```go-html-template +{{ $colors := $image.Colors }} +``` + +This method is fast, but if you also scale down your images, it would be good for performance to extract the colors from the scaled down image. + + +### Exif + +Provides an [Exif] object containing image metadata. + +You may access Exif data in JPEG and TIFF images. To prevent errors when processing images without Exif data, wrap the access in a [`with`] statement. + +```go-html-template +{{ with $image.Exif }} + Date: {{ .Date }} + Lat/Long: {{ .Lat }}/{{ .Long }} + Tags: + {{ range $k, $v := .Tags }} + TAG: {{ $k }}: {{ $v }} + {{ end }} +{{ end }} +``` + +You may also access Exif fields individually, using the [`lang.FormatNumber`] function to format the fields as needed. + +```go-html-template +{{ with $image.Exif }} +
    + {{ with .Date }}
  • Date: {{ .Format "January 02, 2006" }}
    • {{ end }} + {{ with .Tags.ApertureValue }}
  • Aperture: {{ lang.FormatNumber 2 . }}
    • {{ end }} + {{ with .Tags.BrightnessValue }}
  • Brightness: {{ lang.FormatNumber 2 . }}
    • {{ end }} + {{ with .Tags.ExposureTime }}
  • Exposure Time: {{ . }}
    • {{ end }} + {{ with .Tags.FNumber }}
  • F Number: {{ . }}
    • {{ end }} + {{ with .Tags.FocalLength }}
  • Focal Length: {{ . }}
    • {{ end }} + {{ with .Tags.ISOSpeedRatings }}
  • ISO Speed Ratings: {{ . }}
    • {{ end }} + {{ with .Tags.LensModel }}
  • Lens Model: {{ . }}
    • {{ end }} +
+{{ end }} +``` + +#### Exif Variables + +.Date +: Image creation date/time. Format with the [time.Format] function. + +.Lat +: GPS latitude in degrees. + +.Long +: GPS longitude in degrees. + +.Tags +: A collection of the available Exif tags for this image. You may include or exclude specific tags from this collection in the [site configuration](#exif-data). + +## Image Processing Options + +The [`Resize`], [`Fit`], [`Fill`], and [`Crop`] methods accept a space-separated, case-insensitive list of options. The order of the options within the list is irrelevant. + +### Dimensions + +With the [`Resize`] method you must specify width, height, or both. The [`Fit`], [`Fill`], and [`Crop`] methods require both width and height. All dimensions are in pixels. + +```go-html-template +{{ $image := $image.Resize "600x" }} +{{ $image := $image.Resize "x400" }} +{{ $image := $image.Resize "600x400" }} +{{ $image := $image.Fit "600x400" }} +{{ $image := $image.Fill "600x400" }} +{{ $image := $image.Crop "600x400" }} +``` + +### Rotation + +Rotates an image counter-clockwise by the given angle. Hugo performs rotation _before_ scaling. For example, if the original image is 600x400 and you wish to rotate the image 90 degrees counter-clockwise while scaling it by 50%: + +```go-html-template +{{ $image = $image.Resize "200x r90" }} +``` + +In the example above, the width represents the desired width _after_ rotation. + +To rotate an image without scaling, use the dimensions of the original image: + +```go-html-template +{{ with .Resources.GetMatch "sunset.jpg" }} + {{ with .Resize (printf "%dx%d r90" .Height .Width) }} + + {{ end }} +{{ end }} +``` + +In the example above, on the second line, we have reversed width and height to reflect the desired dimensions _after_ rotation. + +### Anchor + +When using the [`Crop`] or [`Fill`] method, the _anchor_ determines the placement of the crop box. You may specify `TopLeft`, `Top`, `TopRight`, `Left`, `Center`,`Right`, `BottomLeft`, `Bottom`, `BottomRight`, or `Smart`. + +The default value is `Smart`, which uses [Smartcrop] image analysis to determine the optimal placement of the crop box. You may override the default value in the [site configuration]. + +For example, if you have a 400x200 image with a bird in the upper left quadrant, you can create a 200x100 thumbnail containing the bird: + +```go-html-template +{{ $image.Crop "200x100 TopLeft" }} +``` + +If you apply [rotation](#rotation) when using the [`Crop`] or [`Fill`] method, specify the anchor relative to the rotated image. + +### Target Format + +By default, Hugo encodes the image in the source format. You may convert the image to another format by specifying `bmp`, `gif`, `jpeg`, `jpg`, `png`, `tif`, `tiff`, or `webp`. + +```go-html-template +{{ $image.Resize "600x webp" }} +``` + +To convert an image without scaling, use the dimensions of the original image: + +```go-html-template +{{ with .Resources.GetMatch "sunset.jpg" }} + {{ with .Resize (printf "%dx%d webp" .Width .Height) }} + + {{ end }} +{{ end }} +``` + +### Quality + +Applicable to JPEG and WebP images, the `q` value determines the quality of the converted image. Higher values produce better quality images, while lower values produce smaller files. Set this value to a whole number between 1 and 100, inclusive. + +The default value is 75. You may override the default value in the [site configuration]. + +```go-html-template +{{ $image.Resize "600x webp q50" }} +``` + +### Hint + + + +Applicable to WebP images, this option corresponds to a set of predefined encoding parameters. + +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 + +The default value is `photo`. You may override the default value in the [site configuration]. + +```go-html-template +{{ $image.Resize "600x webp picture" }} +``` + +### Background Color + +When converting an image from a format that supports transparency (e.g., PNG) to a format that does _not_ support transparency (e.g., JPEG), you may specify the background color of the resulting image. + +Use either a 3-digit or a 6-digit hexadecimal color code (e.g., `#00f` or `#0000ff`). + +The default value is `#ffffff` (white). You may override the default value in the [site configuration]. + +```go-html-template +{{ $image.Resize "600x jpg #b31280" }} +``` + +### Resampling Filter + +You may specify the resampling filter used when resizing an image. Commonly used resampling filters include: + +Filter|Description +:--|:-- +`Box`|Simple and fast averaging filter appropriate for downscaling +`Lanczos`|High-quality resampling filter for photographic images yielding sharp results +`CatmullRom`|Sharp cubic filter that is faster than the Lanczos filter while providing similar results +`MitchellNetravali`|Cubic filter that produces smoother results with less ringing artifacts than CatmullRom +`Linear`|Bilinear resampling filter, produces smooth output, faster than cubic filters +`NearestNeighbor`|Fastest resampling filter, no antialiasing + +The default value is `Box`. You may override the default value in the [site configuration]. + +```go-html-template +{{ $image.Resize "600x400 Lanczos" }} +``` + +See [github.com/disintegration/imaging] for the complete list of resampling filters. If you wish to improve image quality at the expense of performance, you may wish to experiment with the alternative filters. + +## Image Processing Examples + +_The photo of the sunset used in the examples below is Copyright [Bjørn Erik Pedersen](https://commons.wikimedia.org/wiki/User:Bep) (Creative Commons Attribution-Share Alike 4.0 International license)_ + +{{< imgproc sunset Resize "300x" />}} + +{{< imgproc sunset Fill "90x120 left" />}} + +{{< imgproc sunset Fill "90x120 right" />}} + +{{< imgproc sunset Fit "90x90" />}} + +{{< imgproc sunset Crop "250x250 center" />}} + +{{< imgproc sunset Resize "300x q10" />}} + +This is the shortcode used to generate the examples above: + +{{< code file="layouts/shortcodes/imgproc.html" >}} +{{< readfile file="layouts/shortcodes/imgproc.html" >}} +{{< /code >}} + +Call the shortcode from your Markdown like this: + +```go-html-template +{{}} +``` + +{{% note %}} +Note the self-closing shortcode syntax above. You may call the `imgproc` shortcode with or without **inner content**. +{{% /note %}} + +## Imaging Configuration + +### Processing Options + +Define an `imaging` section in your site configuration to set the default [image processing options](#image-processing-options). + - {{< code-toggle file="config" copy=true >}} ++{{< code-toggle file="hugo" copy=true >}} +[imaging] +resampleFilter = "Box" +quality = 75 +hint = "photo" +anchor = "Smart" +bgColor = "#ffffff" +{{< /code-toggle >}} + +anchor +: See image processing options: [anchor](#anchor). + +bgColor +: See image processing options: [background color](#background-color). + +hint +: See image processing options: [hint](#hint). + +quality +: See image processing options: [quality](#quality). + +resampleFilter +: See image processing options: [resampling filter](#resampling-filter). + +### Exif Data + +Define an `imaging.exif` section in your site configuration to control the availability of Exif data. + - {{< code-toggle file="config" copy=true >}} ++{{< code-toggle file="hugo" copy=true >}} +[imaging.exif] +includeFields = "" +excludeFields = "" +disableDate = false +disableLatLong = false +{{< /code-toggle >}} + +disableDate +: Hugo extracts the image creation date/time into `.Date`. Set this to `true` to disable. Default is `false`. + +disableLatLong +: Hugo extracts the GPS latitude and longitude into `.Lat` and `.Long`. Set this to `true` to disable. Default is `false`. + +excludeFields +: Regular expression matching the Exif tags to exclude from the `.Tags` collection. Default is `""`. + +includeFields +: Regular expression matching the Exif tags to include in the `.Tags` collection. Default is `""`. To include all available tags, set this value to `".*"`. + +{{% note %}} +To improve performance and decrease cache size, if you set neither `excludeFields` nor `includeFields`, Hugo excludes the following tags: `ColorSpace`, `Contrast`, `Exif`, `Exposure[M|P|B]`, `Flash`, `GPS`, `JPEG`, `Metering`, `Resolution`, `Saturation`, `Sensing`, `Sharp`, and `WhiteBalance`. +{{% /note %}} + +## Smart Cropping of Images + +By default, Hugo uses the [Smartcrop] library when cropping images with the `Crop` or`Fill` methods. You can set the anchor point manually, but in most cases the `Smart` option will make a good choice. + +Examples using the sunset image from above: + +{{< imgproc sunset Fill "200x200 smart" />}} + +{{< imgproc sunset Crop "200x200 smart" />}} + +## Image Processing Performance Consideration + +Hugo caches processed images in the `resources` directory. If you include this directory in source control, Hugo will not have to regenerate the images in a CI/CD workflow (e.g., GitHub Pages, GitLab Pages, Netlify, etc.). This results in faster builds. + +If you change image processing methods or options, or if you rename or remove images, the `resources` directory will contain unused images. To remove the unused images, perform garbage collection with: + +```bash +hugo --gc +``` + +[time.Format]: /functions/dateformat +[`anchor`]: /content-management/image-processing#anchor +[mounted]: /hugo-modules/configuration#module-config-mounts +[page bundle]: /content-management/page-bundles +[`lang.FormatNumber`]: /functions/lang +[filters]: /functions/images +[github.com/disintegration/imaging]: +[Smartcrop]: +[Exif]: +[`Colors`]: #colors +[`Crop`]: #crop +[`Exif`]: #exif +[`Fill`]: #fill +[`Filter`]: #filter +[`Fit`]: #fit +[`Resize`]: #resize +[site configuration]: #processing-options +[`with`]: /functions/with/ diff --cc docs/content/en/content-management/menus.md index 369938aba,000000000..07bf41669 mode 100644,000000..100644 --- a/docs/content/en/content-management/menus.md +++ b/docs/content/en/content-management/menus.md @@@ -1,225 -1,0 +1,225 @@@ +--- +title: Menus +description: Create menus by defining entries, localizing each entry, and rendering the resulting data structure. +categories: [content management] +keywords: [menus] +menu: + docs: + parent: content-management + weight: 190 +toc: true +weight: 190 +aliases: [/extras/menus/] +--- + +## Overview + +To create a menu for your site: + +1. Define the menu entries +2. [Localize] each entry +3. 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. + +There are three ways to define menu entries: + +1. Automatically +1. In front matter +1. In site configuration + +{{% 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. +{{% /note %}} + +## Define automatically + +To automatically define menu entries for each top-level section of your site, enable the section pages menu in your site configuration. + - {{< code-toggle file="config" copy=false >}} ++{{< code-toggle file="hugo" copy=false >}} +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. + +## Define in front matter + +To add a page to the "main" menu: + +{{< code-toggle file="content/about.md" copy=false fm=true >}} +title = 'About' +menu = 'main' +{{< /code-toggle >}} + +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: + +{{< code-toggle file="content/contact.md" copy=false fm=true >}} +title = 'Contact' +menu = ['main','footer'] +{{< /code-toggle >}} + +Access the entry with `site.Menus.main` and `site.Menus.footer` in your templates. See [menu templates] for details. + +### Properties {#properties-front-matter} + +Use these properties when defining menu entries in front matter: + +identifier +: (`string`) Required when two or more menu entries have the same `name`, or when localizing the `name` using translation tables. Must start with a letter, followed by letters, digits, or underscores. + +name +: (`string`) The text to display when rendering the menu entry. + +params +: (`map`) User-defined properties for the menu entry. + +parent +: (`string`) The `identifier` of the parent menu entry. If `identifier` is not defined, use `name`. Required for child entries in a nested menu. + +post +: (`string`) The HTML to append when rendering the menu entry. + +pre +: (`string`) The HTML to prepend when rendering the menu entry. + +title +: (`string`) The HTML `title` attribute of the rendered menu entry. + +weight +: (`int`) A non-zero integer indicating the entry's position relative the root of the menu, or to its parent for a child entry. Lighter entries float to the top, while heavier entries sink to the bottom. + +### Example {#example-front-matter} + +This front matter menu entry demonstrates some of the available properties: + +{{< code-toggle file="content/products/software.md" copy=false fm=true >}} +title = 'Software' +[menu.main] +parent = 'Products' +weight = 20 +pre = '' +[menu.main.params] +class = 'center' +{{< /code-toggle >}} + +Access the entry with `site.Menus.main` in your templates. See [menu templates] for details. + + +## Define in site configuration + +To define entries for the "main" menu: + - {{< code-toggle file="config" copy=false >}} ++{{< code-toggle file="hugo" copy=false >}} +[[menu.main]] +name = 'Home' +pageRef = '/' +weight = 10 + +[[menu.main]] +name = 'Products' +pageRef = '/products' +weight = 20 + +[[menu.main]] +name = 'Services' +pageRef = '/services' +weight = 30 +{{< /code-toggle >}} + +This creates a menu structure that you can access with `site.Menus.main` in your templates. See [menu templates] for details. + +To define entries for the "footer" menu: + - {{< code-toggle file="config" copy=false >}} ++{{< code-toggle file="hugo" copy=false >}} +[[menu.footer]] +name = 'Terms' +pageRef = '/terms' +weight = 10 + +[[menu.footer]] +name = 'Privacy' +pageRef = '/privacy' +weight = 20 +{{< /code-toggle >}} + +This creates a menu structure that you can access with `site.Menus.footer` in your templates. See [menu templates] for details. + +### Properties {#properties-site-configuration} + +{{% note %}} +The [properties available to entries defined in front matter] are also available to entries defined in site configuration. + +[properties available to entries defined in front matter]: /content-management/menus/#properties-front-matter +{{% /note %}} + +Each menu entry defined in site configuration requires two or more properties: + +- Specify `name` and `pageRef` for internal links +- Specify `name` and `url` for external links + +pageRef +: (`string`) The file path of the target page, relative to the `content` directory. Omit language code and file extension. Required for *internal* links. + +Kind|pageRef +:--|:-- +home|`/` +page|`/books/book-1` +section|`/books` +taxonomy|`/tags` +term|`/tags/foo` + +url +: (`string`) Required for *external* links. + +### Example {#example-site-configuration} + +This nested menu demonstrates some of the available properties: + - {{< code-toggle file="config" copy=false >}} ++{{< code-toggle file="hugo" copy=false >}} +[[menu.main]] +name = 'Products' +pageRef = '/products' +weight = 10 + +[[menu.main]] +name = 'Hardware' +pageRef = '/products/hardware' +parent = 'Products' +weight = 1 + +[[menu.main]] +name = 'Software' +pageRef = '/products/software' +parent = 'Products' +weight = 2 + +[[menu.main]] +name = 'Services' +pageRef = '/services' +weight = 20 + +[[menu.main]] +name = 'Hugo' +pre = '' +url = 'https://gohugo.io/' +weight = 30 +[menu.main.params] +rel = 'external' +{{< /code-toggle >}} + +This creates a menu structure that you can access with `site.Menus.main` in your templates. See [menu templates] for details. + +## Localize + +Hugo provides two methods to localize your menu entries. See [multilingual]. + +## Render + +See [menu templates]. + +[localize]: /content-management/multilingual/#menus +[menu templates]: /templates/menu-templates/ +[multilingual]: /content-management/multilingual/#menus +[template]: /templates/menu-templates/ diff --cc docs/content/en/content-management/multilingual.md index f1f25086a,000000000..71adc214d mode 100644,000000..100644 --- a/docs/content/en/content-management/multilingual.md +++ b/docs/content/en/content-management/multilingual.md @@@ -1,652 -1,0 +1,652 @@@ +--- +title: Multilingual Mode +linkTitle: Multilingual +description: Hugo supports the creation of websites with multiple languages side by side. +categories: [content management] +keywords: [multilingual,i18n, internationalization] +menu: + docs: + parent: content-management + weight: 230 +toc: true +weight: 230 +aliases: [/content/multilingual/,/tutorials/create-a-multilingual-site/] +--- + +You should define the available languages in a `languages` section in your site configuration. + +Also See [Hugo Multilingual Part 1: Content translation]. + +## Configure Languages + +The following is an example of a site configuration for a multilingual Hugo project: + - {{< code-toggle file="config" >}} ++{{< code-toggle file="hugo" >}} +defaultContentLanguage = "en" +copyright = "Everything is mine" + +[params] +[params.navigation] +help = "Help" + +[languages] +[languages.en] +title = "My blog" +weight = 1 +[languages.en.params] +linkedin = "https://linkedin.com/whoever" + +[languages.fr] +title = "Mon blogue" +weight = 2 +[languages.fr.params] +linkedin = "https://linkedin.com/fr/whoever" +[languages.fr.params.navigation] +help = "Aide" + +[languages.ar] +title = "مدونتي" +weight = 2 +languagedirection = "rtl" + +[languages.pt-pt] +title = "O meu blog" +weight = 3 +{{< /code-toggle >}} + +Anything not defined in a `languages` block will fall back to the global value for that key (e.g., `copyright` for the English `en` language). This also works for `params`, as demonstrated with `help` above: You will get the value `Aide` in French and `Help` in all the languages without this parameter set. + +With the configuration above, all content, sitemap, RSS feeds, pagination, +and taxonomy pages will be rendered below `/` in English (your default content language) and then below `/fr` in French. + +When working with front matter `Params` in [single page templates], omit the `params` in the key for the translation. + +`defaultContentLanguage` sets the project's default language. If not set, the default language will be `en`. + +If the default language needs to be rendered below its own language code (`/en`) like the others, set `defaultContentLanguageInSubdir: true`. + +Only the obvious non-global options can be overridden per language. Examples of global options are `baseURL`, `buildDrafts`, etc. + +**Please note:** use lowercase language codes, even when using regional languages (ie. use pt-pt instead of pt-PT). Currently Hugo language internals lowercase language codes, which can cause conflicts with settings like `defaultContentLanguage` which are not lowercased. Please track the evolution of this issue in [Hugo repository issue tracker](https://github.com/gohugoio/hugo/issues/7344) + +### Changes in Hugo 0.112.0 + +{{< new-in "0.112.0" >}} + - In version `0.112.0` of Hugo we did a major we consolidated all configuration options, but also improved how the languages and their params gets merged with the main configuration. But while testing this on Hugo sites out there, we got some error reports. ++In Hugo `v0.112.0` we consolidated all configuration options, and improved how the languages and their parameters are merged with the main configuration. But while testing this on Hugo sites out there, we received some error reports and reverted some of the changes in favor of deprecation warnings: + +1. `site.Language.Params` is deprecated. Use `site.Params` directly. - 1. The `params` sections on site and language is the only place to put custom user parameters, and `site.Params` will only contain these user defined parameters (see example below). ++1. Adding custom params to the top level language config is deprecated, add all of these below `[params]`, see `color` in the example below. + +```toml +title = "My blog" +languageCode = "en-us" + +[languages] +[languages.sv] +title = "Min blogg" +languageCode = "sv" +[languages.en.params] +color = "blue" +``` + - In the example above, all the settings exept the `color` below `params` maps to predefined configuration options in Hguo for the site and its language, and should be accessed via the documented accessors: ++In the example above, all settings except `color` below `params` map to predefined configuration options in Hugo for the site and its language, and should be accessed via the documented accessors: + +``` +{{ site.Title }} +{{ site.LanguageCode }} +{{ site.Params.color }} +``` + +### Disable a Language + +You can disable one or more languages. This can be useful when working on a new translation. + - {{< code-toggle file="config" >}} ++{{< code-toggle file="hugo" >}} +disableLanguages = ["fr", "ja"] +{{< /code-toggle >}} + +Note that you cannot disable the default content language. + +We kept this as a standalone setting to make it easier to set via [OS environment]: + +```bash +HUGO_DISABLELANGUAGES="fr ja" hugo +``` + - If you have already a list of disabled languages in `config.toml`, you can enable them in development like this: ++If you have already a list of disabled languages in `hugo.toml`, you can enable them in development like this: + +```bash +HUGO_DISABLELANGUAGES=" " hugo server +``` + +### Configure Multilingual Multihost + +From **Hugo 0.31** we support multiple languages in a multihost configuration. See [this issue](https://github.com/gohugoio/hugo/issues/4027) for details. + +This means that you can now configure a `baseURL` per `language`: + +{{% note %}} +If a `baseURL` is set on the `language` level, then all languages must have one and they must all be different. +{{% /note %}} + +Example: + - {{< code-toggle file="config" >}} ++{{< code-toggle file="hugo" >}} +[languages] +[languages.fr] +baseURL = "https://example.fr" +languageName = "Français" +weight = 1 +title = "En Français" + +[languages.en] +baseURL = "https://example.com" +languageName = "English" +weight = 2 +title = "In English" +{{}} + +With the above, the two sites will be generated into `public` with their own root: + +```text +public +├── en +└── fr +``` + +**All URLs (i.e `.Permalink` etc.) will be generated from that root. So the English home page above will have its `.Permalink` set to `https://example.com/`.** + +When you run `hugo server` we will start multiple HTTP servers. You will typically see something like this in the console: + +```text +Web Server is available at 127.0.0.1:1313 (bind address 127.0.0.1) +Web Server is available at 127.0.0.1:1314 (bind address 127.0.0.1) +Press Ctrl+C to stop +``` + +Live reload and `--navigateToChanged` between the servers work as expected. + + +## Translate Your Content + +There are two ways to manage your content translations. Both ensure each page is assigned a language and is linked to its counterpart translations. + +### Translation by filename + +Considering the following example: + +1. `/content/about.en.md` +2. `/content/about.fr.md` + +The first file is assigned the English language and is linked to the second. +The second file is assigned the French language and is linked to the first. + +Their language is __assigned__ according to the language code added as a __suffix to the filename__. + +By having the same **path and base filename**, the content pieces are __linked__ together as translated pages. + +{{% note %}} +If a file has no language code, it will be assigned the default language. +{{% /note %}} + +### Translation by content directory + +This system uses different content directories for each of the languages. Each language's content directory is set using the `contentDir` param. + - {{< code-toggle file="config" >}} ++{{< code-toggle file="hugo" >}} +languages: + en: + weight: 10 + languageName: "English" + contentDir: "content/english" + fr: + weight: 20 + languageName: "Français" + contentDir: "content/french" +{{< /code-toggle >}} + +The value of `contentDir` can be any valid path -- even absolute path references. The only restriction is that the content directories cannot overlap. + +Considering the following example in conjunction with the configuration above: + +1. `/content/english/about.md` +2. `/content/french/about.md` + +The first file is assigned the English language and is linked to the second. +The second file is assigned the French language and is linked to the first. + +Their language is __assigned__ according to the content directory they are __placed__ in. + +By having the same **path and basename** (relative to their language content directory), the content pieces are __linked__ together as translated pages. + +### Bypassing default linking + +Any pages sharing the same `translationKey` set in front matter will be linked as translated pages regardless of basename or location. + +Considering the following example: + +1. `/content/about-us.en.md` +2. `/content/om.nn.md` +3. `/content/presentation/a-propos.fr.md` + +{{< code-toggle >}} +translationKey: "about" +{{< /code-toggle >}} + +By setting the `translationKey` front matter param to `about` in all three pages, they will be __linked__ as translated pages. + +### Localizing permalinks + +Because paths and filenames are used to handle linking, all translated pages will share the same URL (apart from the language subdirectory). + +To localize URLs: + +- For a regular page, set either [`slug`] or [`url`] in front matter +- For a section page, set [`url`] in front matter + +[`slug`]: /content-management/urls/#slug +[`url`]: /content-management/urls/#url + +For example, a French translation can have its own localized slug. + +{{< code-toggle file="content/about.fr.md" fm=true copy=false >}} +title: A Propos +slug: "a-propos" +{{< /code-toggle >}} + +At render, Hugo will build both `/about/` and `/fr/a-propos/` without affecting the translation link. + +### Page Bundles + +To avoid the burden of having to duplicate files, each Page Bundle inherits the resources of its linked translated pages' bundles except for the content files (Markdown files, HTML files etc...). + +Therefore, from within a template, the page will have access to the files from all linked pages' bundles. + +If, across the linked bundles, two or more files share the same basename, only one will be included and chosen as follows: + +* File from current language bundle, if present. +* First file found across bundles by order of language `Weight`. + +{{% note %}} +Page Bundle resources follow the same language assignment logic as content files, both by filename (`image.jpg`, `image.fr.jpg`) and by directory (`english/about/header.jpg`, `french/about/header.jpg`). +{{%/ note %}} + +## Reference the Translated Content + +To create a list of links to translated content, use a template similar to the following: + +{{< code file="layouts/partials/i18nlist.html" >}} +{{ if .IsTranslated }} +

{{ i18n "translations" }}

+ +{{ end }} +{{< /code >}} + +The above can be put in a `partial` (i.e., inside `layouts/partials/`) and included in any template, whether a [single content page][contenttemplate] or the [homepage]. It will not print anything if there are no translations for a given page. + +The above also uses the [`i18n` function][i18func] described in the next section. + +### List All Available Languages + +`.AllTranslations` on a `Page` can be used to list all translations, including the page itself. On the home page it can be used to build a language navigator: + +{{< code file="layouts/partials/allLanguages.html" >}} + +{{< /code >}} + +## Translation of Strings + +Hugo uses [go-i18n] to support string translations. [See the project's source repository][go-i18n-source] to find tools that will help you manage your translation workflows. + +Translations are collected from the `themes//i18n/` folder (built into the theme), as well as translations present in `i18n/` at the root of your project. In the `i18n`, the translations will be merged and take precedence over what is in the theme folder. Language files should be named according to [RFC 5646] with names such as `en-US.toml`, `fr.toml`, etc. + +Artificial languages with private use subtags as defined in [RFC 5646 § 2.2.7](https://datatracker.ietf.org/doc/html/rfc5646#section-2.2.7) are also supported. You may omit the `art-x-` prefix for brevity. For example: + +```text +art-x-hugolang +hugolang +``` + +Private use subtags must not exceed 8 alphanumeric characters. + +### Query basic translation + +From within your templates, use the `i18n` function like this: + +```go-html-template +{{ i18n "home" }} +``` + +The function will search for the `"home"` id: + +{{< code-toggle file="i18n/en-US" >}} +[home] +other = "Home" +{{< /code-toggle >}} + +The result will be + +```text +Home +``` + +### Query a flexible translation with variables + +Often you will want to use the page variables in the translation strings. To do so, pass the `.` context when calling `i18n`: + +```go-html-template +{{ i18n "wordCount" . }} +``` + +The function will pass the `.` context to the `"wordCount"` id: + +{{< code-toggle file="i18n/en-US" >}} +[wordCount] +other = "This article has {{ .WordCount }} words." +{{< /code-toggle >}} + +Assume `.WordCount` in the context has value is 101. The result will be: + +```text +This article has 101 words. +``` + +### Query a singular/plural translation + +In other to meet singular/plural requirement, you must pass a dictionary (map) with a numeric `.Count` property to the `i18n` function. The below example uses `.ReadingTime` variable which has a built-in `.Count` property. + +```go-html-template +{{ i18n "readingTime" .ReadingTime }} +``` + +The function will read `.Count` from `.ReadingTime` and evaluate whether the number is singular (`one`) or plural (`other`). After that, it will pass to `readingTime` id in `i18n/en-US.toml` file: + +{{< code-toggle file="i18n/en-US" >}} +[readingTime] +one = "One minute to read" +other = "{{ .Count }} minutes to read" +{{< /code-toggle >}} + +Assuming `.ReadingTime.Count` in the context has value is 525600. The result will be: + +```text +525600 minutes to read +``` + +If `.ReadingTime.Count` in the context has value is 1. The result is: + +```text +One minute to read +``` + +In case you need to pass a custom data: (`(dict "Count" numeric_value_only)` is minimum requirement) + +```go-html-template +{{ i18n "readingTime" (dict "Count" 25 "FirstArgument" true "SecondArgument" false "Etc" "so on, so far") }} +``` + +## Localization + +The following localization examples assume your site's primary language is English, with translations to French and German. + - {{< code-toggle file="config" >}} ++{{< code-toggle file="hugo" >}} +defaultContentLanguage = 'en' + +[languages] +[languages.en] +contentDir = 'content/en' +languageName = 'English' +weight = 1 +[languages.fr] +contentDir = 'content/fr' +languageName = 'Français' +weight = 2 +[languages.de] +contentDir = 'content/de' +languageName = 'Deutsch' +weight = 3 + +{{< /code-toggle >}} + +### Dates + +With this front matter: + +{{< code-toggle >}} +date = 2021-11-03T12:34:56+01:00 +{{< /code-toggle >}} + +And this template code: + +```go-html-template +{{ .Date | time.Format ":date_full" }} +``` + +The rendered page displays: + +Language|Value +:--|:-- +English|Wednesday, November 3, 2021 +Français|mercredi 3 novembre 2021 +Deutsch|Mittwoch, 3. November 2021 + +See [time.Format] for details. + +### Currency + +With this template code: + +```go-html-template +{{ 512.5032 | lang.FormatCurrency 2 "USD" }} +``` + +The rendered page displays: + +Language|Value +:--|:-- +English|$512.50 +Français|512,50 $US +Deutsch|512,50 $ + +See [lang.FormatCurrency] and [lang.FormatAccounting] for details. + +### Numbers + +With this template code: + +```go-html-template +{{ 512.5032 | lang.FormatNumber 2 }} +``` + +The rendered page displays: + +Language|Value +:--|:-- +English|512.50 +Français|512,50 +Deutsch|512,50 + +See [lang.FormatNumber] and [lang.FormatNumberCustom] for details. + +### Percentages + +With this template code: + +```go-html-template +{{ 512.5032 | lang.FormatPercent 2 }} ---> 512.50% +``` + +The rendered page displays: + +Language|Value +:--|:-- +English|512.50% +Français|512,50 % +Deutsch|512,50 % + +See [lang.FormatPercent] for details. + +## Menus + +Localization of menu entries depends on the 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 site configuration], you can (a) use translation tables, or (b) create language-specific menu entries under each language key. + +### Use translation tables + +When rendering the text that appears in menu each entry, the [example menu template] does this: + +```go-html-template +{{ or (T .Identifier) .Name | safeHTML }} +``` + +It queries the translation table for the current language using the menu entry's `identifier` and returns the translated string. If the translation table does not exist, or if the `identifier` key is not present in the translation table, it falls back to `name`. + +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 site configuration] or [in front matter], set the `identifier` property to the desired value. + +For example, if you define menu entries in site configuration: + - {{< code-toggle file="config" copy=false >}} ++{{< code-toggle file="hugo" copy=false >}} +[[menu.main]] + identifier = 'products' + name = 'Products' + pageRef = '/products' + weight = 10 +[[menu.main]] + identifier = 'services' + name = 'Services' + pageRef = '/services' + weight = 20 +{{< / code-toggle >}} + +Create corresponding entries in the translation tables: + +{{< code-toggle file="i18n/de" copy=false >}} +products = 'Produkte' +services = 'Leistungen' +{{< / code-toggle >}} + +[example menu template]: /templates/menu-templates/#example +[automatically]: /content-management/menus/#define-automatically +[in front matter]: /content-management/menus/#define-in-front-matter +[in site configuration]: /content-management/menus/#define-in-site-configuration + +### Create language-specific menu entries + +For example: + - {{< code-toggle file="config" copy=false >}} ++{{< code-toggle file="hugo" copy=false >}} +[languages.de] +languageCode = 'de-DE' +languageName = 'Deutsch' +weight = 1 + +[[languages.de.menu.main]] +name = 'Produkte' +pageRef = '/products' +weight = 10 + +[[languages.de.menu.main]] +name = 'Leistungen' +pageRef = '/services' +weight = 20 + +[languages.en] +languageCode = 'en-US' +languageName = 'English' +weight = 2 + +[[languages.en.menu.main]] +name = 'Products' +pageRef = '/products' +weight = 10 + +[[languages.en.menu.main]] +name = 'Services' +pageRef = '/services' +weight = 20 +{{< /code-toggle >}} + +For a simple menu with two languages, these menu entries are easy to create and maintain. For a larger menu, or with more than two languages, using translation tables as described above is preferable. + +## Missing Translations + +If a string does not have a translation for the current language, Hugo will use the value from the default language. If no default value is set, an empty string will be shown. + +While translating a Hugo website, it can be handy to have a visual indicator of missing translations. The [`enableMissingTranslationPlaceholders` configuration option][config] will flag all untranslated strings with the placeholder `[i18n] identifier`, where `identifier` is the id of the missing translation. + +{{% note %}} +Hugo will generate your website with these missing translation placeholders. It might not be suitable for production environments. +{{% /note %}} + +For merging of content from other languages (i.e. missing content translations), see [lang.Merge]. + +To track down missing translation strings, run Hugo with the `--printI18nWarnings` flag: + +```bash +hugo --printI18nWarnings | grep i18n +i18n|MISSING_TRANSLATION|en|wordCount +``` + +## Multilingual Themes support + +To support Multilingual mode in your themes, some considerations must be taken for the URLs in the templates. If there is more than one language, URLs must meet the following criteria: + +* Come from the built-in `.Permalink` or `.RelPermalink` +* Be constructed with the [`relLangURL` template function][rellangurl] or the [`absLangURL` template function][abslangurl] **OR** be prefixed with `{{ .LanguagePrefix }}` + +If there is more than one language defined, the `LanguagePrefix` variable will equal `/en` (or whatever your `CurrentLanguage` is). If not enabled, it will be an empty string (and is therefore harmless for single-language Hugo websites). + + +## Generate multilingual content with `hugo new` + +If you organize content with translations in the same directory: + +```text +hugo new post/test.en.md +hugo new post/test.de.md +``` + +If you organize content with translations in different directories: + +```text +hugo new content/en/post/test.md +hugo new content/de/post/test.md +``` + +[abslangurl]: /functions/abslangurl +[config]: /getting-started/configuration/ +[contenttemplate]: /templates/single-page-templates/ +[go-i18n-source]: https://github.com/nicksnyder/go-i18n +[go-i18n]: https://github.com/nicksnyder/go-i18n +[homepage]: /templates/homepage/ +[Hugo Multilingual Part 1: Content translation]: https://regisphilibert.com/blog/2018/08/hugo-multilingual-part-1-managing-content-translation/ +[i18func]: /functions/i18n/ +[lang.FormatAccounting]: /functions/lang +[lang.FormatCurrency]: /functions/lang +[lang.FormatNumber]: /functions/lang +[lang.FormatNumberCustom]: /functions/lang +[lang.FormatPercent]: /functions/lang +[lang.Merge]: /functions/lang.merge/ +[menus]: /content-management/menus/ +[OS environment]: /getting-started/configuration/#configure-with-environment-variables +[rellangurl]: /functions/rellangurl +[RFC 5646]: https://tools.ietf.org/html/rfc5646 +[single page templates]: /templates/single-page-templates/ +[time.Format]: /functions/dateformat diff --cc docs/content/en/content-management/page-resources.md index 4bbd159be,000000000..54494c2e1 mode 100644,000000..100644 --- a/docs/content/en/content-management/page-resources.md +++ b/docs/content/en/content-management/page-resources.md @@@ -1,203 -1,0 +1,203 @@@ +--- +title: Page Resources +description: Page resources -- images, other pages, documents, etc. -- have page-relative URLs and their own metadata. +categories: [content management] +keywords: [bundle,content,resources] +menu: + docs: + parent: content-management + weight: 80 +toc: true +weight: 80 +--- +Page resources are only accessible from [page bundles](/content-management/page-bundles), those directories with `index.md` or +`_index.md` files at their root. Page resources are only available to the +page with which they are bundled. + +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 +content +└── post + ├── first-post + │ ├── images + │ │ ├── a.jpg + │ │ ├── b.jpg + │ │ └── c.jpg + │ ├── index.md (root of page bundle) + │ ├── latest.html + │ ├── manual.json + │ ├── notice.md + │ ├── office.mp3 + │ ├── pocket.mp4 + │ ├── rating.pdf + │ └── safety.txt + └── second-post + └── index.md (root of page bundle) +``` + +## Properties + +ResourceType +: The main type of the resource's [Media Type](/templates/output-formats/#media-types). For example, a file of MIME type `image/jpeg` has the ResourceType `image`. A `Page` will have `ResourceType` with value `page`. + +Name +: Default value is the filename (relative to the owning page). Can be set in front matter. + +Title +: Default value is the same as `.Name`. Can be set in front matter. + +Permalink +: The absolute URL to the resource. Resources of type `page` will have no value. + +RelPermalink +: The relative URL to the resource. Resources of type `page` will have no value. + +Content +: The content of the resource itself. For most resources, this returns a string +with the contents of the file. Use this to create inline resources. + +```go-html-template +{{ with .Resources.GetMatch "script.js" }} + +{{ end }} + +{{ with .Resources.GetMatch "style.css" }} + +{{ end }} + +{{ with .Resources.GetMatch "img.png" }} + +{{ end }} +``` + +MediaType +: The MIME type of the resource, such as `image/jpeg`. + +MediaType.MainType +: The main type of the resource's MIME type. For example, a file of MIME type `application/pdf` has for MainType `application`. + +MediaType.SubType - : The subtype of the resource's MIME type. For example, a file of MIME type `application/pdf` has for SubType `pdf`. Note that this is not the same as the file extension - PowerPoint files have a subtype of `vnd.mspowerpoint`. ++: The subtype of the resource's MIME type. For example, a file of MIME type `application/pdf` has for SubType `pdf`. Note that this is not the same as the file extension. For example, Microsoft PowerPoint files (`.ppt`) have a subtype of `vnd.ms-powerpoint`. + +MediaType.Suffixes +: A slice of possible suffixes for the resource's MIME type. + +## Methods + +ByType +: Returns the page resources of the given type. + +```go-html-template +{{ .Resources.ByType "image" }} +``` +Match +: Returns all the page resources (as a slice) whose `Name` matches the given Glob pattern ([examples](https://github.com/gobwas/glob/blob/master/readme.md)). The matching is case-insensitive. + +```go-html-template +{{ .Resources.Match "images/*" }} +``` + +GetMatch +: Same as `Match` but will return the first match. + +### Pattern Matching + +```go +// Using Match/GetMatch to find this images/sunset.jpg ? +.Resources.Match "images/sun*" ✅ +.Resources.Match "**/sunset.jpg" ✅ +.Resources.Match "images/*.jpg" ✅ +.Resources.Match "**.jpg" ✅ +.Resources.Match "*" 🚫 +.Resources.Match "sunset.jpg" 🚫 +.Resources.Match "*sunset.jpg" 🚫 + +``` + +## Page Resources Metadata + +The page resources' metadata is managed from the corresponding page's front matter with an array/table parameter named `resources`. You can batch assign values using [wildcards](https://tldp.org/LDP/GNU-Linux-Tools-Summary/html/x11655.htm). + +{{% note %}} +Resources of type `page` get `Title` etc. from their own front matter. +{{% /note %}} + +name +: Sets the value returned in `Name`. + +{{% note %}} +The methods `Match`, `Get` and `GetMatch` use `Name` to match the resources. +{{% /note %}} + +title +: Sets the value returned in `Title` + +params +: A map of custom key/values. + +### Resources metadata example + +{{< code-toggle copy=false >}} +title: Application +date : 2018-01-25 +resources : +- src : "images/sunset.jpg" + name : "header" +- src : "documents/photo_specs.pdf" + title : "Photo Specifications" + params: + icon : "photo" +- src : "documents/guide.pdf" + title : "Instruction Guide" +- src : "documents/checklist.pdf" + title : "Document Checklist" +- src : "documents/payment.docx" + title : "Proof of Payment" +- src : "**.pdf" + name : "pdf-file-:counter" + params : + icon : "pdf" +- src : "**.docx" + params : + icon : "word" +{{}} + +From the example above: + +- `sunset.jpg` will receive a new `Name` and can now be found with `.GetMatch "header"`. +- `documents/photo_specs.pdf` will get the `photo` icon. +- `documents/checklist.pdf`, `documents/guide.pdf` and `documents/payment.docx` will get `Title` as set by `title`. +- Every `PDF` in the bundle except `documents/photo_specs.pdf` will get the `pdf` icon. +- All `PDF` files will get a new `Name`. The `name` parameter contains a special placeholder [`:counter`](#the-counter-placeholder-in-name-and-title), so the `Name` will be `pdf-file-1`, `pdf-file-2`, `pdf-file-3`. +- Every docx in the bundle will receive the `word` icon. + +{{% note %}} +The __order matters__ --- Only the **first set** values of the `title`, `name` and `params`-**keys** will be used. Consecutive parameters will be set only for the ones not already set. In the above example, `.Params.icon` is first set to `"photo"` in `src = "documents/photo_specs.pdf"`. So that would not get overridden to `"pdf"` by the later set `src = "**.pdf"` rule. +{{% /note %}} + +### The `:counter` placeholder in `name` and `title` + +The `:counter` is a special placeholder recognized in `name` and `title` parameters `resources`. + +The counter starts at 1 the first time they are used in either `name` or `title`. + +For example, if a bundle has the resources `photo_specs.pdf`, `other_specs.pdf`, `guide.pdf` and `checklist.pdf`, and the front matter has specified the `resources` as: + +{{< code-toggle copy=false >}} +[[resources]] + src = "*specs.pdf" + title = "Specification #:counter" +[[resources]] + src = "**.pdf" + name = "pdf-file-:counter" +{{}} + +the `Name` and `Title` will be assigned to the resource files as follows: + +| Resource file | `Name` | `Title` | +|-------------------|-------------------|-----------------------| +| checklist.pdf | `"pdf-file-1.pdf` | `"checklist.pdf"` | +| guide.pdf | `"pdf-file-2.pdf` | `"guide.pdf"` | +| other\_specs.pdf | `"pdf-file-3.pdf` | `"Specification #1"` | +| photo\_specs.pdf | `"pdf-file-4.pdf` | `"Specification #2"` | diff --cc docs/content/en/content-management/related.md index 823e3035c,000000000..e80c0f06b mode 100644,000000..100644 --- a/docs/content/en/content-management/related.md +++ b/docs/content/en/content-management/related.md @@@ -1,188 -1,0 +1,188 @@@ +--- +title: Related Content +description: List related content in "See Also" sections. +categories: [content management] +keywords: [content] +menu: + docs: + parent: content-management + weight: 110 +toc: true +weight: 110 +aliases: [/content/related/,/related/] +--- + +Hugo uses a set of factors to identify a page's related content based on Front Matter parameters. This can be tuned to the desired set of indices and parameters or left to Hugo's default [Related Content configuration](#configure-related-content). + +## List Related Content + +To list up to 5 related pages (which share the same _date_ or _keyword_ parameters) is as simple as including something similar to this partial in your single page template: + +{{< code file="layouts/partials/related.html" >}} +{{ $related := .Site.RegularPages.Related . | first 5 }} +{{ with $related }} +

See Also

+ +{{ end }} +{{< /code >}} + +The `Related` method takes one argument which may be a `Page` or a options map. The options map have these options: + +indices +: The indices to search in. + +document +: The document to search for related content for. + +namedSlices +: The keywords to search for. + +fragments +: Fragments holds a a list of special keywords that is used for indices configured as type "fragments". This will match the fragment identifiers of the documents. + +A fictional example using all of the above options: + +```go-html-template +{{ $page := . }} +{{ $opts := + "indices" (slice "tags" "keywords") + "document" $page + "namedSlices" (slice (keyVals "tags" "hugo" "rocks") (keyVals "date" $page.Date)) + "fragments" (slice "heading-1" "heading-2") +}} +``` + +{{% note %}} +We improved and simplified this feature in Hugo 0.111.0. Before this we had 3 different methods: `Related`, `RelatedTo` and `RelatedIndicies`. 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 %}} + +## Index Content Headings in Related Content + +{{< new-in "0.111.0" >}} + +Hugo can index the headings in your content and use this to find related content. You can enable this by adding a index of type `fragments` to your `related` configuration: + - {{< code-toggle file="config" copy=false >}} ++{{< code-toggle file="hugo" copy=false >}} +[related] +threshold = 20 +includeNewer = true +toLower = false +[[related.indices]] +name = "fragmentrefs" +type = "fragments" +applyFilter = false +weight = 80 +{{< /code-toggle >}} + +* The `name` maps to a optional front matter slice attribute that can be used to link from the page level down to the fragment/heading level. +* If `applyFilter`is enabled, the `.HeadingsFiltered` on each page in the result will reflect the filtered headings. This is useful if you want to show the headings in the related content listing: + +```go-html-template +{{ $related := .Site.RegularPages.Related . | first 5 }} +{{ with $related }} +

See Also

+
    + {{ range $i, $p := . }} +
  • + {{ .Title }} + {{ with .HeadingsFiltered }} +
      + {{ range . }} + {{ $link := printf "%s#%s" $p.RelPermalink .ID | safeURL }} +
    • + {{ .Title }} +
      • + {{ end }} +
    + {{ end }} +
    • + {{ end }} +
+{{ end }} +``` + +## Configure Related Content + +Hugo provides a sensible default configuration of Related Content, but you can fine-tune this in your configuration, on the global or language level if needed. + +### Default configuration + +Without any `related` configuration set on the project, Hugo's Related Content methods will use the following. + - {{< code-toggle file="config" >}} ++{{< code-toggle file="hugo" >}} +related: + threshold: 80 + includeNewer: false + toLower: false + indices: + - name: keywords + weight: 100 + - name: date + weight: 10 +{{< /code-toggle >}} + +Note that if you have configured `tags` as a taxonomy, `tags` will also be added to the default configuration above with the weight of `80`. + +Custom configuration should be set using the same syntax. + +{{% note %}} +If you add a `related` config section, you need to add a complete configuration. It is not possible to just set, say, `includeNewer` and use the rest from the Hugo defaults. +{{% /note %}} + +### Top Level Config Options + +threshold +: A value between 0-100. Lower value will give more, but maybe not so relevant, matches. + +includeNewer +: Set to true to include **pages newer than the current page** in the related content listing. This will mean that the output for older posts may change as new related content gets added. + +toLower +: Set to true to lower case keywords in both the indexes and the queries. This may give more accurate results at a slight performance penalty. Note that this can also be set per index. + +### Config Options per Index + +name +: The index name. This value maps directly to a page param. Hugo supports string values (`author` in the example) and lists (`tags`, `keywords` etc.) and time and date objects. + +type +: {{< new-in "0.111.0" >}}. One of `basic`(default) or `fragments`. + +applyFilter +: {{< new-in "0.111.0" >}}. Apply a `type` specific filter to the result of a search. This is currently only used for the `fragments` type. + +weight +: An integer weight that indicates _how important_ this parameter is relative to the other parameters. It can be 0, which has the effect of turning this index off, or even negative. Test with different values to see what fits your content best. + + +cardinalityThreshold (default 0) +: {{< new-in "0.111.0" >}}. A percentage (0-100) used to remove common keywords from the index. As an example, setting this to 50 will remove all keywords that are used in more than 50% of the documents in the index. + +pattern +: This is currently only relevant for dates. When listing related content, we may want to list content that is also close in time. Setting "2006" (default value for date indexes) as the pattern for a date index will add weight to pages published in the same year. For busier blogs, "200601" (year and month) may be a better default. + +toLower +: See above. + +## Performance Considerations + +**Fast is Hugo's middle name** and we would not have released this feature had it not been blistering fast. + +This feature has been in the back log and requested by many for a long time. The development got this recent kick start from this Twitter thread: + +{{< tweet user="scott_lowe" id="898398437527363585" >}} + +Scott S. Lowe removed the "Related Content" section built using the `intersect` template function on tags, and the build time dropped from 30 seconds to less than 2 seconds on his 1700 content page sized blog. + +He should now be able to add an improved version of that "Related Content" section without giving up the fast live-reloads. But it's worth noting that: + +* If you don't use any of the `Related` methods, you will not use the Relate Content feature, and performance will be the same as before. +* Calling `.RegularPages.Related` etc. will create one inverted index, also sometimes named posting list, that will be reused for any lookups in that same page collection. Doing that in addition to, as an example, calling `.Pages.Related` will work as expected, but will create one additional inverted index. This should still be very fast, but worth having in mind, especially for bigger sites. + +{{% note %}} +We currently do not index **Page content**. We thought we would release something that will make most people happy before we start solving [Sherlock's last case](https://github.com/joearms/sherlock). +{{% /note %}} diff --cc docs/content/en/content-management/shortcodes.md index 35ffc390f,000000000..b2c98fc65 mode 100644,000000..100644 --- a/docs/content/en/content-management/shortcodes.md +++ b/docs/content/en/content-management/shortcodes.md @@@ -1,411 -1,0 +1,411 @@@ +--- +title: Shortcodes +description: Shortcodes are simple snippets inside your content files calling built-in or custom templates. +categories: [content management] +keywords: [markdown,content,shortcodes] +menu: + docs: + parent: content-management + weight: 100 +toc: true +weight: 100 +aliases: [/extras/shortcodes/] +testparam: "Hugo Rocks!" +--- + +## What a Shortcode is + +Hugo loves Markdown because of its simple content format, but there are times when Markdown falls short. Often, content authors are forced to add raw HTML (e.g., video ` + +{{< /code >}} + +{{< code file="youtube-embed.html" copy=false >}} +
+ +
+{{< /code >}} + +### Single Named Example: `image` + +Let's say you want to create your own `img` shortcode rather than use Hugo's built-in [`figure` shortcode][figure]. Your goal is to be able to call the shortcode as follows in your content files: + +{{< code file="content-image.md" >}} +{{}} +{{< /code >}} + +You have created the shortcode at `/layouts/shortcodes/img.html`, which loads the following shortcode template: + +{{< code file="/layouts/shortcodes/img.html" >}} + +
+ {{ with .Get "link" }}{{ end }} + + {{ if .Get "link" }}{{ end }} + {{ if or (or (.Get "title") (.Get "caption")) (.Get "attr") }} +
{{ if isset .Params "title" }} +

{{ .Get "title" }}

{{ end }} + {{ if or (.Get "caption") (.Get "attr") }}

+ {{ .Get "caption" }} + {{ with .Get "attrlink" }} {{ end }} + {{ .Get "attr" }} + {{ if .Get "attrlink" }} {{ end }} +

{{ end }} +
+ {{ end }} +
+ +{{< /code >}} + +Would be rendered as: + +{{< code file="img-output.html" copy=false >}} +
+ +
+

Steve Francia

+
+
+{{< /code >}} + +### Single Flexible Example: `vimeo` + +```go-html-template +{{}} +{{}} +``` + +Would load the template found at `/layouts/shortcodes/vimeo.html`: + +{{< code file="/layouts/shortcodes/vimeo.html" >}} +{{ if .IsNamedParams }} +
+ +
+{{ else }} +
+ +
+{{ end }} +{{< /code >}} + +Would be rendered as: + +{{< code file="vimeo-iframes.html" copy=false >}} +
+ +
+
+ +
+{{< /code >}} + +### Paired Example: `highlight` + +The following is taken from `highlight`, which is a [built-in shortcode] that ships with Hugo. + +{{< code file="highlight-example.md" >}} +{{}} + + This HTML + +{{}} +{{< /code >}} + +The template for the `highlight` shortcode uses the following code, which is already included in Hugo: + +```go-html-template +{{ .Get 0 | highlight .Inner }} +``` + +The rendered output of the HTML example code block will be as follows: + +{{< code file="syntax-highlighted.html" copy=false >}} +
<html>
 +    <body> This HTML </body>
 +</html>
 +
+{{< /code >}} + +### Nested Shortcode: Image Gallery + +Hugo's [`.Parent` shortcode variable][parent] provides access to the parent shortcode context when the shortcode in question is called within the context of a *parent* shortcode. This provides an inheritance model for common shortcode parameters. + +The following example is contrived but demonstrates the concept. Assume you have a `gallery` shortcode that expects one named `class` parameter: + +{{< code file="layouts/shortcodes/gallery.html" >}} +
+ {{ .Inner }} +
+{{< /code >}} + +You also have an `img` shortcode with a single named `src` parameter that you want to call inside of `gallery` and other shortcodes, so that the parent defines the context of each `img`: + +{{< code file="layouts/shortcodes/img.html" >}} +{{- $src := .Get "src" -}} +{{- with .Parent -}} + +{{- else -}} + +{{- end -}} +{{< /code >}} + +You can then call your shortcode in your content as follows: + +```go-html-template +{{}} + {{}} + {{}} +{{}} +{{}} +``` + +This will output the following HTML. Note how the first two `img` shortcodes inherit the `class` value of `content-gallery` set with the call to the parent `gallery`, whereas the third `img` only uses `src`: + +```html +
+ + +
+ +``` + +## Error Handling in Shortcodes + +Use the [errorf](/functions/errorf) template func and [.Position](/variables/shortcodes/) variable to get useful error messages in shortcodes: + +```bash +{{ with .Get "name" }} +{{ else }} +{{ errorf "missing value for param 'name': %s" .Position }} +{{ end }} +``` + +When the above fails, you will see an `ERROR` log similar to the below: + +```bash +ERROR 2018/11/07 10:05:55 missing value for param name: "/Users/bep/dev/go/gohugoio/hugo/docs/content/en/variables/shortcodes.md:32:1" +``` + +## More Shortcode Examples + +More shortcode examples can be found in the [shortcodes directory for spf13.com][spfscs] and the [shortcodes directory for the Hugo docs][docsshortcodes]. + +## Inline Shortcodes + +You can also implement your shortcodes inline -- e.g. where you use them in the content file. This can be useful for scripting that you only need in one place. + +This feature is disabled by default, but can be enabled in your site config: + - {{< code-toggle file="config">}} ++{{< code-toggle file="hugo" >}} +enableInlineShortcodes = true +{{< /code-toggle >}} + +It is disabled by default for security reasons. The security model used by Hugo's template handling assumes that template authors are trusted, but that the content files are not, so the templates are injection-safe from malformed input data. But in most situations you have full control over the content, too, and then `enableInlineShortcodes = true` would be considered safe. But it's something to be aware of: It allows ad-hoc [Go Text templates](https://golang.org/pkg/text/template/) to be executed from the content files. + +And once enabled, you can do this in your content files: + + ```go-text-template + {{}}{{ now }}{{}} + ``` + +The above will print the current date and time. + + Note that an inline shortcode's inner content is parsed and executed as a Go text template with the same context as a regular shortcode template. + +This means that the current page can be accessed via `.Page.Title` etc. This also means that there are no concept of "nested inline shortcodes". + +The same inline shortcode can be reused later in the same content file, with different params if needed, using the self-closing syntax: + + ```go-text-template +{{}} +``` + +[basic content files]: /content-management/formats/ "See how Hugo leverages markdown--and other supported formats--to create content for your website." +[built-in shortcode]: /content-management/shortcodes/ +[config]: /getting-started/configuration/ "Learn more about Hugo's built-in configuration variables as well as how to us your site's configuration file to include global key-values that can be used throughout your rendered website." +[Content Management: Shortcodes]: /content-management/shortcodes/#using-hugo-s-built-in-shortcodes "Check this section if you are not familiar with the definition of what a shortcode is or if you are unfamiliar with how to use Hugo's built-in shortcodes in your content files." +[source organization]: /getting-started/directory-structure/#directory-structure-explained "Learn how Hugo scaffolds new sites and what it expects to find in each of your directories." +[docsshortcodes]: https://github.com/gohugoio/hugo/tree/master/docs/layouts/shortcodes "See the shortcode source directory for the documentation site you're currently reading." +[figure]: /content-management/shortcodes/#figure +[hugosc]: /content-management/shortcodes/#using-hugo-s-built-in-shortcodes +[lookup order]: /templates/lookup-order/ "See the order in which Hugo traverses your template files to decide where and how to render your content at build time" +[pagevars]: /variables/page/ "See which variables you can leverage in your templating for page vs list templates." +[parent]: /variables/shortcodes/ +[shortcodesvars]: /variables/shortcodes/ "Certain variables are specific to shortcodes, although most .Page variables can be accessed within your shortcode template." +[spfscs]: https://github.com/spf13/spf13.com/tree/master/layouts/shortcodes "See more examples of shortcodes by visiting the shortcode directory of the source for spf13.com, the blog of Hugo's creator, Steve Francia." +[templates]: /templates/ "The templates section of the Hugo docs." +[vimeoexample]: #single-flexible-example-vimeo +[youtubeshortcode]: /content-management/shortcodes/#youtube "See how to use Hugo's built-in YouTube shortcode." diff --cc docs/content/en/templates/sitemap-template.md index d0738a362,000000000..37462a086 mode 100644,000000..100644 --- a/docs/content/en/templates/sitemap-template.md +++ b/docs/content/en/templates/sitemap-template.md @@@ -1,84 -1,0 +1,84 @@@ +--- +title: Sitemap Templates +description: Hugo provides built-in sitemap templates. +categories: [templates] +keywords: [sitemap, xml, templates] +menu: + docs: + parent: templates + weight: 160 +weight: 160 +aliases: [/layout/sitemap/,/templates/sitemap/] +toc: true +--- + +## Overview + +Hugo's built-in sitemap templates conform to v0.9 of the [sitemap protocol]. + +With a monolingual project, Hugo generates a sitemap.xml file in the root of the [`publishDir`] using the built-in [sitemap.xml] template. + +With a multilingual project, Hugo generates: + +- A sitemap.xml file in the root of each site (language) using the built-in [sitemap.xml] template +- A sitemap.xml file in the root of the [`publishDir`] using the built-in [sitemapindex.xml] template + +## Configuration + +Set the default values for [change frequency] and [priority], and the name of the generated file, in your site configuration. + - {{< code-toggle file="config" >}} ++{{< code-toggle file="hugo" >}} +[sitemap] + changefreq = 'monthly' + filename = 'sitemap.xml' + priority = 0.5 +{{}} + +changefreq +: How frequently a page is likely to change. Valid values are `always`, `hourly`, `daily`, `weekly`, `monthly`, `yearly`, and `never`. Default is `""` (change frequency omitted from rendered sitemap). + +filename +: The name of the generated file. Default is `sitemap.xml`. + +priority +: The priority of a page relative to any other page on the site. Valid values range from 0.0 to 1.0. Default is `-1` (priority omitted from rendered sitemap). + +## Override Default Values + +Override the default values for a given page in front matter. + +{{< code-toggle file="news.md" fm=true >}} +title = 'News' +[sitemap] + changefreq = 'weekly' + priority = 0.8 +{{}} + +## Override Built-in Templates + +To override the built-in sitemap.xml template, create a new file in either of these locations: + +- layouts/sitemap.xml +- layouts/_default/sitemap.xml + +When ranging through the page collection, access the _change frequency_ and _priority_ with `.Sitemap.ChangeFreq` and `.Sitemap.Priority` respectively. + +To override the built-in sitemapindex.xml template, create a new file in either of these locations: + +- layouts/sitemapindex.xml +- layouts/_default/sitemapindex.xml + +## Disable Sitemap Generation + +You may disable sitemap generation in your site configuration: + - {{< code-toggle file="config" >}} ++{{< code-toggle file="hugo" >}} +disableKinds = ['sitemap'] +{{}} + +[`publishDir`]: /getting-started/configuration#publishdir +[change frequency]: +[priority]: +[sitemap protocol]: +[sitemap.xml]: +[sitemapindex.xml]: diff --cc docs/content/en/variables/page.md index f8266965e,000000000..edad543ad mode 100644,000000..100644 --- a/docs/content/en/variables/page.md +++ b/docs/content/en/variables/page.md @@@ -1,325 -1,0 +1,325 @@@ +--- +title: Page Variables +description: Page-level variables are defined in a content file's front matter, derived from the content's file location, or extracted from the content body itself. +categories: [variables and params] +keywords: [pages] +menu: + docs: + parent: variables + weight: 20 +weight: 20 +toc: true +--- + +The following is a list of page-level variables. Many of these will be defined in the front matter, derived from file location, or extracted from the content itself. + +## Page Variables + +.AlternativeOutputFormats +: contains all alternative formats for a given page; this variable is especially useful `link rel` list in your site's ``. (See [Output Formats](/templates/output-formats/).) + +.Aliases +: aliases of this page + +.Ancestors +: get the ancestors of each page, simplify [breadcrumb navigation](/content-management/sections#example-breadcrumb-navigation) implementation complexity + +.BundleType +: the [bundle] type: `leaf`, `branch`, or an empty string if the page is not a bundle. + +.Content +: the content itself, defined below the front matter. + +.Data +: the data specific to this type of page. + +.Date +: the date associated with the page; `.Date` pulls from the `date` field in a content's front matter. See also `.ExpiryDate`, `.PublishDate`, and `.Lastmod`. + +.Description +: the description for the page. + +.Draft +: a boolean, `true` if the content is marked as a draft in the front matter. + +.ExpiryDate +: the date on which the content is scheduled to expire; `.ExpiryDate` pulls from the `expirydate` field in a content's front matter. See also `.PublishDate`, `.Date`, and `.Lastmod`. + +.File +: filesystem-related data for this content file. See also [File Variables]. + +.Fragments +: Fragments returns the fragments for this page. See [Page Fragments](#page-fragments). + +.FuzzyWordCount +: the approximate number of words in the content. + +.IsHome +: `true` in the context of the [homepage](/templates/homepage/). + +.IsNode +: always `false` for regular content pages. + +.IsPage +: always `true` for regular content pages. + +.IsSection +: `true` if [`.Kind`](/templates/section-templates/#page-kinds) is `section`. + +.IsTranslated +: `true` if there are translations to display. + +.Keywords +: the meta keywords for the content. + +.Kind +: the page's *kind*. Possible return values are `page`, `home`, `section`, `taxonomy`, or `term`. Note that there are also `RSS`, `sitemap`, `robotsTXT`, and `404` kinds, but these are only available during the rendering of each of these respective page's kind and therefore *not* available in any of the `Pages` collections. + +.Language - : a language object that points to the language's definition in the site `config`. `.Language.Lang` gives you the language code. ++: a language object that points to the language's definition in the site configuration. `.Language.Lang` gives you the language code. + +.Lastmod +: the date the content was last modified. `.Lastmod` pulls from the `lastmod` field in a content's front matter. + + - If `lastmod` is not set, and `.GitInfo` feature is disabled, the front matter `date` field will be used. + - If `lastmod` is not set, and `.GitInfo` feature is enabled, `.GitInfo.AuthorDate` will be used instead. + +See also `.ExpiryDate`, `.Date`, `.PublishDate`, and [`.GitInfo`][gitinfo]. + +.LinkTitle +: access when creating links to the content. If set, Hugo will use the `linktitle` from the front matter before `title`. + +.Next +: Points up to the next [regular page](/variables/site/#site-pages) (sorted by Hugo's [default sort](/templates/lists#default-weight--date--linktitle--filepath)). Example: `{{ with .Next }}{{ .Permalink }}{{ end }}`. Calling `.Next` from the first page returns `nil`. + +.NextInSection +: Points up to the next [regular page](/variables/site/#site-pages) below the same top level section (e.g. in `/blog`)). Pages are sorted by Hugo's [default sort](/templates/lists#default-weight--date--linktitle--filepath). Example: `{{ with .NextInSection }}{{ .Permalink }}{{ end }}`. Calling `.NextInSection` from the first page returns `nil`. + +.OutputFormats +: contains all formats, including the current format, for a given page. Can be combined the with [`.Get` function](/functions/get/) to grab a specific format. (See [Output Formats](/templates/output-formats/).) + +.Pages +: a collection of associated pages. This value will be `nil` within + the context of regular content pages. See [`.Pages`](#pages). + +.Permalink +: the Permanent link for this page; see [Permalinks](/content-management/urls/) + +.Plain +: the Page content stripped of HTML tags and presented as a string. You may need to pipe the result through the [`htmlUnescape`](/functions/htmlunescape/) function when rendering this value with the HTML [output format](/templates/output-formats#output-format-definitions). + +.PlainWords +: the slice of strings that results from splitting .Plain into words, as defined in Go's [strings.Fields](https://pkg.go.dev/strings#Fields). + +.Prev +: Points down to the previous [regular page](/variables/site/#site-pages) (sorted by Hugo's [default sort](/templates/lists#default-weight--date--linktitle--filepath)). Example: `{{ if .Prev }}{{ .Prev.Permalink }}{{ end }}`. Calling `.Prev` from the last page returns `nil`. + +.PrevInSection +: Points down to the previous [regular page](/variables/site/#site-pages) below the same top level section (e.g. `/blog`). Pages are sorted by Hugo's [default sort](/templates/lists#default-weight--date--linktitle--filepath). Example: `{{ if .PrevInSection }}{{ .PrevInSection.Permalink }}{{ end }}`. Calling `.PrevInSection` from the last page returns `nil`. + +.PublishDate +: the date on which the content was or will be published; `.Publishdate` pulls from the `publishdate` field in a content's front matter. See also `.ExpiryDate`, `.Date`, and `.Lastmod`. + +.RawContent +: raw markdown content without the front matter. Useful with [remarkjs.com]( +https://remarkjs.com) + +.ReadingTime +: the estimated time, in minutes, it takes to read the content. + +.Resources +: resources such as images and CSS that are associated with this page + +.Ref +: returns the permalink for a given reference (e.g., `.Ref "sample.md"`). `.Ref` does *not* handle in-page fragments correctly. See [Cross References](/content-management/cross-references/). + +.RelPermalink +: the relative permanent link for this page. + +.RelRef +: returns the relative permalink for a given reference (e.g., `RelRef +"sample.md"`). `.RelRef` does *not* handle in-page fragments correctly. See [Cross References](/content-management/cross-references/). + +.Site +: see [Site Variables](/variables/site/). + +.Sites +: returns all sites (languages). A typical use case would be to link back to the main language: `...`. + +.Sites.First +: returns the site for the first language. If this is not a multilingual setup, it will return itself. + +.Summary +: a generated summary of the content for easily showing a snippet in a summary view. The breakpoint can be set manually by inserting <!--more--> at the appropriate place in the content page, or the summary can be written independent of the page text. See [Content Summaries](/content-management/summaries/) for more details. + +.TableOfContents +: the rendered [table of contents](/content-management/toc/) for the page. + +.Title +: the title for this page. + +.Translations +: a list of translated versions of the current page. See [Multilingual Mode](/content-management/multilingual/) for more information. + +.TranslationKey +: the key used to map language translations of the current page. See [Multilingual Mode](/content-management/multilingual/) for more information. + +.Truncated +: a boolean, `true` if the `.Summary` is truncated. Useful for showing a "Read more..." link only when necessary. See [Summaries](/content-management/summaries/) for more information. + +.Type +: the [content type](/content-management/types/) of the content (e.g., `posts`). + +.Weight +: assigned weight (in the front matter) to this content, used in sorting. + +.WordCount +: the number of words in the content. + +## Writable Page-scoped Variables + +[.Scratch][scratch] +: returns a Scratch to store and manipulate data. In contrast to the [`.Store`][store] method, this scratch is reset on server rebuilds. + +[.Store][store] +: returns a Scratch to store and manipulate data. In contrast to the [`.Scratch`][scratch] method, this scratch is not reset on server rebuilds. + +## Section Variables and Methods + +Also see [Sections](/content-management/sections/). + +{{< readfile file="/content/en/readfiles/sectionvars.md" markdown="true" >}} + +## The `.Pages` Variable {#pages} + +`.Pages` is an alias to `.Data.Pages`. It is conventional to use the +aliased form `.Pages`. + +### `.Pages` compared to `.Site.Pages` + +{{< getcontent path="readfiles/pages-vs-site-pages.md" >}} + +## Page Fragments + +{{< new-in "0.111.0" >}} + +The `.Fragments` method returns a list of fragments for the current page. + +.Headings +: A recursive list of headings for the current page. Can be used to generate a table of contents. + +{{< todo >}}add .Headings toc example{{< /todo >}} + +.Identifiers +: A sorted list of identifiers for the current page. Can be used to check if a page contains a specific identifier or if a page contains duplicate identifiers: + +```go-html-template +{{ if .Fragments.Identifiers.Contains "my-identifier" }} +

Page contains identifier "my-identifier"

+{{ end }} + +{{ if gt (.Fragments.Identifiers.Count "my-identifier") 1 }} +

Page contains duplicate "my-identifier" fragments

+{{ end }} +``` + +.HeadingsMap +: Holds a map of headings for the current page. Can be used to start the table of contents from a specific heading. + +Also see the [Go Doc](https://pkg.go.dev/github.com/gohugoio/hugo@v0.111.0/markup/tableofcontents#Fragments) for the return type. + +### Fragments in hooks and shortcodes + +`.Fragments` are safe to call from render hooks, even on the page you're on (`.Page.Fragments`). For shortcodes we recommend that all `.Fragments` usage is nested inside the `{{}}` shortcode delimiter (`{{%/**/%}}` takes part in the ToC creation so it's easy to end up in a situation where you bite yourself in the tail). + + +## The global page function + +{{< new-in "0.111.1" >}} + +Hugo almost always passes a `Page` as the data context into the top level template (e.g. `single.html`) (the one exception is the multihost sitemap template). This means that you can access the current page with the `.` variable in the template. + +But when you're deeply nested inside `.Render`, partial etc., accessing that `Page` object isn't always practical or possible. + +For this reason, Hugo provides a global `page` function that you can use to access the current page from anywhere in any template. + +```go-html-template +{{ page.Title }} +``` + +There are one caveat with this, and this isn't new, but it's worth mentioning here: There are situations in Hugo where you may see a cached value, e.g. when using `partialCached` or in a shortcode. + +## Page-level Params + +Any other value defined in the front matter in a content file, including taxonomies, will be made available as part of the `.Params` variable. + +{{< code-toggle file="content/example.md" fm=true copy=false >}} +title: Example +categories: [one] +tags: [two,three,four] +{{< /code-toggle >}} + +With the above front matter, the `tags` and `categories` taxonomies are accessible via the following: + +* `.Params.tags` +* `.Params.categories` + +The `.Params` variable is particularly useful for the introduction of user-defined front matter fields in content files. For example, a Hugo website on book reviews could have the following front matter: + +{{< code-toggle file="content/example.md" fm=true copy=false >}} +title: Example +affiliatelink: "http://www.my-book-link.here" +recommendedby: "My Mother" +{{< /code-toggle >}} + +These fields would then be accessible to via `.Params.affiliatelink` and `.Params.recommendedby`. + +```go-html-template +

Buy this book

+

It was recommended by {{ .Params.recommendedby }}.

+``` + +This template would render as follows: + +```html +

Buy this book

+

It was recommended by my Mother.

+``` + +{{% note %}} +See [Archetypes](/content-management/archetypes/) for consistency of `Params` across pieces of content. +{{% /note %}} + +### The `.Param` Method + +In Hugo, you can declare params in individual pages and globally for your entire website. A common use case is to have a general value for the site param and a more specific value for some of the pages (i.e., a header image): + +```go-html-template +{{ $.Param "header_image" }} +``` + - The `.Param` method provides a way to resolve a single value according to it's definition in a page parameter (i.e. in the content's front matter) or a site parameter (i.e., in your `config`). ++The `.Param` method provides a way to resolve a single value according to it's definition in a page parameter (i.e. in the content's front matter) or a site parameter (i.e., in your site configuration). + +### Access Nested Fields in Front Matter + +When front matter contains nested fields like the following: + +{{< code-toggle file="content/example.md" fm=true copy=false >}} +title: Example +author: + given_name: John + family_name: Feminella + display_name: John Feminella +{{< /code-toggle >}} + +`.Param` can access these fields by concatenating the field names together with a dot: + +```go-html-template +{{ $.Param "author.display_name" }} +``` + +[gitinfo]: /variables/git/ +[File Variables]: /variables/files/ +[bundle]: /content-management/page-bundles +[scratch]: /functions/scratch +[store]: /functions/store diff --cc docs/content/en/variables/site.md index 71111eb83,000000000..7e587cc79 mode 100644,000000..100644 --- a/docs/content/en/variables/site.md +++ b/docs/content/en/variables/site.md @@@ -1,123 -1,0 +1,123 @@@ +--- +title: Site Variables +description: Many, but not all, site-wide variables are defined in your site's configuration. However, Hugo provides a number of built-in variables for convenient access to global values in your templates. +categories: [variables and params] +keywords: [global,site] +menu: + docs: + parent: variables + weight: 10 +weight: 10 +aliases: [/variables/site-variables/] +toc: true +--- + +The following is a list of site-level (aka "global") variables. Many of these variables are defined in your site's [configuration file][config], whereas others are built into Hugo's core for convenient usage in your templates. + +## Get the Site object from a partial + +All the methods below, e.g. `.Site.RegularPages` can also be reached via the global [`site`](/functions/site/) function, e.g. `site.RegularPages`, which can be handy in partials where the `Page` object isn't easily available. + +## Site Variables List + +.Site.AllPages +: array of all pages, regardless of their translation. + +.Site.BaseURL +: the base URL for the site as defined in the site configuration. + +.Site.BuildDrafts +: a boolean (default: `false`) to indicate whether to build drafts as defined in the site configuration. + +.Site.Copyright +: a string representing the copyright of your website as defined in the site configuration. + +.Site.Data +: custom data, see [Data Templates](/templates/data-templates/). + +.Site.DisqusShortname +: a string representing the shortname of the Disqus shortcode as defined in the site configuration. + +.Site.GoogleAnalytics +: a string representing your tracking code for Google Analytics as defined in the site configuration. + +.Site.Home +: reference to the homepage's [page object](https://gohugo.io/variables/page/) + +.Site.IsMultiLingual +: whether there are more than one language in this site. See [Multilingual](/content-management/multilingual/) for more information. + +.Site.IsServer +: a boolean to indicate if the site is being served with Hugo's built-in server. See [`hugo server`](/commands/hugo_server/) for more information. + +.Site.Language.Lang +: the language code of the current locale (e.g., `en`). + +.Site.Language.LanguageName +: the full language name (e.g. `English`). + +.Site.Language.Weight +: the weight that defines the order in the `.Site.Languages` list. + +.Site.Language +: indicates the language currently being used to render the website. This object's attributes are set in site configurations' language definition. + +.Site.LanguageCode +: a string representing the language tag as defined in the site configuration. + +.Site.LanguagePrefix +: this can be used to prefix URLs to point to the correct language. It will even work when only one defined language. See also the functions [absLangURL](/functions/abslangurl/) and [relLangURL](/functions/rellangurl). + +.Site.Languages +: an ordered list (ordered by defined weight) of languages. + +.Site.LastChange +: a string representing the date/time of the most recent change to your site. This string is based on the [`date` variable in the front matter](/content-management/front-matter) of your content pages. + +.Site.Menus +: all the menus in the site. + +.Site.Pages +: array of all content ordered by Date with the newest first. This array contains only the pages in the current language. See [`.Site.Pages`](#site-pages). + +.Site.RegularPages +: a shortcut to the *regular* page collection. `.Site.RegularPages` is equivalent to `where .Site.Pages "Kind" "page"`. See [`.Site.Pages`](#site-pages). + +.Site.Sections +: top-level directories of the site. + +.Site.Taxonomies +: the [taxonomies](/content-management/taxonomies/) for the entire site. Also see section [Access taxonomy data from any template](/variables/taxonomy/#access-taxonomy-data-from-any-template). + +.Site.Title +: a string representing the title of the site. + +## The `.Site.Params` Variable + +`.Site.Params` is a container holding the values from the `params` section of your site configuration. + +### Example: `.Site.Params` + +The following `config.[yaml|toml|json]` defines a site-wide param for `description`: + - {{< code-toggle file="config" >}} ++{{< code-toggle file="hugo" >}} +baseURL = "https://yoursite.example.com/" + +[params] + description = "Tesla's Awesome Hugo Site" + author = "Nikola Tesla" +{{}} + +You can use `.Site.Params` in a [partial template](/templates/partials/) to call the default site description: + +{{< code file="layouts/partials/head.html" >}} + +{{< /code >}} + +## The `.Site.Pages` Variable {#site-pages} + +### `.Site.Pages` compared to `.Pages` + +{{< getcontent path="readfiles/pages-vs-site-pages.md" >}} + +[config]: /getting-started/configuration/ diff --cc docs/go.mod index 07badfeaf,000000000..3c5460fd5 mode 100644,000000..100644 --- a/docs/go.mod +++ b/docs/go.mod @@@ -1,5 -1,0 +1,5 @@@ +module github.com/gohugoio/hugoDocs + +go 1.16 + - require github.com/gohugoio/gohugoioTheme v0.0.0-20230418063032-99f9185b8e11 // indirect ++require github.com/gohugoio/gohugoioTheme v0.0.0-20230527124826-78bc315d7b8a // indirect diff --cc docs/go.sum index 6783cb92e,000000000..9db956ea8 mode 100644,000000..100644 --- a/docs/go.sum +++ b/docs/go.sum @@@ -1,65 -1,0 +1,67 @@@ +github.com/gohugoio/gohugoioTheme v0.0.0-20190808163145-07b3c0f73b02/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= +github.com/gohugoio/gohugoioTheme v0.0.0-20191014144142-1f3a01deed7b h1:PWNjl46fvtz54PKO0BdiXOF6/4L/uCP0F3gtcCxGrJs= +github.com/gohugoio/gohugoioTheme v0.0.0-20191014144142-1f3a01deed7b/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= +github.com/gohugoio/gohugoioTheme v0.0.0-20191021162625-2e7250ca437d h1:D3DcaYkuJbotdWNNAQpQl37txX4HQ6R5uMHoxVmTw0w= +github.com/gohugoio/gohugoioTheme v0.0.0-20191021162625-2e7250ca437d/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= +github.com/gohugoio/gohugoioTheme v0.0.0-20200123151337-9475fd449324 h1:UZwHDYtGY0uOKIvcm2LWd+xfFxD3X5L222LIJdI5RE4= +github.com/gohugoio/gohugoioTheme v0.0.0-20200123151337-9475fd449324/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= +github.com/gohugoio/gohugoioTheme v0.0.0-20200123204146-589b4c309025 h1:ScYFARz+bHX1rEr1donVknhRdxGY/cwqK1hHvWEfrlc= +github.com/gohugoio/gohugoioTheme v0.0.0-20200123204146-589b4c309025/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= +github.com/gohugoio/gohugoioTheme v0.0.0-20200123205007-5d6620a0db26 h1:acXfduibbWxji9tW0WkLHbjcXFsnd5uIwXe0WfwOazg= +github.com/gohugoio/gohugoioTheme v0.0.0-20200123205007-5d6620a0db26/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= +github.com/gohugoio/gohugoioTheme v0.0.0-20200128164921-1d0bc5482051 h1:cS14MnUGS6xwWYfPNshimm8HdMCZiYBxWkCD0VnvgVw= +github.com/gohugoio/gohugoioTheme v0.0.0-20200128164921-1d0bc5482051/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= +github.com/gohugoio/gohugoioTheme v0.0.0-20200327225449-368f4cbef8d7 h1:cZ+ahAjSetbFv3aDJ9ipDbKyqaVlmkbSZ5cULgBTh+w= +github.com/gohugoio/gohugoioTheme v0.0.0-20200327225449-368f4cbef8d7/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= +github.com/gohugoio/gohugoioTheme v0.0.0-20200327231942-7f80b3d02bfa h1:kG+O/wT9UXomzp5eQiUuFVZ0l7YylAW6EVPLyjMxi/c= +github.com/gohugoio/gohugoioTheme v0.0.0-20200327231942-7f80b3d02bfa/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= +github.com/gohugoio/gohugoioTheme v0.0.0-20200328100657-2bfd5f8c6aee h1:PJZhCwnuVLyafDWNPSHk9iJvk6gEIvPRnycy7Pq3peA= +github.com/gohugoio/gohugoioTheme v0.0.0-20200328100657-2bfd5f8c6aee/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= +github.com/gohugoio/gohugoioTheme v0.0.0-20200518164958-62cbad03c40f h1:Ge3JACszSUyJW2Az9cJzWdo4PUqdijJA1RxoQSVMBSI= +github.com/gohugoio/gohugoioTheme v0.0.0-20200518164958-62cbad03c40f/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= +github.com/gohugoio/gohugoioTheme v0.0.0-20200518165806-0095b7b902a7 h1:Sy0hlWyZmFtdSY0Cobvw1ZYm3G1aR5+4DuFNRbMkh48= +github.com/gohugoio/gohugoioTheme v0.0.0-20200518165806-0095b7b902a7/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= +github.com/gohugoio/gohugoioTheme v0.0.0-20200711112515-b0dfe471654f h1:BWJyycs4HD7tUbaU8RIGeMay84bIBWRVVLE3yajPas4= +github.com/gohugoio/gohugoioTheme v0.0.0-20200711112515-b0dfe471654f/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= +github.com/gohugoio/gohugoioTheme v0.0.0-20210301124928-2c15837dfec3 h1:ShqzOFeeg54FPSuS6q8HSeTVgj2xNZRe/YS0jNbi21g= +github.com/gohugoio/gohugoioTheme v0.0.0-20210301124928-2c15837dfec3/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= +github.com/gohugoio/gohugoioTheme v0.0.0-20210409065807-6383d8cbaf65 h1:EJzierSWKqwsrUXU6MaFe0J97c0e5pzl5dBNRRrV2Nc= +github.com/gohugoio/gohugoioTheme v0.0.0-20210409065807-6383d8cbaf65/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= +github.com/gohugoio/gohugoioTheme v0.0.0-20210409071416-c88da48134b7 h1:uRCgPslaBgLYy4ANXBoPbBQVM8aNiHoxIZTKUXpkuUA= +github.com/gohugoio/gohugoioTheme v0.0.0-20210409071416-c88da48134b7/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= +github.com/gohugoio/gohugoioTheme v0.0.0-20211211125852-b85e21c1f3d6 h1:lAgdWrn8VEg0PrNCPX4DflCg2msDKpSYV6E8RTNV3N0= +github.com/gohugoio/gohugoioTheme v0.0.0-20211211125852-b85e21c1f3d6/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= +github.com/gohugoio/gohugoioTheme v0.0.0-20220228085601-7cfbda06d135 h1:6hVzfE9YhSsZP5t6jWjvVp7MoPm7Y5fEhH/ls4ahhKk= +github.com/gohugoio/gohugoioTheme v0.0.0-20220228085601-7cfbda06d135/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= +github.com/gohugoio/gohugoioTheme v0.0.0-20220905093719-cb8b64046950 h1:Ovlh3nuy/aNptYZHmIra2MP+ZUEqiihY0HxvhdaMqGg= +github.com/gohugoio/gohugoioTheme v0.0.0-20220905093719-cb8b64046950/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= +github.com/gohugoio/gohugoioTheme v0.0.0-20220912070954-88dcaf003b4d h1:UYJL6RmEepprvlgHvDnFCWtPOvjmqzFCQ90cRDRBO7U= +github.com/gohugoio/gohugoioTheme v0.0.0-20220912070954-88dcaf003b4d/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= +github.com/gohugoio/gohugoioTheme v0.0.0-20220914071648-0ef1c51685bf h1:A8Ksnvp8reNt2Ap0mUK7gFkJkCjt9R60yopGsezcOBA= +github.com/gohugoio/gohugoioTheme v0.0.0-20220914071648-0ef1c51685bf/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= +github.com/gohugoio/gohugoioTheme v0.0.0-20221116211530-5ae8dcdd68d6 h1:eG53kL1LkQuKmrDdzbvvx6d60qM07zp2Wjo/tYxkDOY= +github.com/gohugoio/gohugoioTheme v0.0.0-20221116211530-5ae8dcdd68d6/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= +github.com/gohugoio/gohugoioTheme v0.0.0-20221118083537-967e29e21382 h1:e30rl1dxWkYOcgdl0omeOK0HBzgDLI/b9MfYHrINjzU= +github.com/gohugoio/gohugoioTheme v0.0.0-20221118083537-967e29e21382/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= +github.com/gohugoio/gohugoioTheme v0.0.0-20221124154621-1451a01f406b h1:TRrIisSY7ckt9FVHOOQtmKG4jsnORCYn72UMvMu+IQ0= +github.com/gohugoio/gohugoioTheme v0.0.0-20221124154621-1451a01f406b/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= +github.com/gohugoio/gohugoioTheme v0.0.0-20221206093948-1408550ab675 h1:wjpYa1cTELeceWndBDV7IG2vRxRWICBBO79HObOfTtk= +github.com/gohugoio/gohugoioTheme v0.0.0-20221206093948-1408550ab675/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= +github.com/gohugoio/gohugoioTheme v0.0.0-20221217122332-1c1752ad8f14 h1:K6tPFpi7W0zb89QIf+lNdgdTXfDFemU6NKk46MlX9lQ= +github.com/gohugoio/gohugoioTheme v0.0.0-20221217122332-1c1752ad8f14/go.mod h1:kpw3SS48xZvLQGEXKu8u5XHgXkPvL8DX3oGa07+z8Bs= +github.com/gohugoio/gohugoioTheme v0.0.0-20221220160735-8ffa1ef883b6 h1:yEoQecRBoLGfc7yTybMD3Mhm03bTScZFYPvwe0p75vA= +github.com/gohugoio/gohugoioTheme v0.0.0-20221220160735-8ffa1ef883b6/go.mod h1:GOYeAPQJ/ok8z7oz1cjfcSlsFpXrmx6VkzQ5RpnyhZM= +github.com/gohugoio/gohugoioTheme v0.0.0-20230109120406-12694c4a9456 h1:RSLItaapVjWkqSdQhumAmJkodFDbWMGNZmkVW/AFx0c= +github.com/gohugoio/gohugoioTheme v0.0.0-20230109120406-12694c4a9456/go.mod h1:GOYeAPQJ/ok8z7oz1cjfcSlsFpXrmx6VkzQ5RpnyhZM= +github.com/gohugoio/gohugoioTheme v0.0.0-20230119103504-3bcd960d6f1b h1:i/iaEOOuR1mKRR0qUOET587ooVhG8c2tllpA5HsrWNU= +github.com/gohugoio/gohugoioTheme v0.0.0-20230119103504-3bcd960d6f1b/go.mod h1:GOYeAPQJ/ok8z7oz1cjfcSlsFpXrmx6VkzQ5RpnyhZM= +github.com/gohugoio/gohugoioTheme v0.0.0-20230120185049-2c3c4d0ba232 h1:bEojKgKInbsLkID5Arh95vP4+0xydtn/+ayT6I8vkiU= +github.com/gohugoio/gohugoioTheme v0.0.0-20230120185049-2c3c4d0ba232/go.mod h1:GOYeAPQJ/ok8z7oz1cjfcSlsFpXrmx6VkzQ5RpnyhZM= +github.com/gohugoio/gohugoioTheme v0.0.0-20230124135550-462d5fe4a87f h1:8wI3zOTWQG15aKkbAZQaoGnUQff46hO95opQndBHRE4= +github.com/gohugoio/gohugoioTheme v0.0.0-20230124135550-462d5fe4a87f/go.mod h1:GOYeAPQJ/ok8z7oz1cjfcSlsFpXrmx6VkzQ5RpnyhZM= +github.com/gohugoio/gohugoioTheme v0.0.0-20230330081257-7a8c9614432c h1:TyHgmowfiMyxKrqTdRxm/yWIFeN7XRh7Hm6/dOG6yDA= +github.com/gohugoio/gohugoioTheme v0.0.0-20230330081257-7a8c9614432c/go.mod h1:GOYeAPQJ/ok8z7oz1cjfcSlsFpXrmx6VkzQ5RpnyhZM= +github.com/gohugoio/gohugoioTheme v0.0.0-20230418063032-99f9185b8e11 h1:mDcricMewd66x8QjKqNun7Div7iYVLtl8s1dVs9VnB8= +github.com/gohugoio/gohugoioTheme v0.0.0-20230418063032-99f9185b8e11/go.mod h1:GOYeAPQJ/ok8z7oz1cjfcSlsFpXrmx6VkzQ5RpnyhZM= ++github.com/gohugoio/gohugoioTheme v0.0.0-20230527124826-78bc315d7b8a h1:ruyA3QZ4Ym0fBLhTW2eoUSvHUaj2xWqaPHIbaI+tbZo= ++github.com/gohugoio/gohugoioTheme v0.0.0-20230527124826-78bc315d7b8a/go.mod h1:GOYeAPQJ/ok8z7oz1cjfcSlsFpXrmx6VkzQ5RpnyhZM= diff --cc docs/layouts/shortcodes/code-toggle.html index b4cfaaa20,000000000..3b151669f mode 100644,000000..100644 --- a/docs/layouts/shortcodes/code-toggle.html +++ b/docs/layouts/shortcodes/code-toggle.html @@@ -1,87 -1,0 +1,87 @@@ +{{- /* +Renders syntax-highlighted configuration data in JSON, TOML, and YAML formats. + +@param {string} [config] The section of site.Data.docs.config to render. +@param {bool} [copy=true] If true, display a copy to clipboard button. +@param {string} [file] The file name to display above the rendered code. +@param {bool} [fm=false] If true, render the code as front matter. +@param {bool} [skipHeader=false] If false, omit top level key(s) when rendering a section of site.Data.docs.config. + +@returns {template.HTML} +*/}} + +{{- /* Initialize. */}} +{{- $config := "" }} +{{- $copy := true }} +{{- $file := "" }} +{{- $fm := false }} +{{- $skipHeader := false }} + +{{- /* Get parameters. */}} +{{- $config = .Get "config" }} +{{- $file = .Get "file" }} +{{- if in (slice "false" false 0) (.Get "copy") }} + {{- $copy = false }} +{{- else if in (slice "true" true 1) (.Get "copy")}} + {{- $copy = true }} +{{- end }} +{{- if in (slice "false" false 0) (.Get "fm") }} + {{- $fm = false }} +{{- else if in (slice "true" true 1) (.Get "fm")}} + {{- $fm = true }} +{{- end }} +{{- if in (slice "false" false 0) (.Get "skipHeader") }} + {{- $skipHeader = false }} +{{- else if in (slice "true" true 1) (.Get "skipHeader")}} + {{- $skipHeader = true }} +{{- end }} + +{{- /* Define constants. */}} +{{- $delimiters := dict "toml" "+++" "yaml" "---" }} +{{- $langs := slice "yaml" "toml" "json" }} +{{- $placeHolder := "#-hugo-placeholder-#" }} + +{{- /* Render. */}} +{{- $code := "" }} +{{- with $config }} - {{- $file = $file | default "config" }} ++ {{- $file = $file | default "hugo" }} + {{- $sections := (split . ".") }} + {{- $configSection := index $.Site.Data.docs.config $sections }} + {{- $code = dict $sections $configSection }} + {{- if $skipHeader }} + {{- $code = $configSection }} + {{- end }} +{{- else }} + {{- $code = $.Inner }} +{{- end }} +
+
+ {{- with $file }} +
+ {{ . }}{{ if not $fm }}.{{ end }} +
+ {{- end }} + {{- range $langs }} + +   + {{- end }} +
+
+ {{- range $langs }} +
+ {{- $hCode := $code | transform.Remarshal . }} + {{- if and $fm (in (slice "toml" "yaml") .) }} + {{- $hCode = printf "%s\n%s\n%s" $placeHolder $hCode $placeHolder }} + {{- end }} + {{- $hCode = $hCode | replaceRE `\n+` "\n" }} + {{ highlight $hCode . "" | replaceRE $placeHolder (index $delimiters .) | safeHTML }} +
+ {{- if $copy }} + + {{- /* Functionality located within filesaver.js The copy here is located in the css with .copy class so it can be replaced with JS on success */}} + {{- end }} + {{- end }} +
+
diff --cc docs/layouts/shortcodes/new-in.html index e81fda3c5,000000000..71d1abfdf mode 100644,000000..100644 --- a/docs/layouts/shortcodes/new-in.html +++ b/docs/layouts/shortcodes/new-in.html @@@ -1,8 -1,0 +1,13 @@@ +{{ $version := .Get 0 }} +{{ if not $version }} - {{ errorf "Missing version in new-in shortcode "}} ++ {{ errorf "Missing version in new-in shortcode " }} +{{ end }} +{{ $version = $version | strings.TrimPrefix "v" }} - diff --cc docs/netlify.toml index a07e29a94,000000000..c3c26e87f mode 100644,000000..100644 --- a/docs/netlify.toml +++ b/docs/netlify.toml @@@ -1,35 -1,0 +1,35 @@@ +[build] +publish = "public" +command = "hugo --gc --minify" + +[context.production.environment] - HUGO_VERSION = "0.111.3" ++HUGO_VERSION = "0.112.3" +HUGO_ENV = "production" +HUGO_ENABLEGITINFO = "true" + +[context.split1] +command = "hugo --gc --minify --enableGitInfo" + +[context.split1.environment] - HUGO_VERSION = "0.111.3" ++HUGO_VERSION = "0.112.3" +HUGO_ENV = "production" + +[context.deploy-preview] +command = "hugo --gc --minify --buildFuture -b $DEPLOY_PRIME_URL" + +[context.deploy-preview.environment] - HUGO_VERSION = "0.111.3" ++HUGO_VERSION = "0.112.3" + +[context.branch-deploy] +command = "hugo --gc --minify -b $DEPLOY_PRIME_URL" + +[context.branch-deploy.environment] - HUGO_VERSION = "0.111.3" ++HUGO_VERSION = "0.112.3" + +[context.next.environment] +HUGO_ENABLEGITINFO = "true" + +[[redirects]] +from = "/npmjs/*" +to = "/npmjs/" +status = 200