Managing Images

Up until now, you’ve used placeholder images in your pages, but you’re going to want to place images in your blog posts, or screenshots of your projects. And you might even want an image on your home page. Hugo offers a few options for managing images: you can host images externally and link to them, you can place them in the static folder like you did with CSS files, or you can create a resource bundle and keep images with their associated content.

You already brought in images from an external site in Chapter 3, ​Adding Content Sections​. If your images are hosted elsewhere, you can use that same approach.

To link to images in the static folder of your theme or your site, use a standard <img> tag with a site-relative URL. This works in both your layouts and in your Markdown content.

Test this out by adding a local image to your site’s footer. In the companion files for this book, you’ll find an images directory. Copy the hugo-logo-wide.svg file from that directory to your site’s static directory. You could also place it in the static directory within your theme. Either way, you’ll access the file the same way, as the static directories are merged together.

With the file in place, open your theme’s footer partial at themes/basic/layouts/partials/footer.html and add the following code to include the image with a link to the official Hugo website:

Even though the image is located at /static/hugo-logo-wide.svg, you don’t specify the static part of the path to the file, as the contents of the static folder are copied to the root of the site. Using the relURL function ensures that the paths are generated relative to the page.

Save the file. When you load the page in your browser, the Hugo logo appears in the footer:

If you’re going to store more images in the static folder, you’ll probably want better organization. Create an images folder to store your images, and then include images in your image paths.

Images in the static folder are available in your content pages as well. When you’re working in Markdown documents, you include an image using Markdown’s image syntax like this:

However, if you’re going to include images in your Markdown content, Hugo has a better way, which will give you access to powerful functions to transform images: page bundles.

Using Page Bundles to Organize Content

Up until now, each piece of content you’ve created is a Markdown file with a name that somewhat resembles its title. But you can also create a page bundle, which is a collection of content files, including images, PDF files, or any other type of asset you want to keep close to your content. A page bundle is a folder inside of your content section, rather than an individual file.

To test this out, add a fourth blog post to your site. This post will contain a few images in addition to the text, and by using a page bundle, you’ll be able to keep those images in the same location as the text, making the content easier to organize.

Use the hugo new command to create the page bundle:

Notice that instead of calling the post my-vacation.md, you’re specifying my-vacation as part of the path, and specifying a file named index.md. Hugo creates the following structure:

This new my-vacation folder is where all of the assets associated with your post will go. Create a new images folder inside of this folder using your IDE or the following Terminal command:

In the companion files you downloaded for this book, you’ll find three photos in the images folder: badlands.jpg, rushmore.jpg, and bison.jpg. Copy all three of these photos to the content/posts/my-vacation/images folder.

Open portfolio/content/posts/my-vacation/index.md and add the following content:

Now, include one of the images in your document. But instead of using a regular <img> tag, you’ll use a <figure> tag, which lets you associate an image with a caption. Here’s what that might look like, but don’t add this code to your page, as Hugo doesn’t support raw HTML code in Markdown documents:

Instead of typing that code, you’ll use a shortcode, which is a way for you to extend Hugo’s Markdown capabilities. Shortcodes are functions powered by Go’s templating mechanism that you can use in your Markdown. You call them and pass them options, and they generate output. Hugo has built-in shortcodes for adding code snippets, YouTube videos, and of course, figures. Add this code to your file:

This generates the <figure> element, the caption, and the alternative text just as if you’d entered them manually.

The image you’ve added is quite large, though. You’ll tackle that properly in the next section. For now, add a CSS rule for images inside of figures that resizes the images appropriately for different devices:

With this style rule in place, the image will stay within the container:

It will also scale down on smaller screens:

Hugo’s built-in shortcodes are great for incorporating assets into your posts, but you can write your own shortcodes to have even more control over your assets.

Using a Shortcode to Process Images

When you’re working with images for the web, you often need to resize them so they’re smaller, or perform other processing tasks. Hugo has built-in methods for altering images, provided they’re defined as page resources. Anything in your page bundle is automatically a page resource, so that means Hugo can manipulate the images you’ve copied into the my-vacation folder.

In a nutshell, Hugo makes it possible to do something like this with an image:

When Hugo builds your site, it creates a new resized image, rather than the original high-resolution one you supplied. There are many other image processing functions^[35] for resampling, cropping, and fitting images into your pages. In addition, there are other image functions^[36] that let you control brightness, gamma, contrast, and color.

Unfortunately, you can’t take advantage of these features directly in your content pages, as their functionality is only available within Hugo’s layouts.

To get around that, you can create your own shortcodes. Shortcodes let you do things in your Markdown content that you’d normally only be able to do in your layouts. With a shortcode, you can use conditional logic, page variables, and of course, process images. To create your own shortcode, create a shortcodes directory in the layouts directory of your theme or site, create an HTML file with the name of the shortcode, and write the code that you want to execute when you invoke the shortcode in your Markdown.

Let’s create a shortcode called postimage that will accept an image and some alternative text. It’ll generate a <figure> element with a caption. It’ll automatically resize the image, but also create a link to the original image, so your readers can access the larger image by clicking the smaller version.

First, create a shortcodes directory in the layouts dfirectory of your theme. The following terminal command can do that for you:

Then, create the file themes/basic/layouts/shortcodes/postimage.html and add the following code to get a reference to an image and create a smaller version of the image:

The (.Get 0) piece gives you access to the first argument, which will be the image’s filename. Once you have the image reference, you create the smaller version using the .Resize function. Passing the width only will tell Hugo to keep the aspect ratio of the image so that you won’t end up with a distorted image or have to determine the aspect ratio yourself.

Now, add this code to create the figure element with the hyperlink, image tag, and caption:

The .Get 1 piece fetches the second argument passed to the shortcode, which is the text for the caption and the image’s alternative text. The {{ with $smallImage }} block switches the context so that you can call the Width and Height functions without having to prefix them each with $smallImage. It’s not necessary, but it saves keystrokes. Since the context has changed, you must prefix .Get 1 with a dollar sign ($), so you can reach outside of the current scope.

Save the file and open the blog post again (content/my-vacation/index.md). Replace the existing figure with the shortcode you just created:

When you reload the page, you won’t see any differences at first, but you can now click each image to see the full-sized version. Hugo performed the smaller version of the image when it generated the page. If you view the page’s source, you’ll see that it’s now referencing both the small and large images:

Add the badlands.jpg and bison.jpg images the same way:

Processing images with Hugo can make the build process take considerably longer. To keep things running quickly, Hugo caches the converted images, saving them to the resources folder in the root of your site so that it doesn’t have to build them all of the time. However, if you change your settings or sizes, you’ll end up with extra files in the resources directory that you no longer need. Use the hugo -gc command to build the site and clean up cached files.

Hugo does a great job of helping you manage your styles and images. Now let’s explore how to manage JavaScript files.