Back to top

Image Links

This section will provides few alternatives for linking to images in Org files in a way that’s compatible with ox-hugo and Hugo.

For the sake of the below explanation, let’s have the HUGO_BASE_DIR (the directory containing the Hugo site’s config.toml file) be ~/hugo/. Then the Hugo static directory will be ~/hugo/static/.

References to files in the static directory #

Now if you have a file ~/hugo/static/images/foo.png, ox-hugo makes it convenient for you to reference that image by simply /images/foo.png.

Note that this is not the default behavior of other Org exporters.

But in the case of Hugo, as the referenced file will normally be in the Hugo static directory, ox-hugo allows the /images/foo.png style of short reference if that is a valid path under that Hugo site’s static directory.

See the below examples on how to reference images in different ways:

Inline image – Unhyperlinked #

Figure 1: Unhyperlinked image (don’t click it)

Figure 1: Unhyperlinked image (don’t click it) 

[[/images/org-mode-unicorn-logo-200px.png]]

Inline image – Also hyperlinked to an image #

Figure 2: Image hyperlinked to an image (click it!)

Figure 2: Image hyperlinked to an image (click it!) 

[[/images/org-mode-unicorn-logo-200px.png][file:/images/org-mode-unicorn-logo-50px.png]]

This style of link is normally used if you want to link a low resolution image to its higher resolution version.

NOTE 1
The file: prefix has to be used in the Description component of the Org link.
NOTE 2
The file: prefix can be used for the Link component of the Org link too — it doesn’t hurt.
NOTE 3
A space in the path in the Description component of the Org link has to be encoded to “%20”.

Click here to see org-mode-unicorn-logo-200px.png

[[/images/org-mode-unicorn-logo-200px.png][Click here to see org-mode-unicorn-logo-200px.png]]

This style of linking will work for references to non-image files in the static directory too.

References to files outside the static directory #

This is a unique feature of ox-hugo.

(i) If a reference is made to a file outside the Hugo static directory, and (ii) if it has one of the extensions listed in org-hugo-external-file-extensions-allowed-for-copying, then that file is copied by ox-hugo to the static directory.

Here is an example link:

[[~/some-dir/static/images/foo.png]]

Source path contains /static/ #

If you link to files outside of the Hugo static directory, just ensure that the path contains the string /static/ if you like to preserve the directory structure. Necessary directories are then created inside the static directory to preserve the structure.

Example translations between outside static directory paths to the copied location inside static:

Table 1: Where files get copied to if their path contains static/
File location outside static Copied-to location inside static Explanation
~/temp/static/images/foo.png <HUGO_BASE_DIR>/static/images/foo.png If the outside path has /static/ in it, the directory structure after that is preserved when copied.
~/temp/static/img/foo.png <HUGO_BASE_DIR>/static/img/foo.png (same as above)
~/temp/static/foo.png <HUGO_BASE_DIR>/static/foo.png (same as above)
~/temp/static/articles/zoo.pdf <HUGO_BASE_DIR>/static/articles/zoo.pdf (same as above)

See the Usage → Before you export section to learn how to set the HUGO_BASE_DIR.

Source path does not contain /static/ #

Here is an example link where the source path does not contain /static/:

[[~/some-dir/bar/foo.png]]

In this case, that file is copied directly to the org-hugo-default-static-subdirectory-for-externals sub-directory (ox-hugo/ by default) within the Hugo static directory. No directory structure generation happens in this case.

Table 2: Where files get copied to if their path does not contain static/
File location outside static Copied-to location inside static Explanation
~/temp/bar/baz/foo.png <HUGO_BASE_DIR>/static/ox-hugo/foo.png Here, as the outside path does not have /static/ in it, the file is copied to the ox-hugo/ dir in Hugo static/ dir.

Disable auto-copying #

This auto-copying behavior can be disabled completely by setting org-hugo-external-file-extensions-allowed-for-copying to nil.. but you might not want that if you keep your files outside the Hugo static directory.

Hiding figure caption numbers #

The “Figure <number>:” part of the figure captions can be hidden by adding this to the CSS:

.figure-number {
  display: none;
}

See Linking numbered elements.

Exported from ox-hugo-manual.org using Emacs 26.3 + Org mode 9.6.20 + ox-hugo and published using Hugo 0.101.0 + Onyx
Fork me on GitHub