Include image in Jekyll markdown collection

Question

I created a custom collection in my Jekyll configuration:

collections:
  tutorials:
    output: true
    permalink: /tutorials/:path/

I have a markdown file with the path: _tutorial/category/ios.md I also have an image with the path: _tutorial/category/xcode.png

In ios.md I use: ![xcode](xcode.png)

Which should make sense since they are on the same directory.

In the _site generated folder, I see

tutorial/
  category/
    xcode.png
    ios/
      index.html

So obviously the generated HTML is looking at the wrong place for the image since they are no longer in the same directory.

I thought of changing my structure to have my markdown file be _tutorial/category/ios/index.md, however all it did was create a folder called index so the problem is the same.

What is the expected way to include images in Jekyll/Markdown?

Am I supposed to keep them all in a folder at the root of the site? That would obviously work but it makes it hard to keep track of which images are associated with each post...

Answer 1

Because your collection has a permalink ending with a slash:

permalink: /tutorials/:path/

Jekyll will turn your Markdown file into an index.html file to make the link pretty. So ios.md becomes ios/index.html.

You can dodge this issue entirely by using links with extensions. This is the default option. Note there's no trailing slash:

permalink: /tutorials/:path

---

If you still want extension-free links, then for the relative image paths to work, you can either move the Markdown up one directory:

ios.md
ios/
  xcode.png

or change the image path to ![xcode](../xcode.png). Both approaches seem counter-intuitive.