Trouble getting embedded docs to work

(1.1) Originally by anonymous with edits by Richard Hipp (drh) on 2021-06-11 22:43:32 from 1.0 [source]

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?

(2) By Richard Hipp (drh) on 2021-06-11 22:58:47 in reply to 1.1 [link] [source]

I don't know why your second example does not work. It seems to work for the canonical fossil repo. Compare:

As for why the first URL of the third example does not work: The /doc page wants a url like:

/doc/branch/path-to-file

You seem to be leaving out the branch.

On the second URL of the third example, I'm assuming you have not yet checked in the file you are trying to view, so it is not yet on "trunk". You can work around that for testing purposes by using the "--ckout-alias trunk" command-line option to "fossil ui".

(3) By anonymous on 2021-06-12 01:41:21 in reply to 1.1 [link] [source]

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.

(4) By george on 2021-06-12 19:40:27 in reply to 2 [link] [source]

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?

(5) By Stephan Beal (stephan) on 2021-06-12 19:52:02 in reply to 4 [link] [source]

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.

(6.1) Originally by anonymous with edits by Stephan Beal (stephan) on 2021-06-13 21:20:18 from 6.0 in reply to 3 [link] [source]

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.)

(7) By anonymous on 2021-06-14 00:42:30 in reply to 6.1 [link] [source]

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.

(8) By anonymous on 2021-06-15 01:03:03 in reply to 7 [link] [source]

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.

(9) By anonymous on 2021-06-15 01:10:34 in reply to 7 [link] [source]

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).

(10) By anonymous on 2021-06-15 22:25:47 in reply to 9 [link] [source]

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.

(11) By matt w. (maphew) on 2021-06-16 15:33:17 in reply to 10 [link] [source]

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.