--- /dev/null
- : `inline` or `block`. If `inline` (default), surrounding ´<p></p>` on short snippets will be trimmed.
+---
+title: .RenderString
+description: "Renders markup to HTML."
+godocref:
+date: 2019-12-18
+categories: [functions]
+menu:
+ docs:
+ parent: "functions"
+keywords: [markdown,goldmark,render]
+signature: [".RenderString MARKUP"]
+---
+
+{{< new-in "0.62.0" >}}
+
+`.RenderString` is a method on `Page` that renders some markup to HTML using the content renderer defined for that page (if not set in the options).
+
+*Note* that this method does not parse and render shortcodes.
+
+The method takes an optional map argument with these options:
+
+display ("inline")
++: `inline` or `block`. If `inline` (default), surrounding `<p></p>` on short snippets will be trimmed.
+
+markup (defaults to the Page's markup)
+: See identifiers in [List of content formats](/content-management/formats/#list-of-content-formats).
+
+Some examples:
+
+```go-html-template
+{{ $optBlock := dict "display" "block" }}
+{{ $optOrg := dict "markup" "org" }}
+{{ "**Bold Markdown**" | $p.RenderString }}
+{{ "**Bold Block Markdown**" | $p.RenderString $optBlock }}
+{{ "/italic org mode/" | $p.RenderString $optOrg }}
+```
+
+
+**Note** that this method is more powerful than the similar [markdownify](/functions/markdownify/) function as it also supports [Render Hooks](/getting-started/configuration-markup/#markdown-render-hooks) and it has options to render other markup formats.
--- /dev/null
--- /dev/null
++---
++title: site
++linktitle: site
++description: The `site` function provides global access the same data as `.Site` page method
++godocref:
++date: 2021-02-11
++publishdate: 2021-02-11
++lastmod: 2021-02-11
++keywords: []
++categories: [functions]
++menu:
++ docs:
++ parent: "functions"
++toc:
++signature: ["site"]
++workson: []
++hugoversion:
++relatedfuncs: ["hugo"]
++deprecated: false
++draft: false
++aliases: []
++---
++
++`site` is a global function which returns the same data as the `.Site` page method. See: [Site Variables]({{< relref "/variables/site" >}}).
++
++
--- /dev/null
- description: Deploy Hugo as a GitHub Pages project or personal/organizational site and automate the whole process with a simple shell script.
+---
+title: Host on GitHub
+linktitle: Host on GitHub
- lastmod: 2018-09-22
++description: Deploy Hugo as a GitHub Pages project or personal/organizational site and automate the whole process with Github Action Workflow
+date: 2014-03-21
+publishdate: 2014-03-21
- draft: false
+categories: [hosting and deployment]
+keywords: [github,git,deployment,hosting]
+authors: [Spencer Lyon, Gunnar Morling]
+menu:
+ docs:
+ parent: "hosting-and-deployment"
+ weight: 30
+weight: 30
+sections_weight: 30
- GitHub provides free and fast static hosting over SSL for personal, organization, or project pages directly from a GitHub repository via its [GitHub Pages service][].
+toc: true
+aliases: [/tutorials/github-pages-blog/]
+---
+
- There are 2 types of GitHub Pages:
++GitHub provides free and fast static hosting over SSL for personal, organization, or project pages directly from a GitHub repository via its [GitHub Pages service][] and automate development workflows and build with [GitHub Actions].
+
+## Assumptions
+
+1. You have Git 2.8 or greater [installed on your machine][installgit].
+2. You have a GitHub account. [Signing up][ghsignup] for GitHub is free.
+3. You have a ready-to-publish Hugo website or have at least completed the [Quick Start][].
+
+## Types of GitHub Pages
+
- To create a User/Organization Pages site, follow the single method in the *GitHub User and Organization Pages* section below.
-
- To create a Project Pages site, choose a method from the *Project Pages* section below.
-
++There are two types of GitHub Pages:
+
+- User/Organization Pages (`https://<USERNAME|ORGANIZATION>.github.io/`)
+- Project Pages (`https://<USERNAME|ORGANIZATION>.github.io/<PROJECT>/`)
+
+Please refer to the [GitHub Pages documentation][ghorgs] to decide which type of site you would like to create as it will determine which of the below methods to use.
+
- ### Step-by-step Instructions
-
- 1. Create a `<YOUR-PROJECT>` (e.g. `blog`) repository on GitHub. This repository will contain Hugo's content and other source files.
- 2. Create a `<USERNAME>.github.io` GitHub repository. This is the repository that will contain the fully rendered version of your Hugo website.
- 3. `git clone <YOUR-PROJECT-URL> && cd <YOUR-PROJECT>`
- 4. Paste your existing Hugo project into the new local `<YOUR-PROJECT>` repository. Make sure your website works locally (`hugo server` or `hugo server -t <YOURTHEME>`) and open your browser to <http://localhost:1313>.
- 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 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
-
- You're almost done. In order to automate next steps create a `deploy.sh` script. You can also make it executable with `chmod +x deploy.sh`.
-
- The following are the contents of the `deploy.sh` script:
-
- ```
- #!/bin/sh
-
- # If a command fails then the deploy stops
- set -e
-
- printf "\033[0;32mDeploying updates to GitHub...\033[0m\n"
-
- # Build the project.
- hugo # if using a theme, replace with `hugo -t <YOURTHEME>`
-
- # Go To Public folder
- cd public
-
- # Add changes to git.
- git add .
-
- # Commit changes.
- msg="rebuilding site $(date)"
- if [ -n "$*" ]; then
- msg="$*"
- fi
- git commit -m "$msg"
-
- # Push source and build repos.
- git push origin main
- ```
-
-
- You can then run `./deploy.sh "Your optional commit message"` to send changes to `<USERNAME>.github.io`. Note that you likely will want to commit changes to your `<YOUR-PROJECT>` repository as well.
-
- That's it! Your personal page should be up and running at `https://<USERNAME>.github.io` within a couple minutes.
-
- ## GitHub Project Pages
-
- {{% note %}}
- 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 `main` branch
-
- [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
- ```
-
- 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** → **GitHub Pages**
- 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 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 `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:
+## GitHub User or Organization Pages
+
+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 `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.
+
- * 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.
++## Build Hugo With GitHub Action
+
- #### Preparations for `gh-pages` Branch
++GitHub execute your software development workflows. Everytime you push your code on the Github repository, Github Action will build the site automatically.
+
- These steps only need to be done once. Replace `upstream` with the name of your remote; e.g., `origin`:
++Create a file in `.github/workflows/gh-pages.yml` containing the following content (based on https://github.com/marketplace/actions/hugo-setup ):
+
- ##### Add the `public` Folder
++```yml
++name: github pages
+
- First, add the `public` folder to your `.gitignore` file at the project root so that the directory is ignored on the main branch:
++on:
++ push:
++ branches:
++ - main # Set a branch to deploy
+
- ```
- echo "public" >> .gitignore
- ```
-
- ##### Initialize Your `gh-pages` Branch
++jobs:
++ deploy:
++ runs-on: ubuntu-18.04
++ steps:
++ - uses: actions/checkout@v2
++ with:
++ submodules: true # Fetch Hugo themes (true OR recursive)
++ fetch-depth: 0 # Fetch all history for .GitInfo and .Lastmod
+
- You can now initialize your `gh-pages` branch as an empty [orphan branch][]:
++ - name: Setup Hugo
++ uses: peaceiris/actions-hugo@v2
++ with:
++ hugo-version: 'latest'
++ # extended: true
+
- git checkout --orphan gh-pages
- git reset --hard
- git commit --allow-empty -m "Initializing gh-pages branch"
- git push upstream gh-pages
- git checkout main
- ```
-
- #### Build and Deployment
-
- Now check out the `gh-pages` branch into your `public` folder using git's [worktree feature][]. Essentially, the worktree allows you to have multiple branches of the same local repository to be checked out in different directories:
-
- ```
- rm -rf public
- git worktree add -B gh-pages public upstream/gh-pages
- ```
-
- Regenerate the site using the `hugo` command and commit the generated files on the `gh-pages` branch:
-
- {{< code file="commit-gh-pages-files.sh">}}
- hugo
- cd public && git add --all && git commit -m "Publishing to gh-pages" && cd ..
- {{< /code >}}
-
- If the changes in your local `gh-pages` branch look alright, push them to the remote repo:
-
- ```
- git push upstream gh-pages
- ```
-
- ##### Set `gh-pages` as Your Publish Branch
-
- In order to use your `gh-pages` branch as your publishing branch, you'll need to configure the repository within the GitHub UI. This will likely happen automatically once GitHub realizes you've created this branch. You can also set the branch manually from within your GitHub project:
-
- 1. Go to **Settings** → **GitHub Pages**
- 2. From **Source**, select "gh-pages branch" and then **Save**. If the option isn't enabled, you likely have not created the branch yet OR you have not pushed the branch from your local machine to the hosted repository on GitHub.
-
- After a short while, you'll see the updated contents on your GitHub Pages site.
-
- #### Put it Into a Script
-
- To automate these steps, you can create a script with the following contents:
-
- {{< code file="publish_to_ghpages.sh" >}}
- #!/bin/sh
-
- if [ "`git status -s`" ]
- then
- echo "The working directory is dirty. Please commit any pending changes."
- exit 1;
- fi
-
- echo "Deleting old publication"
- rm -rf public
- mkdir public
- git worktree prune
- rm -rf .git/worktrees/public/
-
- echo "Checking out gh-pages branch into public"
- git worktree add -B gh-pages public upstream/gh-pages
-
- echo "Removing existing files"
- rm -rf public/*
-
- echo "Generating site"
- hugo
-
- echo "Updating gh-pages branch"
- cd public && git add --all && git commit -m "Publishing to gh-pages (publish.sh)"
-
- #echo "Pushing to github"
- #git push --all
- {{< /code >}}
-
- 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 `main` Branch
-
- 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 `main` as your publishable branch from within the GitHub UI:
++ - name: Build
++ run: hugo --minify
+
++ - name: Deploy
++ uses: peaceiris/actions-gh-pages@v3
++ with:
++ github_token: ${{ secrets.GITHUB_TOKEN }}
++ publish_dir: ./public
+```
- 1. Go to **Settings** → **GitHub Pages**
- 2. From **Source**, select "main branch" and then **Save**.
+
- If you'd like to use a custom domain for your GitHub Pages site, create a file `static/CNAME`. Your custom domain name should be the only contents inside `CNAME`. Since it's inside `static`, the published site will contain the CNAME file at the root of the published site, which is a requirements of GitHub Pages.
++For more advance settings https://github.com/marketplace/actions/hugo-setup
+
+## Use a Custom Domain
+
++If you'd like to use a custom domain for your GitHub Pages site, create a file `static/CNAME`. Your custom domain name should be the only contents inside `CNAME`. Since it's inside `static`, the published site will contain the CNAME file at the root of the published site, which is a requirement of GitHub Pages.
+
+Refer to the [official documentation for custom domains][domains] for further information.
+
+[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/
+[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/#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
++[GitHub Actions]: https://docs.github.com/en/actions
--- /dev/null
+---
+title: Configure Modules
+linktitle: Configure Modules
+description: This page describes the configuration options for a module.
+date: 2019-07-24
+categories: [hugo modules]
+keywords: [themes, source, organization, directories]
+menu:
+ docs:
+ parent: "modules"
+ weight: 10
+weight: 10
+sections_weight: 10
+toc: true
+---
+
+## Module Config: Top level
+
+{{< code-toggle file="config">}}
+[module]
+noVendor = ""
+proxy = "direct"
+noProxy = "none"
+private = "*.*"
+replacements = ""
+{{< /code-toggle >}}
+
+
+noVendor {{< new-in "0.75.0" >}}
+: A optional Glob pattern matching module paths to skip when vendoring, e.g. "github.com/**"
+
+vendorClosest {{< new-in "0.81.0" >}}
+: When enabled, we will pick the vendored module closest to the module using it. The default behaviour is to pick the first. Note that there can still be only one dependency of a given module path, so once it is in use it cannot be redefined.
+
+proxy
+: Defines the proxy server to use to download remote modules. Default is `direct`, which means "git clone" and similar.
+
+noProxy
+: Comma separated glob list matching paths that should not use the proxy configured above.
+
+private
+: Comma separated glob list matching paths that should be treated as private.
+
+replacements {{< new-in "0.77.0" >}}
+: A comma separated (or a slice) list of module path to directory replacement mapping, e.g. `"github.com/bep/myprettytheme -> ../..,github.com/bep/shortcodes -> /some/path`. This is mostly useful for temporary locally development of a module, and then it makes sense to set it as an OS environment variable, e.g: `env HUGO_MODULE_REPLACEMENTS="github.com/bep/myprettytheme -> ../.."`. Any relative path is relate to [themesDir](https://gohugo.io/getting-started/configuration/#all-configuration-settings), and absolute paths are allowed.
+
+Note that the above terms maps directly to their counterparts in Go Modules. Some of these setting may be natural to set as OS environment variables. To set the proxy server to use, as an example:
+
+```
+env HUGO_MODULE_PROXY=https://proxy.example.org hugo
+```
+
+{{< gomodules-info >}}
+
+## Module Config: hugoVersion
+
+If your module requires a particular version of Hugo to work, you can indicate that in the `module` section and the user will be warned if using a too old/new version.
+
+{{< code-toggle file="config">}}
+[module]
+[module.hugoVersion]
+ min = ""
+ max = ""
+ extended = false
+
+{{< /code-toggle >}}
+
+Any of the above can be omitted.
+
+min
+: The minimum Hugo version supported, e.g. `0.55.0`
+
+max
+: The maximum Hugo version supported, e.g. `0.55.0`
+
+extended
+: Whether the extended version of Hugo is required.
+
+## Module Config: imports
+
+{{< code-toggle file="config">}}
+[module]
+[[module.imports]]
+ path = "github.com/gohugoio/hugoTestModules1_linux/modh1_2_1v"
+ ignoreConfig = false
++ ignoreImports = false
+ disable = false
+[[module.imports]]
+ path = "my-shortcodes"
+{{< /code-toggle >}}
+
+path
+: Can be either a valid Go Module module path, e.g. `github.com/gohugoio/myShortcodes`, or the directory name for the module as stored in your themes folder.
+
+ignoreConfig
+: If enabled, any module configuration file, e.g. `config.toml`, will not be loaded. Note that this will also stop the loading of any transitive module dependencies.
+
++ignoreImports {{< new-in "0.80.0" >}}
++: If enabled, module imports will not be followed.
++
+disable
+: Set to `true` to disable the module while keeping any version info in the `go.*` files.
+
+{{< gomodules-info >}}
+
+
+## Module Config: mounts
+
+{{% note %}}
+When the `mounts` config was introduced in Hugo 0.56.0, we were careful to preserve the existing `staticDir` and similar configuration to make sure all existing sites just continued to work. But you should not have both: if you add a `mounts` section you should remove the old `staticDir` etc. settings.
+{{% /note %}}
+
+{{% warning %}}
+When you add a mount, the default mount for the concerned target root is ignored: be sure to explicitly add it.
+{{% /warning %}}
+
+**Default mounts**
+{{< code-toggle file="config">}}
+[module]
+[[module.mounts]]
+ source="content"
+ target="content"
+[[module.mounts]]
+ source="static"
+ target="static"
+[[module.mounts]]
+ source="layouts"
+ target="layouts"
+[[module.mounts]]
+ source="data"
+ target="data"
+[[module.mounts]]
+ source="assets"
+ target="assets"
+[[module.mounts]]
+ source="i18n"
+ target="i18n"
+[[module.mounts]]
+ source="archetypes"
+ target="archetypes"
+{{< /code-toggle >}}
+
+source
+: The source directory of the mount. For the main project, this can be either project-relative or absolute and even a symbolic link. For other modules it must be project-relative.
+
+target
+: Where it should be mounted into Hugo's virtual filesystem. It must start with one of Hugo's component folders: `static`, `content`, `layouts`, `data`, `assets`, `i18n`, or `archetypes`. E.g. `content/blog`.
+
+lang
+: The language code, e.g. "en". Only relevant for `content` mounts, and `static` mounts when in multihost mode.
+
--- /dev/null
- Wil resolve to `hello3.{js,ts,tsx,jsx}` inside `assets/my/module`.
+---
+title: JavaScript Building
+description: Hugo Pipes can process JavaScript files with [ESBuild](https://github.com/evanw/esbuild).
+date: 2020-07-20
+publishdate: 2020-07-20
+lastmod: 2020-07-20
+categories: [asset management]
+keywords: []
+menu:
+ docs:
+ parent: "pipes"
+ weight: 45
+weight: 45
+sections_weight: 45
+draft: false
+---
+
+Any JavaScript resource file can be transpiled and "tree shaken" using `js.Build` which takes for argument either a string for the filepath or a dict of options listed below.
+
+### Options
+
+targetPath [string]
+: 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.
+
+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]
+: 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
+
+inject [slice] {{< new-in "0.81.0" >}}
+: This option allows you to automatically replace a global variable with an import from another file. The path names must be relative to `assets`. See https://esbuild.github.io/api/#inject
+
+shims {{< new-in "0.81.0" >}}
+: This option allows swapping out a component with another. A common use case is to load dependencies like React from a CDN (with _shims_) when in production, but running with the full bundled `node_modules` dependency during development:
+
+```
+{{ $shims := dict "react" "js/shims/react.js" "react-dom" "js/shims/react-dom.js" }}
+{{ $js = $js | js.Build dict "shims" $shims }}
+```
+
+The _shim_ files may look like these:
+
+```js
+// js/shims/react.js
+module.exports = window.React;
+```
+
+```js
+// js/shims/react-dom.js
+module.exports = window.ReactDOM;
+```
+
+
+With the above, these imports should work in both scenarios:
+
+```js
+import * as React from 'react'
+import * as ReactDOM from 'react-dom';
+```
+
+target [string]
+: The language target.
+ One of: `es5`, `es2015`, `es2016`, `es2017`, `es2018`, `es2019`, `es2020` or `esnext`.
+ Default is `esnext`.
+
+externals [slice]
+: External dependencies. Use this to trim dependencies you know will never be executed. See https://esbuild.github.io/api/#external
+
+
+defines [map]
+: Allow to define a set of string replacement to be performed when building. Should be a map where each key is to be replaced by its value.
+
+```go-html-template
+{{ $defines := dict "process.env.NODE_ENV" `"development"` }}
+```
+
+format [string] {{< new-in "0.74.3" >}}
+: The output format.
+ One of: `iife`, `cjs`, `esm`.
+ 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';
+```
+
++Will 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.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).
+
+
+
+### 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
+
+```go-html-template
+{{ $built := resources.Get "js/index.js" | js.Build "main.js" }}
+```
+
+Or with options:
+
+```go-html-template
+{{ $externals := slice "react" "react-dom" }}
+{{ $defines := dict "process.env.NODE_ENV" `"development"` }}
+
+{{ $opts := dict "targetPath" "main.js" "externals" $externals "defines" $defines }}
+{{ $built := resources.Get "scripts/main.js" | js.Build $opts }}
+<script type="text/javascript" src="{{ $built.RelPermalink }}" defer></script>
+```
+
+
--- /dev/null
- This template respects the version 1.0 of the [Sitemap Protocol](https://www.sitemaps.org/protocol.html).
+---
+title: Sitemap Template
+# linktitle: Sitemap
+description: Hugo ships with a built-in template file observing the v0.9 of the Sitemap Protocol, but you can override this template if needed.
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-01
+categories: [templates]
+keywords: [sitemap, xml, templates]
+menu:
+ docs:
+ parent: "templates"
+ weight: 160
+weight: 160
+sections_weight: 160
+draft: false
+aliases: [/layout/sitemap/,/templates/sitemap/]
+toc: false
+---
+
+A single Sitemap template is used to generate the `sitemap.xml` file.
+Hugo automatically comes with this template file. *No work is needed on
+the users' part unless they want to customize `sitemap.xml`.*
+
+A sitemap is a `Page` and therefore has all the [page variables][pagevars] available to use in this template along with Sitemap-specific ones:
+
+`.Sitemap.ChangeFreq`
+: The page change frequency
+
+`.Sitemap.Priority`
+: The priority of the page
+
+`.Sitemap.Filename`
+: The sitemap filename
+
+If provided, Hugo will use `/layouts/sitemap.xml` instead of the internal `sitemap.xml` template that ships with Hugo.
+
+## Sitemap Templates
+
+Hugo has built-on Sitemap templates, but you can provide your own if needed, in either `layouts/sitemap.xml` or `layouts/_default/sitemap.xml`.
+
+For multilingual sites, we also create a Sitemap index. You can provide a custom layout for that in either `layouts/sitemapindex.xml` or `layouts/_default/sitemapindex.xml`.
+
+## Hugo’s sitemap.xml
+
++This template respects the version 0.9 of the [Sitemap Protocol](https://www.sitemaps.org/protocol.html).
+
+```xml
+{{ printf "<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"yes\" ?>" | safeHTML }}
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
+ xmlns:xhtml="http://www.w3.org/1999/xhtml">
+ {{ range .Data.Pages }}
+ <url>
+ <loc>{{ .Permalink }}</loc>{{ if not .Lastmod.IsZero }}
+ <lastmod>{{ safeHTML ( .Lastmod.Format "2006-01-02T15:04:05-07:00" ) }}</lastmod>{{ end }}{{ with .Sitemap.ChangeFreq }}
+ <changefreq>{{ . }}</changefreq>{{ end }}{{ if ge .Sitemap.Priority 0.0 }}
+ <priority>{{ .Sitemap.Priority }}</priority>{{ end }}{{ if .IsTranslated }}{{ range .Translations }}
+ <xhtml:link
+ rel="alternate"
+ hreflang="{{ .Lang }}"
+ href="{{ .Permalink }}"
+ />{{ end }}
+ <xhtml:link
+ rel="alternate"
+ hreflang="{{ .Lang }}"
+ href="{{ .Permalink }}"
+ />{{ end }}
+ </url>
+ {{ end }}
+</urlset>
+```
+
+## Hugo's sitemapindex.xml
+
+This is used to create a Sitemap index in multilingual mode:
+
+```xml
+{{ printf "<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"yes\" ?>" | safeHTML }}
+<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+ {{ range . }}
+ <sitemap>
+ <loc>{{ .SitemapAbsURL }}</loc>
+ {{ if not .LastChange.IsZero }}
+ <lastmod>{{ .LastChange.Format "2006-01-02T15:04:05-07:00" | safeHTML }}</lastmod>
+ {{ end }}
+ </sitemap>
+ {{ end }}
+</sitemapindex>
+```
+
+## Configure `sitemap.xml`
+
+Defaults for `<changefreq>`, `<priority>` and `filename` values can be set in the site's config file, e.g.:
+
+{{< code-toggle file="config" >}}
+[sitemap]
+ changefreq = "monthly"
+ priority = 0.5
+ filename = "sitemap.xml"
+{{</ code-toggle >}}
+
+The same fields can be specified in an individual content file's front matter in order to override the value assigned to that piece of content at render time.
+
+
+
+[pagevars]: /variables/page/
--- /dev/null
- : the [taxonomies](/taxonomies/usage/) for the entire site. Replaces the now-obsolete `.Site.Indexes` since v0.11. Also see section [Taxonomies elsewhere](#taxonomies-elsewhere).
+---
+title: Site Variables
+linktitle: Site Variables
+description: Many, but not all, site-wide variables are defined in your site's configuration. However, Hugo provides a number of built-in variables for convenient access to global values in your templates.
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-01
+categories: [variables and params]
+keywords: [global,site]
+draft: false
+menu:
+ docs:
+ parent: "variables"
+ weight: 10
+weight: 10
+sections_weight: 10
+aliases: [/variables/site-variables/]
+toc: true
+---
+
+The following is a list of site-level (aka "global") variables. Many of these variables are defined in your site's [configuration file][config], whereas others are built into Hugo's core for convenient usage in your templates.
+
+## Get the Site object from a partial
+
+All the methods below, e.g. `.Site.RegularPages` can also be reached via the global `site` function, e.g. `site.RegularPages`, which can be handy in partials where the `Page` object isn't easily available. {{< new-in "0.53" >}}.
+
+## Site Variables List
+
+.Site.AllPages
+: array of all pages, regardless of their translation.
+
+.Site.Author
+: a map of the authors as defined in the site configuration.
+
+.Site.BaseURL
+: the base URL for the site as defined in the site configuration.
+
+.Site.BuildDrafts
+: a boolean (default: `false`) to indicate whether to build drafts as defined in the site configuration.
+
+.Site.Copyright
+: a string representing the copyright of your website as defined in the site configuration.
+
+.Site.Data
+: custom data, see [Data Templates](/templates/data-templates/).
+
+.Site.DisqusShortname
+: a string representing the shortname of the Disqus shortcode as defined in the site configuration.
+
+.Site.GoogleAnalytics
+: a string representing your tracking code for Google Analytics as defined in the site configuration.
+
+.Site.Home
+: reference to the homepage's [page object](https://gohugo.io/variables/page/)
+
+.Site.IsMultiLingual
+: whether there are more than one language in this site. See [Multilingual](/content-management/multilingual/) for more information.
+
+.Site.IsServer
+: a boolean to indicate if the site is being served with Hugo's built-in server. See [`hugo server`](/commands/hugo_server/) for more information.
+
+.Site.Language.Lang
+: the language code of the current locale (e.g., `en`).
+
+.Site.Language.LanguageName
+: the full language name (e.g. `English`).
+
+.Site.Language.Weight
+: the weight that defines the order in the `.Site.Languages` list.
+
+.Site.Language
+: indicates the language currently being used to render the website. This object's attributes are set in site configurations' language definition.
+
+.Site.LanguageCode
+: a string representing the language as defined in the site configuration. This is mostly used to populate the RSS feeds with the right language code.
+
+.Site.LanguagePrefix
+: this can be used to prefix URLs to point to the correct language. It will even work when only one defined language. See also the functions [absLangURL](/functions/abslangurl/) and [relLangURL](/functions/rellangurl).
+
+.Site.Languages
+: an ordered list (ordered by defined weight) of languages.
+
+.Site.LastChange
+: a string representing the date/time of the most recent change to your site. This string is based on the [`date` variable in the front matter](/content-management/front-matter) of your content pages.
+
+.Site.Menus
+: all of the menus in the site.
+
+.Site.Pages
+: array of all content ordered by Date with the newest first. This array contains only the pages in the current language. See [`.Site.Pages`](#site-pages).
+
+.Site.RegularPages
+: a shortcut to the *regular* page collection. `.Site.RegularPages` is equivalent to `where .Site.Pages "Kind" "page"`. See [`.Site.Pages`](#site-pages).
+
+.Site.Sections
+: top-level directories of the site.
+
+.Site.Taxonomies
++: the [taxonomies](/taxonomies/usage/) for the entire site. Also see section [Taxonomies elsewhere](#taxonomies-elsewhere).
+
+.Site.Title
+: a string representing the title of the site.
+
+## The `.Site.Params` Variable
+
+`.Site.Params` is a container holding the values from the `params` section of your site configuration.
+
+### Example: `.Site.Params`
+
+The following `config.[yaml|toml|json]` defines a site-wide param for `description`:
+
+{{< code-toggle file="config" >}}
+baseURL = "https://yoursite.example.com/"
+
+[params]
+ description = "Tesla's Awesome Hugo Site"
+ author = "Nikola Tesla"
+{{</ code-toggle >}}
+
+You can use `.Site.Params` in a [partial template](/templates/partials/) to call the default site description:
+
+{{< code file="layouts/partials/head.html" >}}
+<meta name="description" content="{{if .IsHome}}{{ $.Site.Params.description }}{{else}}{{.Description}}{{end}}" />
+{{< /code >}}
+
+## The `.Site.Pages` Variable {#site-pages}
+
+### `.Site.Pages` compared to `.Pages`
+
+{{< readfile file="/content/en/readfiles/pages-vs-site-pages.md" markdown="true" >}}
+
+
+
+
+[config]: /getting-started/configuration/
projects / brevno-suite / hugo / commitdiff