Relative paths in image links and Pandoc

johseb's Avatar


12 Jul, 2018 05:32 PM

Hi Brett,
thanks for the release 2.5.19 which solved the issue of colons inside headings id.
This time I'm writing because I'm facing problems with image links in markdown docs to be processed by Pandoc.

Let's say I have a MD file with a link to an image saved in Resources folder so the hierarchy is something like:


In Advanced preferences I specified the following Pandoc argument (among the others):


so that Pandoc can locate the image if I use a relative path in a link:

![A nice image](MyImage.jpg)

If I use Pandoc on the command line to process the file everything works fine but unfortunately if I open the file in Marked 2 I see the missing image placeholder and the html created by Marked 2 is:

<img src="MyImage.jpg" alt="A nice image" /><figcaption>A nice image</figcaption>

which shows why the image cannot be located.

Also notice that Marked 2 correctly shows the image if I use the link

![A nice image](./ResourcesFolder/MyImage.jpg)

even if this syntax doesn't work in Pandoc (because the base for relative links is the working directory and not the directory containing the MD file).

Given the behaviour I described I suspect that Marked 2 is somehow pre-processing images paths before handing down the ball to Pandoc. Is this the case?


  1. Support Staff 1 Posted by Brett on 13 Jul, 2018 04:03 PM

    Brett's Avatar

    Marked does do some processing on image paths, both before and after the
    main processor runs. If a path is relative, it tries to flesh out the
    path based on document location or a Base: metadata tag. This is
    primarily because it needs to find the images to watch them for changes,
    but also to accommodate a few inconsistencies in the way that different
    processors handle things like spaces in paths.

    However, if the output you're showing is what it's leaving, I'm not
    certain that it's making the change. If you open Help->Custom Processor
    Log, do the image paths being output by Pandoc directly differ from
    what's showing up in the preview?

    Using the metadata base: might help, and not require you to change the
    document itself...

    Base: /Volumes/myUSBdisk/path/to/BaseFolder/ResourcesFolder/

    Let me know if your processor log differs from the output. You can also
    right click and inspect the broken image to see the path that the
    preview itself is using, which may differ from the source or export


  2. 2 Posted by johseb on 13 Jul, 2018 08:04 PM

    johseb's Avatar

    Hi Brett,
    thanks for your reply.

    I made a few additional tests and I think I can say it's an issue with Pandoc and not Marked 2.

    In my configs there was a difference between Terminal Pandoc command and Marked 2 preview with Pandoc as processor: Pandoc command had a --self-contained option that was missing in Marked 2 processor args.
    Once I added the --self-contained option to Marked 2 processor args the preview showed the image correctly.

    So if you don't use the --self-contained option Pandoc seems to succeed in locating the image making use of the --resource-path option (Pandoc is not complaining about not finding the image as it does if you remove the --resource-path option) but it doesn't write the HTML <img> correctly and generate the wrong HTML:

    <img src="MyImage.jpg" alt="A nice image" /><figcaption>A nice image</figcaption>

    which I thought was generated by Marked 2.

    If you use the --self-contained option Pandoc locates the image and correctly add the base64 encoded portion.

    I must investigate the issue but I didn't find anything relevant on the Internet so I wonder if you, or any other Pandoc user reading this, are seeing the same behaviour.

    Of course there's always the possibility to specify the full path for the image source but that's what I was trying to avoid.

  3. Support Staff 3 Posted by Brett on 13 Jul, 2018 08:11 PM

    Brett's Avatar

    Yes, avoiding writing full, absolute paths is a fair objective :).

    Unfortunately, I'm not an in-depth enough user of Pandoc to have dealt
    much with these particular settings. Might be worth googling for a more
    active group, as people who've already solved an issue or know the
    solution aren't typically reading the support tickets for them here...


  4. 4 Posted by David on 05 Aug, 2021 06:43 AM

    David's Avatar

    For anyone that happens along and wants to use "--resource-path=..." you'll have to use it combined with either of these flags:




  5. 5 Posted by matt on 05 Jan, 2022 03:57 PM

    matt's Avatar

    @David thanks for the heads up; that solved my issue perfectly

Reply to this discussion

Internal reply

Formatting help / Preview (switch to plain text) No formatting (switch to Markdown)

Attaching KB article:


Attached Files

You can attach files up to 10MB

If you don't have an account yet, we need to confirm you're human and not a machine trying to post spam.

Keyboard shortcuts


? Show this help
ESC Blurs the current field

Comment Form

r Focus the comment reply box
^ + ↩ Submit the comment

You can use Command ⌘ instead of Control ^ on Mac