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
This commit is contained in:
Bjørn Erik Pedersen 2020-11-27 09:26:24 +01:00
parent b74591123e
commit 9f1265fde4
21 changed files with 236 additions and 668 deletions

View file

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

View file

@ -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: The following is an example of a site configuration for a multilingual Hugo project:
{{< code-toggle file="config" >}} {{< code-toggle file="config" >}}
DefaultContentLanguage = "en" defaultContentLanguage = "en"
copyright = "Everything is mine" copyright = "Everything is mine"
[params] [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. 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 ### Disable a Language

View file

@ -2,7 +2,6 @@
title : "Page Bundles" title : "Page Bundles"
description : "Content organization using Page Bundles" description : "Content organization using Page Bundles"
date : 2018-01-24T13:09:00-05:00 date : 2018-01-24T13:09:00-05:00
lastmod : 2018-01-28T22:26:40-05:00
linktitle : "Page Bundles" linktitle : "Page Bundles"
keywords : ["page", "bundle", "leaf", "branch"] keywords : ["page", "bundle", "leaf", "branch"]
categories : ["content management"] categories : ["content management"]
@ -186,4 +185,4 @@ The hierarchy depth at which a branch bundle is created does not
matter. matter.
{{% /note %}} {{% /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.

View file

@ -1,7 +1,7 @@
--- ---
title: with title: with
# linktitle: 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: godocref:
date: 2017-02-01 date: 2017-02-01
publishdate: 2017-02-01 publishdate: 2017-02-01
@ -18,7 +18,11 @@ relatedfuncs: []
deprecated: false 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: 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:

View file

@ -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. 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. - Each directory holds a group of files containing settings unique to an environment.
- Files can be localized to become language specific. - Files can be localized to become language specific.
@ -304,6 +315,7 @@ The `build` configuration section contains global build-related configuration op
[build] [build]
useResourceCacheWhen="fallback" useResourceCacheWhen="fallback"
writeStats = false writeStats = false
noJSConfigInAssets = false
{{< /code-toggle >}} {{< /code-toggle >}}
@ -313,6 +325,9 @@ useResourceCacheWhen
writeStats {{< new-in "0.69.0" >}} 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. : 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 ## Configure Server
{{< new-in "0.67.0" >}} {{< new-in "0.67.0" >}}

View file

@ -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) [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 tutorials
### Video Playlist by Mike Dane ### Video Playlist by Mike Dane

View file

@ -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: 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 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. 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: 5. Once you are happy with the results:
* Press <kbd>Ctrl</kbd>+<kbd>C</kbd> to kill the server * Press <kbd>Ctrl</kbd>+<kbd>C</kbd> to kill the server
* Before proceeding run `rm -rf public` to completely remove the `public` directory * 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` 7. Make sure the `baseURL` in your config file is updated with: `<USERNAME>.github.io`
### Put it Into a Script ### Put it Into a Script
@ -92,7 +92,7 @@ fi
git commit -m "$msg" git commit -m "$msg"
# Push source and build repos. # 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. 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 %}} {{% /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" publishDir = "docs"
@ -117,18 +117,18 @@ publishDir = "docs"
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** 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 %}} {{% 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 %}} {{% /note %}}
### Deployment of Project Pages From Your `gh-pages` branch ### 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. * 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. * 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 ##### 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 echo "public" >> .gitignore
@ -154,7 +154,7 @@ git checkout --orphan gh-pages
git reset --hard git reset --hard
git commit --allow-empty -m "Initializing gh-pages branch" git commit --allow-empty -m "Initializing gh-pages branch"
git push upstream gh-pages git push upstream gh-pages
git checkout master git checkout main
``` ```
#### Build and Deployment #### 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. 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** 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 ## Use a Custom Domain
@ -243,11 +243,11 @@ Refer to the [official documentation for custom domains][domains] for further in
[config]: /getting-started/configuration/ [config]: /getting-started/configuration/
[domains]: https://help.github.com/articles/using-a-custom-domain-with-github-pages/ [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 [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 [ghsignup]: https://github.com/join
[GitHub Pages service]: https://help.github.com/articles/what-is-github-pages/ [GitHub Pages service]: https://help.github.com/articles/what-is-github-pages/
[installgit]: https://git-scm.com/downloads [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/ [Quick Start]: /getting-started/quick-start/
[submodule]: https://github.com/blog/2104-working-with-submodules [submodule]: https://github.com/blog/2104-working-with-submodules
[worktree feature]: https://git-scm.com/docs/git-worktree [worktree feature]: https://git-scm.com/docs/git-worktree

View file

@ -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: 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: 2. Use the following values during creation:
Field | Value Field | Value
------------------- | ------------------- ------------------- | -------------------
**Environment** | `Static Site`
**Build Command** | `hugo --gc --minify` (or your own build command) **Build Command** | `hugo --gc --minify` (or your own build command)
**Publish Directory** | `public` (or your own output directory) **Publish Directory** | `public` (or your own output directory)

View file

@ -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. 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 ## Print Dependency Graph

View file

@ -23,9 +23,26 @@ targetPath [string]
: If not set, the source path will be used as the base target path. : If not set, the source path will be used as the base target path.
Note that the target path's extension may change if the target MIME type is different, e.g. when the source is TypeScript. Note that the target path's extension may change if the target MIME type is different, e.g. when the source is TypeScript.
params [map or slice] {{< new-in "0.78.0" >}}
: Params that can be imported as JSON in your JS files, e.g.:
```go-html-template
{{ $js := resources.Get "js/main.js" | js.Build (dict "params" (dict "api" "https://example.org/api")) }}
```
And then in your JS file:
```js
import * as params from '@params';
```
Note that this is meant for small data sets, e.g. config settings. For larger data, please put/mount the files into `/assets` and import them directly.
minify [bool] minify [bool]
: Let `js.Build` handle the minification. : Let `js.Build` handle the minification.
avoidTDZ {{< new-in "0.78.0" >}}
: There is/was a bug in WebKit with severe performance issue with the tracking of TDZ checks in JavaScriptCore. Enabling this flag removes the TDZ and `const` assignment checks and may improve performance of larger JS codebases until the WebKit fix is in widespread use. See https://bugs.webkit.org/show_bug.cgi?id=199866
target [string] target [string]
: The language target. : The language target.
One of: `es5`, `es2015`, `es2016`, `es2017`, `es2018`, `es2019`, `es2020` or `esnext`. One of: `es5`, `es2015`, `es2016`, `es2017`, `es2018`, `es2019`, `es2020` or `esnext`.
@ -52,6 +69,65 @@ format [string] {{< new-in "0.74.3" >}}
One of: `iife`, `cjs`, `esm`. One of: `iife`, `cjs`, `esm`.
Default is `iife`, a self-executing function, suitable for inclusion as a <script> tag. Default is `iife`, a self-executing function, suitable for inclusion as a <script> tag.
sourceMap
: Whether to generate source maps. Enum, currently only `inline` (we will improve that).
### Import JS code from /assets
{{< new-in "0.78.0" >}}
Since Hugo `v0.78.0` `js.Build` has full support for the virtual union file system in [Hugo Modules](/hugo-modules/). You can see some simple examples in this [test project](https://github.com/gohugoio/hugoTestProjectJSModImports), but in short this means that you can do this:
```js
import { hello } from 'my/module';
```
And it will resolve to the top-most `index.{js,ts,tsx,jsx}` inside `assets/my/module` in the layered file system.
```js
import { hello3 } from 'my/module/hello3';
```
Wil resolve to `hello3.{js,ts,tsx,jsx}` inside `assets/my/module`.
Any imports starting with `.` is resolved relative to the current file:
```js
import { hello4 } from './lib';
```
For other files (e.g. `JSON`, `CSS`) you need to use the relative path including any extension, e.g:
```js
import * as data from 'my/module/data.json';
```
Any imports in a file outside `/assets` or that does not resolve to a component inside `/assets` will be resolved by [ESBuild](https://esbuild.github.io/) with the **project directory** as the resolve directory (used as the starting point when looking for `node_modules` etc.). Also see [hugo mod npm pack](/commands/hugo_mod_npm_pack/). If you have any imported NPM dependencies in your project, you need to make sure to run `npm install` before you run `hugo`.
Also note the new `params` option that can be passed from template to your JS files, e.g.:
```go-html-template
{{ $js := resources.Get "js/main.js" | js.Build (dict "params" (dict "api" "https://example.org/api")) }}
```
And then in your JS file:
```js
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).
### Include Dependencies In package.json / node_modules
Any imports in a file outside `/assets` or that does not resolve to a component inside `/assets` will be resolved by [ESBuild](https://esbuild.github.io/) with the **project directory** as the resolve directory (used as the starting point when looking for `node_modules` etc.). Also see [hugo mod npm pack](/commands/hugo_mod_npm_pack/). If you have any imported NPM dependencies in your project, you need to make sure to run `npm install` before you run `hugo`.
{{< new-in "0.78.1" >}} From Hugo `0.78.1` the start directory for resolving NPM packages (aka. packages that live inside a `node_modules` folder) is always the main project folder.
**Note:** If you're developing a theme/component that is supposed to be imported and depends on dependencies inside `package.json`, we recommend reading about [hugo mod npm pack](/commands/hugo_mod_npm_pack/), a tool to consolidate all the NPM dependencies in a project.
### Examples ### Examples
```go-html-template ```go-html-template
@ -70,6 +146,7 @@ Or with options:
``` ```
#### Shimming a JS library #### 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 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.
Firstly, add the following to your project's `package.json`: Firstly, add the following to your project's `package.json`:

View file

@ -21,7 +21,7 @@ It is possible to create a resource directly from the template using `resources.
The following example creates a resource file containing localized variables for every project's languages. The following example creates a resource file containing localized variables for every project's languages.
```go-html-template ```go-html-template
{{ $string := (printf "var rootURL: '%s'; var apiURL: '%s';" (absURL "/") (.Param "API_URL")) }} {{ $string := (printf "var rootURL = '%s'; var apiURL = '%s';" (absURL "/") (.Param "API_URL")) }}
{{ $targetPath := "js/vars.js" }} {{ $targetPath := "js/vars.js" }}
{{ $vars := $string | resources.FromString $targetPath }} {{ $vars := $string | resources.FromString $targetPath }}
{{ $global := resources.Get "js/global.js" | resources.Minify }} {{ $global := resources.Get "js/global.js" | resources.Minify }}

Binary file not shown.

After

Width:  |  Height:  |  Size: 46 KiB

View file

@ -0,0 +1,50 @@
---
date: 2020-11-03
title: "Hugo 0.78.0: Full Hugo Modules Support in js.Build"
description: "Resolve JavaScript imports top-down in the layered filesystem, pass parameters from template to JS, new JS intellisense helper, improved JS build errors."
categories: ["Releases"]
---
This release finally brings full [Hugo Modules](https://gohugo.io/hugo-modules/) support to [js.Build](https://gohugo.io/hugo-pipes/js/), curtsy of he new plugin API in the really, really fast [ESBuild](https://github.com/evanw/esbuild) by [@evanw](https://github.com/evanw).
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.
* 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:
In the template:
```go-html-template
{{ $js := resources.Get "js/main.js" | js.Build (dict "params" (dict "api" "https://example.org/api" ) }}
```
And then in a JavaScript component:
```js
import * as params from '@params';
// Will resolve to one of `hello.{js,ts,tsx,jsx}` inside `assets/my/module`.
import { hello } from 'my/module/hello';
var api = params.api;
hello();
```
## Changes
* Add avoidTDZ option [3b2fe3cd](https://github.com/gohugoio/hugo/commit/3b2fe3cd33b74166c3debec9826826f2b5a54fd9) [@bep](https://github.com/bep) [#7865](https://github.com/gohugoio/hugo/issues/7865)
* Make js.Build fully support modules [85e4dd73](https://github.com/gohugoio/hugo/commit/85e4dd7370eae97ae367e596aa6a10ba42fd4b7c) [@bep](https://github.com/bep) [#7816](https://github.com/gohugoio/hugo/issues/7816)[#7777](https://github.com/gohugoio/hugo/issues/7777)[#7916](https://github.com/gohugoio/hugo/issues/7916)
* Generate tsconfig files [3089fc0b](https://github.com/gohugoio/hugo/commit/3089fc0ba171be14670b19439bc2eab6b077b6c3) [@richtera](https://github.com/richtera) [#7777](https://github.com/gohugoio/hugo/issues/7777)

View file

@ -0,0 +1,20 @@
---
date: 2020-11-05
title: "Hugo 0.78.1: A couple of Bug Fixes"
description: "This version fixes a couple of bugs introduced in 0.78.0."
categories: ["Releases"]
images:
- images/blog/hugo-bug-poster.png
---
The main fix in this release is that of dependency resolution for package.json/node_modules in theme components. See [the documentation](https://gohugo.io/hugo-pipes/js/#include-dependencies-in-packagejson--node_modules) for more information.
* Disable NPM test on Travis on Windows [3437174c](https://github.com/gohugoio/hugo/commit/3437174c3a7b96925b82b351ac87530b4fa796a5) [@bep](https://github.com/bep)
* travis: Install nodejs on Windows [f66302ca](https://github.com/gohugoio/hugo/commit/f66302ca0579171ffd1730eb8f33dd05af3d9a00) [@bep](https://github.com/bep)
* js: Remove external source map option [944150ba](https://github.com/gohugoio/hugo/commit/944150bafbbb5c3e807ba3688174e70764dbdc64) [@bep](https://github.com/bep) [#7932](https://github.com/gohugoio/hugo/issues/7932)
* js: Misc fixes [bf2837a3](https://github.com/gohugoio/hugo/commit/bf2837a314eaf70135791984a423b0b09f58741d) [@bep](https://github.com/bep) [#7924](https://github.com/gohugoio/hugo/issues/7924)[#7923](https://github.com/gohugoio/hugo/issues/7923)

View file

@ -0,0 +1,28 @@
---
date: 2020-11-13
title: "Hugo 0.78.2: A couple of Bug Fixes"
description: "This version fixes a couple of bugs introduced in 0.78.0."
categories: ["Releases"]
images:
- images/blog/hugo-bug-poster.png
---
This is a bug-fix release with a couple of important fixes.
* js: Let ESBuild handle all imports from node_modules [78f227b6](https://github.com/gohugoio/hugo/commit/78f227b664d86c30fbb25f7a953b7ef8f2dacf13) [@bep](https://github.com/bep) [#7948](https://github.com/gohugoio/hugo/issues/7948)
* build(deps): bump github.com/evanw/esbuild from 0.8.5 to 0.8.6 [5e03f644](https://github.com/gohugoio/hugo/commit/5e03f644a4507f51bdbcdb42b65ce4e99095374f) [@dependabot[bot]](https://github.com/apps/dependabot)
* build(deps): bump github.com/evanw/esbuild from 0.8.4 to 0.8.5 [a92ef20f](https://github.com/gohugoio/hugo/commit/a92ef20ff6e43ba05844539b60782e8190712cdc) [@dependabot[bot]](https://github.com/apps/dependabot)
* build(deps): bump github.com/getkin/kin-openapi from 0.22.1 to 0.26.0 [0d54a844](https://github.com/gohugoio/hugo/commit/0d54a844061e808dd5b4ff4874b2e4bd9df4d556) [@dependabot[bot]](https://github.com/apps/dependabot)
* Update GH docs to say "main" as default branch [943f3c93](https://github.com/gohugoio/hugo/commit/943f3c932f5f67ab52bf8e0636e57751dc9b1891) [@maco](https://github.com/maco)
* Updated year in header [4f20bf29](https://github.com/gohugoio/hugo/commit/4f20bf29eb246a2e65508175fdd5f25b44e98370) [@AdamKorcz](https://github.com/AdamKorcz)
* Added first fuzzer [4c613d5d](https://github.com/gohugoio/hugo/commit/4c613d5d5d60b80a262e968ae8a4525eba8619a2) [@AdamKorcz](https://github.com/AdamKorcz)
* build(deps): bump github.com/frankban/quicktest from 1.11.1 to 1.11.2 [82a182e5](https://github.com/gohugoio/hugo/commit/82a182e52c4165b4f51d0cc8ef0f21df5d628c69) [@dependabot[bot]](https://github.com/apps/dependabot)
* build(deps): bump golang.org/x/text from 0.3.3 to 0.3.4 [dfc662b2](https://github.com/gohugoio/hugo/commit/dfc662b2086430dde96c18ccb6b92bba4f1be428) [@dependabot[bot]](https://github.com/apps/dependabot)
* build(deps): bump github.com/evanw/esbuild from 0.8.3 to 0.8.4 [2f0917cc](https://github.com/gohugoio/hugo/commit/2f0917cc014557e201a9348664736d608a7fa131) [@dependabot[bot]](https://github.com/apps/dependabot)

View file

@ -46,7 +46,7 @@ This is a basic example of a 404.html template:
Your 404.html file can be set to load automatically when a visitor enters a mistaken URL path, dependent upon the web serving environment you are using. For example: Your 404.html file can be set to load automatically when a visitor enters a mistaken URL path, dependent upon the web serving environment you are using. For example:
* [GitHub Pages](/hosting-and-deployment/hosting-on-github/). The 404 page is automatic. * [GitHub Pages](/hosting-and-deployment/hosting-on-github/) and [GitLab Pages](/hosting-and-deployment/hosting-on-gitlab/). The 404 page is automatic.
* Apache. You can specify `ErrorDocument 404 /404.html` in an `.htaccess` file in the root of your site. * Apache. You can specify `ErrorDocument 404 /404.html` in an `.htaccess` file in the root of your site.
* Nginx. You might specify `error_page 404 /404.html;` in your `nginx.conf` file. * Nginx. You might specify `error_page 404 /404.html;` in your `nginx.conf` file.
* Amazon AWS S3. When setting a bucket up for static web serving, you can specify the error file from within the S3 GUI. * Amazon AWS S3. When setting a bucket up for static web serving, you can specify the error file from within the S3 GUI.

View file

@ -29,6 +29,7 @@ The following starter kits are developed by active members of the Hugo community
* [Blaupause][]. Blaupause is a developer-friendly Hugo starter kit based on Gulp tasks. It comes ES6-ready with several helpers for SVG and fonts and basic structure for HTML, SCSS, and JavaScript. * [Blaupause][]. Blaupause is a developer-friendly Hugo starter kit based on Gulp tasks. It comes ES6-ready with several helpers for SVG and fonts and basic structure for HTML, SCSS, and JavaScript.
* [hugulp][]. hugulp is a tool to optimize the assets of a Hugo website. The main idea is to recreate the famous Ruby on Rails Asset Pipeline, which minifies, concatenates and fingerprints the assets used in your website. * [hugulp][]. hugulp is a tool to optimize the assets of a Hugo website. The main idea is to recreate the famous Ruby on Rails Asset Pipeline, which minifies, concatenates and fingerprints the assets used in your website.
* [Atlas][]. Atlas is a Hugo boilerplate designed to speed up development with support for Netlify, Hugo Pipes, SCSS & more. It's actively maintained and contributions are always welcome. * [Atlas][]. Atlas is a Hugo boilerplate designed to speed up development with support for Netlify, Hugo Pipes, SCSS & more. It's actively maintained and contributions are always welcome.
* [Hyas][]. Hyas is a Hugo starter helping you build modern websites that are secure, fast, and SEO-ready — by default. It is Netlify-ready (functions, redirects, headers) and comes with [documentation](https://gethyas.com/) to easily make it your own.
[addkit]: https://github.com/gohugoio/hugo/edit/master/docs/content/en/tools/starter-kits.md [addkit]: https://github.com/gohugoio/hugo/edit/master/docs/content/en/tools/starter-kits.md
@ -41,3 +42,4 @@ The following starter kits are developed by active members of the Hugo community
[hugulp]: https://github.com/jbrodriguez/hugulp [hugulp]: https://github.com/jbrodriguez/hugulp
[Victor Hugo]: https://github.com/netlify/victor-hugo [Victor Hugo]: https://github.com/netlify/victor-hugo
[Atlas]: https://github.com/indigotree/atlas [Atlas]: https://github.com/indigotree/atlas
[Hyas]: https://github.com/h-enk/hyas

View file

@ -3,7 +3,7 @@ publish = "public"
command = "hugo --gc --minify" command = "hugo --gc --minify"
[context.production.environment] [context.production.environment]
HUGO_VERSION = "0.77.0" HUGO_VERSION = "0.78.2"
HUGO_ENV = "production" HUGO_ENV = "production"
HUGO_ENABLEGITINFO = "true" HUGO_ENABLEGITINFO = "true"
@ -11,20 +11,20 @@ HUGO_ENABLEGITINFO = "true"
command = "hugo --gc --minify --enableGitInfo" command = "hugo --gc --minify --enableGitInfo"
[context.split1.environment] [context.split1.environment]
HUGO_VERSION = "0.77.0" HUGO_VERSION = "0.78.2"
HUGO_ENV = "production" HUGO_ENV = "production"
[context.deploy-preview] [context.deploy-preview]
command = "hugo --gc --minify --buildFuture -b $DEPLOY_PRIME_URL" command = "hugo --gc --minify --buildFuture -b $DEPLOY_PRIME_URL"
[context.deploy-preview.environment] [context.deploy-preview.environment]
HUGO_VERSION = "0.77.0" HUGO_VERSION = "0.78.2"
[context.branch-deploy] [context.branch-deploy]
command = "hugo --gc --minify -b $DEPLOY_PRIME_URL" command = "hugo --gc --minify -b $DEPLOY_PRIME_URL"
[context.branch-deploy.environment] [context.branch-deploy.environment]
HUGO_VERSION = "0.77.0" HUGO_VERSION = "0.78.2"
[context.next.environment] [context.next.environment]
HUGO_ENABLEGITINFO = "true" HUGO_ENABLEGITINFO = "true"

Binary file not shown.

After

Width:  |  Height:  |  Size: 25 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 37 KiB

File diff suppressed because one or more lines are too long

Before

Width:  |  Height:  |  Size: 206 KiB

After

Width:  |  Height:  |  Size: 193 KiB