Squashed 'docs/' changes from 1de7a358c..ef9c4913c

ef9c4913c Clean up and removal of outdated examples
46122c9aa add godot tutorials to showcase
06d1d1ea2 Update scss-sass.md
1fc63c100 Spelling fix in 0.79.1 release notes
ad2f50e3d Update plainwords description (#1296)
33021d451 Update substr examples (#1304)
6b1cc59bb Release 0.80.0
521db8c6d Merge branch 'tempv0.80.0'
58626c2b3 releaser: Add release notes to /docs for release of 0.80.0
f81d118af dartsass: Dart Sass only supports `expanded` and `compressed`
7da6f54be Add Dart Sass support
b1f2661bb Replace jsconfig.js with jsconfig.json
38de0c1a4 Update index.md
223ceae80 Update index.md
f7ac0e59d Release v0.79.1
2d4583d43 Merge branch 'temp791-2'
1d34e609b releaser: Add release notes to /docs for release of 0.79.1
e26769988 Merge branch 'temp791'
75694d904 Fix Resource.ResourceType so it always returns MIME's main type
0f65d7783 Typo s/adds/add (#1298)
0b896b2c0 images: Add images.Overlay filter
0d4257dcd Clarify documentation on shimming
fcf601ddf Update index.html
6bf9bc1c1 Update index.html
1ce76bf3a Update index.html
e7d976eec Update index.html
db2996e64 Update index.html
245e5bfc9 news: Add post about Apple M1
3ad4115ed tpl: Add title parameter to YouTube shortcode
76ed976f8 Added two useful extensions to the list (#1243)
e5a30dd11 Update related.md
25cf8f48b Improve substr examples
e16e57e9a Update path.Split.md
2749b88fd Update path.Split.md
d76cad3ff Release 0.79.0
f5ccfbe98 releaser: Add release notes to /docs for release of 0.79.0
ebf1b87b0 Merge commit '9f1265fde4b9ef186148337c99f08601633b6056'
1f1e8f39c Allow setting the delimiter used for setting config via OS env, e.g. HUGO_
e9b1414dd deps: Update to github.com/evanw/esbuild 0.8.11 to 0.8.14
0f76cf66c docs: Regen docshelper
1ada5d47e Add menu params
1c120aef0 Revert "docs: Regenerate docshelper"
7b60b5624 docs: Regenerate docshelper

git-subtree-dir: docs
git-subtree-split: ef9c4913cdcf95d62ec12d872f412f97e55a55ad

content/en/content-management/menus.md

@@ -113,6 +113,24 @@ This means that `.Title` will be used unless `.LinkTitle` is present, etc. In pr
 
 In this example, the top level of the menu is defined in your [site `config` file][config]. All content entries are attached to one of these entries via the `.Parent` field.
 
+## Params
+
+You can also add user-defined content to menu items via the `params` field. 
+
+A common use case is to define a custom param to add a css class to a specific menu item.
+
+{{< code-toggle file="config" >}}
+[[menu.main]]
+    name = "about hugo"
+    pre = "<i class='fa fa-heart'></i>"
+    weight = -110
+    identifier = "about"
+    url = "/about/"
+    [menu.main.params]
+      class = "highlight-menu-item"
+{{</ code-toggle >}}
+
+
 ## Render Menus
 
 See [Menu Templates](/templates/menu-templates/) for information on how to render your site menus within your templates.

content/en/content-management/page-resources.md

@@ -21,7 +21,9 @@ the lowest page they are bundled with, and simple which names does not contain `
 ## Properties
 
 ResourceType
-: The main type of the resource. For example, a file of MIME type `image/jpeg` has the ResourceType `image`.
+: The main type of the resource's [Media Type](/templates/output-formats/#media-types). For example, a file of MIME type `image/jpeg` has the ResourceType `image`. A `Page` will have `ResourceType` with value `page`.
+
+{{< new-in "0.80.0" >}} Note that we in Hugo `v0.80.0` fixed a bug where non-image resources (e.g. video) would return the MIME sub type, e.g. `json`.
 
 Name
 : Default value is the filename (relative to the owning page). Can be set in front matter.

content/en/content-management/related.md

@@ -84,6 +84,8 @@ related:
     weight: 10
 {{< /code-toggle >}}
 
+Note that if you have configured `tags` as a taxonomy, `tags` will also be added to the default configuration abve with the weight of `80`.
+
 Custom configuration should be set using the same syntax.
 
 {{% note %}}

content/en/content-management/shortcodes.md

@@ -398,6 +398,13 @@ Furthermore, you can automatically start playback of the embedded video by setti
 {{</* youtube id="w7Ft2ymGmfc" autoplay="true" */>}}
 {{< /code >}}
 
+For [accessibility reasons](https://dequeuniversity.com/tips/provide-iframe-titles), it's best to provide a title for your YouTube video.  You  can do this using the shortcode by providing a `title` parameter. If no title is provided, a default of "YouTube Video" will be used.
+
+{{< code file="example-youtube-input-with-title.md" >}}
+{{</* youtube id="w7Ft2ymGmfc" title="A New Hugo Site in Under Two Minutes" */>}}
+{{< /code >}}
+
+
 #### Example `youtube` Output
 
 Using the preceding `youtube` example, the following HTML will be added to your rendered website's markup:

content/en/functions/images/index.md

@@ -17,6 +17,30 @@ toc: true
 
 See [images.Filter](#filter) for how to apply these filters to an image.
 
+### Overlay
+
+{{< new-in "0.80.0" >}}
+
+{{% funcsig %}}
+images.Overlay SRC X Y
+{{% /funcsig %}}
+
+Overlay creates a filter that overlays the source image at position x y, e.g:
+
+
+```go-html-template
+{{ $logoFilter := (images.Overlay $logo 50 50 ) }}
+{{ $img := $img | images.Filter $logoFilter }}
+```
+
+A shorter version of the above, if you only need to apply the filter once:
+
+```go-html-template
+{{ $img := $img.Filter (images.Overlay $logo 50 50 )}}
+```
+
+The above will overlay `$logo` in the upper left corner of `$img` (at position `x=50, y=50`).
+
 ### Brightness
 
 {{% funcsig %}}

content/en/functions/path.Split.md

@@ -25,7 +25,7 @@ If there is no slash in `PATH`, it returns an empty directory and the base is se
 **Note:** On Windows, `PATH` is converted to slash (`/`) separators.
 
 ```
-{{ path.Split "a/news.html" }} → "a/", "news.html"
-{{ path.Split "news.html" }} → "", "news.html"
-{{ path.Split "a/b/c" }} → "a/b/", "c"
+{{ $dirFile := path.Split "a/news.html" }} → $dirDile.Dir → "a/", $dirFile.File → "news.html"
+{{ $dirFile := path.Split "news.html" }} → $dirDile.Dir → "", $dirDile.File → "news.html"
+{{ $dirFile := path.Split "a/b/c" }} → $dirDile.Dir → "a/b/", $dirDile.File →  "c"
 ```

content/en/functions/substr.md

@@ -26,6 +26,21 @@ To extract characters from the end of the string, use a negative start number.
 In addition, borrowing from the extended behavior described at https://php.net substr, if `length` is given and is negative, that number of characters will be omitted from the end of string.
 
 ```
-{{substr "BatMan" 0 -3}} → "Bat"
-{{substr "BatMan" 3 3}} → "Man"
+{{ substr "abcdef" 0 }} → "abcdef"
+{{ substr "abcdef" 1 }} → "bcdef"
+
+{{ substr "abcdef" 0 1 }} → "a"
+{{ substr "abcdef" 1 1 }} → "b"
+
+{{ substr "abcdef" 0 -1 }} → "abcde"
+{{ substr "abcdef" 1 -1 }} → "bcde"
+
+{{ substr "abcdef" -1 }} → "f"
+{{ substr "abcdef" -2 }} → "ef"
+
+{{ substr "abcdef" -1 1 }} → "f"
+{{ substr "abcdef" -2 1 }} → "e"
+
+{{ substr "abcdef" -3 -1 }} → "de"
+{{ substr "abcdef" -3 -2 }} → "d"
 ```

content/en/getting-started/configuration.md

@@ -326,7 +326,7 @@ 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.
 
 noJSConfigInAssets {{< new-in "0.78.0" >}}
-: Turn off writing a `jsconfig.js` 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.
+: 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
 
@@ -438,6 +438,8 @@ Names must be prefixed with `HUGO_` and the configuration key must be set in upp
 To set config params, prefix the name with `HUGO_PARAMS_`
 {{% /note %}}
 
+{{< new-in "0.79.0" >}} If you are using snake_cased variable names, the above will not work, so since Hugo 0.79.0 Hugo determines the delimiter to use by the first character after `HUGO`. This allows you to define environment variables on the form `HUGOxPARAMSxAPI_KEY=abcdefgh`, using any [allowed](https://stackoverflow.com/questions/2821043/allowed-characters-in-linux-environment-variable-names#:~:text=So%20names%20may%20contain%20any,not%20begin%20with%20a%20digit.) delimiter.
+
 {{< todo >}}
 Test and document setting params via JSON env var.
 {{< /todo >}}

content/en/hugo-pipes/babel.md

@@ -29,7 +29,7 @@ If you are using the Hugo Snap package, Babel and plugin(s) need to be installed
 
 {{< new-in "v0.75.0" >}}
 
-In Hugo `v0.75` we improved the way we resolve JS configuration and dependencies. One of them is that we now adds the main project's `node_modules` to `NODE_PATH` when running Babel and similar tools. There are some known [issues](https://github.com/babel/babel/issues/5618) with Babel in this area, so if you have a `babel.config.js` living in a Hugo Module (and not in the project itself), we recommend using `require` to load the presets/plugins, e.g.:
+In Hugo `v0.75` we improved the way we resolve JS configuration and dependencies. One of them is that we now add the main project's `node_modules` to `NODE_PATH` when running Babel and similar tools. There are some known [issues](https://github.com/babel/babel/issues/5618) with Babel in this area, so if you have a `babel.config.js` living in a Hugo Module (and not in the project itself), we recommend using `require` to load the presets/plugins, e.g.:
 
 
 ```js

content/en/hugo-pipes/js.md

@@ -115,7 +115,7 @@ And then in your JS file:
 import * as params from '@params';
 ```
 
-Hugo will, by default, generate a `assets/jsconfig.js` file that maps the imports. This is useful for navigation/intellisense help inside code editors, but if you don't need/want it, you can [turn it off](/getting-started/configuration/#configure-build).
+Hugo will, by default, generate a `assets/jsconfig.json` file that maps the imports. This is useful for navigation/intellisense help inside code editors, but if you don't need/want it, you can [turn it off](/getting-started/configuration/#configure-build).
 
 
 
@@ -147,27 +147,27 @@ Or with options:
 
 #### Shimming a JS library 
 
-It's a very common practice to load external libraries using CDN rather than importing all packages in a single JS file, making it bulky. To do the same with Hugo, you'll need to shim the libraries as follows. In this example, `algoliasearch` and `instantsearch.js` will be shimmed.
+It's a common practice to load external libraries using a content delivery network (CDN) rather than importing all packages in a single JS file. To load scripts from a CDN with Hugo, you'll need to shim the libraries as follows. In this example, `react` and `react-dom` will be shimmed.
 
-Firstly, add the following to your project's `package.json`:
+First, add React and ReactDOM [CDN script tags](https://reactjs.org/docs/add-react-to-a-website.html#tip-minify-javascript-for-production) in your HTML template files. Then create `assets/js/shims/react.js` and `assets/js/shims/react-dom.js` with the following contents:
+```js
+// In assets/js/shims/react.js
+module.exports = window.React;
+
+// In assets/js/shims/react-dom.js
+module.exports = window.ReactDOM;
+```
+
+Finally, add the following to your project's `package.json`:
 ```json
 {
   "browser": {
-    "algoliasearch/lite": "./public/js/shims/algoliasearch.js",
-    "instantsearch.js/es/lib/main": "./public/js/shims/instantsearch.js"
+    "react": "./assets/js/shims/react.js",
+    "react-dom": "./assets/js/shims/react-dom.js"
   }
 }
 ```
 
-What this does is it tells Hugo to look for the listed packages somewhere else. Here we're telling Hugo to look for `algoliasearch/lite` and `instantsearch.js/es/lib/main` in the project's `public/js/shims` folder.
+This tells Hugo's `js.Build` command to look for `react` and `react-dom` in the project's `assets/js/shims` folder. Note that the `browser` field in your `package.json` file will cause React and ReactDOM to be excluded from your JavaScript bundle. Therefore, **it is unnecessary to add them to the `js.Build` command's `externals` argument.**
 
-Now we'll need to create the shim JS files which export the global JS variables `module.exports = window.something`. You can create a separate shim JS file in your `assets` directory, and redirect the import paths there if you wish, but a much cleaner way is to create these files on the go, by having the following before your JS is built.
-
-```go-html-template
-{{ $a := "module.exports = window.algoliasearch" | resources.FromString "js/shims/algoliasearch.js" }}
-{{ $i := "module.exports = window.instantsearch" | resources.FromString "js/shims/instantsearch.js" }}
-
-{{/* Call RelPermalink unnecessarily to generate JS files */}}
-{{ $placebo := slice $a.RelPermalink $i.RelPermalink }}
-```
 That's it! You should now have a browser-friendly JS which can use external JS libraries.

content/en/hugo-pipes/scss-sass.md

@@ -24,14 +24,19 @@ Any SASS or SCSS file can be transformed into a CSS file using `resources.ToCSS`
 ```
 
 ### Options
+
+transpiler [string] {{< new-in "0.80.0" >}}
+
+: The `transpiler` to use, valid values are `libsass` (default) and `dartsass`. Note that the Embedded Dart Sass project is still in beta (beta 5 at the time of writing). The release is scheduled for Q1 2021. We will try to improve the installation process by then, but if you want to use Hugo with Dart Sass you need to download a release binary from [Embedded Dart Sass](https://github.com/sass/dart-sass-embedded/releases) (beta 5) and make sure it's in your PC's `$PATH` (or `%PATH%` on Windows).
+
 targetPath [string]
 : If not set, the resource's target path will be the asset file original path with its extension replaced by `.css`.
 
 outputStyle [string]
-: Default is `nested`. Other available output styles are `expanded`, `compact` and `compressed`.
+: Default is `nested` (LibSass) and `expanded` (Dart Sass). Other available output styles for LibSass are `expanded`, `compact` and `compressed`. Dart Sass only supports `expanded` and `compressed`.
 
 precision [int]
-: Precision of floating point math.
+: Precision of floating point math. **Note:** This option is not supported by Dart Sass.
 
 enableSourceMap [bool]
 : When enabled, a source map will be generated.

content/en/news/0.78.0-relnotes/index.md

@@ -12,7 +12,7 @@ Some notes on the improvements in this release:
 
 * Now `js.Build` fully supports the virtual union filesystem in [Hugo Modules](https://gohugo.io/hugo-modules/). Any import inside your JavaScript components will resolve starting from the top component mount inside `/assets` with a fallback to the traditional "JS way" (`node_modules` etc.)
 * You can now pass configuration data from the templates to your scripts via a new `params` option.
-* Hugo now writes a `jsconfig.js` file inside `/assets` (you can turn it off) with import mappings to help editors such as VS Code with intellisense/navigation, which is especially useful when there is no common root and the source lives inside some temporary directory.
+* Hugo now writes a `jsconfig.json` file inside `/assets` (you can turn it off) with import mappings to help editors such as VS Code with intellisense/navigation, which is especially useful when there is no common root and the source lives inside some temporary directory.
 * We have also improved the build errors you get from `js.Build`. In server mode you will get a preview of the failing lines and in the console you will get a link to the location.
 
 Read more about this in [the documentation](https://gohugo.io/hugo-pipes/js/), but a short usage example would look like: