From: Bjørn Erik Pedersen Date: Sun, 4 Jul 2021 14:34:53 +0000 (+0200) Subject: Merge commit '7eb0e10a80708c638554b8221a3120dc1168566c' X-Git-Tag: v0.85.0~9 X-Git-Url: http://git.maquefel.me/?a=commitdiff_plain;h=4479f09c9cfde4e0aeb6cc72b5b0197f3eefb0d2;p=brevno-suite%2Fhugo Merge commit '7eb0e10a80708c638554b8221a3120dc1168566c' --- 4479f09c9cfde4e0aeb6cc72b5b0197f3eefb0d2 diff --cc docs/content/en/content-management/image-processing/index.md index 40af0d6a,00000000..76679717 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,348 -1,0 +1,346 @@@ +--- +title: "Image Processing" +description: "Image Page resources can be resized and cropped." +date: 2018-01-24T13:10:00-05:00 +linktitle: "Image Processing" +categories: ["content management"] +keywords: [resources, images] +weight: 4004 +draft: false +toc: true +menu: + docs: + parent: "content-management" + weight: 32 +--- + +## The Image Page Resource + +The `image` is a [Page Resource]({{< relref "/content-management/page-resources" >}}), and the processing methods listed below do not work on images inside your `/static` folder. + +To print all images paths in a [Page Bundle]({{< relref "/content-management/organization#page-bundles" >}}): + +```go-html-template +{{ with .Resources.ByType "image" }} +{{ range . }} +{{ .RelPermalink }} +{{ end }} +{{ end }} + +``` + +## The Image Resource + +The `image` resource can also be retrieved from a [global resource]({{< relref "/hugo-pipes/introduction#from-file-to-resource" >}}) + +```go-html-template +{{- $image := resources.Get "images/logo.jpg" -}} +``` + +## Image Processing Methods + +The `image` resource implements the `Resize`, `Fit`, `Fill`, and `Filter` methods, each returning a transformed image using the specified dimensions and processing options. + +{{% note %}} +Metadata (EXIF, IPTC, XMP, etc.) is not preserved during image transformation. Use the [`Exif`](#exif) method with the _original_ image to extract EXIF metadata from JPEG or TIFF images. +{{% /note %}} + +### Resize + +Resizes the image to the specified width and height. + +```go +// Resize to a width of 600px and preserve ratio +{{ $image := $resource.Resize "600x" }} + +// Resize to a height of 400px and preserve ratio +{{ $image := $resource.Resize "x400" }} + +// Resize to a width 600px and a height of 400px +{{ $image := $resource.Resize "600x400" }} +``` + +### Fit + +Scale down the image to fit the given dimensions while maintaining aspect ratio. Both height and width are required. + +```go +{{ $image := $resource.Fit "600x400" }} +``` + +### Fill + +Resize and crop the image to match the given dimensions. Both height and width are required. + +```go +{{ $image := $resource.Fill "600x400" }} +``` + +### Filter + +Apply one or more filters to your image. See [Image Filters](/functions/images/#image-filters) for a full list. + +```go-html-template +{{ $img = $img.Filter (images.GaussianBlur 6) (images.Pixelate 8) }} +``` + +The above can also be written in a more functional style using pipes: + +```go-html-template +{{ $img = $img | images.Filter (images.GaussianBlur 6) (images.Pixelate 8) }} +``` + +The filters will be applied in the given order. + +Sometimes it can be useful to create the filter chain once and then reuse it: + +```go-html-template +{{ $filters := slice (images.GaussianBlur 6) (images.Pixelate 8) }} +{{ $img1 = $img1.Filter $filters }} +{{ $img2 = $img2.Filter $filters }} +``` + +### Exif + +Provides an [Exif](https://en.wikipedia.org/wiki/Exif) object with metadata about the image. + +Note that this is only supported for JPEG and TIFF images, so it's recommended to wrap the access with a `with`, e.g.: + +```go-html-template +{{ with $img.Exif }} +Date: {{ .Date }} +Lat/Long: {{ .Lat}}/{{ .Long }} +Tags: +{{ range $k, $v := .Tags }} +TAG: {{ $k }}: {{ $v }} +{{ end }} +{{ end }} +``` + +Or individually access EXIF data with dot access, e.g.: + +```go-html-template +{{ with $src.Exif }} + +{{ end }} +``` + +Some fields may need to be formatted with [`lang.NumFmt`]({{< relref "functions/numfmt" >}}) function to prevent display like `Aperture: 2.278934289` instead of `Aperture: 2.28`. + +#### Exif fields + +Date +: "photo taken" date/time + +Lat +: "photo taken where", GPS latitude + +Long +: "photo taken where", GPS longitude + +See [Image Processing Config](#image-processing-config) for how to configure what gets included in Exif. + +## Image Processing Options + +In addition to the dimensions (e.g. `600x400`), Hugo supports a set of additional image options. + +### Background Color + +The background color to fill into the transparency layer. This is mostly useful when converting to a format that does not support transparency, e.g. `JPEG`. + +You can set the background color to use with a 3 or 6 digit hex code starting with `#`. + +```go +{{ $image.Resize "600x jpg #b31280" }} +``` + +For color codes, see https://www.google.com/search?q=color+picker + +**Note** that you also set a default background color to use, see [Image Processing Config](#image-processing-config). + +### JPEG and WebP Quality + +Only relevant for JPEG and WebP images, values 1 to 100 inclusive, higher is better. Default is 75. + +```go +{{ $image.Resize "600x q50" }} +``` + +{{< new-in "0.83.0" >}} WebP support was added in Hugo 0.83.0. + +### Hint + + {{< new-in "0.83.0" >}} + + {{< new-in "0.83.0" >}} + +Hint about what type of image this is. Currently only used when encoding to WebP. + +Default value is `photo`. + +Valid values are `picture`, `photo`, `drawing`, `icon`, or `text`. + +```go +{{ $image.Resize "600x webp drawing" }} +``` + +### Rotate + +Rotates an image by the given angle counter-clockwise. The rotation will be performed first to get the dimensions correct. The main use of this is to be able to manually correct for [EXIF orientation](https://github.com/golang/go/issues/4341) of JPEG images. + +```go +{{ $image.Resize "600x r90" }} +``` + +### Anchor + +Only relevant for the `Fill` method. This is useful for thumbnail generation where the main motive is located in, say, the left corner. + +Valid values are `Smart`, `Center`, `TopLeft`, `Top`, `TopRight`, `Left`, `Right`, `BottomLeft`, `Bottom`, `BottomRight`. + +Default value is `Smart`, which uses [Smartcrop](https://github.com/muesli/smartcrop) to determine the best crop. + +```go +{{ $image.Fill "300x200 BottomLeft" }} +``` + +### Resample Filter + +Filter used in resizing. Default is `Box`, a simple and fast resampling filter appropriate for downscaling. + +Examples are: `Box`, `NearestNeighbor`, `Linear`, `Gaussian`. + +See https://github.com/disintegration/imaging for more. If you want to trade quality for faster processing, this may be a option to test. + +```go +{{ $image.Resize "600x400 Gaussian" }} +``` + +### Target Format + +By default the images is encoded in the source format, but you can set the target format as an option. + +Valid values are `jpg`, `png`, `tif`, `bmp`, `gif` and `webp`. + +```go +{{ $image.Resize "600x jpg" }} +``` + +{{< new-in "0.83.0" >}} WebP support was added in Hugo 0.83.0. + +## Image Processing Examples + +_The photo of the sunset used in the examples below is Copyright [Bjørn Erik Pedersen](https://commons.wikimedia.org/wiki/User:Bep) (Creative Commons Attribution-Share Alike 4.0 International license)_ + +{{< imgproc sunset Resize "300x" />}} + +{{< imgproc sunset Fill "90x120 left" />}} + +{{< imgproc sunset Fill "90x120 right" />}} + +{{< imgproc sunset Fit "90x90" />}} + +{{< imgproc sunset Resize "300x q10" />}} + +This is the shortcode used in the examples above: + +{{< code file="layouts/shortcodes/imgproc.html" >}} +{{< readfile file="layouts/shortcodes/imgproc.html" >}} +{{< /code >}} + +And it is used like this: + +```go-html-template +{{}} +``` + +{{% note %}} +**Tip:** Note the self-closing shortcode syntax above. The `imgproc` shortcode can be called both with and without **inner content**. +{{% /note %}} + +## Image Processing Config + +You can configure an `imaging` section in `config.toml` with default image processing options: + +```toml +[imaging] +# Default resample filter used for resizing. Default is Box, +# a simple and fast averaging filter appropriate for downscaling. +# See https://github.com/disintegration/imaging +resampleFilter = "box" + +# Default JPEG or WebP quality setting. Default is 75. +quality = 75 + +# Default hint about what type of image. Currently only used for WebP encoding. +# Default is "photo". +# Valid values are "picture", "photo", "drawing", "icon", or "text". +hint = "photo" + +# Anchor used when cropping pictures. +# Default is "smart" which does Smart Cropping, using https://github.com/muesli/smartcrop +# Smart Cropping is content aware and tries to find the best crop for each image. +# Valid values are Smart, Center, TopLeft, Top, TopRight, Left, Right, BottomLeft, Bottom, BottomRight +anchor = "smart" + +# Default background color. +# Hugo will preserve transparency for target formats that supports it, +# but will fall back to this color for JPEG. +# Expects a standard HEX color string with 3 or 6 digits. +# See https://www.google.com/search?q=color+picker +bgColor = "#ffffff" + +[imaging.exif] + # Regexp matching the fields you want to Exclude from the (massive) set of Exif info +# available. As we cache this info to disk, this is for performance and +# disk space reasons more than anything. +# If you want it all, put ".*" in this config setting. +# Note that if neither this or ExcludeFields is set, Hugo will return a small +# default set. +includeFields = "" + +# Regexp matching the Exif fields you want to exclude. This may be easier to use +# than IncludeFields above, depending on what you want. +excludeFields = "" + +# Hugo extracts the "photo taken" date/time into .Date by default. +# Set this to true to turn it off. +disableDate = false + +# Hugo extracts the "photo taken where" (GPS latitude and longitude) into +# .Long and .Lat. Set this to true to turn it off. +disableLatLong = false - - +``` + +## Smart Cropping of Images + +By default, Hugo will use [Smartcrop](https://github.com/muesli/smartcrop), a library created by [muesli](https://github.com/muesli), when cropping images with `.Fill`. You can set the anchor point manually, but in most cases the smart option will make a good choice. And we will work with the library author to improve this in the future. + +An example using the sunset image from above: + +{{< imgproc sunset Fill "200x200 smart" />}} + +## Image Processing Performance Consideration + +Processed images are stored below `/resources` (can be set with `resourceDir` config setting). This folder is deliberately placed in the project, as it is recommended to check these into source control as part of the project. These images are not "Hugo fast" to generate, but once generated they can be reused. + +If you change your image settings (e.g. size), remove or rename images etc., you will end up with unused images taking up space and cluttering your project. + +To clean up, run: + +```bash +hugo --gc +``` + +{{% note %}} +**GC** is short for **Garbage Collection**. +{{% /note %}} diff --cc docs/content/en/content-management/sections.md index 79ae201d,00000000..6806e342 mode 100644,000000..100644 --- a/docs/content/en/content-management/sections.md +++ b/docs/content/en/content-management/sections.md @@@ -1,98 -1,0 +1,101 @@@ +--- +title: Content Sections +linktitle: Sections +description: "Hugo generates a **section tree** that matches your content." +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +categories: [content management] +keywords: [lists,sections,content types,organization] +menu: + docs: + parent: "content-management" + weight: 50 +weight: 50 #rem +draft: false +aliases: [/content/sections/] +toc: true +--- + +A **Section** is a collection of pages that gets defined based on the +organization structure under the `content/` directory. + +By default, all the **first-level** directories under `content/` form their own - sections (**root sections**). ++sections (**root sections**) provided they constitute [Branch Bundles][branch bundles]. ++Directories which are just [Leaf Bundles][leaf bundles] do *not* form ++their own sections, despite being first-level directories. + +If a user needs to define a section `foo` at a deeper level, they need to create +a directory named `foo` with an `_index.md` file (see [Branch Bundles][branch bundles] +for more information). + + +{{% note %}} +A **section** cannot be defined or overridden by a front matter parameter -- it +is strictly derived from the content organization structure. +{{% /note %}} + +## Nested Sections + +The sections can be nested as deeply as you need. + +```bash +content +└── blog <-- Section, because first-level dir under content/ + ├── funny-cats + │   ├── mypost.md + │   └── kittens <-- Section, because contains _index.md + │   └── _index.md + └── tech <-- Section, because contains _index.md + └── _index.md +``` + +**The important part to understand is, that to make the section tree fully navigational, at least the lower-most section needs a content file. (e.g. `_index.md`).** + +{{% note %}} +When we talk about a **section** in correlation with template selection, it is +currently always the *root section* only (`/blog/funny-cats/mypost/ => blog`). + +If you need a specific template for a sub-section, you need to adjust either the `type` or `layout` in front matter. +{{% /note %}} + +## Example: Breadcrumb Navigation + +With the available [section variables and methods](#section-page-variables-and-methods) you can build powerful navigation. One common example would be a partial to show Breadcrumb navigation: + +{{< code file="layouts/partials/breadcrumb.html" download="breadcrumb.html" >}} +
    + {{ template "breadcrumbnav" (dict "p1" . "p2" .) }} +
+{{ define "breadcrumbnav" }} +{{ if .p1.Parent }} +{{ template "breadcrumbnav" (dict "p1" .p1.Parent "p2" .p2 ) }} +{{ else if not .p1.IsHome }} +{{ template "breadcrumbnav" (dict "p1" .p1.Site.Home "p2" .p2 ) }} +{{ end }} + + {{ .p1.Title }} + +{{ end }} +{{< /code >}} + +## Section Page Variables and Methods + +Also see [Page Variables](/variables/page/). + +{{< readfile file="/content/en/readfiles/sectionvars.md" markdown="true" >}} + +## Content Section Lists + +Hugo will automatically create pages for each *root section* that list all of the content in that section. See the documentation on [section templates][] for details on customizing the way these pages are rendered. + +## Content *Section* vs Content *Type* + +By default, everything created within a section will use the [content `type`][content type] that matches the *root section* name. For example, Hugo will assume that `posts/post-1.md` has a `posts` content `type`. If you are using an [archetype][] for your `posts` section, Hugo will generate front matter according to what it finds in `archetypes/posts.md`. + +[archetype]: /content-management/archetypes/ +[content type]: /content-management/types/ +[directory structure]: /getting-started/directory-structure/ +[section templates]: /templates/section-templates/ ++[leaf bundles]: /content-management/page-bundles/#leaf-bundles +[branch bundles]: /content-management/page-bundles/#branch-bundles diff --cc docs/content/en/functions/errorf.md index a20ad4f4,00000000..41ea2f19 mode 100644,000000..100644 --- a/docs/content/en/functions/errorf.md +++ b/docs/content/en/functions/errorf.md @@@ -1,52 -1,0 +1,51 @@@ +--- +title: errorf and warnf +description: Log ERROR or WARNING from the templates. +date: 2017-09-30 +publishdate: 2017-09-30 +lastmod: 2017-09-30 +categories: [functions] +menu: + docs: + parent: "functions" +keywords: [strings, log, error] +signature: ["errorf FORMAT INPUT"] +workson: [] +hugoversion: +relatedfuncs: [printf] +deprecated: false +--- + +`errorf` or `warnf` will evaluate a format string, then output the result to the ERROR or WARNING log (and only once per error message to avoid flooding the log). + +Any ERROR will also cause the build to fail (the `hugo` command will `exit -1`). + +Both functions return an empty string, so the messages are only printed to the console. + +``` +{{ errorf "Failed to handle page %q" .Path }} +``` + +``` +{{ warnf "You should update the shortcodes in %q" .Path }} +``` + - Note that `errorf` and `warnf` support all the formatting verbs of the [fmt](https://golang.org/pkg/fmt/) package. ++Note that `errorf`, `erroridf`, and `warnf` support all the formatting verbs of the [fmt](https://golang.org/pkg/fmt/) package. + +## Suppress errors + - Some times it may make sense to let the user suppress an ERROR and make the build succeed. ++Sometimes it may make sense to let the user suppress an ERROR and make the build succeed. + - You can do this by using the `erroridf` function. This functions takes an error ID as the first arument. ++You can do this by using the `erroridf` function. This functions takes an error ID as the first argument. + - - `` - {{ erroridf "my-custom-error" "You should consider fixing this."}} ++``` ++{{ erroridf "my-custom-error" "You should consider fixing this." }} +``` + +This will produce: + +``` +ERROR 2021/06/07 17:47:38 You should consider fixing this. +If you feel that this should not be logged as an ERROR, you can ignore it by adding this to your site config: +ignoreErrors = ["my-custom-error"] +``` diff --cc docs/content/en/getting-started/configuration.md index 05383dda,00000000..36c8c1b5 mode 100644,000000..100644 --- a/docs/content/en/getting-started/configuration.md +++ b/docs/content/en/getting-started/configuration.md @@@ -1,614 -1,0 +1,614 @@@ +--- +title: Configure Hugo +linktitle: Configuration +description: How to configure your Hugo site. +date: 2013-07-01 +publishdate: 2017-01-02 +lastmod: 2017-03-05 +categories: [getting started,fundamentals] +keywords: [configuration,toml,yaml,json] +menu: + docs: + parent: "getting-started" + weight: 60 +weight: 60 +sections_weight: 60 +draft: false +aliases: [/overview/source-directory/,/overview/configuration/] +toc: true +--- + + +## Configuration File + +Hugo uses the `config.toml`, `config.yaml`, or `config.json` (if found in the +site root) as the default site config file. + +The user can choose to override that default with one or more site config files +using the command line `--config` switch. + +Examples: + +``` +hugo --config debugconfig.toml +hugo --config a.toml,b.toml,c.toml +``` + +{{% note %}} +Multiple site config files can be specified as a comma-separated string to the `--config` switch. +{{% /note %}} + +{{< todo >}}TODO: distinct config.toml and others (the root object files){{< /todo >}} + +## Configuration Directory + +In addition to using a single site config file, one can use the `configDir` directory (default to `config/`) to maintain easier organization and environment specific settings. + +- Each file represents a configuration root object, such as `params.toml` for `[Params]`, `menu(s).toml` for `[Menu]`, `languages.toml` for `[Languages]` etc... +- Each file's content must be top-level, for example: + +{{< code-toggle file="config" >}} +[Params] + foo = "bar" +{{< /code-toggle >}} + +{{< code-toggle file="params" >}} +foo = "bar" +{{< /code-toggle >}} + +- Each directory holds a group of files containing settings unique to an environment. +- Files can be localized to become language specific. + + +``` +├── config +│ ├── _default +│ │ ├── config.toml +│ │ ├── languages.toml +│ │ ├── menus.en.toml +│ │ ├── menus.zh.toml +│ │ └── params.toml +│ ├── production +│ │ ├── config.toml +│ │ └── params.toml +│ └── staging +│ ├── config.toml +│ └── params.toml +``` + +Considering the structure above, when running `hugo --environment staging`, Hugo will use every settings from `config/_default` and merge `staging`'s on top of those. +{{% note %}} +Default environments are __development__ with `hugo server` and __production__ with `hugo`. +{{%/ note %}} + +## Merge Configuration from Themes + +{{< new-in "0.84.0" >}} The configuration merge described below was improved in Hugo 0.84.0 and made fully configurable. The big change/improvement was that we now, by default, do deep merging of `params` maps from themes. + +The configuration value for `_merge` can be one of: + +none +: No merge. + +shallow +: Only add values for new keys. + - shallow ++deep +: Add values for new keys, merge existing. + +Note that you don't need to be so verbose as in the default setup below; a `_merge` value higher up will be inherited if not set. + +{{< code-toggle config="mergeStrategy" skipHeader=true />}} + +## All Configuration Settings + +The following is the full list of Hugo-defined variables with their default +value in parentheses. Users may choose to override those values in their site +config file(s). + +archetypeDir ("archetypes") +: The directory where Hugo finds archetype files (content templates). {{% module-mounts-note %}} + +assetDir ("assets") +: The directory where Hugo finds asset files used in [Hugo Pipes](/hugo-pipes/). {{% module-mounts-note %}} + +baseURL +: Hostname (and path) to the root, e.g. https://bep.is/ + +blackfriday +: See [Configure Blackfriday](/getting-started/configuration-markup#blackfriday) + +build +: See [Configure Build](#configure-build) + +buildDrafts (false) +: Include drafts when building. + +buildExpired (false) +: Include content already expired. + +buildFuture (false) +: Include content with publishdate in the future. + +caches +: See [Configure File Caches](#configure-file-caches) + +canonifyURLs (false) +: Enable to turn relative URLs into absolute. + +contentDir ("content") +: The directory from where Hugo reads content files. {{% module-mounts-note %}} + +dataDir ("data") +: The directory from where Hugo reads data files. {{% module-mounts-note %}} + +defaultContentLanguage ("en") +: Content without language indicator will default to this language. + +defaultContentLanguageInSubdir (false) +: Render the default content language in subdir, e.g. `content/en/`. The site root `/` will then redirect to `/en/`. + +disableAliases (false) +: Will disable generation of alias redirects. Note that even if `disableAliases` is set, the aliases themselves are preserved on the page. The motivation with this is to be able to generate 301 redirects in an `.htaccess`, a Netlify `_redirects` file or similar using a custom output format. + +disableHugoGeneratorInject (false) +: Hugo will, by default, inject a generator meta tag in the HTML head on the _home page only_. You can turn it off, but we would really appreciate if you don't, as this is a good way to watch Hugo's popularity on the rise. + +disableKinds ([]) +: Enable disabling of all pages of the specified *Kinds*. Allowed values in this list: `"page"`, `"home"`, `"section"`, `"taxonomy"`, `"term"`, `"RSS"`, `"sitemap"`, `"robotsTXT"`, `"404"`. + +disableLiveReload (false) +: Disable automatic live reloading of browser window. + +disablePathToLower (false) +: Do not convert the url/path to lowercase. + +enableEmoji (false) +: Enable Emoji emoticons support for page content; see the [Emoji Cheat Sheet](https://www.webpagefx.com/tools/emoji-cheat-sheet/). + +enableGitInfo (false) +: Enable `.GitInfo` object for each page (if the Hugo site is versioned by Git). This will then update the `Lastmod` parameter for each page using the last git commit date for that content file. + +enableInlineShortcodes (false) +: Enable inline shortcode support. See [Inline Shortcodes](/templates/shortcode-templates/#inline-shortcodes). + +enableMissingTranslationPlaceholders (false) +: Show a placeholder instead of the default value or an empty string if a translation is missing. + +enableRobotsTXT (false) +: Enable generation of `robots.txt` file. + +frontmatter + +: See [Front matter Configuration](#configure-front-matter). + +footnoteAnchorPrefix ("") +: Prefix for footnote anchors. + +footnoteReturnLinkContents ("") +: Text to display for footnote return links. + +googleAnalytics ("") +: Google Analytics tracking ID. + +hasCJKLanguage (false) +: If true, auto-detect Chinese/Japanese/Korean Languages in the content. This will make `.Summary` and `.WordCount` behave correctly for CJK languages. + +imaging +: See [Image Processing Config](/content-management/image-processing/#image-processing-config). + +languages +: See [Configure Languages](/content-management/multilingual/#configure-languages). + +languageCode ("") +: The site's language code. It is used in the default [RSS template](/templates/rss/#configure-rss) and can be useful for [multi-lingual sites](/content-management/multilingual/#configure-multilingual-multihost). + +languageName ("") +: The site's language name. + +disableLanguages +: See [Disable a Language](/content-management/multilingual/#disable-a-language) + +layoutDir ("layouts") +: The directory from where Hugo reads layouts (templates). + +log (false) +: Enable logging. + +logFile ("") +: Log File path (if set, logging enabled automatically). + +markup +: See [Configure Markup](/getting-started/configuration-markup).{{< new-in "0.60.0" >}} + +mediaTypes +See [Configure Media Types](/templates/output-formats/#media-types). + +menu +: See [Add Non-content Entries to a Menu](/content-management/menus/#add-non-content-entries-to-a-menu). + +minify +: See [Configure Minify](#configure-minify) + +module +: Module config see [Module Config](/hugo-modules/configuration/).{{< new-in "0.56.0" >}} + +newContentEditor ("") +: The editor to use when creating new content. + +noChmod (false) +: Don't sync permission mode of files. + +noTimes (false) +: Don't sync modification time of files. + +outputFormats +See [Configure Output Formats](#configure-additional-output-formats). + +paginate (10) +: Default number of elements per page in [pagination](/templates/pagination/). + +paginatePath ("page") +: The path element used during pagination (https://example.com/page/2). + +permalinks +: See [Content Management](/content-management/urls/#permalinks). + +pluralizeListTitles (true) +: Pluralize titles in lists. + +publishDir ("public") +: The directory to where Hugo will write the final static site (the HTML files etc.). + +related +: See [Related Content](/content-management/related/#configure-related-content).{{< new-in "0.27" >}} + +relativeURLs (false) +: Enable this to make all relative URLs relative to content root. Note that this does not affect absolute URLs. + +refLinksErrorLevel ("ERROR") +: When using `ref` or `relref` to resolve page links and a link cannot resolved, it will be logged with this logg 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. + +rssLimit (unlimited) +: Maximum number of items in the RSS feed. + +sectionPagesMenu ("") +: See ["Section Menu for Lazy Bloggers"](/templates/menu-templates/#section-menu-for-lazy-bloggers). + +sitemap +: Default [sitemap configuration](/templates/sitemap-template/#configure-sitemapxml). + +staticDir ("static") +: A directory or a list of directories from where Hugo reads [static files][static-files]. {{% module-mounts-note %}} + +summaryLength (70) +: The length of text in words to show in a [`.Summary`](/content-management/summaries/#hugo-defined-automatic-summary-splitting). + +taxonomies +: See [Configure Taxonomies](/content-management/taxonomies#configure-taxonomies). + +theme ("") +: Theme to use (located by default in `/themes/THEMENAME/`). + +themesDir ("themes") +: The directory where Hugo reads the themes from. + +timeout (10000) +: Timeout for generating page contents, in milliseconds (defaults to 10 seconds). *Note:* this is used to bail out of recursive content generation, if your pages are slow to generate (e.g., because they require large image processing or depend on remote contents) you might need to raise this limit. + +title ("") +: Site title. + +titleCaseStyle ("AP") +: See [Configure Title Case](#configure-title-case) + +uglyURLs (false) +: When enabled, creates URL of the form `/filename.html` instead of `/filename/`. + +verbose (false) +: Enable verbose output. + +verboseLog (false) +: Enable verbose logging. + +watch (false) +: Watch filesystem for changes and recreate as needed. + +{{% note %}} +If you are developing your site on a \*nix machine, here is a handy shortcut for finding a configuration option from the command line: +``` +cd ~/sites/yourhugosite +hugo config | grep emoji +``` + +which shows output like + +``` +enableemoji: true +``` +{{% /note %}} + +## Configure Build + +{{< new-in "0.66.0" >}} + +The `build` configuration section contains global build-related configuration options. + +{{< code-toggle file="config">}} +[build] +useResourceCacheWhen="fallback" +writeStats = false +noJSConfigInAssets = false +{{< /code-toggle >}} + + +useResourceCacheWhen +: When to use the cached resources in `/resources/_gen` for PostCSS and ToCSS. Valid values are `never`, `always` and `fallback`. The last value means that the cache will be tried if PostCSS/extended version is not available. + +writeStats {{< new-in "0.69.0" >}} +: When enabled, a file named `hugo_stats.json` will be written to your project root with some aggregated data about the build, e.g. list of HTML entities published to be used to do [CSS pruning](/hugo-pipes/postprocess/#css-purging-with-postcss). If you're only using this for the production build, you should consider placing it below [config/production](/getting-started/configuration/#configuration-directory). It's also worth mentioning that, due to the nature of the partial server builds, new HTML entities will be added when you add or change them while the server is running, but the old values will not be removed until you restart the server or run a regular `hugo` build. + +**Note** that the prime use case for this is purging of unused CSS; it is build for speed and there may be false positives (e.g. elements that isn't really a HTML element). + +noJSConfigInAssets {{< new-in "0.78.0" >}} +: Turn off writing a `jsconfig.json` into your `/assets` folder with mapping of imports from running [js.Build](https://gohugo.io/hugo-pipes/js). This file is intended to help with intellisense/navigation inside code editors such as [VS Code](https://code.visualstudio.com/). Note that if you do not use `js.Build`, no file will be written. + +## Configure Server + +{{< new-in "0.67.0" >}} + +This is only relevant when running `hugo server`, and it allows to set HTTP headers during development, which allows you to test out your Content Security Policy and similar. The configuration format matches [Netlify's](https://docs.netlify.com/routing/headers/#syntax-for-the-netlify-configuration-file) with slighly more powerful [Glob matching](https://github.com/gobwas/glob): + + +{{< code-toggle file="config">}} +[server] +[[server.headers]] +for = "/**.html" + +[server.headers.values] +X-Frame-Options = "DENY" +X-XSS-Protection = "1; mode=block" +X-Content-Type-Options = "nosniff" +Referrer-Policy = "strict-origin-when-cross-origin" +Content-Security-Policy = "script-src localhost:1313" +{{< /code-toggle >}} + +Since this is is "development only", it may make sense to put it below the `development` environment: + + +{{< code-toggle file="config/development/server">}} +[[headers]] +for = "/**.html" + +[headers.values] +X-Frame-Options = "DENY" +X-XSS-Protection = "1; mode=block" +X-Content-Type-Options = "nosniff" +Referrer-Policy = "strict-origin-when-cross-origin" +Content-Security-Policy = "script-src localhost:1313" +{{< /code-toggle >}} + + +{{< new-in "0.72.0" >}} + +You can also specify simple redirects rules for the server. The syntax is again similar to Netlify's. + +Note that a `status` code of 200 will trigger a [URL rewrite](https://docs.netlify.com/routing/redirects/rewrites-proxies/), which is what you want in SPA situations, e.g: + +{{< code-toggle file="config/development/server">}} +[[redirects]] +from = "/myspa/**" +to = "/myspa/" +status = 200 +force = false +{{< /code-toggle >}} + +{{< new-in "0.76.0" >}} Setting `force=true` will make a redirect even if there is existing content in the path. Note that before Hugo 0.76 `force` was the default behaviour, but this is inline with how Netlify does it. + +## Configure Title Case + +Set `titleCaseStyle` to specify the title style used by the [title](/functions/title/) template function and the automatic section titles in Hugo. It defaults to [AP Stylebook](https://www.apstylebook.com/) for title casing, but you can also set it to `Chicago` or `Go` (every word starts with a capital letter). + +## Configuration Environment Variables + +HUGO_NUMWORKERMULTIPLIER +: Can be set to increase or reduce the number of workers used in parallel processing in Hugo. If not set, the number of logical CPUs will be used. + +## Configuration Lookup Order + +Similar to the template [lookup order][], Hugo has a default set of rules for searching for a configuration file in the root of your website's source directory as a default behavior: + +1. `./config.toml` +2. `./config.yaml` +3. `./config.json` + +In your `config` file, you can direct Hugo as to how you want your website rendered, control your website's menus, and arbitrarily define site-wide parameters specific to your project. + + +## Example Configuration + +The following is a typical example of a configuration file. The values nested under `params:` will populate the [`.Site.Params`][] variable for use in [templates][]: + +{{< code-toggle file="config">}} +baseURL: "https://yoursite.example.com/" +title: "My Hugo Site" +footnoteReturnLinkContents: "↩" +permalinks: + posts: /:year/:month/:title/ +params: + Subtitle: "Hugo is Absurdly Fast!" + AuthorName: "Jon Doe" + GitHubUser: "spf13" + ListOfFoo: + - "foo1" + - "foo2" + SidebarRecentLimit: 5 +{{< /code-toggle >}} + +## Configure with Environment Variables + +In addition to the 3 config options already mentioned, configuration key-values can be defined through operating system environment variables. + +For example, the following command will effectively set a website's title on Unix-like systems: + +``` +$ env HUGO_TITLE="Some Title" hugo +``` + +This is really useful if you use a service such as Netlify to deploy your site. Look at the Hugo docs [Netlify configuration file](https://github.com/gohugoio/hugoDocs/blob/master/netlify.toml) for an example. + +{{% note "Setting Environment Variables" %}} +Names must be prefixed with `HUGO_` and the configuration key must be set in uppercase when setting operating system environment variables. + +To set config params, prefix the name with `HUGO_PARAMS_` +{{% /note %}} + +{{< new-in "0.79.0" >}} If you are using snake_cased variable names, the above will not work, so since Hugo 0.79.0 Hugo determines the delimiter to use by the first character after `HUGO`. This allows you to define environment variables on the form `HUGOxPARAMSxAPI_KEY=abcdefgh`, using any [allowed](https://stackoverflow.com/questions/2821043/allowed-characters-in-linux-environment-variable-names#:~:text=So%20names%20may%20contain%20any,not%20begin%20with%20a%20digit.) delimiter. + +{{< todo >}} +Test and document setting params via JSON env var. +{{< /todo >}} + +## Ignore Content and Data Files when Rendering + +To exclude specific files from the content and data directories when rendering your site, set `ignoreFiles` to one or more regular expressions. + +For example, to ignore content and data files ending with `.foo` and `.boo`: + +{{< code-toggle >}} +ignoreFiles = [ "\\.foo$","\\.boo$"] +{{< /code-toggle >}} + +## Configure Front Matter + +### Configure Dates + +Dates are important in Hugo, and you can configure how Hugo assigns dates to your content pages. You do this by adding a `frontmatter` section to your `config.toml`. + + +The default configuration is: + +{{< code-toggle file="config" >}} +[frontmatter] +date = ["date", "publishDate", "lastmod"] +lastmod = [":git", "lastmod", "date", "publishDate"] +publishDate = ["publishDate", "date"] +expiryDate = ["expiryDate"] +{{< /code-toggle >}} + +If you, as an example, have a non-standard date parameter in some of your content, you can override the setting for `date`: + +{{< code-toggle file="config" >}} +[frontmatter] +date = ["myDate", ":default"] +{{< /code-toggle >}} + +The `:default` is a shortcut to the default settings. The above will set `.Date` to the date value in `myDate` if present, if not we will look in `date`,`publishDate`, `lastmod` and pick the first valid date. + +In the list to the right, values starting with ":" are date handlers with a special meaning (see below). The others are just names of date parameters (case insensitive) in your front matter configuration. Also note that Hugo have some built-in aliases to the above: `lastmod` => `modified`, `publishDate` => `pubdate`, `published` and `expiryDate` => `unpublishdate`. With that, as an example, using `pubDate` as a date in front matter, will, by default, be assigned to `.PublishDate`. + +The special date handlers are: + + +`:fileModTime` +: Fetches the date from the content file's last modification timestamp. + +An example: + +{{< code-toggle file="config" >}} +[frontmatter] +lastmod = ["lastmod", ":fileModTime", ":default"] +{{< /code-toggle >}} + + +The above will try first to extract the value for `.Lastmod` starting with the `lastmod` front matter parameter, then the content file's modification timestamp. The last, `:default` should not be needed here, but Hugo will finally look for a valid date in `:git`, `date` and then `publishDate`. + + +`:filename` +: Fetches the date from the content file's filename. For example, `2018-02-22-mypage.md` will extract the date `2018-02-22`. Also, if `slug` is not set, `mypage` will be used as the value for `.Slug`. + +An example: + +{{< code-toggle file="config" >}} +[frontmatter] +date = [":filename", ":default"] +{{< /code-toggle >}} + +The above will try first to extract the value for `.Date` from the filename, then it will look in front matter parameters `date`, `publishDate` and lastly `lastmod`. + + +`:git` +: This is the Git author date for the last revision of this content file. This will only be set if `--enableGitInfo` is set or `enableGitInfo = true` is set in site config. + +## Configure Additional Output Formats + +Hugo v0.20 introduced the ability to render your content to multiple output formats (e.g., to JSON, AMP html, or CSV). See [Output Formats][] for information on how to add these values to your Hugo project's configuration file. + +## Configure Minify + +{{< new-in "0.68.0" >}} + +Default configuration: + +{{< code-toggle config="minify" />}} + +## Configure File Caches + +Since Hugo 0.52 you can configure more than just the `cacheDir`. This is the default configuration: + +{{< code-toggle >}} +[caches] +[caches.getjson] +dir = ":cacheDir/:project" +maxAge = -1 +[caches.getcsv] +dir = ":cacheDir/:project" +maxAge = -1 +[caches.images] +dir = ":resourceDir/_gen" +maxAge = -1 +[caches.assets] +dir = ":resourceDir/_gen" +maxAge = -1 +[caches.modules] +dir = ":cacheDir/modules" +maxAge = -1 +{{< /code-toggle >}} + +You can override any of these cache settings in your own `config.toml`. + +### The keywords explained + +`:cacheDir` +: This is the value of the `cacheDir` config option if set (can also be set via OS env variable `HUGO_CACHEDIR`). It will fall back to `/opt/build/cache/hugo_cache/` on Netlify, or a `hugo_cache` directory below the OS temp dir for the others. This means that if you run your builds on Netlify, all caches configured with `:cacheDir` will be saved and restored on the next build. For other CI vendors, please read their documentation. For an CircleCI example, see [this configuration](https://github.com/bep/hugo-sass-test/blob/6c3960a8f4b90e8938228688bc49bdcdd6b2d99e/.circleci/config.yml). + +`:project` +: The base directory name of the current Hugo project. This means that, in its default setting, every project will have separated file caches, which means that when you do `hugo --gc` you will not touch files related to other Hugo projects running on the same PC. + +`:resourceDir` +: This is the value of the `resourceDir` config option. + +maxAge +: This is the duration before a cache entry will be evicted, -1 means forever and 0 effectively turns that particular cache off. Uses Go's `time.Duration`, so valid values are `"10s"` (10 seconds), `"10m"` (10 minutes) and `"10h"` (10 hours). + +dir +: The absolute path to where the files for this cache will be stored. Allowed starting placeholders are `:cacheDir` and `:resourceDir` (see above). + +## Configuration Format Specs + +* [TOML Spec][toml] +* [YAML Spec][yaml] +* [JSON Spec][json] + +[`.Site.Params`]: /variables/site/ +[directory structure]: /getting-started/directory-structure +[json]: https://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf "Specification for JSON, JavaScript Object Notation" +[lookup order]: /templates/lookup-order/ +[Output Formats]: /templates/output-formats/ +[templates]: /templates/ +[toml]: https://github.com/toml-lang/toml +[yaml]: https://yaml.org/spec/ +[static-files]: /content-management/static-files/ diff --cc docs/content/en/news/0.84.0-relnotes/index.md index 3bd7b379,00000000..8d3dfac2 mode 100644,000000..100644 --- a/docs/content/en/news/0.84.0-relnotes/index.md +++ b/docs/content/en/news/0.84.0-relnotes/index.md @@@ -1,160 -1,0 +1,160 @@@ + +--- +date: 2021-06-18 +title: "Config Revamp" +description: "Hugo 0.84.0: Deep merge of theme configuration, config dir support now also in themes/modules, HTTP header support in getJSON, and more." +categories: ["Releases"] +--- + +**This release brings several configuration fixes and improvements that will be especially useful for themes.** + +## Deep merge of theme Params + - One of the most common complaint from Hugo theme owners/users has been about the configuration handling. Hugo has up until now only performed a shallow merge of theme `params` into the configuration. ++One of the most common complaints from Hugo theme owners/users has been about the configuration handling. Hugo has up until now only performed a shallow merge of theme `params` into the configuration. + +With that, given this example from a theme configuration: + +```toml +[params] +[params.colours] +blue="#337DFF" +green="#68FF33" +red="#FF3358" +``` + - If you would like to use the above theme, but want a different shade of red, you earlier had to copy the entire block, even the colours you're totally happy with. This was painful even the simplest setup. ++If you would like to use the above theme, but want a different shade of red, you earlier had to copy the entire block, even the colours you're totally happy with. This was painful with even the simplest setup. + +Now you can just override the `params` keys you want to change, e.g.: + +```toml +[params] +[params.colours] +red="#fc0f03" +``` + +For more information, and especially about the way you can opt out of the above behaviour, see [Merge Configuration from Themes](https://gohugo.io/getting-started/configuration/#merge-configuration-from-themes). + +## Themes now support the config directory + +Now both the project and themes/modules can store its configuration in both the top level config file (e.g. `config.toml`) or in the `config` directory. See [Configuration Directory](https://gohugo.io/getting-started/configuration/#configuration-directory). + +## HTTP headers in getJSON/getCSV + +`getJSON` now supports custom HTTP headers. This has been a big limitation in Hugo, especially considering the [Authorization](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization) header. + +We have updated the internal Instagram shortcode to pass the access token in a header: + +``` +{{ $hideCaption := cond (eq (.Get 1) "hidecaption") "1" "0" }} +{{ $headers := dict "Authorization" (printf "Bearer %s" $accessToken) }} +{{ with getJSON "https://graph.facebook.com/v8.0/instagram_oembed/?url=https://instagram.com/p/" $id "/&hidecaption=" $hideCaption $headers }} + {{ .html | safeHTML }} +{{ end }} +``` + + Also see the discussion [this issue](https://github.com/gohugoio/hugo/issues/7879) about the access token above. + +## New erroridf template func + - Sometime, especially when creating themes, it is useful to be able to let the user decide if an error situation is critical enough to fail the build. The new `erroridf` produces `ERROR` log statements that can be toggled off: ++Sometimes, especially when creating themes, it is useful to be able to let the user decide if an error situation is critical enough to fail the build. The new `erroridf` produces `ERROR` log statements that can be toggled off: + +```html +{{ erroridf "some-custom-id" "Some error message." }} +``` + +Will log: + +``` +ERROR: Some error message. +If you feel that this should not be logged as an ERROR, you can ignore it by adding this to your site config: +ignoreErrors = ["some-custom-id"] +``` +## Stats + +This release represents **46 contributions by 11 contributors** to the main Hugo code base.[@bep](https://github.com/bep) leads the Hugo development with a significant amount of contributions, but also a big shoutout to [@jmooring](https://github.com/jmooring), [@satotake](https://github.com/satotake), and [@Seirdy](https://github.com/Seirdy) for their ongoing contributions. +And a big thanks to [@digitalcraftsman](https://github.com/digitalcraftsman) for his relentless work on keeping the themes site in pristine condition. + +Many have also been busy writing and fixing the documentation in [hugoDocs](https://github.com/gohugoio/hugoDocs), +which has received **20 contributions by 10 contributors**. A special thanks to [@salim-b](https://github.com/salim-b), [@bep](https://github.com/bep), [@thomasjsn](https://github.com/thomasjsn), and [@lucasew](https://github.com/lucasew) for their work on the documentation site. + + +Hugo now has: + +* 52487+ [stars](https://github.com/gohugoio/hugo/stargazers) +* 432+ [contributors](https://github.com/gohugoio/hugo/graphs/contributors) +* 370+ [themes](http://themes.gohugo.io/) + + +## Notes + +* We now do deep merging of `params` from theme config(s). That is you most likely what you want, but [Merge Configuration from Themes](https://gohugo.io/getting-started/configuration/#merge-configuration-from-themes) describes how you can get the old behaviour back. + +## Enhancements + +### Templates + +* Rename err-missing-instagram-accesstoken => error-missing-instagram-accesstoken [9096842b](https://github.com/gohugoio/hugo/commit/9096842b0494166e401cc08a70b93ae2ee19a198) [@bep](https://github.com/bep) +* Add a terse pagination template variant to improve performance [73483d0f](https://github.com/gohugoio/hugo/commit/73483d0f9eb46838d41640f88cc05c1d16811dc5) [@jmooring](https://github.com/jmooring) [#8599](https://github.com/gohugoio/hugo/issues/8599) +* Add erroridf template func [f55d2f43](https://github.com/gohugoio/hugo/commit/f55d2f43769053b80b419a690554e747dc5dcede) [@bep](https://github.com/bep) [#8613](https://github.com/gohugoio/hugo/issues/8613) +* Print response body on HTTP errors [282f1aa3](https://github.com/gohugoio/hugo/commit/282f1aa3db9f6420fdd360e46db1ffadd5b083a1) [@bep](https://github.com/bep) +* Misc header improvements, tests, allow multiple headers of same key [fcd63de3](https://github.com/gohugoio/hugo/commit/fcd63de3a54fadcd30972654d8eb86dc4d889784) [@bep](https://github.com/bep) [#5617](https://github.com/gohugoio/hugo/issues/5617) +* Allows user-defined HTTP headers with getJSON and getCSV [150d7573](https://github.com/gohugoio/hugo/commit/150d75738b54acddc485d363436757189144da6a) [@chamberlainpj](https://github.com/chamberlainpj) [#5617](https://github.com/gohugoio/hugo/issues/5617) +* Allow 'Querify' to take lone slice/interface argument [c46fc838](https://github.com/gohugoio/hugo/commit/c46fc838a9320adfc6532b1b543e903c48b3b4cb) [@importhuman](https://github.com/importhuman) [#6735](https://github.com/gohugoio/hugo/issues/6735) + +### Output + +* Make WebAppManifestFormat NotAlternative=true [643b6719](https://github.com/gohugoio/hugo/commit/643b671931ed5530855e7d4819896790bf3f6c28) [@bep](https://github.com/bep) [#8624](https://github.com/gohugoio/hugo/issues/8624) +* Adjust test assertion [ab4e1dfa](https://github.com/gohugoio/hugo/commit/ab4e1dfa4eebe0ac18f1d1f60a9647cbb7b41d7f) [@bep](https://github.com/bep) [#8625](https://github.com/gohugoio/hugo/issues/8625) +* support application/manifest+json [02f31897](https://github.com/gohugoio/hugo/commit/02f31897b4f7252154850a65c900e88e0b237fa3) [@Seirdy](https://github.com/Seirdy) [#8624](https://github.com/gohugoio/hugo/issues/8624) + +### Other + +* Regenerate docs helper [be6b901c](https://github.com/gohugoio/hugo/commit/be6b901cf7d07238337334e6b6d886a7b039f5e6) [@bep](https://github.com/bep) +* Regenerate docshelper [402da3f8](https://github.com/gohugoio/hugo/commit/402da3f8f327f97302c4b5d69cd4832a94bd189b) [@bep](https://github.com/bep) +* Implement configuration in a directory for modules [bb2aa087](https://github.com/gohugoio/hugo/commit/bb2aa08709c812a5be29922a1a7f4d814e200cab) [@bep](https://github.com/bep) [#8654](https://github.com/gohugoio/hugo/issues/8654) +* Update github.com/alecthomas/chroma v0.9.1 => v0.9.2 [3aa7f0b2](https://github.com/gohugoio/hugo/commit/3aa7f0b27fc736b4c32adbb1fc1fc7fbefd6efd9) [@bep](https://github.com/bep) [#8658](https://github.com/gohugoio/hugo/issues/8658) +* Run go mod tidy [9b870aa7](https://github.com/gohugoio/hugo/commit/9b870aa788ab1b5159bc836fbac6e60a29bee329) [@bep](https://github.com/bep) +* Split out the puthe path/filepath functions into common/paths [93aad3c5](https://github.com/gohugoio/hugo/commit/93aad3c543828efca2adeb7f96cf50ae29878593) [@bep](https://github.com/bep) [#8654](https://github.com/gohugoio/hugo/issues/8654) +* Update to Goldmark v1.3.8 [8eafe084](https://github.com/gohugoio/hugo/commit/8eafe0845d66efd3cf442a8ed89a6da5c1d3117b) [@jmooring](https://github.com/jmooring) [#8648](https://github.com/gohugoio/hugo/issues/8648) +* Do not read config from os.Environ when running tests [31fb29fb](https://github.com/gohugoio/hugo/commit/31fb29fb3f306678f3697e05bbccefb2078d7f78) [@bep](https://github.com/bep) [#8655](https://github.com/gohugoio/hugo/issues/8655) +* Set a dummy Instagram token [a886dd53](https://github.com/gohugoio/hugo/commit/a886dd53b80322e1edf924f2ede4d4ea037c5baf) [@bep](https://github.com/bep) +* Regenerate docs helper [a91cd765](https://github.com/gohugoio/hugo/commit/a91cd7652f7559492b070dbe02fe558348f3d0b6) [@bep](https://github.com/bep) +* Update to Go 1.16.5, Goreleaser 0.169.0 [552cef5c](https://github.com/gohugoio/hugo/commit/552cef5c576ae4dbf4626f77f3c8b15b42a9e7f3) [@bep](https://github.com/bep) [#8619](https://github.com/gohugoio/hugo/issues/8619)[#8263](https://github.com/gohugoio/hugo/issues/8263) +* Upgrade Instagram shortcode [9b5debe4](https://github.com/gohugoio/hugo/commit/9b5debe4b820132759cfdf7bff7fe9c1ad0a6bb1) [@bep](https://github.com/bep) [#7879](https://github.com/gohugoio/hugo/issues/7879) +* Set modTime at creation time [06d29542](https://github.com/gohugoio/hugo/commit/06d295427f798da85de469924fd10f58c0de9a58) [@bep](https://github.com/bep) [#6161](https://github.com/gohugoio/hugo/issues/6161) +* Add math.Max and math.Min [01758f99](https://github.com/gohugoio/hugo/commit/01758f99b915f34fe7ca4621e4d1ee09efe385b1) [@jmooring](https://github.com/jmooring) [#8583](https://github.com/gohugoio/hugo/issues/8583) +* Catch incomplete shortcode error [845a7ba4](https://github.com/gohugoio/hugo/commit/845a7ba4fc30c61842148d67d31d0fa3db8f40b9) [@satotake](https://github.com/satotake) [#6866](https://github.com/gohugoio/hugo/issues/6866) +* Use SPDX license identifier [10f60de8](https://github.com/gohugoio/hugo/commit/10f60de89a5a53528f1e3a47a77224e5c7915e4e) [@jmooring](https://github.com/jmooring) [#8555](https://github.com/gohugoio/hugo/issues/8555) +* Cache and copy Menu for sorting [785a31b5](https://github.com/gohugoio/hugo/commit/785a31b5b84643f4769f9bd363599cbcce86f098) [@satotake](https://github.com/satotake) [#7594](https://github.com/gohugoio/hugo/issues/7594) +* Update to LibSASS 3.6.5 [bc1e0528](https://github.com/gohugoio/hugo/commit/bc1e05286a96d08ad02ad200d6a4076bb01c486e) [@bep](https://github.com/bep) +* Make the HTML element collector more robust [f518b4f7](https://github.com/gohugoio/hugo/commit/f518b4f71e1a61b09d660b5c284121ebf3b3b86b) [@bep](https://github.com/bep) [#8530](https://github.com/gohugoio/hugo/issues/8530) +* Make the HTML element collector more robust" [dc6b7a75](https://github.com/gohugoio/hugo/commit/dc6b7a75ff5b7fcb8a0b0e3f7ed406422d847624) [@bep](https://github.com/bep) +* Get the collector in line with the io.Writer interface" [3f515f0e](https://github.com/gohugoio/hugo/commit/3f515f0e3395b24776ae24045b846ff2b33b8906) [@bep](https://github.com/bep) +* Get the collector in line with the io.Writer interface [a9bcd381](https://github.com/gohugoio/hugo/commit/a9bcd38181ceb79afba82adcd4de1aebf571e74c) [@bep](https://github.com/bep) +* Make the HTML element collector more robust [ef0f1a72](https://github.com/gohugoio/hugo/commit/ef0f1a726901d6c614040cfc2d7e8f9a2ca97816) [@bep](https://github.com/bep) [#8530](https://github.com/gohugoio/hugo/issues/8530) +* Add Scratch.DeleteInMap [abbc99d4](https://github.com/gohugoio/hugo/commit/abbc99d4c60b102e2779e4362ceb433095719384) [@meehawk](https://github.com/meehawk) [#8504](https://github.com/gohugoio/hugo/issues/8504) +* Display version when building site (#8533) [76c95f55](https://github.com/gohugoio/hugo/commit/76c95f55a5d18290baa7f23667161d4af9fb9b53) [@jmooring](https://github.com/jmooring) [#8531](https://github.com/gohugoio/hugo/issues/8531) +* Update querify function description and examples [2c7f5b62](https://github.com/gohugoio/hugo/commit/2c7f5b62f6c1fa1c7b3cf2c1f3a1663b18e75004) [@jmooring](https://github.com/jmooring) +* Change SetEscapeHTML to false [504c78da](https://github.com/gohugoio/hugo/commit/504c78da4b5020e1fd13a1195ad38a9e85f8289a) [@peaceiris](https://github.com/peaceiris) [#8512](https://github.com/gohugoio/hugo/issues/8512) +* Add a benchmark [b660ea8d](https://github.com/gohugoio/hugo/commit/b660ea8d545d6ba5479dd28a670044d57e5d196f) [@bep](https://github.com/bep) +* Update dependency list [64f88f30](https://github.com/gohugoio/hugo/commit/64f88f3011de5a510d8e6d6bad8ac4a091b11c0c) [@bep](https://github.com/bep) + +## Fixes + +### Templates + +* Fix countwords to handle special chars [7a2c10ae](https://github.com/gohugoio/hugo/commit/7a2c10ae60f096dacee4b44e0c8ae0a1b66ae033) [@ResamVi](https://github.com/ResamVi) [#8479](https://github.com/gohugoio/hugo/issues/8479) + +### Other + +* Fix fill with smartcrop sometimes returning 0 bytes images [5af045eb](https://github.com/gohugoio/hugo/commit/5af045ebab109d3e5501b8b6d9fd448840c96c9a) [@bep](https://github.com/bep) [#7955](https://github.com/gohugoio/hugo/issues/7955) +* Misc config loading fixes [d392893c](https://github.com/gohugoio/hugo/commit/d392893cd73dc00c927f342778f6dca9628d328e) [@bep](https://github.com/bep) [#8633](https://github.com/gohugoio/hugo/issues/8633)[#8618](https://github.com/gohugoio/hugo/issues/8618)[#8630](https://github.com/gohugoio/hugo/issues/8630)[#8591](https://github.com/gohugoio/hugo/issues/8591)[#6680](https://github.com/gohugoio/hugo/issues/6680)[#5192](https://github.com/gohugoio/hugo/issues/5192) +* Fix nested OS env config override when parent does not exist [12530519](https://github.com/gohugoio/hugo/commit/12530519d8fb4513c9c18a6494099b7dff8e4fd4) [@bep](https://github.com/bep) [#8618](https://github.com/gohugoio/hugo/issues/8618) +* Fix invalid timestamp of the "public" folder [26ae12c0](https://github.com/gohugoio/hugo/commit/26ae12c0c64b847d24bde60d7d710ea2efcb40d4) [@anthonyfok](https://github.com/anthonyfok) [#6161](https://github.com/gohugoio/hugo/issues/6161) +* Fix env split to allow = character in values [ee733085](https://github.com/gohugoio/hugo/commit/ee733085b7f5d3f2aef1667901ab6ecb8041d699) [@xqbumu](https://github.com/xqbumu) [#8589](https://github.com/gohugoio/hugo/issues/8589) +* Fix warning regression in i18n [ececd1b1](https://github.com/gohugoio/hugo/commit/ececd1b122c741567a80acd8d60ccd6356fa5323) [@bep](https://github.com/bep) [#8492](https://github.com/gohugoio/hugo/issues/8492) + + + + + diff --cc docs/content/en/news/0.84.2-relnotes/index.md index 7fd61cb2,00000000..d2469ff0 mode 100644,000000..100644 --- a/docs/content/en/news/0.84.2-relnotes/index.md +++ b/docs/content/en/news/0.84.2-relnotes/index.md @@@ -1,26 -1,0 +1,26 @@@ + +--- +date: 2021-06-28 +title: "Hugo 0.84.2: A couple of Bug Fixes" +description: "This version fixes a couple of bugs introduced in 0.84.0." +categories: ["Releases"] +images: +- images/blog/hugo-bug-poster.png + +--- + + + - This is a bug-fix release with a couple of important fixes. ++This is mostly a bug fix release, but it also contains some minor modules related improvements. Most notable you now get some more information in ` hugo config mounts`, and even more so when typing ` hugo config mounts -v`. + +* modules: Add module.import.noMounts config [40dfdd09](https://github.com/gohugoio/hugo/commit/40dfdd09521bcb8f56150e6791d60445198f27ab) [@bep](https://github.com/bep) [#8708](https://github.com/gohugoio/hugo/issues/8708) +* modules: Use value type for module.Time [3a6dc6d3](https://github.com/gohugoio/hugo/commit/3a6dc6d3f423c4acb79ef21b5a76e616fa2c9477) [@bep](https://github.com/bep) +* commands: Add version time to "hugo config mounts" [6cd2110a](https://github.com/gohugoio/hugo/commit/6cd2110ab295f598907a18da91e34d31407c1d9d) [@bep](https://github.com/bep) +* commands: Add some more info to "hugo config mounts" [6a365c27](https://github.com/gohugoio/hugo/commit/6a365c2712c7607e067e192d213b266f0c88d0f3) [@bep](https://github.com/bep) +* Fix config handling with empty config entries after merge [19aa95fc](https://github.com/gohugoio/hugo/commit/19aa95fc7f4cd58dcc8a8ff075762cfc86d41dc3) [@bep](https://github.com/bep) [#8701](https://github.com/gohugoio/hugo/issues/8701) +* Fix config loading for "hugo mod init" [923dd9d1](https://github.com/gohugoio/hugo/commit/923dd9d1c1f649142f3f377109318b07e0f44d5d) [@bep](https://github.com/bep) [#8697](https://github.com/gohugoio/hugo/issues/8697) +* deps: Update to Minify v2.9.18 [d9bdd37d](https://github.com/gohugoio/hugo/commit/d9bdd37d35ccd436b4dd470ef99efa372a6a086b) [@bep](https://github.com/bep) [#8693](https://github.com/gohugoio/hugo/issues/8693) +* Remove credit from release notes [b2eaf4c8](https://github.com/gohugoio/hugo/commit/b2eaf4c8c2e31aa1c1bc4a2c0061f661e01d2de1) [@digitalcraftsman](https://github.com/digitalcraftsman) + + + diff --cc docs/content/en/templates/lookup-order.md index 0d52213c,00000000..45e4e82e mode 100644,000000..100644 --- a/docs/content/en/templates/lookup-order.md +++ b/docs/content/en/templates/lookup-order.md @@@ -1,85 -1,0 +1,83 @@@ +--- +title: Hugo's Lookup Order +linktitle: Template Lookup Order +description: Hugo searches for the layout to use for a given page in a well defined order, starting from the most specific. +godocref: +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-07-05 +categories: [templates,fundamentals] +keywords: [templates] +menu: + docs: + parent: "templates" + weight: 15 + quicklinks: +weight: 15 +sections_weight: 15 +draft: false +aliases: [/templates/lookup/] +toc: true +--- + +## Hugo Layouts Lookup Rules + +Hugo takes the parameters listed below into consideration when choosing a layout for a given page. They are listed in a priority order. This should feel natural, but look at the table below for concrete examples of the different parameter variations. + + +Kind +: The page `Kind` (the home page is one). See the example tables below per kind. This also determines if it is a **single page** (i.e. a regular content page. We then look for a template in `_default/single.html` for HTML) or a **list page** (section listings, home page, taxonomy lists, taxonomy terms. We then look for a template in `_default/list.html` for HTML). + +Layout +: Can be set in page front matter. + +Output Format +: See [Custom Output Formats](/templates/output-formats). An output format has both a `name` (e.g. `rss`, `amp`, `html`) and a `suffix` (e.g. `xml`, `html`). We prefer matches with both (e.g. `index.amp.html`, but look for less specific templates. + ++Note that if the output format's Media Type has more than one suffix defined, only the first is considered. ++ +Language +: We will consider a language code in the template name. If the site language is `fr`, `index.fr.amp.html` will win over `index.amp.html`, but `index.amp.html` will be chosen before `index.fr.html`. + +Type +: Is value of `type` if set in front matter, else it is the name of the root section (e.g. "blog"). It will always have a value, so if not set, the value is "page". + +Section +: Is relevant for `section`, `taxonomy` and `term` types. + +{{% note %}} +**Tip:** The examples below look long and complex. That is the flexibility talking. Most Hugo sites contain just a handful of templates: + +```bash +├── _default +│   ├── baseof.html +│   ├── list.html +│   └── single.html +└── index.html +``` +{{% /note %}} + + +## Hugo Layouts Lookup Rules With Theme + +In Hugo, layouts can live in either the project's or the themes' layout folders, and the most specific layout will be chosen. Hugo will interleave the lookups listed below, finding the most specific one either in the project or themes. + +## Examples: Layout Lookup for Regular Pages + +{{< datatable-filtered "output" "layouts" "Kind == page" "Example" "OutputFormat" "Suffix" "Template Lookup Order" >}} + +## Examples: Layout Lookup for Home Page + +{{< datatable-filtered "output" "layouts" "Kind == home" "Example" "OutputFormat" "Suffix" "Template Lookup Order" >}} + +## Examples: Layout Lookup for Section Pages + +{{< datatable-filtered "output" "layouts" "Kind == section" "Example" "OutputFormat" "Suffix" "Template Lookup Order" >}} + +## Examples: Layout Lookup for Taxonomy Pages + +{{< datatable-filtered "output" "layouts" "Kind == taxonomy" "Example" "OutputFormat" "Suffix" "Template Lookup Order" >}} + +## Examples: Layout Lookup for Term Pages + +{{< datatable-filtered "output" "layouts" "Kind == term" "Example" "OutputFormat" "Suffix" "Template Lookup Order" >}} - - - - diff --cc docs/content/en/templates/shortcode-templates.md index 19ec6dea,00000000..888b7ca4 mode 100644,000000..100644 --- a/docs/content/en/templates/shortcode-templates.md +++ b/docs/content/en/templates/shortcode-templates.md @@@ -1,414 -1,0 +1,418 @@@ +--- +title: Create Your Own Shortcodes +linktitle: Shortcode Templates +description: You can extend Hugo's built-in shortcodes by creating your own using the same templating syntax as that for single and list pages. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +categories: [templates] +keywords: [shortcodes,templates] +menu: + docs: + parent: "templates" + weight: 100 +weight: 100 +sections_weight: 100 +draft: false +aliases: [] +toc: true +--- + +Shortcodes are a means to consolidate templating into small, reusable snippets that you can embed directly inside of your content. In this sense, you can think of shortcodes as the intermediary between [page and list templates][templates] and [basic content files][]. + +{{% note %}} +Hugo also ships with built-in shortcodes for common use cases. (See [Content Management: Shortcodes](/content-management/shortcodes/).) +{{% /note %}} + +## Create Custom Shortcodes + +Hugo's built-in shortcodes cover many common, but not all, use cases. Luckily, Hugo provides the ability to easily create custom shortcodes to meet your website's needs. + +{{< youtube Eu4zSaKOY4A >}} + +### File Location + +To create a shortcode, place an HTML template in the `layouts/shortcodes` directory of your [source organization][]. Consider the file name carefully since the shortcode name will mirror that of the file but without the `.html` extension. For example, `layouts/shortcodes/myshortcode.html` will be called with either `{{}}` or `{{%/* myshortcode /*/%}}` depending on the type of parameters you choose. + +You can organize your shortcodes in subfolders, e.g. in `layouts/shortcodes/boxes`. These shortcodes would then be accessible with their relative path, e.g: + +``` +{{}} +``` + +Note the forward slash. + +### Shortcode Template Lookup Order + +Shortcode templates have a simple [lookup order][]: + +1. `/layouts/shortcodes/.html` +2. `/themes//layouts/shortcodes/.html` + +### Positional vs Named Parameters + +You can create shortcodes using the following types of parameters: + +* Positional parameters +* Named parameters +* Positional *or* named parameters (i.e, "flexible") + +In shortcodes with positional parameters, the order of the parameters is important. If a shortcode has a single required value (e.g., the `youtube` shortcode below), positional parameters work very well and require less typing from content authors. + +For more complex layouts with multiple or optional parameters, named parameters work best. While less terse, named parameters require less memorization from a content author and can be added in a shortcode declaration in any order. + +Allowing both types of parameters (i.e., a "flexible" shortcode) is useful for complex layouts where you want to set default values that can be easily overridden by users. + +### Access Parameters + +All shortcode parameters can be accessed via the `.Get` method. Whether you pass a key (i.e., string) or a number to the `.Get` method depends on whether you are accessing a named or positional parameter, respectively. + +To access a parameter by name, use the `.Get` method followed by the named parameter as a quoted string: + +``` +{{ .Get "class" }} +``` + +To access a parameter by position, use the `.Get` followed by a numeric position, keeping in mind that positional parameters are zero-indexed: + +``` +{{ .Get 0 }} +``` + +For the second position, you would just use: + +``` +{{ .Get 1 }} +``` + +`with` is great when the output depends on a parameter being set: + +``` - {{ with .Get "class"}} class="{{.}}"{{ end }} ++{{ with .Get "class" }} class="{{ . }}"{{ end }} +``` + +`.Get` can also be used to check if a parameter has been provided. This is +most helpful when the condition depends on either of the values, or both: + +``` - {{ if or (.Get "title") (.Get "alt") }} alt="{{ with .Get "alt"}}{{.}}{{else}}{{.Get "title"}}{{end}}"{{ end }} ++{{ if or (.Get "title") (.Get "alt") }} alt="{{ with .Get "alt" }}{{ . }}{{ else }}{{ .Get "title" }}{{ end }}"{{ end }} +``` + +#### `.Inner` + +If a closing shortcode is used, the `.Inner` variable will be populated with all of the content between the opening and closing shortcodes. If a closing shortcode is required, you can check the length of `.Inner` as an indicator of its existence. + - A shortcode with content declared via the `.Inner` variable can also be declared without the inline content and without the closing shortcode by using the self-closing syntax: ++A shortcode with content declared via the `.Inner` variable can also be declared without the ++content and without the closing ++by using the self-closing syntax: + +``` +{{}} +``` + +#### `.Params` + +The `.Params` variable in shortcodes contains the list parameters passed to shortcode for more complicated use cases. You can also access higher-scoped parameters with the following logic: + +`$.Params` +: these are the parameters passed directly into the shortcode declaration (e.g., a YouTube video ID) + +`$.Page.Params` +: refers to the page's params; the "page" in this case refers to the content file in which the shortcode is declared (e.g., a `shortcode_color` field in a content's front matter could be accessed via `$.Page.Params.shortcode_color`). + +`$.Page.Site.Params` +: refers to global variables as defined in your [site's configuration file][config]. + +#### `.IsNamedParams` + +The `.IsNamedParams` variable checks whether the shortcode declaration uses named parameters and returns a boolean value. + +For example, you could create an `image` shortcode that can take either a `src` named parameter or the first positional parameter, depending on the preference of the content's author. Let's assume the `image` shortcode is called as follows: + +``` - {{}} ++{{}} +``` + +You could then include the following as part of your shortcode templating: + +``` +{{ if .IsNamedParams }} - ++ +{{ else }} - ++ +{{ end }} +``` + +See the [example Vimeo shortcode][vimeoexample] below for `.IsNamedParams` in action. + +{{% warning %}} +While you can create shortcode templates that accept both positional and named parameters, you *cannot* declare shortcodes in content with a mix of parameter types. Therefore, a shortcode declared like `{{}}` will return an error. +{{% /warning %}} + +You can also use the variable `.Page` to access all the normal [page variables][pagevars]. + +A shortcodes can also be nested. In a nested shortcode, you can access the parent shortcode context with [`.Parent` variable][shortcodesvars]. This can be very useful for inheritance of common shortcode parameters from the root. + +### Checking for Existence + +You can check if a specific shortcode is used on a page by calling `.HasShortcode` in that page template, providing the name of the shortcode. This is sometimes useful when you want to include specific scripts or styles in the header that are only used by that shortcode. + +## Custom Shortcode Examples + +The following are examples of the different types of shortcodes you can create via shortcode template files in `/layouts/shortcodes`. + +### Single-word Example: `year` + +Let's assume you would like to keep mentions of your copyright year current in your content files without having to continually review your markdown. Your goal is to be able to call the shortcode as follows: + +``` +{{}} +``` + +{{< code file="/layouts/shortcodes/year.html" >}} +{{ now.Format "2006" }} +{{< /code >}} + +### Single Positional Example: `youtube` + +Embedded videos are a common addition to markdown content that can quickly become unsightly. The following is the code used by [Hugo's built-in YouTube shortcode][youtubeshortcode]: + +``` +{{}} +``` + +Would load the template at `/layouts/shortcodes/youtube.html`: + +{{< code file="/layouts/shortcodes/youtube.html" >}} +
+ +
+{{< /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")}} ++ {{ 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")}}

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

