relative path of dirs locally vs. in deployment in index.md

[lmiq]

I have an docs/src/index.md file which contains something like:

<img src="../figures/plot.png">

(inside a raw html block).

this renders correctly locally with servedocs(), because the index.md file is located at docs/src and the figures dir is docs/src/figures.

However, when this is deployed, since the index.html file is placed in the root page folder, the relative path becomes incorrect, and one need to use src="./figures/plot.png".

Thus, while the local deployment works and the relative paths seem correct, the page is not correctly rendered on the github site.

I'm not sure if this is something that should be handled by LiveServer or by the Documenter infraestructure, though.

[tlienart]

Hmm not sure, @mortenpi sorry to ping you, what do you think? Relative paths confuse me in web dev.

Anyway I imagine the correct behaviour would be to change something in LiveServer but I'd like a more informed opinion before doing anything 😅

[mortenpi]

I don't think LiveServer should try to do anything clever here. There is discussion about what's going on here: https://github.com/JuliaDocs/Documenter.jl/issues/921

In short though, I assume @lmiq, you are using a conditional prettyurls, with prettyurls=false locally. If you're using LiveServer anyway, that's not really necessary, so I'd just run with prettyurls=true (default) everywhere, so it would always be consistent.

[lmiq]

Uhm... I don't seem have changed prettyurls anywhere.

Note that this is specific to the index.md page, because it ends up deployed in a different relative path than the other .md files that are in docs/src.

[mortenpi]

Hmm. If you're not setting prettyurls, then there should be no difference between a local build and a deployed one (deploydocs literally just copies build/ to gh-pages).

If the raw block is in index.md, then the link raw block should be src="./figures/plot.png" (or src="figures/plot.png"). If it was in some other root Markdown file (e.g. foo.md, which then becomes foo/index.html), it must be ../figures/plot.png.

I suppose it could be a bug in LiveServer then? Is it serving the plot.png file at the expected URL?

[lmiq]

Oh, I see.

The issue is that with the local build with LiveServer, BOTH ../figures/plot.png and ./figures/plot.png work, because of the local directory structure generated, and it accesses the figures folder of the docs/src/figures instead.

Not sure if there is anything to do, but with the knowledge that the path in index.md has to be used differently, all is consistent.

Closing it.

[mortenpi]

If it's ../figures/plot.png, then from docs/build/index.html it should point to docs/figures/plot.png and not docs/src/figures/plot.png though? Which shouldn't work?

[lmiq]

Locally the path of index.html is

/docs/build/index.html

a ../figures/plot.png there is pointing to /docs/figures/index.html (which, note, is outside of build).

that one should not work, as the index.html file in the web version is at the same level as the figures directory.

Inside /docs/build there is another figures directory, that is the correct one.

[mortenpi]

that one should not work

Correct, it shouldn't. But you were saying that it does work when using serverdocs() locally?

[lmiq]

Yes, it works.

Although I checked now, in both cases, with ../figures or ./figures, the path of the figure in the built docs is:

http://localhost:8001/figures/KBs.png

so I'm not sure how exactly it ends up with that path. That only occurs with index.md. In the other .md files the correct ../figures is the only one that works.

(it is slightly confusing that index.md needs a different path than all other .md files that are stored in the same directory, but that's something to be handled upstream)

[mortenpi]

Ah, it looks like what's happening here is that the browser just effectively ignores the ..s if they try to go beyond the root of the domain. So figures/KBs.png, ../figures/KBs.png, ../../figures/KBs.png all end up getting resolved to http://localhost:8001/figures/KBs.png.

This actually looks like is consistent with the standard, even though it leads to a slightly confusing behavior here: https://datatracker.ietf.org/doc/html/rfc3986#section-5.4.2

Theoretically, one thing that LiveServer could do here is to have servedocs serve at some directory prefix in the URL. So rather than serving docs/build at http://localhost:8001/, it would get served at something like http://localhost:8001/serve/ or http://localhost:8001/docs/. But it's probably not worth the hassle.

[tlienart]

Thanks @mortenpi :heart: