Images in Content

Conventionally any static content for a Hugo site, like images, PDF files, and other attachments are put in the site static/ directory. Files in that directory are served at the site root when the Hugo publishes that site. So all the content in there can be accessed using the root prefix /. So a static/foo.png file can be accessed at /foo.png.

More detail for this conventional approach can be found in the documentation for referencing files in static directory.

But.. what about putting images along with the content? #

OK, so with that short intro out of the way, ox-hugo supports putting the attachment files in the same directory as the source Org files!

In the below example, the left hand side shows the Org content and attachment file organization that the user would need to do manually. And the right hand side shows the structure that ox-hugo will generate in the content/ and static/ (the conventional way discussed above) directories.

├── images-in-content/
│  ├──
│  │    * Post 1 (Org subtree)   →  ./content/images-in-content/
│  │    * Post 2 (Org subtree)   →  ./content/images-in-content/
│  ├── gnu.png                   →  ./static/ox-hugo/gnu.png
│  └── org.png                   →  ./static/ox-hugo/org.png
├── post3/
│  ├──                 →  ./content/images-in-content/
│  └── gnu-copy.png              →  ./static/ox-hugo/gnu-copy.png
└── post4/
   ├──                 →  ./content/images-in-content/
   └── org-copy.png              →  ./static/ox-hugo/org-copy.png

Have a look at the content-org/images-in-content/ file for an example of how to reference same-directory files (gnu.png and org.png in this example) in an Org file (Hint: Just as you would do in a normal Org file).

The benefit of this same-directory-attachment approach is that you don’t need to use any directory prefix to reference those files (example: [[file:gnu.png]]). When ox-hugo exports those posts though, the images are auto-copied to the static/ox-hugo/ directory1 and /ox-hugo/ prefix is added to those file references in the exported Markdown files.

Also as the image file references are valid within the Org file, you can see those images inline too!

                       Screenshot of an Org mode buffer showing image in content

Examples #

Whether you prefer the subtree-based approach or file-based approach for writing your posts in Org, there are examples for both in the ox-hugo test suite:

  1. To understand why the attachment files get copied to the static/ox-hugo/ directory, have a look at the documentation for referencing files outside static directory. [return]
Fork me on GitHub