Rendering Images in Markdown Preview of Hugo Site

Hugo is an open-source static site generator written in Go that’s optimized for speed, ease of use, and flexibility. Hugo is designed for creating blogs, documentation sites, and other types of websites quickly and efficiently.

You’re using Hugo to host your blog or website. Because of Hugo’s file structure, your articles are located in /content/posts and your images are located in /static/images as shown in the following example:

my-hugo-site/
├── archetypes/
├── content/
|   └── posts/
├── resources/
├── static/
|   └── images/
├── themes/

Hugo renders the images in your articles correctly using ![alt text](/images/my-image.jpg). The links to the images are broken when you attempt to use the preview feature in any markdown editor. This problem is due to your markdown editor being unaware that image paths in Hugo are relative to the static directory. Hugo knows /images is under the static directory, while your markdown editor is looking for /images under the root of your Hugo site.

The most simplistic way to solve this problem without requiring any other configuration changes is to create a symbolic link so your images are available in both locations without having to maintain two copies.

A symbolic or soft link is a link or pointer to the original file or directory, whereas a hard link is a copy of the original file or directory.

Launch PowerShell elevated as an admin and navigate to the root of your Hugo site:

Set-Location -Path <root-of-hugo-site>

Create a symbolic link. Specify images as the value for the Path parameter. This is the name of the symbolic link. Specify the relative path to your images directory as the value for the Target parameter. Using a relative path allows the symbolic link to work cross-platform.

New-Item -ItemType SymbolicLink -Path images -Target .\static\images

You could also use the mklink command on Windows from an elevated instance of cmd.exe to create the symbolic link.

mklink /D images .\static\images

After creating the symbolic link, the images are displayed correctly when using the preview feature of your markdown editor:

Happy blogging!