I'm learning how to use the Embedded Documentation feature, and am having mixed success.

In a new otherwise empty repo I've created a sample-doc.md which references an image in sample-doc.assets. When I view the page in fossil ui using the /doc/ckout url syntax it looks as I expect, including image. When I look a the checked in doc via Files browsing the markdown is rendered but the image is not displayed. When I attempt to look at the doc using /doc url syntax the file is not found.

• Works: http://localhost:8081/doc/ckout/Fixes/extract-invisible-attachment.md
• Markdown is interpreted but image is missing: http://localhost:8081/file?name=Fixes/extract-invisible-attachment.md&ci=tip
• Document is not found http://localhost:8081/doc/Fixes/extract-invisible-attacment.md or http://localhost:8081/doc/trunk/Fixes/extract-invisible-attacment.md

The file system layout is:

D:\REPOS\CURRENT_CKOUT
└───Fixes\extract-invisible-attachment.md
    └───extract-invisible-attachment.assets\invis-attach-email.png

The link text in the markdown document is using relative path:

   ![img](extract-invisible-attachment.assets/invis-attach-email.png)

What am I doing wrong?

The above-mentioned file uses ![results bar chart](./image-format-vs-repo-size.svg) notation.

Can someone please remind me why "./" part is necessary? Why not just ![...](image-format-vs-repo-size.svg)?
Is it documented somewhere?

Can someone please remind me why "./" part is necessary?

Speculating without being sure: to unambiguously differentiate them from wiki pages and artifact hashes? abcdef might be a hash prefix or a wiki page name, but ./abcdef is unambiguously a file reference.

http://localhost:8081/doc/trunk/Fixes/extract-invisible-attacment.md

It dies not work because there's a typo in spelling "attachment". The link has to be:

http://localhost:8081/doc/trunk/Fixes/extract-invisible-attachment.md

,as that's how you named it in your tree.

yes! a typo made #3 example 2 not work, thank you. Correcting the seplling worked (http://localhost:8081/doc/trunk/Fixes/extract-invisible-attachment.md).

However case #2 (http://localhost:8081/file?name=Fixes/extract-invisible-attachment.md&ci=tip) still doesn't show the image. Both the .md file and referenced image are checked in. I get to the page and image with the navigation path "Home >> Files >> {folder name} >> {filename.md}" and "...>> {sub-folder name} >> {filename.png}".

Following George's comment above I changed the image path reference to be be prefixed with ./: there is no change in observed behaviour, file?name= url continues to not show the image.

The raw text for the relevant line of the checked in file is:

   ![img](./extract-invisible-attachment.assets/invis-attach-email.png) 

The rendered html is:

   <p><img src="./extract-invisible-attachment.assets/invis-attach-email.png" alt="img" /> </p>

(Edited by Stephan to add code fence blocks around the otherwise invisible examples.)

However case #2 (http://localhost:8081/file?name=Fixes/extract-invisible-attachment.md&ci=tip) still doesn't show the image.

You may try to reference ci=trunk instead of tip, just so that you're consistent with those examples that do work.

Another idea is to force-refresh the page (in Firefox it's Ctrl-F5 or Shift-Ctrl-R, or something like that). This should bypass the browser caching. Maybe also try it in a Private window, just for a test. Fossil at times has some odd browser cache issues when running on localhost.

Thanks for the suggestions. I tried ci=trunk and removing ?ci=* altogether to no avail.

There is no change in behaviour across browsers Firefox, Chome and Edge. No chance of cache issue with Edge as I don't use it.

It appears to be a localhost and/or Windows issue. I copied the .fossil file to a FreeBSD web host, unchanged, and it Just Worked(tm).

It appears to be a localhost and/or Windows issue.

Glad that you solved this issue for you. Just as a follow-up, this kind of behavior as in case #2 above I observed with Fossil 2.13 (on Linux 32-bit). There must have been some good changes since. With the current version (2.16), the case #2 seems to show the image properly.

I upgraded fossil to 2.15.2 and now case#2 is working properly on localhost. It was v2.13; I see I neglected to post that above. I also can't rule out contamination: I found another fossil.exe in path for v2.7, now removed.