Closed lmiq closed 1 year ago
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 😅
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.
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
.
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?
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.
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?
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.
that one should not work
Correct, it shouldn't. But you were saying that it does work when using serverdocs()
locally?
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)
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.
Thanks @mortenpi :heart:
I have an
docs/src/index.md
file which contains something like:(inside a
raw html
block).this renders correctly locally with
servedocs()
, because theindex.md
file is located atdocs/src
and thefigures
dir isdocs/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 usesrc="./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 theDocumenter
infraestructure, though.