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.

Images and Regular Pages #

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.

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

Have a look at the content-org/images-in-content/images-in-content.org 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/ directory¹ 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!

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:

• Org source
• Exported Markdown

Images and Page Bundles #

See Hugo Bundle section on how to define those via ox-hugo.

Only for page bundles, when a link points to a local attachment, and the image path contains the hugo bundle name, following attachment copying rules apply:

• Assume that the bundle is a Leaf Bundle and its name is bundle-1 (:EXPORT_HUGO_BUNDLE: bundle-1) and that the image (attachment) path relative to the Org file is some-dir-1/bundle-1/some-dir-2/image.png.
• The attachment’s path relative to “bundle-1” is retained and copied to the “bundle-1” directory in the content dir. The path before the “bundle-1” in the attachment path is ignored.
• So after the export, we will see a directory structure like this in the content dir:

  ./content
  ..
   └── bundle-1
      ├── index.md
      └── some-dir-2/image.png
  

Examples #

./content-org
├── posts.org
│    * Bundle 1 (Org subtree)    →  ./content/bundle-1/index.md
│      [[file:bundle-1/image1.png]]
│      [[file:images/bundle-1/image.png]]
│
│    * Bundle 2 (Org subtree)    →  ./content/bundle-2/index.md
│      [[file:images/bundle-2/some-dir/image.png]]
│
├── bundle-1
│  └── image1.png                →  ./content/bundle-1/image1.png
└── images/
   ├── bundle-1
   │  └── image2.png             →  ./content/bundle-1/image2.png
   └── bundle-2
      └── some-dir
         └── image.png           →  ./content/bundle-2/some-dir/image.png

Another example from the test suite:

• images-in-content.org::* Page Bundle with images in the same dir | Exported Markdown | HTML