Notes

Hugo assets directory

If you want any file to be processed by Hugo Pipes, for example compiling Sass stylesheets or converting TypeScript files to JavaScript, it needs to be in the assets/ directory.

Edit on GitHub

Hugo
2 minutes
hugo pipes asset management
  • If you want any file to be processed by Hugo Pipes, for example compiling Sass stylesheets or converting TypeScript files to JavaScript, it needs to be in the assets directory, which by default is assets/, but can be configured in config.toml
  • Only the files in assetDir that are processed will be included in the final build
  • Unlike staticDir which can take an array of values for multiple static directories, there can only be one assetDir
1staticDir = ['assets', 'static']
2assetDir = 'assets/'

  • If you are creating or using a custom theme, the files in the themes asset directory themes/foo/assets will NOT be processed by Hugo pipes by default.

  • You can however mount multiple asset directories. Mounting a new directory means the default directory is ignored, so be sure to explicitly add it again if you want the default directory to work

1# config.toml
2[module]
3  [[module.mounts]]
4    source = 'assets'
5    target = 'assets'
6  [[module.mounts]]
7    source = 'themes/foo/assets'
8    target = 'assets'

Now, if you link to a resource with path css/custom.scss, it will look in both css/custom.scss and themes/amnastic/css/custom.scss

1{{ $scss_options := (dict "transpiler" "libsass" "outputStyle" "compressed") }}
2{{ $scss_file := resources.Get "css/custom.scss" }}
3{{ $customStyles := $scss_file | resources.ToCSS $scss_options | minify }}
4
5<link rel="stylesheet" href="{{ $customStyles.RelPermalink }}">

After the resources are processed, Hugo publishes them to the publishDir, which by default is public/. The link would look like this when compiled

1<link rel="stylesheet" href="/css/custom.min.css">

assetDir vs staticDir

If a file needs to be loaded as a resource and processed by Hugo Pipes, it needs to be in assetDir location(s)

  • Example files: styles.scss, main.ts, images etc.
  • Example processes: Minification, compilation, concatenation, fingerprinting and so on..
  • Default location: assets/ in project base
  • URLs: Since resources are published to the publishDir after they have been processed, you can reference them with their relative URL which would be just the file name. For example: /styles.css instead of assets/styles.css

If i file needs to be in the publishDir when the site is built, and does not need any processing or compiling, it needs to be in the staticDir

  • Example files: favicon.ico, robots.txt, manifest.json etc.
  • Default location: static/ in project base
  • URLs: All files in the static/ directory can be directly referenced by their relative URL. For example, the file at location static/manifest.json can be referenced anywhere in the site with the relative URL /manifest.json. Same as assetDir, no need to mention staticDir in the final URL
Browse all topics