2024 0829 Mount static/ to assets/static/

For Hugo sites, you should probably use module mounts to mount the static directory to assets/static. Doing so allows you to reference static files directly via their path like /file.txt, or using Hugo resources with resources.Get "static/file.txt".

I found this helpful for using the same font both as a web font and in og:image generation. (By the way, did you know that Hugo can generate social preview og:image files!? TODO: write another TIL about this.)

When referencing a font in CSS, it is much more convenient to keep that font in static/ than assets/, because CSS files cannot call resources.Get. (You can call resources.Get "font.woff2" in an HTML partial, and put template variables in the CSS, then use resources.ExecuteAsTemplate to force Hugo to apply those variables from the HTML partial, but this is not a very nice experience. You would much rather put your font in static/ and reference it in CSS as /font.woff2 and be done with it.)

On the other hand, if you want to use the same font with images.Text, which is required for og:image generation, you must use resources.Get to find it, which means it has to be in the assets folder, not static.

… Until recently, that is. With the advent of module mounts, you can now overly any part of your source onto any other part. And specifically, you can virtually mount static/ to assets/static/. Unless you already have an assets/static/ folder for some reason — which would be pretty weird — there are no downsides to this. Everything in static is already deployed to your site, and making it available inside assets/static just lets you use all the files there with resources.Get.

Note that mounts are per-module, and your site and each theme is a separate module. Therefore, your site and each theme must set this in its own config file. I don’t think it’s possible for one module to affect another one.

Requirements:

• A recent-ish Hugo. I’m not sure when exactly virtual mounts were introduced, but they haven’t always been there.
• A config file named hugo.toml/hugo.yaml/hugo.json. The docs actually say that it shouldn’t matter, but I found that the mounts didn’t work with a theme config file named theme.toml, and that they started working once I renamed that file to hugo.toml.

Here’s part of what mine looks like.

[module]

# Defaults
# I think defining these is required
[[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'

# Make all static files available as assets.
[[module.mounts]]
source = "static"
target = "assets/static"

After you set this up, you can make sure that it’s working in Hugo by running hugo config mounts. That will return output like this:

{
   "path": "micahrl",
   "version": "",
   "time": "0001-01-01T00:00:00Z",
   "owner": "me.micahrl.com",
   "dir": "/Users/mrled/mrldata/Repositories/me.micahrl.com/themes/micahrl/",
   "mounts": [
      {
         "source": "static",
         "target": "static"
      },
      {
         "source": "layouts",
         "target": "layouts"
      },
      {
         "source": "assets",
         "target": "assets"
      },
      {
         "source": "archetypes",
         "target": "archetypes"
      },
      {
         "source": "static",
         "target": "assets/static"
      }
   ]
}