+ {{ .Get "caption" }} - {{ with .Get "attrlink"}} {{ end }} ++ {{ with .Get "attrlink" }} {{ end }} + {{ .Get "attr" }} - {{ if .Get "attrlink"}} {{ end }} ++ {{ 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` + +``` +{{}} +{{}} +``` + +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: + +``` - {{ .Get 0 | highlight .Inner }} ++{{ .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] returns a boolean value depending on whether 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}} ++
++ {{ .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 }} ++{{- end -}} +{{< /code >}} + +You can then call your shortcode in your content as follows: + +``` +{{}} + {{}} + {{}} +{{}} +{{}} +``` + +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`: + +``` +
+ + +
+ +``` + + +## 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 + ++{{< new-in "0.52.0" >}} ++ +Since Hugo 0.52, you can 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">}} +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/tools/frontends.md index 27d825a2,00000000..1d1d7fae mode 100644,000000..100644 --- a/docs/content/en/tools/frontends.md +++ b/docs/content/en/tools/frontends.md @@@ -1,33 -1,0 +1,31 @@@ +--- +title: Frontend Interfaces with Hugo +linktitle: Frontends +description: Do you prefer a graphical user interface over a text editor? Give these frontends a try. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +categories: [developer tools] +keywords: [frontend,gui] +menu: + docs: + parent: "tools" + weight: 40 +weight: 40 +sections_weight: 40 +draft: false +aliases: [] +toc: false +--- + +* [enwrite](https://github.com/zzamboni/enwrite). Enwrite enables evernote-powered, statically generated blogs and websites. Now posting to your blog or updating your website is as easy as writing a new note in Evernote! +* [Lipi](https://github.com/SohanChy/Lipi). Lipi is a native GUI frontend written in Java to manage your Hugo websites. +* [Netlify CMS](https://netlifycms.org). Netlify CMS is an open source, serverless solution for managing Git based content in static sites, and it works on any platform that can host static sites. A [Hugo/Netlify CMS starter](https://github.com/netlify-templates/one-click-hugo-cms) is available to get new projects running quickly. +* [Hokus CMS](https://github.com/julianoappelklein/hokus). Hokus CMS is an open source, multi-platform, easy to use, desktop application for Hugo. Build from simple to complex user interfaces for Hugo websites by choosing from a dozen ready-to-use components — all for free, with no vendor lock-in. + + +## Commercial Services + - * [Appernetic.io](https://appernetic.io) is a Hugo Static Site Generator as a Service that is easy to use for non-technical users. - * **Features:** inline PageDown editor, visual tree view, image upload and digital asset management with Cloudinary, site preview, continuous integration with GitHub, atomic deploy and hosting, Git and Hugo integration, autosave, custom domain, project syncing, theme cloning and management. Developers have complete control over the source code and can manage it with GitHub’s deceptively simple workflow. +* [DATOCMS](https://www.datocms.com) DatoCMS is a fully customizable administrative area for your static websites. Use your favorite website generator, let your clients publish new content independently, and the host the site anywhere you like. +* [Forestry.io](https://forestry.io/). Forestry is a git-backed CMS for Hugo, Gatsby, Jekyll and VuePress websites with support for GitHub, GitLab, Bitbucket and Azure Devops. Forestry provides a nice user interface to edit and model content for non technical editors. It supports S3, Cloudinary and Netlify Large Media integrations for storing media. Every time an update is made via the CMS, Forestry will commit changes back to your repo and vice-versa. + diff --cc docs/netlify.toml index 23d321b2,00000000..ebf8f4a5 mode 100644,000000..100644 --- a/docs/netlify.toml +++ b/docs/netlify.toml @@@ -1,31 -1,0 +1,31 @@@ +[build] +publish = "public" +command = "hugo --gc --minify" + +[context.production.environment] - HUGO_VERSION = "0.84.0" ++HUGO_VERSION = "0.84.4" +HUGO_ENV = "production" +HUGO_ENABLEGITINFO = "true" + +[context.split1] +command = "hugo --gc --minify --enableGitInfo" + +[context.split1.environment] - HUGO_VERSION = "0.84.0" ++HUGO_VERSION = "0.84.4" +HUGO_ENV = "production" + +[context.deploy-preview] +command = "hugo --gc --minify --buildFuture -b $DEPLOY_PRIME_URL" + +[context.deploy-preview.environment] - HUGO_VERSION = "0.84.0" ++HUGO_VERSION = "0.84.4" + +[context.branch-deploy] +command = "hugo --gc --minify -b $DEPLOY_PRIME_URL" + +[context.branch-deploy.environment] - HUGO_VERSION = "0.84.0" ++HUGO_VERSION = "0.84.4" + +[context.next.environment] +HUGO_ENABLEGITINFO = "true" +