Squashed 'docs/' changes from 57c1d1a67..1de7a358c

1de7a358c Clarify that "with" blocks do not render with empty values (#1287)
b48de8b0a Update js.md
e0124e4b1 Update js.md
087b39d74 Update hosting-on-render.md (#1286)
8f02b5412 Update js.md (#1284)
8dd8a8d1d Add link to "Build Websites with Hugo" book (#1174)
ae2dc138a Fix typo in page bundles (#1283)
ab14bfec3 Update configuration directory section
17da77ff1 Update multilingual.md (#1280)
5bce8db3a Fix for site-hierarchy image, issue #60
9d7a2366d Fix typo
ad4210c41 Fix typo
c88bc0383 Fix orphan branch url (#1262)
1cf6cf5b3 Hugo 0.78.2
538c3cb86 Merge branch 'tempv0.78.2'
e5e07fc81 releaser: Add release notes to /docs for release of 0.78.2
120a61a47 Fixed wrong var assignment example
4cebbb1a7 Ignore remote JSON errors (for now)
618fcf9ba Add a link to modules config option 'replacements'
e12722779 Fix typo ("wil" -> "will") (#1273)
0670e9894 Update js.md
5bde834cf Update GH docs to say "main" as default branch
26312f93d Update index.md
eb6f51df1 Update js.md
b890dc84d Merge branch 'tempv0.78.1'
6b73ea450 releaser: Add release notes to /docs for release of 0.78.1
46e582112 Update starter-kits.md (#1268)
a62786235 Update 404 docs: GitLab auto-detects 404.html (#1173)
cbd4fd2d9 Fix typo (#1271)
2ba3f9386 Update js.md
7b5109d90 Update js.md
bc75bc962 Release 0.78.0
0b2e8b0f1 releaser: Add release notes to /docs for release of 0.78.0
9ecba8480 Merge commit 'b74591123eac47a20d1f26ff3e2d291cd9c5cfc0'
60a475df7 js: Add avoidTDZ option
3b895261f Make js.Build fully support modules

git-subtree-dir: docs
git-subtree-split: 1de7a358cac94ac09a513456bdaae65e6ae94859

config.toml

@@ -7,6 +7,8 @@ footnotereturnlinkcontents = "↩"
 languageCode = "en-us"
 title = "Hugo"
 
+ ignoreErrors = ["error-remote-getjson"]
+
 
 googleAnalytics = "UA-7131036-4"
 

content/en/content-management/multilingual.md

@@ -26,7 +26,7 @@ You should define the available languages in a `languages` section in your site
 The following is an example of a site configuration for a multilingual Hugo project:
 
 {{< code-toggle file="config" >}}
-DefaultContentLanguage = "en"
+defaultContentLanguage = "en"
 copyright = "Everything is mine"
 
 [params]
@@ -71,7 +71,7 @@ If the default language needs to be rendered below its own language code (`/en`)
 
 Only the obvious non-global options can be overridden per language. Examples of global options are `baseURL`, `buildDrafts`, etc.
 
-**Please note:** use lowercase language codes, even when using regional languages (ie. use pt-pt instead of pt-PT). Currently Hugo language internals lowercase language codes, which can cause conflicts with settings like `DefaultContentLanguage` which are not lowercased. Please track the evolution of this issue in [Hugo repository issue tracker](https://github.com/gohugoio/hugo/issues/7344)
+**Please note:** use lowercase language codes, even when using regional languages (ie. use pt-pt instead of pt-PT). Currently Hugo language internals lowercase language codes, which can cause conflicts with settings like `defaultContentLanguage` which are not lowercased. Please track the evolution of this issue in [Hugo repository issue tracker](https://github.com/gohugoio/hugo/issues/7344)
 
 ### Disable a Language
 

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

@@ -2,7 +2,6 @@
 title : "Page Bundles"
 description : "Content organization using Page Bundles"
 date : 2018-01-24T13:09:00-05:00
-lastmod : 2018-01-28T22:26:40-05:00
 linktitle : "Page Bundles"
 keywords : ["page", "bundle", "leaf", "branch"]
 categories : ["content management"]
@@ -186,4 +185,4 @@ The hierarchy depth at which a branch bundle is created does not
 matter.
 {{% /note %}}
 
-[^fn:1]: The `.md` extension is just an example. The extension can be `.html`, `.json` or any of any valid MIME type.
+[^fn:1]: The `.md` extension is just an example. The extension can be `.html`, `.json` or any valid MIME type.

content/en/functions/with.md

@@ -1,7 +1,7 @@
 ---
 title: with
 # linktitle: with
-description: Rebinds the context (`.`) within its scope and skips the block if the variable is absent.
+description: Rebinds the context (`.`) within its scope and skips the block if the variable is absent or empty.
 godocref:
 date: 2017-02-01
 publishdate: 2017-02-01
@@ -18,7 +18,11 @@ relatedfuncs: []
 deprecated: false
 ---
 
-An alternative way of writing an `if` statement and then referencing the same value is to use `with` instead. `with` rebinds the context (`.`) within its scope and skips the block if the variable is absent or unset.
+An alternative way of writing an `if` statement and then referencing the same value is to use `with` instead. `with` rebinds the context (`.`) within its scope and skips the block if the variable is absent, unset or empty.
+
+The set of *empty* values is defined by [the Go templates package](https://golang.org/pkg/text/template/). Empty values include `false`, the number zero, and the empty string.
+
+If you want to render a block if an index or key is present in a slice, array, channel or map, regardless of whether the value is empty, you should use [`isset`](/functions/isset) instead.
 
 The following example checks for a [user-defined site variable](/variables/site/) called `twitteruser`. If the key-value is not set, the following will render nothing:
 

content/en/getting-started/configuration.md

@@ -44,7 +44,18 @@ Multiple site config files can be specified as a comma-separated string to the `
 
 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`, `Menus`, `Languages` etc...
+- 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:
+
+  In `config.toml` is:
+  ```toml
+  [Params]
+    foo = "bar"
+  ```
+  In `params.toml` is:
+  ```
+  foo = "bar"
+  ```
 - Each directory holds a group of files containing settings unique to an environment.
 - Files can be localized to become language specific.
 
@@ -304,6 +315,7 @@ The `build` configuration section contains global build-related configuration op
 [build]
 useResourceCacheWhen="fallback"
 writeStats = false
+noJSConfigInAssets = false
 {{< /code-toggle >}}
 
 
@@ -313,6 +325,9 @@ useResourceCacheWhen
 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.
+
 ## Configure Server
 
 {{< new-in "0.67.0" >}}

content/en/getting-started/external-learning-resources/index.md

@@ -26,6 +26,10 @@ Hugo in Action is a step-by-step guide to using Hugo to create static websites.
 
 [Hugo In Action Home Page](https://www.manning.com/books/hugo-in-action)
 
+### Build Websites with Hugo
+
+[Build Websites with Hugo - Fast Web Development with Markdown (2020)](https://pragprog.com/titles/bhhugo/) by Brian P. Hogan.
+
 ## Video tutorials
 
 ### Video Playlist by Mike Dane

content/en/hosting-and-deployment/hosting-on-github.md

@@ -45,7 +45,7 @@ To create a Project Pages site, choose a method from the *Project Pages* section
 As mentioned in the [GitHub Pages documentation][ghorgs], you can host a user/organization page in addition to project pages. Here are the key differences in GitHub Pages websites for Users and Organizations:
 
 1. You must use a `<USERNAME>.github.io` to host your **generated** content
-2. Content from the `master` branch will be used to publish your GitHub Pages site
+2. Content from the `main` branch will be used to publish your GitHub Pages site
 
 This is a much simpler setup as your Hugo files and generated content are published into two different repositories.
 
@@ -58,7 +58,7 @@ This is a much simpler setup as your Hugo files and generated content are publis
 5. Once you are happy with the results:
     * Press <kbd>Ctrl</kbd>+<kbd>C</kbd> to kill the server
     * Before proceeding run `rm -rf public` to completely remove the `public` directory
-6. `git submodule add -b master https://github.com/<USERNAME>/<USERNAME>.github.io.git public`. This creates a git [submodule][]. Now when you run the `hugo` command to build your site to `public`, the created `public` directory will have a different remote origin (i.e. hosted GitHub repository).
+6. `git submodule add -b main https://github.com/<USERNAME>/<USERNAME>.github.io.git public`. This creates a git [submodule][]. Now when you run the `hugo` command to build your site to `public`, the created `public` directory will have a different remote origin (i.e. hosted GitHub repository).
 7. Make sure the `baseURL` in your config file is updated with: `<USERNAME>.github.io`
 
 ### Put it Into a Script
@@ -92,7 +92,7 @@ fi
 git commit -m "$msg"
 
 # Push source and build repos.
-git push origin master
+git push origin main
 ```
 
 
@@ -106,9 +106,9 @@ That's it! Your personal page should be up and running at `https://<USERNAME>.gi
 Make sure your `baseURL` key-value in your [site configuration](/getting-started/configuration/) reflects the full URL of your GitHub pages repository if you're using the default GH Pages URL (e.g., `<USERNAME>.github.io/<PROJECT>/`) and not a custom domain.
 {{% /note %}}
 
-### Deployment of Project Pages from `/docs` folder on `master` branch
+### Deployment of Project Pages from `/docs` folder on `main` branch
 
-[As described in the GitHub Pages documentation][ghpfromdocs], you can deploy from a folder called `docs/` on your master branch. To effectively use this feature with Hugo, you need to change the Hugo publish directory in your [site's][config] `config.toml` and `config.yaml`, respectively:
+[As described in the GitHub Pages documentation][ghpfromdocs], you can deploy from a folder called `docs/` on your main branch. To effectively use this feature with Hugo, you need to change the Hugo publish directory in your [site's][config] `config.toml` and `config.yaml`, respectively:
 
 ```
 publishDir = "docs"
@@ -117,18 +117,18 @@ publishDir = "docs"
 publishDir: docs
 ```
 
-After running `hugo`, push your master branch to the remote repository and choose the `docs/` folder as the website source of your repo. Do the following from within your GitHub project:
+After running `hugo`, push your main branch to the remote repository and choose the `docs/` folder as the website source of your repo. Do the following from within your GitHub project:
 
 1. Go to **Settings** &rarr; **GitHub Pages**
-2. From **Source**,  select "master branch /docs folder". If the option isn't enabled, you likely do not have a `docs/` folder in the root of your project.
+2. From **Source**,  select "main branch /docs folder". If the option isn't enabled, you likely do not have a `docs/` folder in the root of your project.
 
 {{% note %}}
-The `docs/` option is the simplest approach but requires you set a publish directory in your site configuration. You cannot currently configure GitHub pages to publish from another directory on master, and not everyone prefers the output site live concomitantly with source files in version control.
+The `docs/` option is the simplest approach but requires you set a publish directory in your site configuration. You cannot currently configure GitHub pages to publish from another directory on main, and not everyone prefers the output site live concomitantly with source files in version control.
 {{% /note %}}
 
 ### Deployment of Project Pages From Your `gh-pages` branch
 
-You can also tell GitHub pages to treat your `master` branch as the published site or point to a separate `gh-pages` branch. The latter approach is a bit more complex but has some advantages:
+You can also tell GitHub pages to treat your `main` branch as the published site or point to a separate `gh-pages` branch. The latter approach is a bit more complex but has some advantages:
 
 * It keeps your source and generated website in different branches and therefore maintains version control history for both.
 * Unlike the preceding `docs/` option, it uses the default `public` folder.
@@ -139,7 +139,7 @@ These steps only need to be done once. Replace `upstream` with the name of your
 
 ##### Add the `public` Folder
 
-First, add the `public` folder to your `.gitignore` file at the project root so that the directory is ignored on the master branch:
+First, add the `public` folder to your `.gitignore` file at the project root so that the directory is ignored on the main branch:
 
 ```
 echo "public" >> .gitignore
@@ -154,7 +154,7 @@ git checkout --orphan gh-pages
 git reset --hard
 git commit --allow-empty -m "Initializing gh-pages branch"
 git push upstream gh-pages
-git checkout master
+git checkout main
 ```
 
 #### Build and Deployment
@@ -225,14 +225,14 @@ cd public && git add --all && git commit -m "Publishing to gh-pages (publish.sh)
 
 This will abort if there are pending changes in the working directory and also makes sure that all previously existing output files are removed. Adjust the script to taste, e.g. to include the final push to the remote repository if you don't need to take a look at the gh-pages branch before pushing.
 
-### Deployment of Project Pages from Your `master` Branch
+### Deployment of Project Pages from Your `main` Branch
 
-To use `master` as your publishing branch, you'll need your rendered website to live at the root of the GitHub repository. Steps should be similar to that of the `gh-pages` branch, with the exception that you will create your GitHub repository with the `public` directory as the root. Note that this does not provide the same benefits of the `gh-pages` branch in keeping your source and output in separate, but version controlled, branches within the same repo.
+To use `main` as your publishing branch, you'll need your rendered website to live at the root of the GitHub repository. Steps should be similar to that of the `gh-pages` branch, with the exception that you will create your GitHub repository with the `public` directory as the root. Note that this does not provide the same benefits of the `gh-pages` branch in keeping your source and output in separate, but version controlled, branches within the same repo.
 
-You will also need to set `master` as your publishable branch from within the GitHub UI:
+You will also need to set `main` as your publishable branch from within the GitHub UI:
 
 1. Go to **Settings** &rarr; **GitHub Pages**
-2. From **Source**,  select "master branch" and then **Save**.
+2. From **Source**,  select "main branch" and then **Save**.
 
 ## Use a Custom Domain
 
@@ -243,11 +243,11 @@ Refer to the [official documentation for custom domains][domains] for further in
 [config]: /getting-started/configuration/
 [domains]: https://help.github.com/articles/using-a-custom-domain-with-github-pages/
 [ghorgs]: https://help.github.com/articles/user-organization-and-project-pages/#user--organization-pages
-[ghpfromdocs]: https://help.github.com/articles/configuring-a-publishing-source-for-github-pages/#publishing-your-github-pages-site-from-a-docs-folder-on-your-master-branch
+[ghpfromdocs]: https://help.github.com/articles/configuring-a-publishing-source-for-github-pages/
 [ghsignup]: https://github.com/join
 [GitHub Pages service]: https://help.github.com/articles/what-is-github-pages/
 [installgit]: https://git-scm.com/downloads
-[orphan branch]: https://git-scm.com/docs/git-checkout/#git-checkout---orphanltnewbranchgt
+[orphan branch]: https://git-scm.com/docs/git-checkout/#Documentation/git-checkout.txt---orphanltnewbranchgt
 [Quick Start]: /getting-started/quick-start/
 [submodule]: https://github.com/blog/2104-working-with-submodules
 [worktree feature]: https://git-scm.com/docs/git-worktree

content/en/hosting-and-deployment/hosting-on-render.md

@@ -46,12 +46,11 @@ Static sites are **completely free** on Render and include the following:
 
 You can set up a Hugo site on Render in two quick steps:
 
-1. Create a new **Web Service** on Render, and give Render permission to access your GitHub/Gitlab repo.
+1. Create a new **Static Site** on Render, and give Render permission to access your GitHub/Gitlab repo.
 2. Use the following values during creation:
 
   Field                | Value
   -------------------  |  -------------------
- **Environment**       | `Static Site`
  **Build Command**     | `hugo --gc --minify` (or your own build command)
  **Publish Directory** | `public` (or your own output directory)
 

content/en/hugo-modules/use-modules.md

@@ -89,6 +89,7 @@ replace github.com/bep/hugotestmods/mypartials => /Users/bep/hugotestmods/mypart
 
 If you have the `hugo server` running, the configuration will be reloaded and `/Users/bep/hugotestmods/mypartials` put on the watch list.
 
+Note that since v.0.77.0 you can use modules config [`replacements`](https://gohugo.io/hugo-modules/configuration/#module-config-top-level) option. {{< new-in "0.77.0" >}}
 
 ## Print Dependency Graph